Skip to main content

Architecture Overview

The Concept Mapping Tool is built as a modern, real-time collaborative web application using React, InstantDB, and React Flow.

Technology Stack​

  • Frontend Framework: React 19 with TypeScript
  • State Management: Zustand for UI state, InstantDB for data state
  • Graph Rendering: React Flow
  • Real-time Sync: InstantDB
  • Styling: Tailwind CSS
  • Build Tool: Vite

Architecture Principles​

  1. Serverless: No backend server for application data; InstantDB handles all data persistence and sync.
  2. Real-time First: All data changes are synchronized instantly
  3. Component-Based: Modular React components with clear responsibilities
  4. Type-Safe: Full TypeScript coverage
  5. Permission-Based: Fine-grained access control via InstantDB permissions

System Architecture​

┌─────────────────────────────────────────┐
│         React Application               │
│  ┌─────────────┐  ┌──────────────┐     │
│  │   UI State  │  │   Data State │     │
│  │  (Zustand)  │  │  (InstantDB) │     │
│  └─────────────┘  └──────────────┘     │
│           │              │              │
│           └──────┬───────┘              │
│                  │                      │
│         ┌────────▼────────┐            │
│         │  React Hooks    │            │
│         │  db.useQuery()  │            │
│         │  db.transact()  │            │
│         └────────┬────────┘            │
└──────────────────┼─────────────────────┘
                   │
         ┌─────────▼─────────┐
         │    InstantDB      │
         │  (Backend as a    │
         │   Service)        │
         └───────────────────┘

Key Concepts​

  • Maps: Top-level containers for concept maps
  • Concepts: Nodes in the concept map
  • Relationships: Edges connecting concepts
  • Perspectives: Filtered views of maps
  • Shares: Access control for maps
  • Commands: Undoable operations using the Command pattern

Data Flow​

  1. User interacts with UI component
  2. Component calls hook (e.g., useCanvasMutations)
  3. Hook creates Command object and executes it
  4. Command uses db.transact() to mutate InstantDB
  5. Command is recorded in undo store for undo/redo
  6. InstantDB syncs changes to all connected clients
  7. db.useQuery() hooks automatically update React components
  8. UI reflects changes in real-time

Undo/Redo System​

The application uses the Command pattern for comprehensive undo/redo functionality:

  • Command Pattern: All mutations are encapsulated as Command objects with execute() and reverse() methods
  • Operation Grouping: Related mutations are grouped into single undoable operations (e.g., entire drag sequences)
  • Previous State Capture: Update commands capture previous state for accurate reversal
  • Redo Support: Full redo functionality with keyboard shortcuts

See Undo/Redo System Guide for detailed documentation.