# shahid0324-git/chronicles architecture

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

- Interactive diagram: https://gitdiagram.com/shahid0324-git/chronicles
- Repository: https://github.com/shahid0324-git/chronicles

## Overview

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: [`apps/web/src/features/atlas/AtlasExperience.tsx`](https://github.com/shahid0324-git/chronicles/blob/main/apps/web/src/features/atlas/AtlasExperience.tsx) (Atlas experience), [`services/intelligence/src/main.py`](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/main.py) (API application), [`services/intelligence/src/orchestration/research_workflow.py`](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/orchestration/research_workflow.py) (Research orchestration), [`services/intelligence/src/infrastructure/persistence/research_repository.py`](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/persistence/research_repository.py) (Research repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Atlas frontend"]
  node_atlas["Atlas experience"]
  node_universe["Universe loading"]
  node_graphview["Graph rendering<br/>[GraphCanvas.tsx]"]
  node_exploration["Exploration state<br/>[exploration.ts]"]
  node_narrativeui["Narrative reader"]
  node_researchui["Research controls"]
  node_proxy["Server forwarding"]
end

subgraph group_api["API and domain"]
  node_entry["API application<br/>[main.py]"]
  node_researchapi["Research API<br/>[research.py]"]
  node_domain["Graph domain<br/>[__init__.py]"]
  node_narrative["Narrative and arcs"]
end

subgraph group_research["Research workflow"]
  node_worker["Research worker<br/>[research_worker.py]"]
  node_workflow["Research orchestration"]
  node_pipeline["Knowledge pipeline"]
  node_retrieval["Evidence retrieval<br/>[retrieval.py]"]
  node_inference["Inference policy<br/>[inference.py]"]
  node_provider["Model adapters<br/>[inference.py]"]
  node_promotion["Graph publication<br/>[promotion.py]"]
end

subgraph group_storage["Persistence and models"]
  node_researchstore["Research repository"]
  node_knowledgestore["Knowledge repository"]
  node_models["Research tables<br/>[research.py]"]
  node_knowledge["Knowledge tables<br/>[knowledge.py]"]
end

node_user(("Atlas reader"))
node_webactor{{"FastAPI service"}}
node_database[("PostgreSQL")]
node_sources(("Permitted sources"))
node_ollama{{"Ollama"}}
node_groq{{"Groq"}}

node_user -->|"explores"| node_atlas
node_atlas -.->|"loads universe"| node_universe
node_universe -->|"requests data"| node_proxy
node_proxy -->|"forwards requests"| node_entry
node_atlas -.->|"renders atlas"| node_graphview
node_atlas -->|"updates state"| node_exploration
node_user -->|"starts research"| node_researchui
node_researchui -->|"polls status"| node_proxy
node_entry -->|"routes research"| node_researchapi
node_entry -->|"serves graph reads"| node_database
node_researchapi -.->|"accesses jobs"| node_researchstore
node_worker -->|"runs workflow"| node_workflow
node_workflow -->|"uses pipeline"| node_pipeline
node_workflow -.->|"retrieves evidence"| node_retrieval
node_workflow -.->|"requests inference"| node_inference
node_inference -->|"selects provider"| node_provider
node_provider -.->|"calls model"| node_ollama
node_provider -.->|"optionally calls"| node_groq
node_pipeline -->|"publishes findings"| node_promotion
node_worker -.->|"claims jobs"| node_researchstore
node_researchstore -->|"persists research"| node_models
node_knowledgestore -->|"persists graph"| node_knowledge
node_researchstore -.->|"reads and writes"| node_database
node_knowledgestore -.->|"reads and writes"| node_database
node_retrieval -->|"searches evidence"| node_sources
node_narrativeui -.->|"requests narrative"| node_proxy
node_entry -.->|"provides narratives"| node_narrative
node_narrative -.->|"reads published data"| node_database
node_promotion -->|"records publication"| node_knowledgestore
node_domain -->|"defines graph records"| node_knowledgestore

click node_atlas "https://github.com/shahid0324-git/chronicles/blob/main/apps/web/src/features/atlas/AtlasExperience.tsx"
click node_universe "https://github.com/shahid0324-git/chronicles/blob/main/apps/web/src/features/universe/useUniverseLoader.ts"
click node_graphview "https://github.com/shahid0324-git/chronicles/blob/main/apps/web/src/features/graph/GraphCanvas.tsx"
click node_exploration "https://github.com/shahid0324-git/chronicles/blob/main/apps/web/src/stores/exploration.ts"
click node_narrativeui "https://github.com/shahid0324-git/chronicles/tree/main/apps/web/src/features/narrative"
click node_researchui "https://github.com/shahid0324-git/chronicles/tree/main/apps/web/src/features/research"
click node_proxy "https://github.com/shahid0324-git/chronicles/tree/main/apps/web/src/app/api/atlas"
click node_entry "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/main.py"
click node_researchapi "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/presentation/api/research.py"
click node_domain "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/domain/entities/__init__.py"
click node_narrative "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/application/arc_intelligence.py"
click node_worker "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/research_worker.py"
click node_workflow "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/orchestration/research_workflow.py"
click node_pipeline "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/orchestration/knowledge_pipeline.py"
click node_retrieval "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/application/retrieval.py"
click node_inference "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/application/inference.py"
click node_provider "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/inference.py"
click node_promotion "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/application/promotion.py"
click node_researchstore "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/persistence/research_repository.py"
click node_knowledgestore "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/persistence/knowledge_repository.py"
click node_models "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/persistence/models/research.py"
click node_knowledge "https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/persistence/models/knowledge.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_atlas,node_universe,node_graphview,node_exploration,node_narrativeui,node_researchui,node_proxy toneBlue
class node_entry,node_researchapi,node_domain,node_narrative,node_database toneAmber
class node_worker,node_workflow,node_pipeline,node_retrieval,node_inference,node_provider,node_promotion,node_webactor toneMint
class node_researchstore,node_knowledgestore,node_models,node_knowledge toneRose
class node_user,node_sources,node_ollama,node_groq toneIndigo
```

## Components

### Atlas frontend

- [Atlas experience](https://github.com/shahid0324-git/chronicles/blob/main/apps/web/src/features/atlas/AtlasExperience.tsx): `apps/web/src/features/atlas/AtlasExperience.tsx`
- [Universe loading](https://github.com/shahid0324-git/chronicles/blob/main/apps/web/src/features/universe/useUniverseLoader.ts): `apps/web/src/features/universe/useUniverseLoader.ts`
- [Graph rendering](https://github.com/shahid0324-git/chronicles/blob/main/apps/web/src/features/graph/GraphCanvas.tsx): `apps/web/src/features/graph/GraphCanvas.tsx`
- [Exploration state](https://github.com/shahid0324-git/chronicles/blob/main/apps/web/src/stores/exploration.ts): `apps/web/src/stores/exploration.ts`
- [Narrative reader](https://github.com/shahid0324-git/chronicles/tree/main/apps/web/src/features/narrative): `apps/web/src/features/narrative`
- [Research controls](https://github.com/shahid0324-git/chronicles/tree/main/apps/web/src/features/research): `apps/web/src/features/research`
- [Server forwarding](https://github.com/shahid0324-git/chronicles/tree/main/apps/web/src/app/api/atlas): `apps/web/src/app/api/atlas`

### API and domain

- [API application](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/main.py): `services/intelligence/src/main.py`
- [Research API](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/presentation/api/research.py): `services/intelligence/src/presentation/api/research.py`
- [Graph domain](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/domain/entities/__init__.py): `services/intelligence/src/domain/entities/__init__.py`
- [Narrative and arcs](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/application/arc_intelligence.py): `services/intelligence/src/application/arc_intelligence.py`

### Research workflow

- [Research worker](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/research_worker.py): `services/intelligence/src/research_worker.py`
- [Research orchestration](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/orchestration/research_workflow.py): `services/intelligence/src/orchestration/research_workflow.py`
- [Knowledge pipeline](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/orchestration/knowledge_pipeline.py): `services/intelligence/src/orchestration/knowledge_pipeline.py`
- [Evidence retrieval](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/application/retrieval.py): `services/intelligence/src/application/retrieval.py`
- [Inference policy](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/application/inference.py): `services/intelligence/src/application/inference.py`
- [Model adapters](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/inference.py): `services/intelligence/src/infrastructure/inference.py`
- [Graph publication](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/application/promotion.py): `services/intelligence/src/application/promotion.py`

### Persistence and models

- [Research repository](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/persistence/research_repository.py): `services/intelligence/src/infrastructure/persistence/research_repository.py`
- [Knowledge repository](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/persistence/knowledge_repository.py): `services/intelligence/src/infrastructure/persistence/knowledge_repository.py`
- [Research tables](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/persistence/models/research.py): `services/intelligence/src/infrastructure/persistence/models/research.py`
- [Knowledge tables](https://github.com/shahid0324-git/chronicles/blob/main/services/intelligence/src/infrastructure/persistence/models/knowledge.py): `services/intelligence/src/infrastructure/persistence/models/knowledge.py`

### Other components

- **Atlas reader**
- **FastAPI service**
- **PostgreSQL**
- **Permitted sources**
- **Ollama**
- **Groq**

## Connections

- Atlas reader → Atlas experience: explores (evidence: `README.md`)
- Atlas experience → Universe loading: loads universe
- Universe loading → Server forwarding: requests data (evidence: `README.md`)
- Server forwarding → API application: forwards requests (evidence: `README.md`)
- Atlas experience → Graph rendering: renders atlas
- Atlas experience → Exploration state: updates state (evidence: `README.md`)
- Atlas reader → Research controls: starts research (evidence: `README.md`)
- Research controls → Server forwarding: polls status (evidence: `README.md`)
- API application → Research API: routes research (evidence: `services/intelligence/src/main.py`)
- API application → PostgreSQL: serves graph reads (evidence: `README.md`)
- Research API → Research repository: accesses jobs (evidence: `services/intelligence/src/presentation/api/research.py`)
- Research worker → Research orchestration: runs workflow (evidence: `services/intelligence/src/research_worker.py`)
- Research orchestration → Knowledge pipeline: uses pipeline (evidence: `services/intelligence/src/orchestration/knowledge_pipeline.py`)
- Research orchestration → Evidence retrieval: retrieves evidence (evidence: `services/intelligence/src/orchestration/research_workflow.py`)
- Research orchestration → Inference policy: requests inference (evidence: `services/intelligence/src/orchestration/research_workflow.py`)
- Inference policy → Model adapters: selects provider (evidence: `services/intelligence/src/infrastructure/inference.py`)
- Model adapters → Ollama: calls model
- Model adapters → Groq: optionally calls (evidence: `README.md`)
- Knowledge pipeline → Graph publication: publishes findings (evidence: `services/intelligence/src/orchestration/knowledge_pipeline.py`)
- Research worker → Research repository: claims jobs (evidence: `services/intelligence/src/research_worker.py`)
- Research repository → Research tables: persists research (evidence: `services/intelligence/src/infrastructure/persistence/research_repository.py`)
- Knowledge repository → Knowledge tables: persists graph (evidence: `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 (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 (evidence: `services/intelligence/src/infrastructure/persistence/knowledge_repository.py`)
