# vijayb-exl/complai architecture

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

- Interactive diagram: https://gitdiagram.com/vijayb-exl/complai
- Repository: https://github.com/vijayb-exl/complai

## Overview

#### Purpose and Entry Points
complAI is a compliance-analysis application: it ingests policy documents, retrieves relevant clauses, queries business metrics through natural-language-to-SQL, evaluates compliance, and produces remediation workflows. The backend service starts at `backend/app/main.py`; API boundaries are `backend/app/api/routes_run.py` for analysis/simulation runs and `backend/app/api/routes_rag.py` for document/RAG operations. The Next.js client begins at `frontend/app/page.tsx` and provides a dedicated RAG workspace at `frontend/app/rag/page.tsx`.

#### API and Execution Boundary
Request/response contracts are centralized in `backend/app/api/schemas.py`. Run APIs hand work to `backend/app/run_manager.py`, separating HTTP lifecycle/status handling from agent execution. RAG routes delegate to the RAG subsystem rather than exposing vector-store details directly. Browser-to-backend calls are encapsulated in `frontend/lib/api.ts` and `frontend/lib/rag-api.ts`.

#### LangGraph Compliance Pipeline
`backend/app/graph/builder.py` compiles the multi-agent workflow, with shared execution state in `backend/app/graph/state.py`. The supervisor in `backend/app/graph/nodes/supervisor.py` routes work across stages:
- policy retrieval: `backend/app/graph/nodes/retrieve_policies.py`
- structured-data querying: `backend/app/graph/nodes/text_to_sql.py`
- policy-versus-metric evaluation: `backend/app/graph/nodes/compliance_reasoning.py`
- remediation-plan production: `backend/app/graph/nodes/remediation_workflow.py`

This graph is the principal control-flow boundary: nodes exchange typed state such as retrieved policies, SQL, results, analysis, and workflow rather than calling UI code.

#### Document Ingestion and RAG
Document ingestion is represented as both a graph stage, `backend/app/graph/nodes/ingest_document.py`, and a reusable service pipeline in `backend/app/rag/ingestion_service.py`. It loads documents, chunks content, extracts entities, and persists embeddings through `backend/app/rag/loaders.py`, `backend/app/rag/chunking.py`, and `backend/app/rag/vector_store.py`. At query time, `backend/app/rag/retrieval_service.py` retrieves candidate policy content; `backend/app/rag/reranker.py` and `backend/app/rag/prompt_builder.py` refine context for RAG responses. ChromaDB is the vector-store infrastructure boundary.

#### LLM and Structured Data Integrations
LLM access is abstracted by `backend/app/connectors/llm.py`, with OpenRouter-specific implementation in `backend/app/connectors/openrouter_llm.py`. SQL generation/execution is isolated in `backend/app/connectors/sql_connector.py`, supporting the Databricks/SQL Server structured-data boundary. The text-to-SQL node should remain the only graph stage that turns user language into database access, preserving read-only and dialect-validation controls.

#### Simulation and Client Visualization
The backend supports dependency-free dummy/live behavior through `backend/app/simulation/engine.py` and `backend/app/simulation/fixtures.py`; this enables streamed synthetic progress without external database access. On the client, `frontend/components/SimulationStreamer.tsx` presents run updates, while `frontend/components/LinearWorkflowMap.tsx` renders the sequential remediation workflow and compliance status lights. RAG interaction, uploads, citations, and agent progress are composed under `frontend/components/rag/RagChat.tsx` and `frontend/components/rag/DocumentUploadPanel.tsx`.

#### Runtime Shape
Backend runtime is Python with LangGraph/LangChain, ChromaDB, LLM-provider connectivity, and optional Databricks or SQL Server credentials configured via `backend/app/config.py`. Frontend runtime is Next.js/React App Router. The frontend is a consumer of backend API and streaming status contracts; it does not own compliance reasoning, embedding, SQL access, or workflow generation.

