# somunaexe/bulwriter architecture

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

- Interactive diagram: https://gitdiagram.com/somunaexe/bulwriter
- Repository: https://github.com/somunaexe/bulwriter

## Overview

Bulwriter is a collaborative screenwriting platform: writers open a project and script, edit a structured screenplay together in real time, and save named snapshots or branches for history and comparison. The editor also supports screenplay import/export and production-planning features such as breakdown, scheduling, casting, budgeting, scouting, shot lists, and press kits. The backend router exposes these domain APIs and the WebSocket sync hub; source excerpts confirm key wiring, while several feature implementations are only represented by the tree and API index.

Main entry points: [`backend/internal/api/api.go`](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/api/api.go) (REST API), [`frontend/src/app/components/editor/editor.component.ts`](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/editor/editor.component.ts) (Script editor), [`frontend/src/app/services/sync.service.ts`](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/services/sync.service.ts) (Collab session), [`frontend/src/app/app.routes.ts`](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/app.routes.ts) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Angular client"]
  node_routes["App routes<br/>[app.routes.ts]"]
  node_dashboard["Project dashboard"]
  node_projectui["Project workspace"]
end

subgraph group_authoring["Screenplay authoring"]
  node_editorui["Script editor"]
  node_syncclient["Collab session<br/>[sync.service.ts]"]
  node_screenplay["Screenplay model"]
  node_fountain["Fountain interchange<br/>[fountain-export.ts]"]
  node_vcui["Branch history UI"]
  node_diffui["Draft comparison"]
  node_vcclient["Version control client"]
end

subgraph group_backend["Backend services"]
  node_api["REST API<br/>[api.go]"]
  node_hub["WebSocket hub<br/>[hub.go]"]
  node_snapshots[("Snapshots and branches<br/>[snapshot.go]")]
end

subgraph group_production["Film production"]
  node_breakdown[("Scene breakdown<br/>[breakdown.go]")]
  node_schedule[("Production schedule<br/>[schedule.go]")]
  node_casting[("Casting<br/>[casting.go]")]
  node_budget[("Budget<br/>[budget.go]")]
  node_scouting[("Location scouting<br/>[scouting.go]")]
  node_shotlist[("Shot list<br/>[shotlist.go]")]
  node_presskit[("Press kit<br/>[presskit.go]")]
  node_productionui["Production tools UI"]
end

subgraph group_platform["Projects and access"]
  node_projects[("Project and script data<br/>[project.go]")]
  node_membership[("Membership and invites<br/>[membership.go]")]
  node_auth["Identity client<br/>[clerk.service.ts]"]
end

node_writer(("Writer"))

node_writer -->|"opens workspace"| node_routes
node_routes -->|"routes to"| node_dashboard
node_routes -->|"routes to"| node_projectui
node_routes -->|"routes to"| node_editorui
node_dashboard -->|"opens project"| node_projectui
node_projectui -->|"opens script"| node_editorui
node_editorui -->|"starts session"| node_syncclient
node_syncclient -.->|"syncs updates"| node_hub
node_hub -.->|"broadcasts updates"| node_syncclient
node_syncclient -->|"builds editor"| node_screenplay
node_syncclient -->|"exports text"| node_fountain
node_editorui -->|"imports and exports"| node_fountain
node_editorui -->|"saves drafts"| node_vcclient
node_editorui -->|"shows branches"| node_vcui
node_editorui -->|"shows diffs"| node_diffui
node_vcui -.->|"requests history"| node_vcclient
node_diffui -.->|"requests comparison"| node_vcclient
node_vcclient -.->|"calls REST"| node_api
node_api -->|"reads and writes"| node_snapshots
node_api -.->|"routes WebSocket"| node_hub
node_api -->|"reads and writes"| node_projects
node_api -->|"checks access"| node_membership
node_auth -.->|"authenticates"| node_writer
node_editorui -->|"opens production tools"| node_productionui
node_api -->|"serves breakdown"| node_breakdown
node_api -.->|"serves schedule"| node_schedule
node_api -->|"serves casting"| node_casting
node_api -->|"serves budgets"| node_budget
node_api -->|"serves scouting"| node_scouting
node_api -->|"serves shot lists"| node_shotlist
node_api -->|"serves press kits"| node_presskit

