# abegerov4/qorgauai architecture

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

- Interactive diagram: https://gitdiagram.com/abegerov4/qorgauai
- Repository: https://github.com/abegerov4/qorgauai

## Overview

QorgauAI is a Kazakhstan legal assistant whose main workflow streams a question through retrieval, tool-assisted research, answer generation and a second-agent citation check, returning claims with legal citations and visible progress. A separate document workflow masks personal data, extracts contract clauses, gathers legal evidence, and verifies clause verdicts before presenting a color-coded review and downloadable report. The README also documents dense-versus-hybrid search comparison, chat history, feedback, quotas and administration. The graph reflects documented routes and sampled calls; several internal links are omitted where excerpts do not establish wiring.

Main entry points: [`backend/app/api/routes.py`](https://github.com/abegerov4/qorgauai/blob/main/backend/app/api/routes.py) (Request routes), [`frontend/components/QorgauApp.tsx`](https://github.com/abegerov4/qorgauai/blob/main/frontend/components/QorgauApp.tsx) (Qorgau app), [`backend/app/retrieval/search.py`](https://github.com/abegerov4/qorgauai/blob/main/backend/app/retrieval/search.py) (Legal search), [`backend/app/main.py`](https://github.com/abegerov4/qorgauai/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Qorgau app<br/>[QorgauApp.tsx]"]
  node_chatui["Chat and answers<br/>[AnswerCard.tsx]"]
  node_reviewui["Review interface<br/>[ContractReview.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
  node_token["Session token<br/>[route.ts]"]
end

subgraph group_api["API and accounts"]
  node_server["FastAPI app<br/>[main.py]"]
  node_routes["Request routes<br/>[routes.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_accounts["Usage and admin<br/>[service.py]"]
end

subgraph group_research["Legal research"]
  node_agent{{"Answer agent<br/>[graph.py]"}}
  node_tools["Legal tool client<br/>[toolbox.py]"]
  node_mcp["MCP legal tools<br/>[server.py]"]
  node_search["Legal search<br/>[search.py]"]
  node_embed["Embeddings<br/>[embeddings.py]"]
  node_qdrant[("Legal corpus index<br/>[qdrant_setup.py]")]
end

subgraph group_contracts["Contract review"]
  node_ingest["Document ingestion<br/>[documents.py]"]
  node_guard["PII and input safeguards<br/>[pii.py]"]
  node_review{{"Clause review<br/>[review.py]"}}
  node_pdf["PDF report<br/>[review_pdf.py]"]
end

subgraph group_ops["State and observability"]
  node_db[("Account database<br/>[db.py]")]
  node_trace["Tracing and costs<br/>[observability.py]"]
end

node_person(("User"))
node_browser(("Browser"))
node_llm{{"OpenAI models"}}
node_langfuse["Langfuse"]

node_person -->|"uses"| node_webapp
node_webapp -->|"renders"| node_chatui
node_webapp -->|"renders"| node_reviewui
node_chatui -->|"submits questions"| node_webapi
node_reviewui -->|"uploads contract"| node_webapi
node_webapp -->|"requests token"| node_token
node_webapi -->|"calls API"| node_browser
node_browser -->|"sends requests"| node_server
node_server -->|"mounts routes"| node_routes
node_routes -->|"checks user"| node_auth
node_routes -->|"runs answer graph"| node_agent
node_agent -->|"invokes tools"| node_tools
node_tools -->|"dispatches calls"| node_mcp
node_mcp -->|"searches corpus"| node_search
node_search -->|"embeds queries"| node_embed
node_search -->|"queries index"| node_qdrant
node_embed -.->|"dense embeddings"| node_llm
node_routes -->|"reads upload"| node_ingest
node_ingest -->|"masks personal data"| node_guard
node_routes -->|"reviews document"| node_review
node_review -->|"retrieves evidence"| node_search
node_routes -->|"renders report"| node_pdf
node_routes -->|"records usage"| node_accounts
node_accounts -->|"reads and writes"| node_db
node_routes -->|"stores account data"| node_db
node_agent -->|"generates and verifies"| node_llm
node_review -->|"assesses clauses"| node_llm
node_server -->|"flushes traces"| node_trace
node_trace -.->|"sends telemetry"| node_langfuse

click node_webapp "https://github.com/abegerov4/qorgauai/blob/main/frontend/components/QorgauApp.tsx"
click node_chatui "https://github.com/abegerov4/qorgauai/blob/main/frontend/components/AnswerCard.tsx"
click node_reviewui "https://github.com/abegerov4/qorgauai/blob/main/frontend/components/ContractReview.tsx"
click node_webapi "https://github.com/abegerov4/qorgauai/blob/main/frontend/lib/api.ts"
click node_token "https://github.com/abegerov4/qorgauai/blob/main/frontend/app/api/token/route.ts"
click node_server "https://github.com/abegerov4/qorgauai/blob/main/backend/app/main.py"
click node_routes "https://github.com/abegerov4/qorgauai/blob/main/backend/app/api/routes.py"
click node_auth "https://github.com/abegerov4/qorgauai/blob/main/backend/app/accounts/auth.py"
click node_accounts "https://github.com/abegerov4/qorgauai/blob/main/backend/app/accounts/service.py"
click node_agent "https://github.com/abegerov4/qorgauai/blob/main/backend/app/agents/graph.py"
click node_tools "https://github.com/abegerov4/qorgauai/blob/main/backend/app/agents/toolbox.py"
click node_mcp "https://github.com/abegerov4/qorgauai/blob/main/backend/app/mcp_tools/server.py"
click node_search "https://github.com/abegerov4/qorgauai/blob/main/backend/app/retrieval/search.py"
click node_embed "https://github.com/abegerov4/qorgauai/blob/main/backend/app/retrieval/embeddings.py"
click node_qdrant "https://github.com/abegerov4/qorgauai/blob/main/backend/app/retrieval/qdrant_setup.py"
click node_ingest "https://github.com/abegerov4/qorgauai/blob/main/backend/app/ingestion/documents.py"
click node_guard "https://github.com/abegerov4/qorgauai/blob/main/backend/app/guardrails/pii.py"
click node_review "https://github.com/abegerov4/qorgauai/blob/main/backend/app/agents/review.py"
click node_pdf "https://github.com/abegerov4/qorgauai/blob/main/backend/app/reports/review_pdf.py"
click node_db "https://github.com/abegerov4/qorgauai/blob/main/backend/app/accounts/db.py"
click node_trace "https://github.com/abegerov4/qorgauai/blob/main/backend/app/observability.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_webapp,node_chatui,node_reviewui,node_webapi,node_token,node_person,node_browser toneBlue
class node_server,node_routes,node_auth,node_accounts toneAmber
class node_agent,node_tools,node_mcp,node_search,node_embed,node_qdrant toneMint
class node_ingest,node_guard,node_review,node_pdf toneRose
class node_db,node_trace,node_llm,node_langfuse toneIndigo
```

## Components

### Web experience

- [Qorgau app](https://github.com/abegerov4/qorgauai/blob/main/frontend/components/QorgauApp.tsx): `frontend/components/QorgauApp.tsx`
- [Chat and answers](https://github.com/abegerov4/qorgauai/blob/main/frontend/components/AnswerCard.tsx): `frontend/components/AnswerCard.tsx`
- [Review interface](https://github.com/abegerov4/qorgauai/blob/main/frontend/components/ContractReview.tsx): `frontend/components/ContractReview.tsx`
- [API client](https://github.com/abegerov4/qorgauai/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Session token](https://github.com/abegerov4/qorgauai/blob/main/frontend/app/api/token/route.ts): `frontend/app/api/token/route.ts`

### API and accounts

- [FastAPI app](https://github.com/abegerov4/qorgauai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Request routes](https://github.com/abegerov4/qorgauai/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Authentication](https://github.com/abegerov4/qorgauai/blob/main/backend/app/accounts/auth.py): `backend/app/accounts/auth.py`
- [Usage and admin](https://github.com/abegerov4/qorgauai/blob/main/backend/app/accounts/service.py): `backend/app/accounts/service.py`

### Legal research

- [Answer agent](https://github.com/abegerov4/qorgauai/blob/main/backend/app/agents/graph.py): `backend/app/agents/graph.py`
- [Legal tool client](https://github.com/abegerov4/qorgauai/blob/main/backend/app/agents/toolbox.py): `backend/app/agents/toolbox.py`
- [MCP legal tools](https://github.com/abegerov4/qorgauai/blob/main/backend/app/mcp_tools/server.py): `backend/app/mcp_tools/server.py`
- [Legal search](https://github.com/abegerov4/qorgauai/blob/main/backend/app/retrieval/search.py): `backend/app/retrieval/search.py`
- [Embeddings](https://github.com/abegerov4/qorgauai/blob/main/backend/app/retrieval/embeddings.py): `backend/app/retrieval/embeddings.py`
- [Legal corpus index](https://github.com/abegerov4/qorgauai/blob/main/backend/app/retrieval/qdrant_setup.py): `backend/app/retrieval/qdrant_setup.py`

### Contract review

- [Document ingestion](https://github.com/abegerov4/qorgauai/blob/main/backend/app/ingestion/documents.py): `backend/app/ingestion/documents.py`
- [PII and input safeguards](https://github.com/abegerov4/qorgauai/blob/main/backend/app/guardrails/pii.py): `backend/app/guardrails/pii.py`
- [Clause review](https://github.com/abegerov4/qorgauai/blob/main/backend/app/agents/review.py): `backend/app/agents/review.py`
- [PDF report](https://github.com/abegerov4/qorgauai/blob/main/backend/app/reports/review_pdf.py): `backend/app/reports/review_pdf.py`

### State and observability

- [Account database](https://github.com/abegerov4/qorgauai/blob/main/backend/app/accounts/db.py): `backend/app/accounts/db.py`
- [Tracing and costs](https://github.com/abegerov4/qorgauai/blob/main/backend/app/observability.py): `backend/app/observability.py`

### Other components

- **User**
- **Browser**
- **OpenAI models**
- **Langfuse**

## Connections

- User → Qorgau app: uses
- Qorgau app → Chat and answers: renders
- Qorgau app → Review interface: renders
- Chat and answers → API client: submits questions
- Review interface → API client: uploads contract
- Qorgau app → Session token: requests token
- API client → Browser: calls API
- Browser → FastAPI app: sends requests
- FastAPI app → Request routes: mounts routes
- Request routes → Authentication: checks user
- Request routes → Answer agent: runs answer graph
- Answer agent → Legal tool client: invokes tools
- Legal tool client → MCP legal tools: dispatches calls
- MCP legal tools → Legal search: searches corpus
- Legal search → Embeddings: embeds queries
- Legal search → Legal corpus index: queries index
- Embeddings → OpenAI models: dense embeddings
- Request routes → Document ingestion: reads upload
- Document ingestion → PII and input safeguards: masks personal data
- Request routes → Clause review: reviews document
- Clause review → Legal search: retrieves evidence
- Request routes → PDF report: renders report
- Request routes → Usage and admin: records usage
- Usage and admin → Account database: reads and writes
- Request routes → Account database: stores account data
- Answer agent → OpenAI models: generates and verifies
- Clause review → OpenAI models: assesses clauses
- FastAPI app → Tracing and costs: flushes traces
- Tracing and costs → Langfuse: sends telemetry