How drex-sayan/northstar works
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: orchestrator.py Narrative orchestrator · production_pipeline.py Production pipeline · production_router.py Production routes · App.jsx Workspace app
Components 27
Writing workspace
- Workspace app
frontend/src/App.jsx - REST client
frontend/src/services/api.js - Writing workspace
frontend/src/pages/Workspace.jsx - Story views
frontend/src/pages - Production dashboard
frontend/src/production-v2/pages/ProductionV2Dashboard.jsx
API and access
- FastAPI app
backend/app/main.py - Project and story routes
backend/app/routes - Authentication
backend/app/routes/auth.py
Narrative intelligence
- Document parser
backend/app/services/document_parser.py - Narrative orchestrator
backend/app/agents/orchestrator.py - Canon extraction
backend/app/agents/extraction_agent.py - Continuity guardian
backend/app/agents/continuity_agent.py - Character intelligence
backend/app/agents/character_agent.py - Timeline analysis
backend/app/agents/timeline_agent.py - Identity resolution
backend/app/services/identity_service.py
Production V2
- Production routes
backend/app/production_v2/routes/production_router.py - Production pipeline
backend/app/production_v2/pipelines/production_pipeline.py - Durable jobs
backend/app/production_v2/services/durable_job_service.py - Task worker
backend/app/production_v2/workers/task_worker.py - Evidence review
backend/app/production_v2/services/strict_evidence_service.py - Version lifecycle
backend/app/production_v2/services/version_activation_service.py - Vault keys
backend/app/production_v2/services/vault_key_management.py
Narrative memory
- Temporal memory
backend/app/services/temporal_memory_service.py - Passage retrieval
backend/app/services/vector_service.py - Knowledge graph
backend/app/services/graph_service.py - Structured canon
backend/app/database/models.py
Other components
- Writer
Connections 35
- Writer → Workspace app: uses
README.md - Workspace app → Writing workspace: routes to
frontend/src/App.jsx - Workspace app → Story views: routes to
frontend/src/App.jsx - Workspace app → Production dashboard: routes to
frontend/src/App.jsx - Writing workspace → REST client: requests
- Production dashboard → REST client: requests
- REST client → FastAPI app: REST calls
README.md - FastAPI app → Project and story routes: mounts
backend/app/main.py - FastAPI app → Production routes: mounts
backend/app/main.py - Project and story routes → Authentication: includes
backend/app/main.py - Authentication → Structured canon: reads and writes
backend/app/routes/auth.py - Project and story routes → Narrative orchestrator: invokes
- Narrative orchestrator → Document parser: parses
backend/app/agents/orchestrator.py - Narrative orchestrator → Canon extraction: extracts canon
backend/app/agents/orchestrator.py - Narrative orchestrator → Continuity guardian: checks continuity
backend/app/agents/orchestrator.py - Narrative orchestrator → Character intelligence: analyzes characters
backend/app/agents/orchestrator.py - Narrative orchestrator → Timeline analysis: analyzes timeline
backend/app/agents/orchestrator.py - Narrative orchestrator → Identity resolution: resolves identities
backend/app/agents/orchestrator.py - Continuity guardian → Temporal memory: uses
backend/app/agents/continuity_agent.py - Continuity guardian → Identity resolution: uses
backend/app/agents/continuity_agent.py - Narrative orchestrator → Passage retrieval: indexes passages
backend/app/agents/orchestrator.py - Narrative orchestrator → Structured canon: stores canon
backend/app/agents/orchestrator.py - Narrative orchestrator → Knowledge graph: builds graph
- Production routes → Production pipeline: starts processing
backend/app/production_v2/routes/production_router.py - Production pipeline → Document parser: parses documents
backend/app/production_v2/pipelines/production_pipeline.py - Production pipeline → Identity resolution: resolves entities
backend/app/production_v2/pipelines/production_pipeline.py - Production pipeline → Passage retrieval: indexes passages
backend/app/production_v2/pipelines/production_pipeline.py - Production pipeline → Continuity guardian: checks continuity
backend/app/production_v2/pipelines/production_pipeline.py - Production pipeline → Structured canon: stores chapters
backend/app/production_v2/pipelines/production_pipeline.py - Production routes → Durable jobs: retries jobs
backend/app/production_v2/routes/production_router.py - Task worker → Durable jobs: runs jobs
backend/app/production_v2/workers/task_worker.py - Task worker → Production pipeline: executes pipeline
backend/app/production_v2/workers/task_worker.py - Production routes → Evidence review: serves evidence
backend/app/production_v2/routes/production_router.py - Production routes → Version lifecycle: manages versions
backend/app/production_v2/routes/production_router.py - Production pipeline → Vault keys: uses vault keys
backend/app/production_v2/pipelines/production_pipeline.py