click node_routes "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/app.routes.ts"
click node_dashboard "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/dashboard/dashboard.component.ts"
click node_projectui "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/project/project.component.ts"
click node_editorui "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/editor/editor.component.ts"
click node_syncclient "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/services/sync.service.ts"
click node_screenplay "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/editor/screenplay-schema.ts"
click node_fountain "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/editor/fountain-export.ts"
click node_vcui "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/branch-panel/branch-panel.component.ts"
click node_diffui "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/diff-viewer/diff-viewer.component.ts"
click node_vcclient "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/services/version-control.service.ts"
click node_api "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/api/api.go"
click node_hub "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/hub/hub.go"
click node_snapshots "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/snapshot/snapshot.go"
click node_projects "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/project/project.go"
click node_membership "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/membership/membership.go"
click node_auth "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/services/clerk.service.ts"
click node_breakdown "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/breakdown/breakdown.go"
click node_schedule "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/schedule/schedule.go"
click node_casting "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/casting/casting.go"
click node_budget "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/budget/budget.go"
click node_scouting "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/scouting/scouting.go"
click node_shotlist "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/shotlist/shotlist.go"
click node_presskit "https://github.com/somunaexe/bulwriter/blob/main/backend/internal/presskit/presskit.go"
click node_productionui "https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/stripboard/stripboard.component.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_routes,node_dashboard,node_projectui toneBlue
class node_editorui,node_syncclient,node_screenplay,node_fountain,node_vcui,node_diffui,node_vcclient toneAmber
class node_api,node_hub,node_snapshots toneMint
class node_breakdown,node_schedule,node_casting,node_budget,node_scouting,node_shotlist,node_presskit,node_productionui toneRose
class node_projects,node_membership,node_auth,node_writer toneIndigo
```

## Components

### Angular client

- [App routes](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/app.routes.ts): `frontend/src/app/app.routes.ts`
- [Project dashboard](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/dashboard/dashboard.component.ts): `frontend/src/app/components/dashboard/dashboard.component.ts`
- [Project workspace](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/project/project.component.ts): `frontend/src/app/components/project/project.component.ts`

### Screenplay authoring

- [Script editor](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/editor/editor.component.ts): `frontend/src/app/components/editor/editor.component.ts`
- [Collab session](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/services/sync.service.ts): `frontend/src/app/services/sync.service.ts`
- [Screenplay model](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/editor/screenplay-schema.ts): `frontend/src/app/editor/screenplay-schema.ts`
- [Fountain interchange](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/editor/fountain-export.ts): `frontend/src/app/editor/fountain-export.ts`
- [Branch history UI](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/branch-panel/branch-panel.component.ts): `frontend/src/app/components/branch-panel/branch-panel.component.ts`
- [Draft comparison](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/diff-viewer/diff-viewer.component.ts): `frontend/src/app/components/diff-viewer/diff-viewer.component.ts`
- [Version control client](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/services/version-control.service.ts): `frontend/src/app/services/version-control.service.ts`

### Backend services

- [REST API](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/api/api.go): `backend/internal/api/api.go`
- [WebSocket hub](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/hub/hub.go): `backend/internal/hub/hub.go`
- [Snapshots and branches](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/snapshot/snapshot.go): `backend/internal/snapshot/snapshot.go`

### Film production

- [Scene breakdown](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/breakdown/breakdown.go): `backend/internal/breakdown/breakdown.go`
- [Production schedule](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/schedule/schedule.go): `backend/internal/schedule/schedule.go`
- [Casting](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/casting/casting.go): `backend/internal/casting/casting.go`
- [Budget](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/budget/budget.go): `backend/internal/budget/budget.go`
- [Location scouting](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/scouting/scouting.go): `backend/internal/scouting/scouting.go`
- [Shot list](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/shotlist/shotlist.go): `backend/internal/shotlist/shotlist.go`
- [Press kit](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/presskit/presskit.go): `backend/internal/presskit/presskit.go`
- [Production tools UI](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/components/stripboard/stripboard.component.ts): `frontend/src/app/components/stripboard/stripboard.component.ts`

### Projects and access

- [Project and script data](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/project/project.go): `backend/internal/project/project.go`
- [Membership and invites](https://github.com/somunaexe/bulwriter/blob/main/backend/internal/membership/membership.go): `backend/internal/membership/membership.go`
- [Identity client](https://github.com/somunaexe/bulwriter/blob/main/frontend/src/app/services/clerk.service.ts): `frontend/src/app/services/clerk.service.ts`

### Other components

- **Writer**

## Connections

- Writer → App routes: opens workspace (evidence: `frontend/src/app/app.routes.ts`)
- App routes → Project dashboard: routes to (evidence: `frontend/src/app/app.routes.ts`)
- App routes → Project workspace: routes to (evidence: `frontend/src/app/app.routes.ts`)
- App routes → Script editor: routes to (evidence: `frontend/src/app/app.routes.ts`)
- Project dashboard → Project workspace: opens project (evidence: `frontend/src/app/components/dashboard/dashboard.component.ts`)
- Project workspace → Script editor: opens script (evidence: `frontend/src/app/components/project/project.component.ts`)
- Script editor → Collab session: starts session (evidence: `frontend/src/app/components/editor/editor.component.ts`)
- Collab session → WebSocket hub: syncs updates (evidence: `README.md`)
- WebSocket hub → Collab session: broadcasts updates (evidence: `README.md`)
- Collab session → Screenplay model: builds editor (evidence: `frontend/src/app/services/sync.service.ts`)
- Collab session → Fountain interchange: exports text (evidence: `frontend/src/app/services/sync.service.ts`)
- Script editor → Fountain interchange: imports and exports (evidence: `frontend/src/app/components/editor/editor.component.ts`)
- Script editor → Version control client: saves drafts (evidence: `frontend/src/app/components/editor/editor.component.ts`)
- Script editor → Branch history UI: shows branches (evidence: `frontend/src/app/components/editor/editor.component.ts`)
- Script editor → Draft comparison: shows diffs (evidence: `frontend/src/app/components/editor/editor.component.ts`)
- Branch history UI → Version control client: requests history
- Draft comparison → Version control client: requests comparison
- Version control client → REST API: calls REST (evidence: `README.md`)
- REST API → Snapshots and branches: reads and writes (evidence: `backend/internal/api/api.go`)
- REST API → WebSocket hub: routes WebSocket (evidence: `README.md`)
- REST API → Project and script data: reads and writes (evidence: `backend/internal/api/api.go`)
- REST API → Membership and invites: checks access (evidence: `backend/internal/api/api.go`)
- Identity client → Writer: authenticates
- Script editor → Production tools UI: opens production tools (evidence: `frontend/src/app/components/editor/editor.component.ts`)
- REST API → Scene breakdown: serves breakdown (evidence: `backend/internal/api/api.go`)
- REST API → Production schedule: serves schedule (evidence: `backend/internal/api/api.go`)
- REST API → Casting: serves casting (evidence: `backend/internal/api/api.go`)
- REST API → Budget: serves budgets (evidence: `backend/internal/api/api.go`)
- REST API → Location scouting: serves scouting (evidence: `backend/internal/api/api.go`)
- REST API → Shot list: serves shot lists (evidence: `backend/internal/api/api.go`)
- REST API → Press kit: serves press kits (evidence: `backend/internal/api/api.go`)
