# manishkumarsingh41/contextengine architecture

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

- Interactive diagram: https://gitdiagram.com/manishkumarsingh41/contextengine
- Repository: https://github.com/manishkumarsingh41/contextengine

## Overview

#### 1. Purpose and Runtime Entry Points
ContextEngine is an enterprise AI workspace combining authenticated chat, RAG document/repository intelligence, multi-agent reasoning, and pluggable LLM providers. The backend runs as FastAPI via `backend/app.py`; the Streamlit client starts at `frontend/app.py`. Container deployment is defined by `docker-compose.yml` and `Dockerfile`.

#### 2. API, Security, and Persistent Application State
FastAPI route modules expose chat, streaming, uploads, sessions, provider selection, authentication, admin, and health endpoints. Authentication supports JWT user sessions and hashed API keys; service-level managers handle auth/session lifecycle and audit concerns. SQLAlchemy models/sessions form the transactional persistence boundary, backed by PostgreSQL or SQLite depending on `DATABASE_URL`.
- `backend/routes/chat.py`
- `backend/dependencies/auth.py`
- `backend/db/models.py`

#### 3. Chat and Streaming Boundary
Chat requests enter through backend routes, validate into Pydantic request/response schemas, select an LLM path, and can return streamed events. Session state persists resumable conversations; the frontend maintains UI/session state and renders messages, agent activity, documents, and workflow output.
- `backend/routes/chat.py`
- `backend/routes/stream.py`
- `frontend/state.py`

#### 4. Provider Abstraction and Resilient Routing
Providers are isolated behind common types/base interfaces and instantiated by a factory. Implementations target OpenAI, Anthropic Claude, Gemini, Cohere, Groq, NVIDIA NIM, Together, Ollama, and OpenRouter. The router adds provider policy selection, health assessment, metrics, and circuit-breaker behavior before calls leave the application boundary for external model APIs.
- `providers/base.py`
- `providers/factory.py`
- `router/router.py`

#### 5. RAG Ingestion and Retrieval
Upload/GitHub ingestion is a distinct pipeline: files or repositories are loaded and parsed, metadata is extracted, content is chunked, embeddings are generated, then vectors are persisted. Query-time retrieval embeds the prompt, searches the vector store, can rerank results, and supplies grounded context to generation. ChromaDB is the vector persistence/search boundary; embedding and store factories make implementations replaceable.
- `rag/ingestion_pipeline.py`
- `rag/retrieval.py`
- `rag/chroma_store.py`

#### 6. Multi-Agent Orchestration
Complex prompts are processed as a workflow with shared state: Planner decomposes work; Retriever obtains relevant context; Generator creates a response; Critic evaluates it; Reflection refines it until the workflow stops. Orchestration owns stage sequencing/state transitions, while individual agents encapsulate role-specific LLM prompting and evaluation.
- `orchestration/workflow.py`
- `orchestration/state.py`
- `agents/planner.py`

#### 7. Frontend and Operational Infrastructure
The Streamlit frontend is a separate client over the backend API, organized into chat/login/upload/settings pages and reusable UI components. Production concerns are embedded in backend observability middleware: structured logging, metrics/Prometheus export, tracing/OpenTelemetry, and health probes. Docker Compose supplies the production-like multi-service runtime; GitHub Actions provides CI, Docker, and release workflows.
- `frontend/pages/chat.py`
- `backend/observability/middleware.py`
- `docker-compose.yml`

