# zayn329/chimeraai architecture

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

- Interactive diagram: https://gitdiagram.com/zayn329/chimeraai
- Repository: https://github.com/zayn329/chimeraai

## Overview

Chimera is an academic assistant that routes student questions to tutoring, exam-strategy, or administrative-policy specialists and returns grounded answers. The main runtime path is the browser UI through the gateway to the API, which checks its semantic cache before invoking the multi-agent workflow; agents can call retrieval tools before producing a response. Knowledge ingestion populates Pinecone, while MongoDB backs workflow checkpointing. The tree and excerpts support the backend flow, but do not show the frontend request implementation or the retrieval-tool internals, so those links are limited accordingly.

Main entry points: [`chimera_backend/orchestrator.py`](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py) (Swarm orchestrator), [`chimera_backend/server.py`](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/server.py) (Chat API), [`chimera_backend/tools.py`](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/tools.py) (Retrieval tools), [`chimera_backend/semantic_cache.py`](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/semantic_cache.py) (Semantic cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Student experience"]
  node_frontend["Web interface<br/>[LandingPage.jsx]"]
end

subgraph group_api["API and routing"]
  node_gateway["Chat gateway<br/>[index.js]"]
  node_server["Chat API<br/>[server.py]"]
  node_cache[("Semantic cache<br/>[semantic_cache.py]")]
  node_breaker["Circuit breaker<br/>[server.py]"]
end

subgraph group_agents["Agent workflow"]
  node_workflow["Swarm orchestrator<br/>[orchestrator.py]"]
  node_intent["Intent router<br/>[orchestrator.py]"]
  node_tutor["Tutor worker<br/>[orchestrator.py]"]
  node_strategist["Strategist worker<br/>[orchestrator.py]"]
  node_bureaucrat["Policy worker<br/>[orchestrator.py]"]
  node_toolnode["Tool dispatcher<br/>[orchestrator.py]"]
end

subgraph group_knowledge["Knowledge and state"]
  node_tools["Retrieval tools<br/>[tools.py]"]
  node_pinecone[("Pinecone vectors")]
  node_ingest["Knowledge ingestion<br/>[cloud_ingest.py]"]
  node_mongodb[("Workflow checkpoints")]
end

node_student(("Student"))
node_gemini{{"Gemini model"}}
node_web{{"Web search"}}

node_student -->|"submits query"| node_frontend
node_gateway -->|"proxies stream"| node_server
node_server -->|"checks cache"| node_cache
node_server -->|"checks status"| node_breaker
node_server -->|"invokes on miss"| node_workflow
node_server -->|"stores answer"| node_cache
node_workflow -->|"classifies intent"| node_intent
node_intent -->|"requests decision"| node_gemini
node_workflow -->|"dispatches"| node_tutor
node_workflow -->|"dispatches"| node_strategist
node_workflow -->|"dispatches"| node_bureaucrat
node_tutor -->|"requests response"| node_gemini
node_strategist -->|"requests response"| node_gemini
node_bureaucrat -->|"requests response"| node_gemini
node_tutor -->|"requests tools"| node_toolnode
node_strategist -->|"requests tools"| node_toolnode
node_bureaucrat -->|"requests tools"| node_toolnode
node_toolnode -->|"executes calls"| node_tools
node_tools -.->|"searches knowledge"| node_pinecone
node_tools -.->|"searches web"| node_web
node_ingest -->|"uploads vectors"| node_pinecone
node_workflow -->|"saves checkpoints"| node_mongodb

click node_frontend "https://github.com/zayn329/chimeraai/blob/main/chimera-frontend/src/pages/LandingPage.jsx"
click node_gateway "https://github.com/zayn329/chimeraai/blob/main/chimera-gateway/index.js"
click node_server "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/server.py"
click node_cache "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/semantic_cache.py"
click node_breaker "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/server.py"
click node_workflow "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py"
click node_intent "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py"
click node_tutor "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py"
click node_strategist "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py"
click node_bureaucrat "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py"
click node_toolnode "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py"
click node_tools "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/tools.py"
click node_ingest "https://github.com/zayn329/chimeraai/blob/main/chimera_backend/cloud_ingest.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_frontend toneBlue
class node_gateway,node_server,node_cache,node_breaker toneAmber
class node_workflow,node_intent,node_tutor,node_strategist,node_bureaucrat,node_toolnode toneMint
class node_tools,node_pinecone,node_ingest,node_mongodb toneRose
class node_student,node_gemini,node_web toneIndigo
```

## Components

### Student experience

- [Web interface](https://github.com/zayn329/chimeraai/blob/main/chimera-frontend/src/pages/LandingPage.jsx): `chimera-frontend/src/pages/LandingPage.jsx`

### API and routing

- [Chat gateway](https://github.com/zayn329/chimeraai/blob/main/chimera-gateway/index.js): `chimera-gateway/index.js`
- [Chat API](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/server.py): `chimera_backend/server.py`
- [Semantic cache](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/semantic_cache.py): `chimera_backend/semantic_cache.py`
- [Circuit breaker](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/server.py): `chimera_backend/server.py`

### Agent workflow

- [Swarm orchestrator](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py): `chimera_backend/orchestrator.py`
- [Intent router](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py): `chimera_backend/orchestrator.py`
- [Tutor worker](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py): `chimera_backend/orchestrator.py`
- [Strategist worker](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py): `chimera_backend/orchestrator.py`
- [Policy worker](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py): `chimera_backend/orchestrator.py`
- [Tool dispatcher](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/orchestrator.py): `chimera_backend/orchestrator.py`

### Knowledge and state

- [Retrieval tools](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/tools.py): `chimera_backend/tools.py`
- **Pinecone vectors**
- [Knowledge ingestion](https://github.com/zayn329/chimeraai/blob/main/chimera_backend/cloud_ingest.py): `chimera_backend/cloud_ingest.py`
- **Workflow checkpoints**

### Other components

- **Student**
- **Gemini model**
- **Web search**

## Connections

- Student → Web interface: submits query
- Chat gateway → Chat API: proxies stream
- Chat API → Semantic cache: checks cache
- Chat API → Circuit breaker: checks status
- Chat API → Swarm orchestrator: invokes on miss
- Chat API → Semantic cache: stores answer
- Swarm orchestrator → Intent router: classifies intent
- Intent router → Gemini model: requests decision
- Swarm orchestrator → Tutor worker: dispatches
- Swarm orchestrator → Strategist worker: dispatches
- Swarm orchestrator → Policy worker: dispatches
- Tutor worker → Gemini model: requests response
- Strategist worker → Gemini model: requests response
- Policy worker → Gemini model: requests response
- Tutor worker → Tool dispatcher: requests tools
- Strategist worker → Tool dispatcher: requests tools
- Policy worker → Tool dispatcher: requests tools
- Tool dispatcher → Retrieval tools: executes calls
- Retrieval tools → Pinecone vectors: searches knowledge
- Retrieval tools → Web search: searches web
- Knowledge ingestion → Pinecone vectors: uploads vectors
- Swarm orchestrator → Workflow checkpoints: saves checkpoints