# team-acatche/cheshire architecture

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

- Interactive diagram: https://gitdiagram.com/team-acatche/cheshire
- Repository: https://github.com/team-acatche/cheshire

## Overview

Cheshire lets a team member upload a technical design PDF, run a standards-based security audit, inspect severity-ranked findings in context, and discuss or report the results. The documented audit stages are parsing/chunking, section audits, deduplication, global checklist review, and PDF locating. The backend also supports policy knowledge, web search, live evaluation controls, authentication, and assessment reports. Relationships for unsampled endpoint and report internals are shown only where documented; the graph does not infer calls from directory names.

Main entry points: [`cheshire-frontend/src/App.tsx`](https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/App.tsx) (Application shell), [`cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py`](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py) (Multistep audit pipeline), [`cheshire-backend/src/server.py`](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/server.py) (FastAPI application), [`cheshire-backend/src/endpoints/evaluate.py`](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/endpoints/evaluate.py) (Evaluation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User experience"]
  node_frontend["Application shell<br/>[App.tsx]"]
  node_upload["PDF validation and submission"]
  node_viewer["PDF findings viewer"]
  node_chatui["Findings chatbot<br/>[chatbot.tsx]"]
  node_reportui["Assessment report UI<br/>[ReportPage.tsx]"]
end

subgraph group_api["API and identity"]
  node_server["FastAPI application<br/>[server.py]"]
  node_authapi["Authentication API<br/>[user_auth.py]"]
  node_authrepo[("User repository<br/>[user_repository.py]")]
  node_evaluate["Evaluation API<br/>[evaluate.py]"]
  node_chatapi["Chat API<br/>[chat.py]"]
  node_reportsapi["Reports API<br/>[reports.py]"]
end

subgraph group_audit["Document audit"]
  node_pipeline["Multistep audit pipeline<br/>[pipelines.py]"]
  node_parsechunk["Parse and chunk<br/>[chunker.py]"]
  node_findings["Findings parsing<br/>[findings_parser.py]"]
  node_auditconfig["LLM configuration<br/>[core.py]"]
  node_generator["Resilient generation"]
end

subgraph group_knowledge["Knowledge and tools"]
  node_search["Web search tool<br/>[exa.py]"]
  node_knowledge_tool["Knowledge tools<br/>[knowledge.py]"]
  node_kb_repo["Knowledge repository<br/>[repository.py]"]
  node_qdrant[("Qdrant knowledge store<br/>[qdrant.py]")]
end

subgraph group_report["Progress and reporting"]
  node_progress["Evaluation progress<br/>[progress.py]"]
  node_session[("Session management<br/>[session_manager.py]")]
  node_reportpdf["PDF report export<br/>[ReportPdf.tsx]"]
end

node_person(("Team member"))
node_openrouter{{"OpenRouter"}}
node_exa{{"Exa search service"}}

node_person -->|"uses"| node_frontend
node_frontend -->|"submits PDF"| node_upload
node_frontend -->|"shows findings"| node_viewer
node_frontend -->|"opens chat"| node_chatui
node_frontend -->|"opens reports"| node_reportui
node_upload -->|"starts evaluation"| node_evaluate
node_evaluate -.->|"runs audit"| node_pipeline
node_pipeline -->|"parses and chunks"| node_parsechunk
node_pipeline -->|"parses findings"| node_findings
node_pipeline -.->|"uses configuration"| node_auditconfig
node_pipeline -->|"generates audit"| node_generator
node_generator -.->|"calls model"| node_openrouter
node_pipeline -->|"uses web search"| node_search
node_search -.->|"searches web"| node_exa
node_chatui -->|"sends chat"| node_chatapi
node_chatapi -.->|"uses tools"| node_knowledge_tool
node_knowledge_tool -->|"queries and saves"| node_kb_repo
node_pipeline -->|"retrieves policies"| node_kb_repo
node_kb_repo -->|"selects backend"| node_qdrant
node_server -->|"registers route"| node_evaluate
node_server -->|"registers route"| node_chatapi
node_server -->|"registers route"| node_reportsapi
node_server -->|"registers route"| node_authapi
node_authapi -->|"uses repository"| node_authrepo
node_person -->|"authenticates"| node_authapi
node_frontend -.->|"polls progress"| node_progress
node_evaluate -.->|"tracks stages"| node_progress
node_frontend -.->|"loads sessions"| node_session
node_reportui -.->|"requests reports"| node_reportsapi
node_reportui -->|"exports PDF"| node_reportpdf
node_reportsapi -.->|"reads assessment history"| node_session

click node_frontend "https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/App.tsx"
click node_upload "https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/lib/helpers/evaluate_document.ts"
click node_viewer "https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/components/document-preview/DocumentPreview.tsx"
click node_chatui "https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/components/chatbot.tsx"
click node_reportui "https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/components/report/ReportPage.tsx"
click node_server "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/server.py"
click node_authapi "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/endpoints/user_auth.py"
click node_authrepo "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/auth/user_repository.py"
click node_evaluate "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/endpoints/evaluate.py"
click node_chatapi "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/endpoints/chat.py"
click node_reportsapi "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/endpoints/reports.py"
click node_pipeline "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py"
click node_parsechunk "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/preprocessors/multistep/components/chunker.py"
click node_findings "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/preprocessors/multistep/components/findings_parser.py"
click node_auditconfig "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/core.py"
click node_generator "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/resilient_generator.py"
click node_search "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/tools/exa.py"
click node_knowledge_tool "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/tools/knowledge.py"
click node_kb_repo "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/knowledge_base/repository.py"
click node_qdrant "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/knowledge_base/qdrant.py"
click node_progress "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/knowledge_base/progress.py"
click node_session "https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/knowledge_base/session_manager.py"
click node_reportpdf "https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/components/report/ReportPdf.tsx"

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,node_upload,node_viewer,node_chatui,node_reportui toneBlue
class node_server,node_authapi,node_authrepo,node_evaluate,node_chatapi,node_reportsapi toneAmber
class node_pipeline,node_parsechunk,node_findings,node_auditconfig,node_generator,node_openrouter toneMint
class node_search,node_knowledge_tool,node_kb_repo,node_qdrant toneRose
class node_progress,node_session,node_reportpdf,node_person,node_exa toneIndigo
```

## Components

### User experience

- [Application shell](https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/App.tsx): `cheshire-frontend/src/App.tsx`
- [PDF validation and submission](https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/lib/helpers/evaluate_document.ts): `cheshire-frontend/src/lib/helpers/evaluate_document.ts`
- [PDF findings viewer](https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/components/document-preview/DocumentPreview.tsx): `cheshire-frontend/src/components/document-preview/DocumentPreview.tsx`
- [Findings chatbot](https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/components/chatbot.tsx): `cheshire-frontend/src/components/chatbot.tsx`
- [Assessment report UI](https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/components/report/ReportPage.tsx): `cheshire-frontend/src/components/report/ReportPage.tsx`

### API and identity

- [FastAPI application](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/server.py): `cheshire-backend/src/server.py`
- [Authentication API](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/endpoints/user_auth.py): `cheshire-backend/src/endpoints/user_auth.py`
- [User repository](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/auth/user_repository.py): `cheshire-backend/src/auth/user_repository.py`
- [Evaluation API](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/endpoints/evaluate.py): `cheshire-backend/src/endpoints/evaluate.py`
- [Chat API](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/endpoints/chat.py): `cheshire-backend/src/endpoints/chat.py`
- [Reports API](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/endpoints/reports.py): `cheshire-backend/src/endpoints/reports.py`

### Document audit

- [Multistep audit pipeline](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py): `cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py`
- [Parse and chunk](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/preprocessors/multistep/components/chunker.py): `cheshire-backend/src/cheshire_configs/preprocessors/multistep/components/chunker.py`
- [Findings parsing](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/preprocessors/multistep/components/findings_parser.py): `cheshire-backend/src/cheshire_configs/preprocessors/multistep/components/findings_parser.py`
- [LLM configuration](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/core.py): `cheshire-backend/src/cheshire_configs/core.py`
- [Resilient generation](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/cheshire_configs/resilient_generator.py): `cheshire-backend/src/cheshire_configs/resilient_generator.py`

### Knowledge and tools

- [Web search tool](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/tools/exa.py): `cheshire-backend/src/tools/exa.py`
- [Knowledge tools](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/tools/knowledge.py): `cheshire-backend/src/tools/knowledge.py`
- [Knowledge repository](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/knowledge_base/repository.py): `cheshire-backend/src/knowledge_base/repository.py`
- [Qdrant knowledge store](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/knowledge_base/qdrant.py): `cheshire-backend/src/knowledge_base/qdrant.py`

### Progress and reporting

- [Evaluation progress](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/knowledge_base/progress.py): `cheshire-backend/src/knowledge_base/progress.py`
- [Session management](https://github.com/team-acatche/cheshire/blob/main/cheshire-backend/src/knowledge_base/session_manager.py): `cheshire-backend/src/knowledge_base/session_manager.py`
- [PDF report export](https://github.com/team-acatche/cheshire/blob/main/cheshire-frontend/src/components/report/ReportPdf.tsx): `cheshire-frontend/src/components/report/ReportPdf.tsx`

### Other components

- **Team member**
- **OpenRouter**
- **Exa search service**

## Connections

- Team member → Application shell: uses (evidence: `README.md`)
- Application shell → PDF validation and submission: submits PDF (evidence: `cheshire-frontend/src/App.tsx`)
- Application shell → PDF findings viewer: shows findings (evidence: `cheshire-frontend/src/App.tsx`)
- Application shell → Findings chatbot: opens chat (evidence: `cheshire-frontend/src/App.tsx`)
- Application shell → Assessment report UI: opens reports (evidence: `cheshire-frontend/src/App.tsx`)
- PDF validation and submission → Evaluation API: starts evaluation (evidence: `README.md`)
- Evaluation API → Multistep audit pipeline: runs audit
- Multistep audit pipeline → Parse and chunk: parses and chunks (evidence: `cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py`)
- Multistep audit pipeline → Findings parsing: parses findings (evidence: `cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py`)
- Multistep audit pipeline → LLM configuration: uses configuration
- Multistep audit pipeline → Resilient generation: generates audit (evidence: `cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py`)
- Resilient generation → OpenRouter: calls model
- Multistep audit pipeline → Web search tool: uses web search (evidence: `cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py`)
- Web search tool → Exa search service: searches web
- Findings chatbot → Chat API: sends chat (evidence: `README.md`)
- Chat API → Knowledge tools: uses tools
- Knowledge tools → Knowledge repository: queries and saves (evidence: `cheshire-backend/src/tools/knowledge.py`)
- Multistep audit pipeline → Knowledge repository: retrieves policies (evidence: `cheshire-backend/src/cheshire_configs/preprocessors/multistep/pipelines.py`)
- Knowledge repository → Qdrant knowledge store: selects backend (evidence: `cheshire-backend/src/knowledge_base/repository.py`)
- FastAPI application → Evaluation API: registers route (evidence: `cheshire-backend/src/server.py`)
- FastAPI application → Chat API: registers route (evidence: `cheshire-backend/src/server.py`)
- FastAPI application → Reports API: registers route (evidence: `cheshire-backend/src/server.py`)
- FastAPI application → Authentication API: registers route (evidence: `cheshire-backend/src/server.py`)
- Authentication API → User repository: uses repository (evidence: `cheshire-backend/src/endpoints/user_auth.py`)
- Team member → Authentication API: authenticates (evidence: `README.md`)
- Application shell → Evaluation progress: polls progress
- Evaluation API → Evaluation progress: tracks stages (evidence: `cheshire-backend/src/endpoints/evaluate.py`)
- Application shell → Session management: loads sessions
- Assessment report UI → Reports API: requests reports
- Assessment report UI → PDF report export: exports PDF (evidence: `README.md`)
- Reports API → Session management: reads assessment history
