How shahid0324-git/chronicles works
Chronicles is a local-first fictional-universe atlas backed by a research and knowledge-publication service. Users browse universes in the web atlas; the frontend requests graph and narrative data from FastAPI, which reads PostgreSQL. A separate research worker can gather source evidence, resolve identities and relationships, and publish accepted findings for later browsing. The graph preserves the documented research, retrieval, narrative, and arc capabilities. Several frontend and backend subsystems are represented by their existing directories because their implementation files were not sampled; those links are included only where README documentation supports them.
Main entry points: AtlasExperience.tsx Atlas experience · main.py API application · research_workflow.py Research orchestration · research_repository.py Research repository
Components 28
Atlas frontend
- Atlas experience
apps/web/src/features/atlas/AtlasExperience.tsx - Universe loading
apps/web/src/features/universe/useUniverseLoader.ts - Graph rendering
apps/web/src/features/graph/GraphCanvas.tsx - Exploration state
apps/web/src/stores/exploration.ts - Narrative reader
apps/web/src/features/narrative - Research controls
apps/web/src/features/research - Server forwarding
apps/web/src/app/api/atlas
API and domain
- API application
services/intelligence/src/main.py - Research API
services/intelligence/src/presentation/api/research.py - Graph domain
services/intelligence/src/domain/entities/__init__.py - Narrative and arcs
services/intelligence/src/application/arc_intelligence.py
Research workflow
- Research worker
services/intelligence/src/research_worker.py - Research orchestration
services/intelligence/src/orchestration/research_workflow.py - Knowledge pipeline
services/intelligence/src/orchestration/knowledge_pipeline.py - Evidence retrieval
services/intelligence/src/application/retrieval.py - Inference policy
services/intelligence/src/application/inference.py - Model adapters
services/intelligence/src/infrastructure/inference.py - Graph publication
services/intelligence/src/application/promotion.py
Persistence and models
- Research repository
services/intelligence/src/infrastructure/persistence/research_repository.py - Knowledge repository
services/intelligence/src/infrastructure/persistence/knowledge_repository.py - Research tables
services/intelligence/src/infrastructure/persistence/models/research.py - Knowledge tables
services/intelligence/src/infrastructure/persistence/models/knowledge.py
Other components
- Atlas reader
- FastAPI service
- PostgreSQL
- Permitted sources
- Ollama
- Groq
Connections 30
- Atlas reader → Atlas experience: explores
README.md - Atlas experience → Universe loading: loads universe
- Universe loading → Server forwarding: requests data
README.md - Server forwarding → API application: forwards requests
README.md - Atlas experience → Graph rendering: renders atlas
- Atlas experience → Exploration state: updates state
README.md - Atlas reader → Research controls: starts research
README.md - Research controls → Server forwarding: polls status
README.md - API application → Research API: routes research
services/intelligence/src/main.py - API application → PostgreSQL: serves graph reads
README.md - Research API → Research repository: accesses jobs
services/intelligence/src/presentation/api/research.py - Research worker → Research orchestration: runs workflow
services/intelligence/src/research_worker.py - Research orchestration → Knowledge pipeline: uses pipeline
services/intelligence/src/orchestration/knowledge_pipeline.py - Research orchestration → Evidence retrieval: retrieves evidence
services/intelligence/src/orchestration/research_workflow.py - Research orchestration → Inference policy: requests inference
services/intelligence/src/orchestration/research_workflow.py - Inference policy → Model adapters: selects provider
services/intelligence/src/infrastructure/inference.py - Model adapters → Ollama: calls model
- Model adapters → Groq: optionally calls
README.md - Knowledge pipeline → Graph publication: publishes findings
services/intelligence/src/orchestration/knowledge_pipeline.py - Research worker → Research repository: claims jobs
services/intelligence/src/research_worker.py - Research repository → Research tables: persists research
services/intelligence/src/infrastructure/persistence/research_repository.py - Knowledge repository → Knowledge tables: persists graph
services/intelligence/src/infrastructure/persistence/knowledge_repository.py - Research repository → PostgreSQL: reads and writes
- Knowledge repository → PostgreSQL: reads and writes
- Evidence retrieval → Permitted sources: searches evidence
README.md - Narrative reader → Server forwarding: requests narrative
- API application → Narrative and arcs: provides narratives
- Narrative and arcs → PostgreSQL: reads published data
- Graph publication → Knowledge repository: records publication
- Graph domain → Knowledge repository: defines graph records
services/intelligence/src/infrastructure/persistence/knowledge_repository.py