# nelay04/meadow architecture

> Architecture diagram of the GitHub repository nelay04/meadow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nelay04/meadow
- Repository: https://github.com/nelay04/meadow

## Overview

Meadow is a collaborative infinite-canvas workspace for drawing, writing, organizing, and sharing glades, with leas as a ruled-page board kind. Users sign in or follow a share link, open a board, edit its shared document, and see collaborators’ updates; they can also manage access, accounts, and preferences. The map includes the web canvas, shared document model, API and realtime persistence, plus the MCP assistant interface. Many subsystem links are documented in the README; unsampled implementation details are not treated as inspected.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/nelay04/meadow/blob/main/apps/web/src/App.tsx) (App routing), [`apps/web/src/canvas/engine.ts`](https://github.com/nelay04/meadow/blob/main/apps/web/src/canvas/engine.ts) (Canvas engine), [`services/api/app/main.py`](https://github.com/nelay04/meadow/blob/main/services/api/app/main.py) (API application), [`apps/web/src/features/board/useCanvas.ts`](https://github.com/nelay04/meadow/blob/main/apps/web/src/features/board/useCanvas.ts) (Canvas host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_app["App routing<br/>[App.tsx]"]
  node_authui["Sign-in and account"]
  node_boardui["Board workspace"]
  node_boards["Board discovery"]
  node_profile["Profile settings"]
  node_api_client["Web API client<br/>[api.ts]"]
end

subgraph group_canvas["Canvas and document"]
  node_canvas_host["Canvas host<br/>[useCanvas.ts]"]
  node_engine["Canvas engine<br/>[engine.ts]"]
  node_render["Canvas rendering"]
  node_tools["Canvas tools"]
  node_text_input["Text and language input"]
  node_schema["Shared document model<br/>[objects.ts]"]
end

subgraph group_api["API and identity"]
  node_api_app["API application<br/>[main.py]"]
  node_auth_api["Authentication routes<br/>[auth.py]"]
  node_board_api["Boards and sharing"]
  node_permissions["Access permissions<br/>[permissions.py]"]
  node_models[("Persistent models<br/>[models.py]")]
end

subgraph group_realtime["Realtime collaboration"]
  node_sync_client["Sync provider<br/>[provider.ts]"]
  node_ws_server["Realtime room server<br/>[server.py]"]
end

subgraph group_assistant["Assistant integration"]
  node_mcp_server["MCP tools<br/>[server.ts]"]
  node_mcp_rooms["MCP board sessions<br/>[room.ts]"]
end

node_person(("Board user"))

node_person -->|"opens"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_boardui
node_app -->|"routes to"| node_boards
node_app -->|"routes to"| node_profile
node_authui -->|"requests"| node_api_client
node_boardui -->|"hosts"| node_canvas_host
node_canvas_host -->|"creates"| node_engine
node_engine -->|"renders with"| node_render
node_engine -.->|"dispatches tools"| node_tools
node_canvas_host -.->|"syncs document"| node_sync_client
node_engine -->|"reads objects"| node_schema
node_tools -.->|"edits objects"| node_schema
node_text_input -->|"supplies text"| node_canvas_host
node_person -->|"requests services"| node_api_client
node_api_client -.->|"calls REST API"| node_api_app
node_api_app -->|"mounts routes"| node_auth_api
node_api_app -->|"mounts routes"| node_board_api
node_auth_api -->|"reads and writes"| node_models
node_board_api -.->|"checks access"| node_permissions
node_api_app -->|"serves rooms"| node_ws_server
node_ws_server -->|"persists board state"| node_models
node_sync_client -.->|"exchanges updates"| node_ws_server
node_mcp_server -->|"opens sessions"| node_mcp_rooms
node_person -.->|"uses assistant"| node_mcp_server
node_mcp_server -->|"reads and plans edits"| node_schema

click node_app "https://github.com/nelay04/meadow/blob/main/apps/web/src/App.tsx"
click node_authui "https://github.com/nelay04/meadow/tree/main/apps/web/src/features/auth"
click node_boardui "https://github.com/nelay04/meadow/tree/main/apps/web/src/features/board"
click node_boards "https://github.com/nelay04/meadow/tree/main/apps/web/src/features/boards"
click node_profile "https://github.com/nelay04/meadow/tree/main/apps/web/src/features/profile"
click node_api_client "https://github.com/nelay04/meadow/blob/main/apps/web/src/lib/api.ts"
click node_canvas_host "https://github.com/nelay04/meadow/blob/main/apps/web/src/features/board/useCanvas.ts"
click node_engine "https://github.com/nelay04/meadow/blob/main/apps/web/src/canvas/engine.ts"
click node_render "https://github.com/nelay04/meadow/tree/main/apps/web/src/canvas/renderers"
click node_tools "https://github.com/nelay04/meadow/tree/main/apps/web/src/canvas/tools"
click node_text_input "https://github.com/nelay04/meadow/tree/main/apps/web/src/text"
click node_sync_client "https://github.com/nelay04/meadow/blob/main/apps/web/src/sync/provider.ts"
click node_schema "https://github.com/nelay04/meadow/blob/main/packages/schema/src/objects.ts"
click node_api_app "https://github.com/nelay04/meadow/blob/main/services/api/app/main.py"
click node_auth_api "https://github.com/nelay04/meadow/blob/main/services/api/app/api/v1/auth.py"
click node_board_api "https://github.com/nelay04/meadow/tree/main/services/api/app/api/v1"
click node_permissions "https://github.com/nelay04/meadow/blob/main/services/api/app/services/permissions.py"
click node_models "https://github.com/nelay04/meadow/blob/main/services/api/app/models.py"
click node_ws_server "https://github.com/nelay04/meadow/blob/main/services/api/app/realtime/server.py"
click node_mcp_server "https://github.com/nelay04/meadow/blob/main/packages/mcp/src/server.ts"
click node_mcp_rooms "https://github.com/nelay04/meadow/blob/main/packages/mcp/src/room.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_authui,node_boardui,node_boards,node_profile,node_api_client,node_person toneBlue
class node_canvas_host,node_engine,node_render,node_tools,node_text_input,node_schema toneAmber
class node_api_app,node_auth_api,node_board_api,node_permissions,node_models toneMint
class node_sync_client,node_ws_server toneRose
class node_mcp_server,node_mcp_rooms toneIndigo
```

## Components

### Web app

- [App routing](https://github.com/nelay04/meadow/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Sign-in and account](https://github.com/nelay04/meadow/tree/main/apps/web/src/features/auth): `apps/web/src/features/auth`
- [Board workspace](https://github.com/nelay04/meadow/tree/main/apps/web/src/features/board): `apps/web/src/features/board`
- [Board discovery](https://github.com/nelay04/meadow/tree/main/apps/web/src/features/boards): `apps/web/src/features/boards`
- [Profile settings](https://github.com/nelay04/meadow/tree/main/apps/web/src/features/profile): `apps/web/src/features/profile`
- [Web API client](https://github.com/nelay04/meadow/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### Canvas and document

- [Canvas host](https://github.com/nelay04/meadow/blob/main/apps/web/src/features/board/useCanvas.ts): `apps/web/src/features/board/useCanvas.ts`
- [Canvas engine](https://github.com/nelay04/meadow/blob/main/apps/web/src/canvas/engine.ts): `apps/web/src/canvas/engine.ts`
- [Canvas rendering](https://github.com/nelay04/meadow/tree/main/apps/web/src/canvas/renderers): `apps/web/src/canvas/renderers`
- [Canvas tools](https://github.com/nelay04/meadow/tree/main/apps/web/src/canvas/tools): `apps/web/src/canvas/tools`
- [Text and language input](https://github.com/nelay04/meadow/tree/main/apps/web/src/text): `apps/web/src/text`
- [Shared document model](https://github.com/nelay04/meadow/blob/main/packages/schema/src/objects.ts): `packages/schema/src/objects.ts`

### API and identity

- [API application](https://github.com/nelay04/meadow/blob/main/services/api/app/main.py): `services/api/app/main.py`
- [Authentication routes](https://github.com/nelay04/meadow/blob/main/services/api/app/api/v1/auth.py): `services/api/app/api/v1/auth.py`
- [Boards and sharing](https://github.com/nelay04/meadow/tree/main/services/api/app/api/v1): `services/api/app/api/v1`
- [Access permissions](https://github.com/nelay04/meadow/blob/main/services/api/app/services/permissions.py): `services/api/app/services/permissions.py`
- [Persistent models](https://github.com/nelay04/meadow/blob/main/services/api/app/models.py): `services/api/app/models.py`

### Realtime collaboration

- [Sync provider](https://github.com/nelay04/meadow/blob/main/apps/web/src/sync/provider.ts): `apps/web/src/sync/provider.ts`
- [Realtime room server](https://github.com/nelay04/meadow/blob/main/services/api/app/realtime/server.py): `services/api/app/realtime/server.py`

### Assistant integration

- [MCP tools](https://github.com/nelay04/meadow/blob/main/packages/mcp/src/server.ts): `packages/mcp/src/server.ts`
- [MCP board sessions](https://github.com/nelay04/meadow/blob/main/packages/mcp/src/room.ts): `packages/mcp/src/room.ts`

### Other components

- **Board user**

## Connections

- Board user → App routing: opens
- App routing → Sign-in and account: routes to (evidence: `apps/web/src/App.tsx`)
- App routing → Board workspace: routes to (evidence: `apps/web/src/App.tsx`)
- App routing → Board discovery: routes to (evidence: `apps/web/src/App.tsx`)
- App routing → Profile settings: routes to (evidence: `apps/web/src/App.tsx`)
- Sign-in and account → Web API client: requests (evidence: `apps/web/src/features/auth/AuthContext.tsx`)
- Board workspace → Canvas host: hosts (evidence: `apps/web/src/features/board/useCanvas.ts`)
- Canvas host → Canvas engine: creates (evidence: `apps/web/src/features/board/useCanvas.ts`)
- Canvas engine → Canvas rendering: renders with (evidence: `apps/web/src/canvas/engine.ts`)
- Canvas engine → Canvas tools: dispatches tools (evidence: `apps/web/src/canvas/engine.ts`)
- Canvas host → Sync provider: syncs document
- Canvas engine → Shared document model: reads objects (evidence: `apps/web/src/canvas/engine.ts`)
- Canvas tools → Shared document model: edits objects
- Text and language input → Canvas host: supplies text
- Board user → Web API client: requests services
- Web API client → API application: calls REST API
- API application → Authentication routes: mounts routes (evidence: `services/api/app/main.py`)
- API application → Boards and sharing: mounts routes (evidence: `services/api/app/main.py`)
- Authentication routes → Persistent models: reads and writes (evidence: `services/api/app/api/v1/auth.py`)
- Boards and sharing → Access permissions: checks access
- API application → Realtime room server: serves rooms (evidence: `services/api/app/main.py`)
- Realtime room server → Persistent models: persists board state (evidence: `services/api/app/realtime/server.py`)
- Sync provider → Realtime room server: exchanges updates
- MCP tools → MCP board sessions: opens sessions (evidence: `packages/mcp/src/server.ts`)
- Board user → MCP tools: uses assistant
- MCP tools → Shared document model: reads and plans edits (evidence: `packages/mcp/src/server.ts`)
