# adrianhajdin/ghost-ai architecture

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

- Interactive diagram: https://gitdiagram.com/adrianhajdin/ghost-ai
- Repository: https://github.com/adrianhajdin/ghost-ai

## Overview

Ghost Arc is a collaborative system-design application: teams create and share projects, ask an AI agent to build an architecture diagram on a multiplayer canvas, refine it together, then generate and download Markdown specifications. The graph distinguishes project management, canvas collaboration, and the two AI stages. The README documents several capabilities whose detailed UI wiring was not sampled; those branches are shown only where the routes and documented runtime support them.

Main entry points: [`lib/prisma.ts`](https://github.com/adrianhajdin/ghost-ai/blob/main/lib/prisma.ts) (Prisma access), [`lib/project-access.ts`](https://github.com/adrianhajdin/ghost-ai/blob/main/lib/project-access.ts) (Project access checks), [`components/editor/canvas/canvas-editor.tsx`](https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/canvas/canvas-editor.tsx) (Canvas editor), [`app/api/ai/design/route.ts`](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/ai/design/route.ts) (Design task API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Team workspace"]
  node_workspace["Workspace UI<br/>[page.tsx]"]
  node_editor["Canvas editor<br/>[canvas-editor.tsx]"]
  node_home["Project home"]
  node_ai_sidebar["AI sidebar<br/>[ai-sidebar.tsx]"]
  node_templates["Starter templates"]
  node_share_ui["Share dialog"]
end

subgraph group_projects["Project services"]
  node_project_api["Project API<br/>[route.ts]"]
  node_project_detail["Project management API<br/>[route.ts]"]
  node_collaborator_api["Collaborator API<br/>[route.ts]"]
  node_access["Project access checks<br/>[project-access.ts]"]
end

subgraph group_ai["AI workflows"]
  node_design_api["Design task API<br/>[route.ts]"]
  node_design_task["Architecture agent<br/>[design-agent.ts]"]
  node_spec_api["Spec task API<br/>[route.ts]"]
  node_spec_task["Spec generator<br/>[generate-spec.ts]"]
  node_spec_list["Spec listing API<br/>[route.ts]"]
  node_spec_download["Spec download API<br/>[route.ts]"]
  node_trigger["Trigger.dev"]
  node_gemini{{"Google Gemini"}}
end

subgraph group_collaboration["Realtime canvas"]
  node_canvas_api["Canvas save API<br/>[route.ts]"]
  node_liveblocks_auth["Room authorization<br/>[route.ts]"]
  node_liveblocks["Liveblocks<br/>[liveblocks.ts]"]
end

subgraph group_storage["Persistence"]
  node_prisma["Prisma access<br/>[prisma.ts]"]
  node_database[("PostgreSQL")]
  node_blob[("Canvas and spec files")]
end

node_team(("Team member"))
node_clerk["Clerk identity"]
node_liveblocks_service["Liveblocks service"]

node_team -->|"opens"| node_workspace
node_team -->|"manages projects"| node_home
node_home -->|"creates and lists"| node_project_api
node_project_api -->|"queries projects"| node_prisma
node_project_detail -->|"updates projects"| node_prisma
node_prisma -->|"reads and writes"| node_database
node_team -->|"shares project"| node_share_ui
node_share_ui -->|"manages access"| node_collaborator_api
node_collaborator_api -->|"stores collaborators"| node_prisma
node_collaborator_api -->|"checks identity"| node_access
node_workspace -->|"opens canvas"| node_editor
node_editor -->|"requests room token"| node_liveblocks_auth
node_liveblocks_auth -->|"checks project access"| node_access
node_liveblocks_auth -->|"authorizes session"| node_liveblocks
node_liveblocks -->|"issues room access"| node_liveblocks_service
node_editor -->|"syncs canvas and presence"| node_liveblocks_service
node_editor -->|"loads and saves canvas"| node_canvas_api
node_canvas_api -->|"checks project access"| node_access
node_canvas_api -->|"reads and writes canvas"| node_blob
node_canvas_api -->|"stores blob reference"| node_prisma
node_ai_sidebar -->|"submits prompt"| node_design_api
node_design_api -->|"starts design task"| node_trigger
node_design_api -->|"records task run"| node_prisma
node_design_task -->|"generates diagram"| node_gemini
node_design_task -->|"updates shared canvas"| node_liveblocks_service
node_ai_sidebar -->|"requests specification"| node_spec_api
node_spec_api -->|"checks project access"| node_access
node_spec_api -->|"starts spec task"| node_trigger
node_spec_api -->|"records task run"| node_prisma
node_spec_task -->|"generates Markdown"| node_gemini
node_spec_task -->|"stores spec metadata"| node_prisma
node_spec_task -->|"stores spec content"| node_blob
node_team -->|"views specifications"| node_spec_list
node_spec_list -->|"checks project access"| node_access
node_spec_list -->|"lists specifications"| node_prisma
node_team -->|"downloads specification"| node_spec_download
node_spec_download -->|"checks project access"| node_access
node_spec_download -->|"finds spec metadata"| node_prisma
node_spec_download -->|"reads Markdown"| node_blob
node_team -->|"authenticates"| node_clerk
node_project_api -->|"checks identity"| node_clerk
node_project_detail -->|"checks identity"| node_clerk
node_design_api -->|"checks identity"| node_clerk
node_liveblocks_auth -->|"checks identity"| node_clerk
node_templates -.->|"offers templates"| node_home

click node_workspace "https://github.com/adrianhajdin/ghost-ai/blob/main/app/editor/page.tsx"
click node_editor "https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/canvas/canvas-editor.tsx"
click node_home "https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/editor-home-client.tsx"
click node_ai_sidebar "https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/ai-sidebar.tsx"
click node_templates "https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/starter-templates.ts"
click node_share_ui "https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/project-share-dialog.tsx"
click node_project_api "https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/route.ts"
click node_project_detail "https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/route.ts"
click node_collaborator_api "https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/collaborators/route.ts"
click node_access "https://github.com/adrianhajdin/ghost-ai/blob/main/lib/project-access.ts"
click node_design_api "https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/ai/design/route.ts"
click node_design_task "https://github.com/adrianhajdin/ghost-ai/blob/main/trigger/design-agent.ts"
click node_spec_api "https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/ai/spec/route.ts"
click node_spec_task "https://github.com/adrianhajdin/ghost-ai/blob/main/trigger/generate-spec.ts"
click node_spec_list "https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/route.ts"
click node_spec_download "https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/%5BspecId%5D/route.ts"
click node_canvas_api "https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/canvas/route.ts"
click node_liveblocks_auth "https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/liveblocks-auth/route.ts"
click node_liveblocks "https://github.com/adrianhajdin/ghost-ai/blob/main/lib/liveblocks.ts"
click node_prisma "https://github.com/adrianhajdin/ghost-ai/blob/main/lib/prisma.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_workspace,node_editor,node_home,node_ai_sidebar,node_templates,node_share_ui toneBlue
class node_project_api,node_project_detail,node_collaborator_api,node_access toneAmber
class node_design_api,node_design_task,node_spec_api,node_spec_task,node_spec_list,node_spec_download,node_trigger,node_gemini toneMint
class node_canvas_api,node_liveblocks_auth,node_liveblocks toneRose
class node_prisma,node_database,node_blob,node_team,node_clerk,node_liveblocks_service toneIndigo
```

## Components

### Team workspace

- [Workspace UI](https://github.com/adrianhajdin/ghost-ai/blob/main/app/editor/page.tsx): `app/editor/page.tsx`
- [Canvas editor](https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/canvas/canvas-editor.tsx): `components/editor/canvas/canvas-editor.tsx`
- [Project home](https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/editor-home-client.tsx): `components/editor/editor-home-client.tsx`
- [AI sidebar](https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/ai-sidebar.tsx): `components/editor/ai-sidebar.tsx`
- [Starter templates](https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/starter-templates.ts): `components/editor/starter-templates.ts`
- [Share dialog](https://github.com/adrianhajdin/ghost-ai/blob/main/components/editor/project-share-dialog.tsx): `components/editor/project-share-dialog.tsx`

### Project services

- [Project API](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/route.ts): `app/api/projects/route.ts`
- [Project management API](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/route.ts): `app/api/projects/[projectId]/route.ts`
- [Collaborator API](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/collaborators/route.ts): `app/api/projects/[projectId]/collaborators/route.ts`
- [Project access checks](https://github.com/adrianhajdin/ghost-ai/blob/main/lib/project-access.ts): `lib/project-access.ts`

### AI workflows

- [Design task API](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/ai/design/route.ts): `app/api/ai/design/route.ts`
- [Architecture agent](https://github.com/adrianhajdin/ghost-ai/blob/main/trigger/design-agent.ts): `trigger/design-agent.ts`
- [Spec task API](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/ai/spec/route.ts): `app/api/ai/spec/route.ts`
- [Spec generator](https://github.com/adrianhajdin/ghost-ai/blob/main/trigger/generate-spec.ts): `trigger/generate-spec.ts`
- [Spec listing API](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/route.ts): `app/api/projects/[projectId]/specs/route.ts`
- [Spec download API](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/%5BspecId%5D/route.ts): `app/api/projects/[projectId]/specs/[specId]/route.ts`
- **Trigger.dev**
- **Google Gemini**

### Realtime canvas

- [Canvas save API](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/canvas/route.ts): `app/api/projects/[projectId]/canvas/route.ts`
- [Room authorization](https://github.com/adrianhajdin/ghost-ai/blob/main/app/api/liveblocks-auth/route.ts): `app/api/liveblocks-auth/route.ts`
- [Liveblocks](https://github.com/adrianhajdin/ghost-ai/blob/main/lib/liveblocks.ts): `lib/liveblocks.ts`

### Persistence

- [Prisma access](https://github.com/adrianhajdin/ghost-ai/blob/main/lib/prisma.ts): `lib/prisma.ts`
- **PostgreSQL**
- **Canvas and spec files**

### Other components

- **Team member**
- **Clerk identity**
- **Liveblocks service**

## Connections

- Team member → Workspace UI: opens
- Team member → Project home: manages projects
- Project home → Project API: creates and lists
- Project API → Prisma access: queries projects
- Project management API → Prisma access: updates projects
- Prisma access → PostgreSQL: reads and writes
- Team member → Share dialog: shares project
- Share dialog → Collaborator API: manages access
- Collaborator API → Prisma access: stores collaborators
- Collaborator API → Project access checks: checks identity
- Workspace UI → Canvas editor: opens canvas
- Canvas editor → Room authorization: requests room token
- Room authorization → Project access checks: checks project access
- Room authorization → Liveblocks: authorizes session
- Liveblocks → Liveblocks service: issues room access
- Canvas editor → Liveblocks service: syncs canvas and presence
- Canvas editor → Canvas save API: loads and saves canvas
- Canvas save API → Project access checks: checks project access
- Canvas save API → Canvas and spec files: reads and writes canvas
- Canvas save API → Prisma access: stores blob reference
- AI sidebar → Design task API: submits prompt
- Design task API → Trigger.dev: starts design task
- Design task API → Prisma access: records task run
- Architecture agent → Google Gemini: generates diagram
- Architecture agent → Liveblocks service: updates shared canvas
- AI sidebar → Spec task API: requests specification
- Spec task API → Project access checks: checks project access
- Spec task API → Trigger.dev: starts spec task
- Spec task API → Prisma access: records task run
- Spec generator → Google Gemini: generates Markdown
- Spec generator → Prisma access: stores spec metadata
- Spec generator → Canvas and spec files: stores spec content
- Team member → Spec listing API: views specifications
- Spec listing API → Project access checks: checks project access
- Spec listing API → Prisma access: lists specifications
- Team member → Spec download API: downloads specification
- Spec download API → Project access checks: checks project access
- Spec download API → Prisma access: finds spec metadata
- Spec download API → Canvas and spec files: reads Markdown
- Team member → Clerk identity: authenticates
- Project API → Clerk identity: checks identity
- Project management API → Clerk identity: checks identity
- Design task API → Clerk identity: checks identity
- Room authorization → Clerk identity: checks identity
- Starter templates → Project home: offers templates