Main entry points: [`backend/app/graph/nodes/supervisor.py`](https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/supervisor.py) (Supervisor), [`frontend/lib/api.ts`](https://github.com/vijayb-exl/complai/blob/main/frontend/lib/api.ts) (API clients), [`backend/app/api/routes_rag.py`](https://github.com/vijayb-exl/complai/blob/main/backend/app/api/routes_rag.py) (RAG APIs), [`backend/app/run_manager.py`](https://github.com/vijayb-exl/complai/blob/main/backend/app/run_manager.py) (Run manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js client"]
  node_client_home["Analysis UI<br/>Next.js page<br/>[page.tsx]"]
  node_client_rag["RAG workspace<br/>Next.js page<br/>[page.tsx]"]
  node_client_api["API clients<br/>browser API layer<br/>[api.ts]"]
  node_simulation_view["Run visualization<br/>React components"]
  node_rag_ui["RAG interaction UI<br/>React components<br/>[RagChat.tsx]"]
end

subgraph group_api["Backend API"]
  node_backend_main["Backend service<br/>Python entry point<br/>[main.py]"]
  node_run_routes["Run APIs<br/>HTTP routes<br/>[routes_run.py]"]
  node_rag_routes["RAG APIs<br/>HTTP routes<br/>[routes_rag.py]"]
  node_run_manager["Run manager<br/>execution lifecycle<br/>[run_manager.py]"]
end

subgraph group_pipeline["Compliance graph"]
  node_workflow_graph{{"Compliance workflow<br/>LangGraph builder<br/>[builder.py]"}}
  node_supervisor["Supervisor<br/>graph router<br/>[supervisor.py]"]
  node_policy_retrieval["Policy retrieval<br/>graph node"]
  node_text_to_sql["Text-to-SQL<br/>graph node<br/>[text_to_sql.py]"]
  node_compliance_reasoning["Compliance evaluation<br/>graph node"]
  node_remediation["Remediation workflow<br/>graph node"]
end

subgraph group_rag["RAG subsystem"]
  node_ingestion["Document ingestion<br/>RAG ingestion service"]
  node_retrieval["Retrieval and context<br/>RAG query service"]
end

subgraph group_integrations["External integrations"]
  node_vector_store[("ChromaDB<br/>vector store<br/>[vector_store.py]")]
  node_llm["LLM provider<br/>LLM connector<br/>[llm.py]"]
  node_structured_data[("Databricks / SQL Server<br/>structured data connector<br/>[sql_connector.py]")]
end

node_client_home -->|"starts runs"| node_client_api
node_client_rag -->|"hosts"| node_rag_ui
node_rag_ui -->|"RAG calls"| node_client_api
node_client_api -->|"HTTP / streaming"| node_run_routes
node_client_api -->|"HTTP"| node_rag_routes
node_run_routes -->|"delegates"| node_run_manager
node_run_manager -->|"executes"| node_workflow_graph
node_workflow_graph -->|"routes state"| node_supervisor
node_supervisor -->|"retrieve clauses"| node_policy_retrieval
node_supervisor -->|"query metrics"| node_text_to_sql
node_supervisor -->|"evaluate"| node_compliance_reasoning
node_supervisor -->|"produce plan"| node_remediation
node_policy_retrieval -->|"retrieves context"| node_retrieval
node_retrieval -->|"similarity search"| node_vector_store
node_rag_routes -->|"uploads"| node_ingestion
node_rag_routes -->|"queries"| node_retrieval
node_ingestion -->|"persists embeddings"| node_vector_store
node_text_to_sql -->|"validated read-only SQL"| node_structured_data
node_compliance_reasoning -->|"analysis"| node_llm
node_remediation -->|"workflow generation"| node_llm
node_run_manager -.->|"run updates"| node_simulation_view

click node_client_home "https://github.com/vijayb-exl/complai/blob/main/frontend/app/page.tsx"
click node_client_rag "https://github.com/vijayb-exl/complai/blob/main/frontend/app/rag/page.tsx"
click node_client_api "https://github.com/vijayb-exl/complai/blob/main/frontend/lib/api.ts"
click node_simulation_view "https://github.com/vijayb-exl/complai/blob/main/frontend/components/SimulationStreamer.tsx"
click node_rag_ui "https://github.com/vijayb-exl/complai/blob/main/frontend/components/rag/RagChat.tsx"
click node_backend_main "https://github.com/vijayb-exl/complai/blob/main/backend/app/main.py"
click node_run_routes "https://github.com/vijayb-exl/complai/blob/main/backend/app/api/routes_run.py"
click node_rag_routes "https://github.com/vijayb-exl/complai/blob/main/backend/app/api/routes_rag.py"
click node_run_manager "https://github.com/vijayb-exl/complai/blob/main/backend/app/run_manager.py"
click node_workflow_graph "https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/builder.py"
click node_supervisor "https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/supervisor.py"
click node_policy_retrieval "https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/retrieve_policies.py"
click node_text_to_sql "https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/text_to_sql.py"
click node_compliance_reasoning "https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/compliance_reasoning.py"
click node_remediation "https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/remediation_workflow.py"
click node_ingestion "https://github.com/vijayb-exl/complai/blob/main/backend/app/rag/ingestion_service.py"
click node_retrieval "https://github.com/vijayb-exl/complai/blob/main/backend/app/rag/retrieval_service.py"
click node_vector_store "https://github.com/vijayb-exl/complai/blob/main/backend/app/rag/vector_store.py"
click node_llm "https://github.com/vijayb-exl/complai/blob/main/backend/app/connectors/llm.py"
click node_structured_data "https://github.com/vijayb-exl/complai/blob/main/backend/app/connectors/sql_connector.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_client_home,node_client_rag,node_client_api,node_simulation_view,node_rag_ui toneBlue
class node_backend_main,node_run_routes,node_rag_routes,node_run_manager toneAmber
class node_workflow_graph,node_supervisor,node_policy_retrieval,node_text_to_sql,node_compliance_reasoning,node_remediation toneMint
class node_ingestion,node_retrieval toneRose
class node_vector_store,node_llm,node_structured_data toneIndigo
```

## Components

### Next.js client

- [Analysis UI](https://github.com/vijayb-exl/complai/blob/main/frontend/app/page.tsx): Next.js page · `frontend/app/page.tsx`
- [RAG workspace](https://github.com/vijayb-exl/complai/blob/main/frontend/app/rag/page.tsx): Next.js page · `frontend/app/rag/page.tsx`
- [API clients](https://github.com/vijayb-exl/complai/blob/main/frontend/lib/api.ts): browser API layer · Encapsulates backend and RAG calls. · `frontend/lib/api.ts`
- [Run visualization](https://github.com/vijayb-exl/complai/blob/main/frontend/components/SimulationStreamer.tsx): React components · Streams progress and renders remediation workflow. · `frontend/components/SimulationStreamer.tsx`
- [RAG interaction UI](https://github.com/vijayb-exl/complai/blob/main/frontend/components/rag/RagChat.tsx): React components · Provides chat, uploads, citations, and agent progress. · `frontend/components/rag/RagChat.tsx`

### Backend API

- [Backend service](https://github.com/vijayb-exl/complai/blob/main/backend/app/main.py): Python entry point · `backend/app/main.py`
- [Run APIs](https://github.com/vijayb-exl/complai/blob/main/backend/app/api/routes_run.py): HTTP routes · Analysis and simulation boundary. · `backend/app/api/routes_run.py`
- [RAG APIs](https://github.com/vijayb-exl/complai/blob/main/backend/app/api/routes_rag.py): HTTP routes · Document and retrieval boundary. · `backend/app/api/routes_rag.py`
- [Run manager](https://github.com/vijayb-exl/complai/blob/main/backend/app/run_manager.py): execution lifecycle · Separates HTTP status handling from agent execution. · `backend/app/run_manager.py`

### Compliance graph

- [Compliance workflow](https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/builder.py): LangGraph builder · Compiles the multi-agent control flow. · `backend/app/graph/builder.py`
- [Supervisor](https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/supervisor.py): graph router · Routes shared typed state across compliance stages. · `backend/app/graph/nodes/supervisor.py`
- [Policy retrieval](https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/retrieve_policies.py): graph node · `backend/app/graph/nodes/retrieve_policies.py`
- [Text-to-SQL](https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/text_to_sql.py): graph node · Sole graph stage for read-only structured-data access. · `backend/app/graph/nodes/text_to_sql.py`
- [Compliance evaluation](https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/compliance_reasoning.py): graph node · `backend/app/graph/nodes/compliance_reasoning.py`
- [Remediation workflow](https://github.com/vijayb-exl/complai/blob/main/backend/app/graph/nodes/remediation_workflow.py): graph node · `backend/app/graph/nodes/remediation_workflow.py`

### RAG subsystem

- [Document ingestion](https://github.com/vijayb-exl/complai/blob/main/backend/app/rag/ingestion_service.py): RAG ingestion service · Loads, chunks, extracts entities, and persists embeddings. · `backend/app/rag/ingestion_service.py`
- [Retrieval and context](https://github.com/vijayb-exl/complai/blob/main/backend/app/rag/retrieval_service.py): RAG query service · Retrieves policy content and prepares RAG context. · `backend/app/rag/retrieval_service.py`

### External integrations

- [ChromaDB](https://github.com/vijayb-exl/complai/blob/main/backend/app/rag/vector_store.py): vector store · Persistent embedding retrieval boundary. · `backend/app/rag/vector_store.py`
- [LLM provider](https://github.com/vijayb-exl/complai/blob/main/backend/app/connectors/llm.py): LLM connector · OpenRouter-backed model access abstraction. · `backend/app/connectors/llm.py`
- [Databricks / SQL Server](https://github.com/vijayb-exl/complai/blob/main/backend/app/connectors/sql_connector.py): structured data connector · Dialect-validated SQL generation and execution boundary. · `backend/app/connectors/sql_connector.py`

## Connections

- Analysis UI → API clients: starts runs
- RAG workspace → RAG interaction UI: hosts
- RAG interaction UI → API clients: RAG calls
- API clients → Run APIs: HTTP / streaming
- API clients → RAG APIs: HTTP
- Run APIs → Run manager: delegates
- Run manager → Compliance workflow: executes
- Compliance workflow → Supervisor: routes state
- Supervisor → Policy retrieval: retrieve clauses
- Supervisor → Text-to-SQL: query metrics
- Supervisor → Compliance evaluation: evaluate
- Supervisor → Remediation workflow: produce plan
- Policy retrieval → Retrieval and context: retrieves context
- Retrieval and context → ChromaDB: similarity search
- RAG APIs → Document ingestion: uploads
- RAG APIs → Retrieval and context: queries
- Document ingestion → ChromaDB: persists embeddings
- Text-to-SQL → Databricks / SQL Server: validated read-only SQL
- Compliance evaluation → LLM provider: analysis
- Remediation workflow → LLM provider: workflow generation
- Run manager → Run visualization: run updates