# richie010/ai-tcase architecture

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

- Interactive diagram: https://gitdiagram.com/richie010/ai-tcase
- Repository: https://github.com/richie010/ai-tcase

## Overview

AI Test Case Portal accepts requirement documents, creates test cases with Gemini-backed retrieval, and returns a formatted Excel workbook. The main path is browser upload → FastAPI job dispatch → extraction, chunking, embedding/retrieval and generation → workbook export → status polling and download. The README also describes positive, negative, boundary, and edge coverage. Edges follow the cited route and pipeline calls; the README supports the documented embedding and retrieval stages where source wiring is incomplete.

Main entry points: [`backend/app/jobs.py`](https://github.com/richie010/ai-tcase/blob/master/backend/app/jobs.py) (Job Orchestration), [`backend/app/main.py`](https://github.com/richie010/ai-tcase/blob/master/backend/app/main.py) (HTTP Routes), [`backend/app/testcase_generator.py`](https://github.com/richie010/ai-tcase/blob/master/backend/app/testcase_generator.py) (RAG Test Generation), [`frontend/app.js`](https://github.com/richie010/ai-tcase/blob/master/frontend/app.js) (Upload and Results UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Portal UI"]
  node_browser["Upload and Results UI<br/>[app.js]"]
end

subgraph group_api["API and Jobs"]
  node_routes["HTTP Routes<br/>[main.py]"]
  node_job["Job Orchestration<br/>[jobs.py]"]
  node_jobstate[("In-Memory Job State<br/>[jobs.py]")]
  node_schemas["Job and Data Models<br/>[models.py]"]
  node_config["Runtime Settings<br/>[config.py]"]
end

subgraph group_pipeline["Requirement Processing"]
  node_extract["Document Extraction<br/>[extraction.py]"]
  node_chunks["Section Chunking<br/>[chunking.py]"]
end

subgraph group_rag["RAG Generation"]
  node_embed["Gemini Embeddings<br/>[gemini_client.py]"]
  node_store[("Cosine Vector Store<br/>[vector_store.py]")]
  node_generator["RAG Test Generation"]
end

subgraph group_output["Workbook Output"]
  node_export["Excel Workbook Export<br/>[excel_export.py]"]
  node_workbook["Generated Workbook"]
end

node_user(("User"))
node_gemini{{"Gemini API"}}

node_user -->|"uploads files"| node_browser
node_browser -->|"submits job"| node_routes
node_routes -->|"creates and dispatches"| node_job
node_routes -->|"reads status"| node_jobstate
node_job -->|"updates state"| node_jobstate
node_job -->|"extracts documents"| node_extract
node_job -->|"chunks sections"| node_chunks
node_job -->|"embeds chunks"| node_embed
node_job -->|"generates cases"| node_generator
node_job -->|"exports cases"| node_export
node_job -->|"reads settings"| node_config
node_extract -.->|"produces sections"| node_schemas
node_chunks -->|"creates chunks"| node_schemas
node_generator -->|"creates test cases"| node_schemas
node_export -->|"reads test cases"| node_schemas
node_generator -->|"embeds queries"| node_embed
node_generator -->|"searches chunks"| node_store
node_job -.->|"stores embeddings"| node_store
node_embed -->|"requests embeddings"| node_gemini
node_generator -->|"requests generation"| node_gemini
node_embed -->|"reads settings"| node_config
node_export -->|"writes workbook"| node_workbook
node_routes -->|"serves frontend"| node_browser
node_browser -->|"polls job"| node_routes
node_browser -->|"downloads workbook"| node_routes
node_routes -->|"serves download"| node_workbook

click node_browser "https://github.com/richie010/ai-tcase/blob/master/frontend/app.js"
click node_routes "https://github.com/richie010/ai-tcase/blob/master/backend/app/main.py"
click node_job "https://github.com/richie010/ai-tcase/blob/master/backend/app/jobs.py"
click node_jobstate "https://github.com/richie010/ai-tcase/blob/master/backend/app/jobs.py"
click node_schemas "https://github.com/richie010/ai-tcase/blob/master/backend/app/models.py"
click node_config "https://github.com/richie010/ai-tcase/blob/master/backend/app/config.py"
click node_extract "https://github.com/richie010/ai-tcase/blob/master/backend/app/extraction.py"
click node_chunks "https://github.com/richie010/ai-tcase/blob/master/backend/app/chunking.py"
click node_embed "https://github.com/richie010/ai-tcase/blob/master/backend/app/gemini_client.py"
click node_store "https://github.com/richie010/ai-tcase/blob/master/backend/app/vector_store.py"
click node_generator "https://github.com/richie010/ai-tcase/blob/master/backend/app/testcase_generator.py"
click node_export "https://github.com/richie010/ai-tcase/blob/master/backend/app/excel_export.py"
click node_workbook "https://github.com/richie010/ai-tcase/tree/master/backend/data/exports"

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_browser,node_user toneBlue
class node_routes,node_job,node_jobstate,node_schemas,node_config toneAmber
class node_extract,node_chunks,node_gemini toneMint
class node_embed,node_store,node_generator toneRose
class node_export,node_workbook toneIndigo
```

## Components

### Portal UI

- [Upload and Results UI](https://github.com/richie010/ai-tcase/blob/master/frontend/app.js): `frontend/app.js`

### API and Jobs

- [HTTP Routes](https://github.com/richie010/ai-tcase/blob/master/backend/app/main.py): `backend/app/main.py`
- [Job Orchestration](https://github.com/richie010/ai-tcase/blob/master/backend/app/jobs.py): `backend/app/jobs.py`
- [In-Memory Job State](https://github.com/richie010/ai-tcase/blob/master/backend/app/jobs.py): `backend/app/jobs.py`
- [Job and Data Models](https://github.com/richie010/ai-tcase/blob/master/backend/app/models.py): `backend/app/models.py`
- [Runtime Settings](https://github.com/richie010/ai-tcase/blob/master/backend/app/config.py): `backend/app/config.py`

### Requirement Processing

- [Document Extraction](https://github.com/richie010/ai-tcase/blob/master/backend/app/extraction.py): `backend/app/extraction.py`
- [Section Chunking](https://github.com/richie010/ai-tcase/blob/master/backend/app/chunking.py): `backend/app/chunking.py`

### RAG Generation

- [Gemini Embeddings](https://github.com/richie010/ai-tcase/blob/master/backend/app/gemini_client.py): `backend/app/gemini_client.py`
- [Cosine Vector Store](https://github.com/richie010/ai-tcase/blob/master/backend/app/vector_store.py): `backend/app/vector_store.py`
- [RAG Test Generation](https://github.com/richie010/ai-tcase/blob/master/backend/app/testcase_generator.py): `backend/app/testcase_generator.py`

### Workbook Output

- [Excel Workbook Export](https://github.com/richie010/ai-tcase/blob/master/backend/app/excel_export.py): `backend/app/excel_export.py`
- [Generated Workbook](https://github.com/richie010/ai-tcase/tree/master/backend/data/exports): `backend/data/exports`

### Other components

- **User**
- **Gemini API**

## Connections

- User → Upload and Results UI: uploads files (evidence: `frontend/app.js`)
- Upload and Results UI → HTTP Routes: submits job (evidence: `frontend/app.js`)
- HTTP Routes → Job Orchestration: creates and dispatches (evidence: `backend/app/main.py`)
- HTTP Routes → In-Memory Job State: reads status (evidence: `backend/app/main.py`)
- Job Orchestration → In-Memory Job State: updates state (evidence: `backend/app/jobs.py`)
- Job Orchestration → Document Extraction: extracts documents (evidence: `backend/app/jobs.py`)
- Job Orchestration → Section Chunking: chunks sections (evidence: `backend/app/jobs.py`)
- Job Orchestration → Gemini Embeddings: embeds chunks (evidence: `backend/app/jobs.py`)
- Job Orchestration → RAG Test Generation: generates cases (evidence: `backend/app/jobs.py`)
- Job Orchestration → Excel Workbook Export: exports cases (evidence: `backend/app/jobs.py`)
- Job Orchestration → Runtime Settings: reads settings (evidence: `backend/app/jobs.py`)
- Document Extraction → Job and Data Models: produces sections
- Section Chunking → Job and Data Models: creates chunks (evidence: `backend/app/chunking.py`)
- RAG Test Generation → Job and Data Models: creates test cases (evidence: `backend/app/testcase_generator.py`)
- Excel Workbook Export → Job and Data Models: reads test cases (evidence: `backend/app/excel_export.py`)
- RAG Test Generation → Gemini Embeddings: embeds queries (evidence: `backend/app/testcase_generator.py`)
- RAG Test Generation → Cosine Vector Store: searches chunks (evidence: `backend/app/testcase_generator.py`)
- Job Orchestration → Cosine Vector Store: stores embeddings (evidence: `backend/app/jobs.py`)
- Gemini Embeddings → Gemini API: requests embeddings (evidence: `backend/app/gemini_client.py`)
- RAG Test Generation → Gemini API: requests generation
- Gemini Embeddings → Runtime Settings: reads settings (evidence: `backend/app/gemini_client.py`)
- Excel Workbook Export → Generated Workbook: writes workbook (evidence: `backend/app/excel_export.py`)
- HTTP Routes → Upload and Results UI: serves frontend (evidence: `backend/app/main.py`)
- Upload and Results UI → HTTP Routes: polls job (evidence: `frontend/app.js`)
- Upload and Results UI → HTTP Routes: downloads workbook (evidence: `frontend/app.js`)
- HTTP Routes → Generated Workbook: serves download (evidence: `backend/app/main.py`)
