# dee-nwanjah/ghost-ai architecture

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

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

## Overview

Ghost Arc is a collaborative system-architecture planner. Users create or open a project, describe a system to the AI, and watch it build a shared canvas that teammates can refine; they can then generate, store, and download a Markdown specification. The map includes project access/sharing, Liveblocks collaboration, and background AI jobs. Source excerpts verify selected API and orchestration links; README documents key capabilities whose implementation files were not sampled, so those links are dashed where unverified.

Main entry points: [`lib/prisma.ts`](https://github.com/dee-nwanjah/ghost-ai/blob/main/lib/prisma.ts) (Prisma client), [`lib/project-access.ts`](https://github.com/dee-nwanjah/ghost-ai/blob/main/lib/project-access.ts) (Project access), [`trigger/generate-spec.ts`](https://github.com/dee-nwanjah/ghost-ai/blob/main/trigger/generate-spec.ts) (Specification generator), [`components/editor/editor-workspace-client.tsx`](https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/editor-workspace-client.tsx) (Editor workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Project workspace"]
  node_projects_ui["Project browser"]
  node_project_actions["Project actions"]
  node_project_api["Project API<br/>[route.ts]"]
  node_workspace["Editor workspace"]
  node_project_management["Project operations<br/>[route.ts]"]
end

subgraph group_canvas["Canvas collaboration"]
  node_canvas_room["Canvas room<br/>[canvas-room.tsx]"]
  node_canvas_editor["Canvas editor<br/>[canvas-editor.tsx]"]
  node_autosave["Canvas autosave"]
  node_canvas_api["Canvas persistence API<br/>[route.ts]"]
  node_liveblocks["Liveblocks service"]
  node_collab_auth["Room authorization<br/>[route.ts]"]
  node_collaborators["Collaborator sharing<br/>[route.ts]"]
  node_collaborator_lib["Sharing rules"]
end

subgraph group_ai["AI planning"]
  node_ai_sidebar["AI prompt panel<br/>[ai-sidebar.tsx]"]
  node_design_api["Design task API<br/>[route.ts]"]
  node_design_task["Architecture agent<br/>[design-agent.ts]"]
  node_trigger["Trigger.dev"]
  node_gemini["Gemini model"]
end

subgraph group_specs["Specifications"]
  node_spec_api["Spec task API<br/>[route.ts]"]
  node_spec_task["Specification generator<br/>[generate-spec.ts]"]
  node_spec_routes["Spec management API<br/>[route.ts]"]
  node_spec_detail["Spec detail API<br/>[route.ts]"]
  node_spec_download["Spec download<br/>[route.ts]"]
  node_markdown_store["Markdown files"]
end

subgraph group_platform["Access and storage"]
  node_access["Project access<br/>[project-access.ts]"]
  node_database[("PostgreSQL")]
  node_prisma["Prisma client<br/>[prisma.ts]"]
  node_clerk["Clerk identity"]
end

node_user(("Team member"))

node_user -.->|"opens projects"| node_projects_ui
node_projects_ui -->|"invokes actions"| node_project_actions
node_project_actions -->|"creates project"| node_project_api
node_project_api -->|"persists project"| node_prisma
node_prisma -.->|"queries"| node_database
node_project_actions -->|"renames or deletes"| node_project_management
node_user -.->|"enters workspace"| node_workspace
node_workspace -->|"renders"| node_canvas_room
node_canvas_room -->|"renders"| node_canvas_editor
node_workspace -->|"renders"| node_ai_sidebar
node_canvas_room -->|"uses"| node_autosave
node_autosave -.->|"saves canvas"| node_canvas_api
node_canvas_api -->|"checks access"| node_access
node_canvas_api -->|"reads or writes"| node_prisma
node_workspace -.->|"requests room auth"| node_collab_auth
node_collab_auth -->|"validates access"| node_access
node_collab_auth -->|"authorizes room"| node_liveblocks
node_canvas_editor -.->|"syncs canvas"| node_liveblocks
node_user -.->|"manages sharing"| node_collaborators
node_collaborators -->|"uses sharing rules"| node_collaborator_lib
node_collaborators -->|"stores collaborators"| node_prisma
node_ai_sidebar -.->|"submits prompt"| node_design_api
node_design_api -->|"triggers task"| node_design_task
node_design_task -.->|"runs job"| node_trigger
node_design_task -.->|"generates diagram"| node_gemini
node_design_task -->|"updates shared canvas"| node_liveblocks
node_user -.->|"requests specification"| node_spec_api
node_spec_api -->|"checks access"| node_access
node_spec_api -->|"triggers task"| node_spec_task
node_spec_task -.->|"runs job"| node_trigger
node_spec_task -.->|"writes specification"| node_gemini
node_spec_task -->|"stores metadata"| node_prisma
node_spec_api -.->|"passes graph"| node_spec_task
node_spec_routes -->|"checks access"| node_access
node_spec_routes -->|"manages metadata"| node_prisma
node_spec_detail -->|"checks access"| node_access
node_spec_detail -->|"manages metadata"| node_prisma
node_spec_download -.->|"reads Markdown"| node_markdown_store
node_access -->|"gets identity"| node_clerk
node_access -->|"checks membership"| node_prisma
node_prisma -.->|"persists records"| node_database

click node_projects_ui "https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/editor-home-client.tsx"
click node_project_actions "https://github.com/dee-nwanjah/ghost-ai/blob/main/hooks/use-project-actions.ts"
click node_project_api "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/route.ts"
click node_workspace "https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/editor-workspace-client.tsx"
click node_project_management "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/route.ts"
click node_canvas_room "https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/canvas/canvas-room.tsx"
click node_canvas_editor "https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/canvas/canvas-editor.tsx"
click node_autosave "https://github.com/dee-nwanjah/ghost-ai/blob/main/hooks/use-canvas-autosave.ts"
click node_canvas_api "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/canvas/route.ts"
click node_collab_auth "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/liveblocks-auth/route.ts"
click node_collaborators "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/collaborators/route.ts"
click node_collaborator_lib "https://github.com/dee-nwanjah/ghost-ai/blob/main/lib/project-collaborators.ts"
click node_ai_sidebar "https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/ai-sidebar.tsx"
click node_design_api "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/ai/design/route.ts"
click node_design_task "https://github.com/dee-nwanjah/ghost-ai/blob/main/trigger/design-agent.ts"
click node_spec_api "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/ai/spec/route.ts"
click node_spec_task "https://github.com/dee-nwanjah/ghost-ai/blob/main/trigger/generate-spec.ts"
click node_spec_routes "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/route.ts"
click node_spec_detail "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/%5BspecId%5D/route.ts"
click node_spec_download "https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/%5BspecId%5D/download/route.ts"
click node_access "https://github.com/dee-nwanjah/ghost-ai/blob/main/lib/project-access.ts"
click node_prisma "https://github.com/dee-nwanjah/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_projects_ui,node_project_actions,node_project_api,node_workspace,node_project_management toneBlue
class node_canvas_room,node_canvas_editor,node_autosave,node_canvas_api,node_liveblocks,node_collab_auth,node_collaborators,node_collaborator_lib toneAmber
class node_ai_sidebar,node_design_api,node_design_task,node_trigger,node_gemini toneMint
class node_spec_api,node_spec_task,node_spec_routes,node_spec_detail,node_spec_download,node_markdown_store toneRose
class node_access,node_database,node_prisma,node_clerk,node_user toneIndigo
```

## Components

### Project workspace

- [Project browser](https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/editor-home-client.tsx): `components/editor/editor-home-client.tsx`
- [Project actions](https://github.com/dee-nwanjah/ghost-ai/blob/main/hooks/use-project-actions.ts): `hooks/use-project-actions.ts`
- [Project API](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/route.ts): `app/api/projects/route.ts`
- [Editor workspace](https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/editor-workspace-client.tsx): `components/editor/editor-workspace-client.tsx`
- [Project operations](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/route.ts): `app/api/projects/[projectId]/route.ts`

### Canvas collaboration

- [Canvas room](https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/canvas/canvas-room.tsx): `components/editor/canvas/canvas-room.tsx`
- [Canvas editor](https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/canvas/canvas-editor.tsx): `components/editor/canvas/canvas-editor.tsx`
- [Canvas autosave](https://github.com/dee-nwanjah/ghost-ai/blob/main/hooks/use-canvas-autosave.ts): `hooks/use-canvas-autosave.ts`
- [Canvas persistence API](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/canvas/route.ts): `app/api/projects/[projectId]/canvas/route.ts`
- **Liveblocks service**
- [Room authorization](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/liveblocks-auth/route.ts): `app/api/liveblocks-auth/route.ts`
- [Collaborator sharing](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/collaborators/route.ts): `app/api/projects/[projectId]/collaborators/route.ts`
- [Sharing rules](https://github.com/dee-nwanjah/ghost-ai/blob/main/lib/project-collaborators.ts): `lib/project-collaborators.ts`

### AI planning

- [AI prompt panel](https://github.com/dee-nwanjah/ghost-ai/blob/main/components/editor/ai-sidebar.tsx): `components/editor/ai-sidebar.tsx`
- [Design task API](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/ai/design/route.ts): `app/api/ai/design/route.ts`
- [Architecture agent](https://github.com/dee-nwanjah/ghost-ai/blob/main/trigger/design-agent.ts): `trigger/design-agent.ts`
- **Trigger.dev**
- **Gemini model**

### Specifications

- [Spec task API](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/ai/spec/route.ts): `app/api/ai/spec/route.ts`
- [Specification generator](https://github.com/dee-nwanjah/ghost-ai/blob/main/trigger/generate-spec.ts): `trigger/generate-spec.ts`
- [Spec management API](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/route.ts): `app/api/projects/[projectId]/specs/route.ts`
- [Spec detail API](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/%5BspecId%5D/route.ts): `app/api/projects/[projectId]/specs/[specId]/route.ts`
- [Spec download](https://github.com/dee-nwanjah/ghost-ai/blob/main/app/api/projects/%5BprojectId%5D/specs/%5BspecId%5D/download/route.ts): `app/api/projects/[projectId]/specs/[specId]/download/route.ts`
- **Markdown files**

### Access and storage

- [Project access](https://github.com/dee-nwanjah/ghost-ai/blob/main/lib/project-access.ts): `lib/project-access.ts`
- **PostgreSQL**
- [Prisma client](https://github.com/dee-nwanjah/ghost-ai/blob/main/lib/prisma.ts): `lib/prisma.ts`
- **Clerk identity**

### Other components

- **Team member**

## Connections

- Team member → Project browser: opens projects
- Project browser → Project actions: invokes actions (evidence: `components/editor/editor-home-client.tsx`)
- Project actions → Project API: creates project (evidence: `hooks/use-project-actions.ts`)
- Project API → Prisma client: persists project (evidence: `app/api/projects/route.ts`)
- Prisma client → PostgreSQL: queries
- Project actions → Project operations: renames or deletes (evidence: `hooks/use-project-actions.ts`)
- Team member → Editor workspace: enters workspace
- Editor workspace → Canvas room: renders (evidence: `components/editor/editor-workspace-client.tsx`)
- Canvas room → Canvas editor: renders (evidence: `components/editor/canvas/canvas-room.tsx`)
- Editor workspace → AI prompt panel: renders (evidence: `components/editor/editor-workspace-client.tsx`)
- Canvas room → Canvas autosave: uses (evidence: `components/editor/canvas/canvas-room.tsx`)
- Canvas autosave → Canvas persistence API: saves canvas
- Canvas persistence API → Project access: checks access (evidence: `app/api/projects/[projectId]/canvas/route.ts`)
- Canvas persistence API → Prisma client: reads or writes (evidence: `app/api/projects/[projectId]/canvas/route.ts`)
- Editor workspace → Room authorization: requests room auth
- Room authorization → Project access: validates access (evidence: `app/api/liveblocks-auth/route.ts`)
- Room authorization → Liveblocks service: authorizes room (evidence: `app/api/liveblocks-auth/route.ts`)
- Canvas editor → Liveblocks service: syncs canvas
- Team member → Collaborator sharing: manages sharing
- Collaborator sharing → Sharing rules: uses sharing rules (evidence: `app/api/projects/[projectId]/collaborators/route.ts`)
- Collaborator sharing → Prisma client: stores collaborators (evidence: `app/api/projects/[projectId]/collaborators/route.ts`)
- AI prompt panel → Design task API: submits prompt
- Design task API → Architecture agent: triggers task (evidence: `app/api/ai/design/route.ts`)
- Architecture agent → Trigger.dev: runs job
- Architecture agent → Gemini model: generates diagram
- Architecture agent → Liveblocks service: updates shared canvas (evidence: `trigger/design-agent.ts`)
- Team member → Spec task API: requests specification
- Spec task API → Project access: checks access (evidence: `app/api/ai/spec/route.ts`)
- Spec task API → Specification generator: triggers task (evidence: `app/api/ai/spec/route.ts`)
- Specification generator → Trigger.dev: runs job
- Specification generator → Gemini model: writes specification
- Specification generator → Prisma client: stores metadata (evidence: `trigger/generate-spec.ts`)
- Spec task API → Specification generator: passes graph (evidence: `app/api/ai/spec/route.ts`)
- Spec management API → Project access: checks access (evidence: `app/api/projects/[projectId]/specs/route.ts`)
- Spec management API → Prisma client: manages metadata (evidence: `app/api/projects/[projectId]/specs/route.ts`)
- Spec detail API → Project access: checks access (evidence: `app/api/projects/[projectId]/specs/[specId]/route.ts`)
- Spec detail API → Prisma client: manages metadata (evidence: `app/api/projects/[projectId]/specs/[specId]/route.ts`)
- Spec download → Markdown files: reads Markdown
- Project access → Clerk identity: gets identity (evidence: `lib/project-access.ts`)
- Project access → Prisma client: checks membership (evidence: `lib/project-access.ts`)
- Prisma client → PostgreSQL: persists records