# drex-sayan/northstar architecture

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

- Interactive diagram: https://gitdiagram.com/drex-sayan/northstar
- Repository: https://github.com/drex-sayan/northstar

## Overview

NorthStar is a browser-based writing workspace that preserves narrative canon and warns authors about continuity conflicts without rewriting their manuscripts. Writers authenticate, manage projects, and submit manuscripts; the backend parses and processes chapters, extracts and resolves narrative entities, checks continuity and chronology, then presents evidence-backed findings and story knowledge in the workspace. The README describes coordinated SQL, semantic-vector, and graph memory, plus character, timeline, and Story Architect capabilities. Production V2 adds versioned processing, durable jobs, canon review, and strict evidence. Several routes and frontend pages are represented by their exact enclosing directories because their implementation was not sampled; some relationships are consequently omitted.

Main entry points: [`backend/app/agents/orchestrator.py`](https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/orchestrator.py) (Narrative orchestrator), [`backend/app/production_v2/pipelines/production_pipeline.py`](https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/pipelines/production_pipeline.py) (Production pipeline), [`backend/app/production_v2/routes/production_router.py`](https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/routes/production_router.py) (Production routes), [`frontend/src/App.jsx`](https://github.com/drex-sayan/northstar/blob/main/frontend/src/App.jsx) (Workspace app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Writing workspace"]
  node_app["Workspace app<br/>[App.jsx]"]
  node_client_api["REST client<br/>[api.js]"]
  node_workspace["Writing workspace<br/>[Workspace.jsx]"]
  node_story_views["Story views"]
  node_production_ui["Production dashboard"]
end

subgraph group_api["API and access"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_routes["Project and story routes"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_narrative["Narrative intelligence"]
  node_parser["Document parser<br/>[document_parser.py]"]
  node_orchestrator["Narrative orchestrator<br/>[orchestrator.py]"]
  node_extraction["Canon extraction"]
  node_continuity["Continuity guardian"]
  node_character["Character intelligence<br/>[character_agent.py]"]
  node_timeline["Timeline analysis<br/>[timeline_agent.py]"]
  node_identity["Identity resolution"]
end

subgraph group_production["Production V2"]
  node_production_routes["Production routes"]
  node_pipeline["Production pipeline"]
  node_jobs["Durable jobs"]
  node_worker["Task worker<br/>[task_worker.py]"]
  node_evidence["Evidence review"]
  node_versions["Version lifecycle"]
  node_vault["Vault keys"]
end

subgraph group_memory["Narrative memory"]
  node_temporal["Temporal memory"]
  node_vector[("Passage retrieval<br/>[vector_service.py]")]
  node_graph["Knowledge graph<br/>[graph_service.py]"]
  node_sql[("Structured canon<br/>[models.py]")]
end

node_writer(("Writer"))

node_writer -->|"uses"| node_app
node_app -->|"routes to"| node_workspace
node_app -->|"routes to"| node_story_views
node_app -->|"routes to"| node_production_ui
node_workspace -.->|"requests"| node_client_api
node_production_ui -.->|"requests"| node_client_api
node_client_api -->|"REST calls"| node_api_app
node_api_app -->|"mounts"| node_routes
node_api_app -->|"mounts"| node_production_routes
node_routes -->|"includes"| node_auth
node_auth -->|"reads and writes"| node_sql
node_routes -.->|"invokes"| node_orchestrator
node_orchestrator -->|"parses"| node_parser
node_orchestrator -->|"extracts canon"| node_extraction
node_orchestrator -->|"checks continuity"| node_continuity
node_orchestrator -->|"analyzes characters"| node_character
node_orchestrator -->|"analyzes timeline"| node_timeline
node_orchestrator -->|"resolves identities"| node_identity
node_continuity -->|"uses"| node_temporal
node_continuity -->|"uses"| node_identity
node_orchestrator -->|"indexes passages"| node_vector
node_orchestrator -->|"stores canon"| node_sql
node_orchestrator -.->|"builds graph"| node_graph
node_production_routes -->|"starts processing"| node_pipeline
node_pipeline -->|"parses documents"| node_parser
node_pipeline -->|"resolves entities"| node_identity
node_pipeline -->|"indexes passages"| node_vector
node_pipeline -->|"checks continuity"| node_continuity
node_pipeline -->|"stores chapters"| node_sql
node_production_routes -->|"retries jobs"| node_jobs
node_worker -->|"runs jobs"| node_jobs
node_worker -->|"executes pipeline"| node_pipeline
node_production_routes -.->|"serves evidence"| node_evidence
node_production_routes -.->|"manages versions"| node_versions
node_pipeline -->|"uses vault keys"| node_vault

click node_app "https://github.com/drex-sayan/northstar/blob/main/frontend/src/App.jsx"
click node_client_api "https://github.com/drex-sayan/northstar/blob/main/frontend/src/services/api.js"
click node_workspace "https://github.com/drex-sayan/northstar/blob/main/frontend/src/pages/Workspace.jsx"
click node_story_views "https://github.com/drex-sayan/northstar/tree/main/frontend/src/pages"
click node_production_ui "https://github.com/drex-sayan/northstar/blob/main/frontend/src/production-v2/pages/ProductionV2Dashboard.jsx"
click node_api_app "https://github.com/drex-sayan/northstar/blob/main/backend/app/main.py"
click node_routes "https://github.com/drex-sayan/northstar/tree/main/backend/app/routes"
click node_auth "https://github.com/drex-sayan/northstar/blob/main/backend/app/routes/auth.py"
click node_production_routes "https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/routes/production_router.py"
click node_parser "https://github.com/drex-sayan/northstar/blob/main/backend/app/services/document_parser.py"
click node_orchestrator "https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/orchestrator.py"
click node_extraction "https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/extraction_agent.py"
click node_continuity "https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/continuity_agent.py"
click node_character "https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/character_agent.py"
click node_timeline "https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/timeline_agent.py"
click node_identity "https://github.com/drex-sayan/northstar/blob/main/backend/app/services/identity_service.py"
click node_temporal "https://github.com/drex-sayan/northstar/blob/main/backend/app/services/temporal_memory_service.py"
click node_vector "https://github.com/drex-sayan/northstar/blob/main/backend/app/services/vector_service.py"
click node_graph "https://github.com/drex-sayan/northstar/blob/main/backend/app/services/graph_service.py"
click node_sql "https://github.com/drex-sayan/northstar/blob/main/backend/app/database/models.py"
click node_pipeline "https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/pipelines/production_pipeline.py"
click node_jobs "https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/services/durable_job_service.py"
click node_worker "https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/workers/task_worker.py"
click node_evidence "https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/services/strict_evidence_service.py"
click node_versions "https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/services/version_activation_service.py"
click node_vault "https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/services/vault_key_management.py"

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_client_api,node_workspace,node_story_views,node_production_ui toneBlue
class node_api_app,node_routes,node_auth toneAmber
class node_parser,node_orchestrator,node_extraction,node_continuity,node_character,node_timeline,node_identity toneMint
class node_production_routes,node_pipeline,node_jobs,node_worker,node_evidence,node_versions,node_vault toneRose
class node_temporal,node_vector,node_graph,node_sql,node_writer toneIndigo
```

## Components

### Writing workspace

- [Workspace app](https://github.com/drex-sayan/northstar/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [REST client](https://github.com/drex-sayan/northstar/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Writing workspace](https://github.com/drex-sayan/northstar/blob/main/frontend/src/pages/Workspace.jsx): `frontend/src/pages/Workspace.jsx`
- [Story views](https://github.com/drex-sayan/northstar/tree/main/frontend/src/pages): `frontend/src/pages`
- [Production dashboard](https://github.com/drex-sayan/northstar/blob/main/frontend/src/production-v2/pages/ProductionV2Dashboard.jsx): `frontend/src/production-v2/pages/ProductionV2Dashboard.jsx`

### API and access

- [FastAPI app](https://github.com/drex-sayan/northstar/blob/main/backend/app/main.py): `backend/app/main.py`
- [Project and story routes](https://github.com/drex-sayan/northstar/tree/main/backend/app/routes): `backend/app/routes`
- [Authentication](https://github.com/drex-sayan/northstar/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`

### Narrative intelligence

- [Document parser](https://github.com/drex-sayan/northstar/blob/main/backend/app/services/document_parser.py): `backend/app/services/document_parser.py`
- [Narrative orchestrator](https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`
- [Canon extraction](https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/extraction_agent.py): `backend/app/agents/extraction_agent.py`
- [Continuity guardian](https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/continuity_agent.py): `backend/app/agents/continuity_agent.py`
- [Character intelligence](https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/character_agent.py): `backend/app/agents/character_agent.py`
- [Timeline analysis](https://github.com/drex-sayan/northstar/blob/main/backend/app/agents/timeline_agent.py): `backend/app/agents/timeline_agent.py`
- [Identity resolution](https://github.com/drex-sayan/northstar/blob/main/backend/app/services/identity_service.py): `backend/app/services/identity_service.py`

### Production V2

- [Production routes](https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/routes/production_router.py): `backend/app/production_v2/routes/production_router.py`
- [Production pipeline](https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/pipelines/production_pipeline.py): `backend/app/production_v2/pipelines/production_pipeline.py`
- [Durable jobs](https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/services/durable_job_service.py): `backend/app/production_v2/services/durable_job_service.py`
- [Task worker](https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/workers/task_worker.py): `backend/app/production_v2/workers/task_worker.py`
- [Evidence review](https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/services/strict_evidence_service.py): `backend/app/production_v2/services/strict_evidence_service.py`
- [Version lifecycle](https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/services/version_activation_service.py): `backend/app/production_v2/services/version_activation_service.py`
- [Vault keys](https://github.com/drex-sayan/northstar/blob/main/backend/app/production_v2/services/vault_key_management.py): `backend/app/production_v2/services/vault_key_management.py`

### Narrative memory

- [Temporal memory](https://github.com/drex-sayan/northstar/blob/main/backend/app/services/temporal_memory_service.py): `backend/app/services/temporal_memory_service.py`
- [Passage retrieval](https://github.com/drex-sayan/northstar/blob/main/backend/app/services/vector_service.py): `backend/app/services/vector_service.py`
- [Knowledge graph](https://github.com/drex-sayan/northstar/blob/main/backend/app/services/graph_service.py): `backend/app/services/graph_service.py`
- [Structured canon](https://github.com/drex-sayan/northstar/blob/main/backend/app/database/models.py): `backend/app/database/models.py`

### Other components

- **Writer**

## Connections

- Writer → Workspace app: uses (evidence: `README.md`)
- Workspace app → Writing workspace: routes to (evidence: `frontend/src/App.jsx`)
- Workspace app → Story views: routes to (evidence: `frontend/src/App.jsx`)
- Workspace app → Production dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Writing workspace → REST client: requests
- Production dashboard → REST client: requests
- REST client → FastAPI app: REST calls (evidence: `README.md`)
- FastAPI app → Project and story routes: mounts (evidence: `backend/app/main.py`)
- FastAPI app → Production routes: mounts (evidence: `backend/app/main.py`)
- Project and story routes → Authentication: includes (evidence: `backend/app/main.py`)
- Authentication → Structured canon: reads and writes (evidence: `backend/app/routes/auth.py`)
- Project and story routes → Narrative orchestrator: invokes
- Narrative orchestrator → Document parser: parses (evidence: `backend/app/agents/orchestrator.py`)
- Narrative orchestrator → Canon extraction: extracts canon (evidence: `backend/app/agents/orchestrator.py`)
- Narrative orchestrator → Continuity guardian: checks continuity (evidence: `backend/app/agents/orchestrator.py`)
- Narrative orchestrator → Character intelligence: analyzes characters (evidence: `backend/app/agents/orchestrator.py`)
- Narrative orchestrator → Timeline analysis: analyzes timeline (evidence: `backend/app/agents/orchestrator.py`)
- Narrative orchestrator → Identity resolution: resolves identities (evidence: `backend/app/agents/orchestrator.py`)
- Continuity guardian → Temporal memory: uses (evidence: `backend/app/agents/continuity_agent.py`)
- Continuity guardian → Identity resolution: uses (evidence: `backend/app/agents/continuity_agent.py`)
- Narrative orchestrator → Passage retrieval: indexes passages (evidence: `backend/app/agents/orchestrator.py`)
- Narrative orchestrator → Structured canon: stores canon (evidence: `backend/app/agents/orchestrator.py`)
- Narrative orchestrator → Knowledge graph: builds graph
- Production routes → Production pipeline: starts processing (evidence: `backend/app/production_v2/routes/production_router.py`)
- Production pipeline → Document parser: parses documents (evidence: `backend/app/production_v2/pipelines/production_pipeline.py`)
- Production pipeline → Identity resolution: resolves entities (evidence: `backend/app/production_v2/pipelines/production_pipeline.py`)
- Production pipeline → Passage retrieval: indexes passages (evidence: `backend/app/production_v2/pipelines/production_pipeline.py`)
- Production pipeline → Continuity guardian: checks continuity (evidence: `backend/app/production_v2/pipelines/production_pipeline.py`)
- Production pipeline → Structured canon: stores chapters (evidence: `backend/app/production_v2/pipelines/production_pipeline.py`)
- Production routes → Durable jobs: retries jobs (evidence: `backend/app/production_v2/routes/production_router.py`)
- Task worker → Durable jobs: runs jobs (evidence: `backend/app/production_v2/workers/task_worker.py`)
- Task worker → Production pipeline: executes pipeline (evidence: `backend/app/production_v2/workers/task_worker.py`)
- Production routes → Evidence review: serves evidence (evidence: `backend/app/production_v2/routes/production_router.py`)
- Production routes → Version lifecycle: manages versions (evidence: `backend/app/production_v2/routes/production_router.py`)
- Production pipeline → Vault keys: uses vault keys (evidence: `backend/app/production_v2/pipelines/production_pipeline.py`)
