# surypratapsingh872/chronogenesis-ai architecture

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

- Interactive diagram: https://gitdiagram.com/surypratapsingh872/chronogenesis-ai
- Repository: https://github.com/surypratapsingh872/chronogenesis-ai

## Overview

ChronoGenesis-AI is an experimental platform for causal world modeling, multi-agent analysis, and exploring possible futures. Its principal workflow takes a task through language processing and knowledge retrieval, builds graph and causal context, delegates work to specialist agents, and produces decision, scenario, risk, and report outputs. The README documents those product capabilities; sampled manager and research code confirms several orchestration and analysis calls. Other branches are represented at subsystem level where source is listed but implementation was not sampled, so their internal wiring is not asserted.

Main entry points: [`backend/agents/manager_agent.py`](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/agents/manager_agent.py) (Manager Agent), [`backend/agents/research_agent.py`](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/agents/research_agent.py) (Research Agent), [`backend/services/graph/graph_builder.py`](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/graph/graph_builder.py) (Knowledge Graph), [`backend/services/rag/retriever.py`](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/rag/retriever.py) (RAG Retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Product Interface"]
  node_api["HTTP API"]
  node_realtime["WebSocket Updates<br/>[routes.py]"]
end

subgraph group_orchestration["Agent Orchestration"]
  node_manager["Manager Agent<br/>[manager_agent.py]"]
  node_nlp["Task NLP<br/>[nlp_pipeline.py]"]
  node_specialists["Specialist Agents"]
  node_research["Research Agent<br/>[research_agent.py]"]
  node_decision["Decision Agent<br/>[decision_agent.py]"]
end

subgraph group_knowledge["Knowledge and Reasoning"]
  node_graph["Knowledge Graph<br/>[graph_builder.py]"]
  node_causal["Causal Reasoning"]
  node_rag["RAG Retrieval<br/>[retriever.py]"]
  node_memory["Memory Services"]
  node_transformers["Transformer Tools"]
  node_world["World Model"]
  node_environment["Environment Model"]
  node_vision["Vision Analysis<br/>[vision_engine.py]"]
end

subgraph group_future["Future Exploration"]
  node_counterfactual["Counterfactual Engine"]
  node_simulation["Scenario Simulation"]
  node_digital_twin["Digital Twin"]
  node_prediction["Future Prediction"]
end

subgraph group_support["Platform Services"]
  node_reports["Report Generation<br/>[report_engine.py]"]
  node_postgres[("Postgres<br/>[postgres.py]")]
  node_neo4j[("Neo4j Graph Store<br/>[neo4j.py]")]
  node_chroma[("Chroma Store<br/>[chroma.py]")]
end

node_user(("User"))

node_user -->|"submits task"| node_api
node_api -.->|"dispatches task"| node_manager
node_user -.->|"sends updates"| node_realtime
node_manager -->|"processes task"| node_nlp
node_manager -->|"retrieves context"| node_memory
node_manager -->|"retrieves context"| node_rag
node_manager -->|"builds graph"| node_graph
node_manager -->|"analyzes causes"| node_causal
node_manager -->|"delegates analysis"| node_specialists
node_manager -->|"requests decision"| node_decision
node_research -->|"retrieves context"| node_memory
node_research -->|"builds graph"| node_graph
node_research -->|"retrieves evidence"| node_rag
node_research -->|"reranks results"| node_transformers
node_research -->|"analyzes causes"| node_causal
node_research -->|"analyzes setting"| node_environment
node_research -->|"predicts future"| node_prediction
node_graph -->|"provides graph"| node_causal
node_graph -.->|"persists graph"| node_neo4j
node_rag -.->|"searches vectors"| node_chroma
node_manager -->|"explores alternatives"| node_counterfactual
node_manager -->|"simulates scenarios"| node_simulation
node_manager -->|"generates report"| node_reports
node_manager -.->|"stores product data"| node_postgres
node_user -.->|"provides visual input"| node_vision
node_world -->|"uses environment"| node_environment
node_manager -->|"models world"| node_world
node_manager -->|"models twin"| node_digital_twin
node_user -.->|"receives results"| node_reports

click node_api "https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/api/v1"
click node_realtime "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/websocket/routes.py"
click node_manager "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/agents/manager_agent.py"
click node_nlp "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/nlp/nlp_pipeline.py"
click node_specialists "https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/agents"
click node_research "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/agents/research_agent.py"
click node_decision "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/agents/decision_agent.py"
click node_graph "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/graph/graph_builder.py"
click node_causal "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/causal_inference/causal_reasoning.py"
click node_rag "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/rag/retriever.py"
click node_memory "https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/services/memory"
click node_transformers "https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/services/transformers"
click node_world "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/world_model/world_model_engine.py"
click node_environment "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/world_model/environment_model.py"
click node_counterfactual "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/counterfactual/counterfactual_engine.py"
click node_simulation "https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/services/simulation"
click node_digital_twin "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/digital_twin/digital_twin_engine.py"
click node_prediction "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/deep_learning/success_predictor.py"
click node_vision "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/vision/vision_engine.py"
click node_reports "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/reporting/report_engine.py"
click node_postgres "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/database/postgres.py"
click node_neo4j "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/database/neo4j.py"
click node_chroma "https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/database/chroma.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_api,node_realtime,node_user toneBlue
class node_manager,node_nlp,node_specialists,node_research,node_decision toneAmber
class node_graph,node_causal,node_rag,node_memory,node_transformers,node_world,node_environment,node_vision toneMint
class node_counterfactual,node_simulation,node_digital_twin,node_prediction toneRose
class node_reports,node_postgres,node_neo4j,node_chroma toneIndigo
```

## Components

### Product Interface

- [HTTP API](https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/api/v1): `backend/api/v1`
- [WebSocket Updates](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/websocket/routes.py): `backend/websocket/routes.py`

### Agent Orchestration

- [Manager Agent](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/agents/manager_agent.py): `backend/agents/manager_agent.py`
- [Task NLP](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/nlp/nlp_pipeline.py): `backend/services/nlp/nlp_pipeline.py`
- [Specialist Agents](https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/agents): `backend/agents`
- [Research Agent](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/agents/research_agent.py): `backend/agents/research_agent.py`
- [Decision Agent](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/agents/decision_agent.py): `backend/agents/decision_agent.py`

### Knowledge and Reasoning

- [Knowledge Graph](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/graph/graph_builder.py): `backend/services/graph/graph_builder.py`
- [Causal Reasoning](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/causal_inference/causal_reasoning.py): `backend/services/causal_inference/causal_reasoning.py`
- [RAG Retrieval](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/rag/retriever.py): `backend/services/rag/retriever.py`
- [Memory Services](https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/services/memory): `backend/services/memory`
- [Transformer Tools](https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/services/transformers): `backend/services/transformers`
- [World Model](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/world_model/world_model_engine.py): `backend/services/world_model/world_model_engine.py`
- [Environment Model](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/world_model/environment_model.py): `backend/services/world_model/environment_model.py`
- [Vision Analysis](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/vision/vision_engine.py): `backend/services/vision/vision_engine.py`

### Future Exploration

- [Counterfactual Engine](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/counterfactual/counterfactual_engine.py): `backend/services/counterfactual/counterfactual_engine.py`
- [Scenario Simulation](https://github.com/surypratapsingh872/chronogenesis-ai/tree/main/backend/services/simulation): `backend/services/simulation`
- [Digital Twin](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/digital_twin/digital_twin_engine.py): `backend/services/digital_twin/digital_twin_engine.py`
- [Future Prediction](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/deep_learning/success_predictor.py): `backend/services/deep_learning/success_predictor.py`

### Platform Services

- [Report Generation](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/services/reporting/report_engine.py): `backend/services/reporting/report_engine.py`
- [Postgres](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/database/postgres.py): `backend/database/postgres.py`
- [Neo4j Graph Store](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/database/neo4j.py): `backend/database/neo4j.py`
- [Chroma Store](https://github.com/surypratapsingh872/chronogenesis-ai/blob/main/backend/database/chroma.py): `backend/database/chroma.py`

### Other components

- **User**

## Connections

- User → HTTP API: submits task
- HTTP API → Manager Agent: dispatches task
- User → WebSocket Updates: sends updates
- Manager Agent → Task NLP: processes task (evidence: `backend/agents/manager_agent.py`)
- Manager Agent → Memory Services: retrieves context (evidence: `backend/agents/manager_agent.py`)
- Manager Agent → RAG Retrieval: retrieves context (evidence: `backend/agents/manager_agent.py`)
- Manager Agent → Knowledge Graph: builds graph (evidence: `backend/agents/manager_agent.py`)
- Manager Agent → Causal Reasoning: analyzes causes (evidence: `backend/agents/manager_agent.py`)
- Manager Agent → Specialist Agents: delegates analysis (evidence: `backend/agents/manager_agent.py`)
- Manager Agent → Decision Agent: requests decision (evidence: `backend/agents/manager_agent.py`)
- Research Agent → Memory Services: retrieves context (evidence: `backend/agents/research_agent.py`)
- Research Agent → Knowledge Graph: builds graph (evidence: `backend/agents/research_agent.py`)
- Research Agent → RAG Retrieval: retrieves evidence (evidence: `backend/agents/research_agent.py`)
- Research Agent → Transformer Tools: reranks results (evidence: `backend/agents/research_agent.py`)
- Research Agent → Causal Reasoning: analyzes causes (evidence: `backend/agents/research_agent.py`)
- Research Agent → Environment Model: analyzes setting (evidence: `backend/agents/research_agent.py`)
- Research Agent → Future Prediction: predicts future (evidence: `backend/agents/research_agent.py`)
- Knowledge Graph → Causal Reasoning: provides graph
- Knowledge Graph → Neo4j Graph Store: persists graph
- RAG Retrieval → Chroma Store: searches vectors
- Manager Agent → Counterfactual Engine: explores alternatives (evidence: `backend/agents/manager_agent.py`)
- Manager Agent → Scenario Simulation: simulates scenarios
- Manager Agent → Report Generation: generates report
- Manager Agent → Postgres: stores product data
- User → Vision Analysis: provides visual input
- World Model → Environment Model: uses environment (evidence: `backend/services/world_model/world_model_engine.py`)
- Manager Agent → World Model: models world (evidence: `backend/agents/manager_agent.py`)
- Manager Agent → Digital Twin: models twin (evidence: `backend/agents/manager_agent.py`)
- User → Report Generation: receives results