Main entry points: [`orchestration/workflow.py`](https://github.com/manishkumarsingh41/contextengine/blob/main/orchestration/workflow.py) (Agent workflow), [`backend/app.py`](https://github.com/manishkumarsingh41/contextengine/blob/main/backend/app.py) (FastAPI application), [`backend/routes/chat.py`](https://github.com/manishkumarsingh41/contextengine/blob/main/backend/routes/chat.py) (Chat and stream routes), [`providers/factory.py`](https://github.com/manishkumarsingh41/contextengine/blob/main/providers/factory.py) (Provider factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_streamlit["Streamlit workspace<br/>Streamlit client<br/>[app.py]"]
  node_ui_state["UI session state<br/>frontend state<br/>[state.py]"]
  node_chat_page["Chat UI<br/>frontend page<br/>[chat.py]"]
end

subgraph group_backend["Backend API"]
  node_api["FastAPI application<br/>API runtime<br/>[app.py]"]
  node_chat_routes["Chat and stream routes<br/>route modules<br/>[chat.py]"]
  node_auth["Auth dependency<br/>security boundary<br/>[auth.py]"]
end

subgraph group_ai["AI Processing"]
  node_workflow{{"Agent workflow<br/>orchestrator<br/>[workflow.py]"}}
  node_workflow_state["Workflow state<br/>shared state<br/>[state.py]"]
  node_planner["Planner agent<br/>agent role<br/>[planner.py]"]
  node_retrieval["Retrieval service<br/>RAG query pipeline<br/>[retrieval.py]"]
  node_ingestion["Ingestion pipeline<br/>RAG indexing pipeline"]
  node_provider_factory["Provider factory<br/>provider abstraction<br/>[factory.py]"]
  node_provider_base["Provider interface<br/>LLM contract<br/>[base.py]"]
  node_llm_router{{"LLM router<br/>resilient router<br/>[router.py]"}}
end

subgraph group_data["Persistence"]
  node_app_db[("Application database<br/>SQLAlchemy models<br/>[models.py]")]
  node_vector_store[("Chroma vector store<br/>vector database adapter<br/>[chroma_store.py]")]
end

subgraph group_ops["Operations"]
  node_observability["Observability middleware<br/>telemetry middleware<br/>[middleware.py]"]
  node_compose["Container runtime<br/>Docker Compose<br/>[docker-compose.yml]"]
end

node_external_llms(("External LLM APIs<br/>model providers"))

node_streamlit -->|"maintains"| node_ui_state
node_streamlit -->|"renders"| node_chat_page
node_chat_page -->|"backend API calls"| node_api
node_api -->|"mounts"| node_chat_routes
node_api -->|"enforces"| node_auth
node_auth -->|"loads sessions and keys"| node_app_db
node_chat_routes -->|"persists conversations"| node_app_db
node_chat_routes -->|"complex prompts"| node_workflow
node_chat_routes -->|"direct generation"| node_llm_router
node_workflow -->|"transitions"| node_workflow_state
node_workflow -->|"plans with"| node_planner
node_workflow -->|"grounds with"| node_retrieval
node_workflow -->|"generates via"| node_llm_router
node_ingestion -->|"indexes vectors"| node_vector_store
node_retrieval -->|"searches"| node_vector_store
node_llm_router -->|"selects provider"| node_provider_factory
node_provider_factory -->|"implements"| node_provider_base
node_provider_factory -->|"calls"| node_external_llms
node_api -->|"instrumented by"| node_observability
node_compose -->|"runs"| node_api
node_compose -->|"runs"| node_streamlit

click node_streamlit "https://github.com/manishkumarsingh41/contextengine/blob/main/frontend/app.py"
click node_ui_state "https://github.com/manishkumarsingh41/contextengine/blob/main/frontend/state.py"
click node_chat_page "https://github.com/manishkumarsingh41/contextengine/blob/main/frontend/pages/chat.py"
click node_api "https://github.com/manishkumarsingh41/contextengine/blob/main/backend/app.py"
click node_chat_routes "https://github.com/manishkumarsingh41/contextengine/blob/main/backend/routes/chat.py"
click node_auth "https://github.com/manishkumarsingh41/contextengine/blob/main/backend/dependencies/auth.py"
click node_app_db "https://github.com/manishkumarsingh41/contextengine/blob/main/backend/db/models.py"
click node_observability "https://github.com/manishkumarsingh41/contextengine/blob/main/backend/observability/middleware.py"
click node_workflow "https://github.com/manishkumarsingh41/contextengine/blob/main/orchestration/workflow.py"
click node_workflow_state "https://github.com/manishkumarsingh41/contextengine/blob/main/orchestration/state.py"
click node_planner "https://github.com/manishkumarsingh41/contextengine/blob/main/agents/planner.py"
click node_retrieval "https://github.com/manishkumarsingh41/contextengine/blob/main/rag/retrieval.py"
click node_ingestion "https://github.com/manishkumarsingh41/contextengine/blob/main/rag/ingestion_pipeline.py"
click node_vector_store "https://github.com/manishkumarsingh41/contextengine/blob/main/rag/chroma_store.py"
click node_provider_factory "https://github.com/manishkumarsingh41/contextengine/blob/main/providers/factory.py"
click node_provider_base "https://github.com/manishkumarsingh41/contextengine/blob/main/providers/base.py"
click node_llm_router "https://github.com/manishkumarsingh41/contextengine/blob/main/router/router.py"
click node_compose "https://github.com/manishkumarsingh41/contextengine/blob/main/docker-compose.yml"

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_streamlit,node_ui_state,node_chat_page toneBlue
class node_api,node_chat_routes,node_auth toneAmber
class node_workflow,node_workflow_state,node_planner,node_retrieval,node_ingestion,node_provider_factory,node_provider_base,node_llm_router toneMint
class node_app_db,node_vector_store toneRose
class node_observability,node_compose toneIndigo
class node_external_llms toneNeutral
```

## Components

### Client

- [Streamlit workspace](https://github.com/manishkumarsingh41/contextengine/blob/main/frontend/app.py): Streamlit client · Chat, login, upload, and settings UI. · `frontend/app.py`
- [UI session state](https://github.com/manishkumarsingh41/contextengine/blob/main/frontend/state.py): frontend state · `frontend/state.py`
- [Chat UI](https://github.com/manishkumarsingh41/contextengine/blob/main/frontend/pages/chat.py): frontend page · `frontend/pages/chat.py`

### Backend API

- [FastAPI application](https://github.com/manishkumarsingh41/contextengine/blob/main/backend/app.py): API runtime · Authenticated application boundary. · `backend/app.py`
- [Chat and stream routes](https://github.com/manishkumarsingh41/contextengine/blob/main/backend/routes/chat.py): route modules · Validates chat requests and emits streaming events. · `backend/routes/chat.py`
- [Auth dependency](https://github.com/manishkumarsingh41/contextengine/blob/main/backend/dependencies/auth.py): security boundary · JWT sessions and API-key authentication. · `backend/dependencies/auth.py`

### AI Processing

- [Agent workflow](https://github.com/manishkumarsingh41/contextengine/blob/main/orchestration/workflow.py): orchestrator · Sequences shared-state reasoning stages. · `orchestration/workflow.py`
- [Workflow state](https://github.com/manishkumarsingh41/contextengine/blob/main/orchestration/state.py): shared state · `orchestration/state.py`
- [Planner agent](https://github.com/manishkumarsingh41/contextengine/blob/main/agents/planner.py): agent role · Decomposes complex prompts. · `agents/planner.py`
- [Retrieval service](https://github.com/manishkumarsingh41/contextengine/blob/main/rag/retrieval.py): RAG query pipeline · Embeds queries, searches, and can rerank context. · `rag/retrieval.py`
- [Ingestion pipeline](https://github.com/manishkumarsingh41/contextengine/blob/main/rag/ingestion_pipeline.py): RAG indexing pipeline · Parses sources, extracts metadata, chunks, and embeds content. · `rag/ingestion_pipeline.py`
- [Provider factory](https://github.com/manishkumarsingh41/contextengine/blob/main/providers/factory.py): provider abstraction · Instantiates common-interface LLM providers. · `providers/factory.py`
- [Provider interface](https://github.com/manishkumarsingh41/contextengine/blob/main/providers/base.py): LLM contract · Common provider types and base interface. · `providers/base.py`
- [LLM router](https://github.com/manishkumarsingh41/contextengine/blob/main/router/router.py): resilient router · Applies policy, health checks, metrics, and circuit breaking. · `router/router.py`

### Persistence

- [Application database](https://github.com/manishkumarsingh41/contextengine/blob/main/backend/db/models.py): SQLAlchemy models · Transactional users, sessions, and audit state. · `backend/db/models.py`
- [Chroma vector store](https://github.com/manishkumarsingh41/contextengine/blob/main/rag/chroma_store.py): vector database adapter · Vector persistence and similarity search boundary. · `rag/chroma_store.py`

### Operations

- [Observability middleware](https://github.com/manishkumarsingh41/contextengine/blob/main/backend/observability/middleware.py): telemetry middleware · Logging, metrics, tracing, and health probes. · `backend/observability/middleware.py`
- [Container runtime](https://github.com/manishkumarsingh41/contextengine/blob/main/docker-compose.yml): Docker Compose · Production-like multi-service deployment. · `docker-compose.yml`

### Other components

- **External LLM APIs**: model providers · OpenAI, Claude, Gemini, Cohere, Groq, NIM, Together, Ollama, and OpenRouter.

## Connections

- Streamlit workspace → UI session state: maintains
- Streamlit workspace → Chat UI: renders
- Chat UI → FastAPI application: backend API calls
- FastAPI application → Chat and stream routes: mounts
- FastAPI application → Auth dependency: enforces
- Auth dependency → Application database: loads sessions and keys
- Chat and stream routes → Application database: persists conversations
- Chat and stream routes → Agent workflow: complex prompts
- Chat and stream routes → LLM router: direct generation
- Agent workflow → Workflow state: transitions
- Agent workflow → Planner agent: plans with
- Agent workflow → Retrieval service: grounds with
- Agent workflow → LLM router: generates via
- Ingestion pipeline → Chroma vector store: indexes vectors
- Retrieval service → Chroma vector store: searches
- LLM router → Provider factory: selects provider
- Provider factory → Provider interface: implements
- Provider factory → External LLM APIs: calls
- FastAPI application → Observability middleware: instrumented by
- Container runtime → FastAPI application: runs
- Container runtime → Streamlit workspace: runs