# nathanblatter/flightdeck architecture

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

- Interactive diagram: https://gitdiagram.com/nathanblatter/flightdeck
- Repository: https://github.com/nathanblatter/flightdeck

## Overview

Flightdeck is a cross-project context service for people and agents: organize projects and work items, retrieve context, then record activity and context outcomes. The web UI and documented HTTP/MCP interfaces support that workflow; additional capabilities include search, analytics, bug intake, and encrypted project sharing between instances. The README documents product-level behavior, but most backend implementations were not excerpted, so internal backend links are omitted or marked unverified rather than inferred from filenames.

Main entry points: [`web/src/App.tsx`](https://github.com/nathanblatter/flightdeck/blob/main/web/src/App.tsx) (Workspace shell), [`internal/api`](https://github.com/nathanblatter/flightdeck/tree/main/internal/api) (HTTP API), [`web/src/api.ts`](https://github.com/nathanblatter/flightdeck/blob/main/web/src/api.ts) (Typed API client), [`web/src/components/ProjectDrawer.tsx`](https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/ProjectDrawer.tsx) (Project context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workspace"]
  node_app["Workspace shell<br/>[App.tsx]"]
  node_board["Kanban board<br/>[Board.tsx]"]
  node_quickadd["Quick add<br/>[QuickAdd.tsx]"]
  node_newproject["Project creation<br/>[NewProject.tsx]"]
  node_drawer["Project context<br/>[ProjectDrawer.tsx]"]
  node_activity["Activity feed<br/>[ActivityFeed.tsx]"]
  node_links["Item links<br/>[ItemLinks.tsx]"]
  node_sharingui["Sharing controls<br/>[Sharing.tsx]"]
  node_setup["First-run setup<br/>[SetupWizard.tsx]"]
  node_client["Typed API client<br/>[api.ts]"]
end

subgraph group_backend["Context service"]
  node_http["HTTP API"]
  node_auth["API-key auth<br/>[auth.go]"]
  node_services["Domain services"]
  node_context["Context retrieval<br/>[context.go]"]
  node_search["Cascading search"]
  node_impact["Context impact<br/>[context_impact.go]"]
  node_webhooks["Webhook delivery<br/>[webhooks.go]"]
  node_database[("PostgreSQL")]
end

subgraph group_sharing["Federated sharing"]
  node_sync["Share sync engine<br/>[engine.go]"]
  node_mailbox["Mailbox server<br/>[main.go]"]
  node_mailboxclient["Mailbox client<br/>[mailbox.go]"]
end

subgraph group_integrations["Agent and intake interfaces"]
  node_mcp["MCP interface<br/>[server.go]"]
  node_widget["Bug widget<br/>[bug-widget.js]"]
  node_ingest["Bug intake<br/>[ingest.go]"]
end

node_person(("Human user"))
node_agent(("Agent client"))
node_site(("Public website"))
node_peer(("Peer instance"))

node_person -->|"uses"| node_app
node_app -->|"renders"| node_board
node_app -->|"renders"| node_activity
node_app -->|"renders"| node_drawer
node_app -->|"renders"| node_quickadd
node_app -->|"renders"| node_newproject
node_app -->|"renders"| node_links
node_app -->|"renders"| node_sharingui
node_app -->|"renders"| node_setup
node_board -->|"updates items"| node_client
node_quickadd -->|"creates items"| node_client
node_newproject -->|"creates projects"| node_client
node_drawer -->|"loads context"| node_client
node_drawer -->|"renders"| node_sharingui
node_activity -->|"loads activity"| node_client
node_links -->|"manages links"| node_client
node_sharingui -->|"manages shares"| node_client
node_setup -->|"checks setup"| node_client
node_client -->|"sends requests"| node_http
node_agent -->|"uses REST API"| node_http
node_http -.->|"checks keys"| node_auth
node_http -.->|"dispatches"| node_services
node_services -.->|"reads and writes"| node_database
node_http -->|"serves context"| node_context
node_http -->|"serves search"| node_search
node_http -->|"records impacts"| node_impact
node_http -->|"manages hooks"| node_webhooks
node_agent -->|"uses tools"| node_mcp
node_mcp -.->|"dispatches tools"| node_services
node_site -->|"hosts"| node_widget
node_widget -->|"submits reports"| node_ingest
node_peer -->|"exchanges messages"| node_mailbox
node_sync -.->|"uses client"| node_mailboxclient
node_mailboxclient -->|"exchanges encrypted data"| node_mailbox
node_http -.->|"coordinates shares"| node_sync

click node_app "https://github.com/nathanblatter/flightdeck/blob/main/web/src/App.tsx"
click node_board "https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/Board.tsx"
click node_quickadd "https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/QuickAdd.tsx"
click node_newproject "https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/NewProject.tsx"
click node_drawer "https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/ProjectDrawer.tsx"
click node_activity "https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/ActivityFeed.tsx"
click node_links "https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/ItemLinks.tsx"
click node_sharingui "https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/Sharing.tsx"
click node_setup "https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/SetupWizard.tsx"
click node_client "https://github.com/nathanblatter/flightdeck/blob/main/web/src/api.ts"
click node_http "https://github.com/nathanblatter/flightdeck/tree/main/internal/api"
click node_auth "https://github.com/nathanblatter/flightdeck/blob/main/internal/auth/auth.go"
click node_services "https://github.com/nathanblatter/flightdeck/tree/main/internal/service"
click node_context "https://github.com/nathanblatter/flightdeck/blob/main/internal/api/context.go"
click node_search "https://github.com/nathanblatter/flightdeck/blob/main/internal/store/items_search.sql.go"
click node_impact "https://github.com/nathanblatter/flightdeck/blob/main/internal/service/context_impact.go"
click node_webhooks "https://github.com/nathanblatter/flightdeck/blob/main/internal/service/webhooks.go"
click node_database "https://github.com/nathanblatter/flightdeck/tree/main/internal/store"
click node_mcp "https://github.com/nathanblatter/flightdeck/blob/main/internal/mcp/server.go"
click node_widget "https://github.com/nathanblatter/flightdeck/blob/main/bug-widget.js"
click node_ingest "https://github.com/nathanblatter/flightdeck/blob/main/internal/api/ingest.go"
click node_sync "https://github.com/nathanblatter/flightdeck/blob/main/internal/sync/engine.go"
click node_mailbox "https://github.com/nathanblatter/flightdeck/blob/main/cmd/flightdeck-mailbox/main.go"
click node_mailboxclient "https://github.com/nathanblatter/flightdeck/blob/main/internal/mailbox/mailbox.go"

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_board,node_quickadd,node_newproject,node_drawer,node_activity,node_links,node_sharingui,node_setup,node_client,node_person,node_agent toneBlue
class node_http,node_auth,node_services,node_context,node_search,node_impact,node_webhooks,node_database toneAmber
class node_sync,node_mailbox,node_mailboxclient toneMint
class node_mcp,node_widget,node_ingest toneRose
class node_site,node_peer toneIndigo
```

## Components

### Web workspace

- [Workspace shell](https://github.com/nathanblatter/flightdeck/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Kanban board](https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/Board.tsx): `web/src/components/Board.tsx`
- [Quick add](https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/QuickAdd.tsx): `web/src/components/QuickAdd.tsx`
- [Project creation](https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/NewProject.tsx): `web/src/components/NewProject.tsx`
- [Project context](https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/ProjectDrawer.tsx): `web/src/components/ProjectDrawer.tsx`
- [Activity feed](https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/ActivityFeed.tsx): `web/src/components/ActivityFeed.tsx`
- [Item links](https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/ItemLinks.tsx): `web/src/components/ItemLinks.tsx`
- [Sharing controls](https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/Sharing.tsx): `web/src/components/Sharing.tsx`
- [First-run setup](https://github.com/nathanblatter/flightdeck/blob/main/web/src/components/SetupWizard.tsx): `web/src/components/SetupWizard.tsx`
- [Typed API client](https://github.com/nathanblatter/flightdeck/blob/main/web/src/api.ts): `web/src/api.ts`

### Context service

- [HTTP API](https://github.com/nathanblatter/flightdeck/tree/main/internal/api): `internal/api`
- [API-key auth](https://github.com/nathanblatter/flightdeck/blob/main/internal/auth/auth.go): `internal/auth/auth.go`
- [Domain services](https://github.com/nathanblatter/flightdeck/tree/main/internal/service): `internal/service`
- [Context retrieval](https://github.com/nathanblatter/flightdeck/blob/main/internal/api/context.go): `internal/api/context.go`
- [Cascading search](https://github.com/nathanblatter/flightdeck/blob/main/internal/store/items_search.sql.go): `internal/store/items_search.sql.go`
- [Context impact](https://github.com/nathanblatter/flightdeck/blob/main/internal/service/context_impact.go): `internal/service/context_impact.go`
- [Webhook delivery](https://github.com/nathanblatter/flightdeck/blob/main/internal/service/webhooks.go): `internal/service/webhooks.go`
- [PostgreSQL](https://github.com/nathanblatter/flightdeck/tree/main/internal/store): `internal/store`

### Federated sharing

- [Share sync engine](https://github.com/nathanblatter/flightdeck/blob/main/internal/sync/engine.go): `internal/sync/engine.go`
- [Mailbox server](https://github.com/nathanblatter/flightdeck/blob/main/cmd/flightdeck-mailbox/main.go): `cmd/flightdeck-mailbox/main.go`
- [Mailbox client](https://github.com/nathanblatter/flightdeck/blob/main/internal/mailbox/mailbox.go): `internal/mailbox/mailbox.go`

### Agent and intake interfaces

- [MCP interface](https://github.com/nathanblatter/flightdeck/blob/main/internal/mcp/server.go): `internal/mcp/server.go`
- [Bug widget](https://github.com/nathanblatter/flightdeck/blob/main/bug-widget.js): `bug-widget.js`
- [Bug intake](https://github.com/nathanblatter/flightdeck/blob/main/internal/api/ingest.go): `internal/api/ingest.go`

### Other components

- **Human user**
- **Agent client**
- **Public website**
- **Peer instance**

## Connections

- Human user → Workspace shell: uses
- Workspace shell → Kanban board: renders (evidence: `web/src/App.tsx`)
- Workspace shell → Activity feed: renders (evidence: `web/src/App.tsx`)
- Workspace shell → Project context: renders (evidence: `web/src/App.tsx`)
- Workspace shell → Quick add: renders (evidence: `web/src/App.tsx`)
- Workspace shell → Project creation: renders (evidence: `web/src/App.tsx`)
- Workspace shell → Item links: renders (evidence: `web/src/App.tsx`)
- Workspace shell → Sharing controls: renders (evidence: `web/src/App.tsx`)
- Workspace shell → First-run setup: renders (evidence: `web/src/App.tsx`)
- Kanban board → Typed API client: updates items (evidence: `web/src/components/Board.tsx`)
- Quick add → Typed API client: creates items (evidence: `web/src/components/QuickAdd.tsx`)
- Project creation → Typed API client: creates projects (evidence: `web/src/components/NewProject.tsx`)
- Project context → Typed API client: loads context (evidence: `web/src/components/ProjectDrawer.tsx`)
- Project context → Sharing controls: renders (evidence: `web/src/components/ProjectDrawer.tsx`)
- Activity feed → Typed API client: loads activity (evidence: `web/src/components/ActivityFeed.tsx`)
- Item links → Typed API client: manages links (evidence: `web/src/components/ItemLinks.tsx`)
- Sharing controls → Typed API client: manages shares (evidence: `web/src/components/Sharing.tsx`)
- First-run setup → Typed API client: checks setup (evidence: `web/src/components/SetupWizard.tsx`)
- Typed API client → HTTP API: sends requests
- Agent client → HTTP API: uses REST API
- HTTP API → API-key auth: checks keys
- HTTP API → Domain services: dispatches
- Domain services → PostgreSQL: reads and writes
- HTTP API → Context retrieval: serves context
- HTTP API → Cascading search: serves search
- HTTP API → Context impact: records impacts
- HTTP API → Webhook delivery: manages hooks
- Agent client → MCP interface: uses tools
- MCP interface → Domain services: dispatches tools
- Public website → Bug widget: hosts
- Bug widget → Bug intake: submits reports
- Peer instance → Mailbox server: exchanges messages
- Share sync engine → Mailbox client: uses client
- Mailbox client → Mailbox server: exchanges encrypted data
- HTTP API → Share sync engine: coordinates shares
