# vedlegendary/gdg-askutd architecture

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

- Interactive diagram: https://gitdiagram.com/vedlegendary/gdg-askutd
- Repository: https://github.com/vedlegendary/gdg-askutd

## Overview

AskUTD is a UTD-information question-answering app: a browser submits a question, the API retrieves relevant official-source passages, and answer generation returns concise cited text or abstains. The graph preserves the UI/API, retrieval and generation stages, plus storage, catalog and feedback capabilities. Corpus ingestion is an offline supporting workflow, not part of answering a request. Several links rely on the README because their implementation excerpts were not provided.

Main entry points: [`backend/app/main.py`](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/generation.py`](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/generation.py) (Answer generator), [`backend/app/routes/chat.py`](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/routes/chat.py) (Chat route), [`backend/app/retrieval.py`](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval.py) (Retrieval service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser experience"]
  node_ui["AskUTD interface<br/>[ask-utd-app.tsx]"]
  node_api_client["Web API client<br/>[api.ts]"]
end

subgraph group_service["API service"]
  node_api["FastAPI app<br/>[main.py]"]
  node_chat["Chat route<br/>[chat.py]"]
  node_catalog["Catalog route<br/>[catalog.py]"]
  node_feedback["Feedback route<br/>[feedback.py]"]
  node_health["Health route<br/>[health.py]"]
  node_limiter["Rate limiter<br/>[ratelimit.py]"]
  node_contracts["Shared answer types<br/>[types.py]"]
end

subgraph group_search["Evidence retrieval"]
  node_retrieval["Retrieval service<br/>[retrieval.py]"]
  node_index["Lexical index<br/>[index.py]"]
  node_query_checks["Query resolution<br/>[query.py]"]
  node_focus["Intent and scope<br/>[focus.py]"]
  node_precision["Evidence checks<br/>[precision.py]"]
end

subgraph group_answer["Answer generation"]
  node_generation["Answer generator<br/>[generation.py]"]
  node_prompts["Answer prompts<br/>[prompts.py]"]
  node_extractive["Extractive fallback<br/>[extractive.py]"]
  node_providers["Model providers"]
end

subgraph group_operations["Corpus and records"]
  node_database[("SQLite records<br/>[db.py]")]
  node_ingestion["PDF ingestion<br/>[add_documents.py]"]
  node_pdf_text["PDF text extraction<br/>[pdf_to_text.py]"]
end

node_student(("Student"))

node_student -->|"asks"| node_ui
node_ui -->|"submits questions"| node_api_client
node_api_client -->|"calls API"| node_api
node_api -->|"routes requests"| node_chat
node_api -->|"routes requests"| node_catalog
node_api -->|"routes requests"| node_feedback
node_api -->|"routes requests"| node_health
node_api -->|"configures"| node_limiter
node_api -->|"initializes"| node_database
node_chat -->|"requests passages"| node_retrieval
node_chat -->|"requests answer"| node_generation
node_retrieval -->|"searches chunks"| node_index
node_retrieval -->|"resolves and checks"| node_query_checks
node_retrieval -->|"reranks evidence"| node_precision
node_query_checks -->|"uses intent rules"| node_focus
node_precision -->|"uses scope rules"| node_focus
node_generation -->|"uses prompts"| node_prompts
node_generation -->|"selects fallback"| node_extractive
node_generation -->|"selects provider"| node_providers
node_generation -->|"checks answer focus"| node_focus
node_generation -->|"checks evidence"| node_precision
node_chat -->|"uses shared types"| node_contracts
node_retrieval -->|"returns passages"| node_contracts
node_generation -->|"returns answer"| node_contracts
node_feedback -->|"stores feedback"| node_database
node_chat -->|"records requests"| node_database
node_ui -->|"sends ratings"| node_feedback
node_catalog -.->|"reads catalog"| node_database
node_ingestion -->|"extracts text"| node_pdf_text

click node_ui "https://github.com/vedlegendary/gdg-askutd/blob/main/components/ask-utd-app.tsx"
click node_api_client "https://github.com/vedlegendary/gdg-askutd/blob/main/lib/api.ts"
click node_api "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/main.py"
click node_chat "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/routes/chat.py"
click node_catalog "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/routes/catalog.py"
click node_feedback "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/routes/feedback.py"
click node_health "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/routes/health.py"
click node_limiter "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/ratelimit.py"
click node_retrieval "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval.py"
click node_index "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval_support/index.py"
click node_query_checks "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval_support/query.py"
click node_focus "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval_support/focus.py"
click node_precision "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval_support/precision.py"
click node_generation "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/generation.py"
click node_prompts "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/prompts.py"
click node_extractive "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/llm/extractive.py"
click node_providers "https://github.com/vedlegendary/gdg-askutd/tree/main/backend/app/llm"
click node_contracts "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/types.py"
click node_database "https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/db.py"
click node_ingestion "https://github.com/vedlegendary/gdg-askutd/blob/main/add_documents.py"
click node_pdf_text "https://github.com/vedlegendary/gdg-askutd/blob/main/pdf_to_text.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_ui,node_api_client toneBlue
class node_api,node_chat,node_catalog,node_feedback,node_health,node_limiter,node_contracts toneAmber
class node_retrieval,node_index,node_query_checks,node_focus,node_precision toneMint
class node_generation,node_prompts,node_extractive,node_providers toneRose
class node_database,node_ingestion,node_pdf_text,node_student toneIndigo
```

## Components

### Browser experience

- [AskUTD interface](https://github.com/vedlegendary/gdg-askutd/blob/main/components/ask-utd-app.tsx): `components/ask-utd-app.tsx`
- [Web API client](https://github.com/vedlegendary/gdg-askutd/blob/main/lib/api.ts): `lib/api.ts`

### API service

- [FastAPI app](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat route](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/routes/chat.py): `backend/app/routes/chat.py`
- [Catalog route](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/routes/catalog.py): `backend/app/routes/catalog.py`
- [Feedback route](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/routes/feedback.py): `backend/app/routes/feedback.py`
- [Health route](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/routes/health.py): `backend/app/routes/health.py`
- [Rate limiter](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/ratelimit.py): `backend/app/ratelimit.py`
- [Shared answer types](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/types.py): `backend/app/types.py`

### Evidence retrieval

- [Retrieval service](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval.py): `backend/app/retrieval.py`
- [Lexical index](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval_support/index.py): `backend/app/retrieval_support/index.py`
- [Query resolution](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval_support/query.py): `backend/app/retrieval_support/query.py`
- [Intent and scope](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval_support/focus.py): `backend/app/retrieval_support/focus.py`
- [Evidence checks](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/retrieval_support/precision.py): `backend/app/retrieval_support/precision.py`

### Answer generation

- [Answer generator](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/generation.py): `backend/app/generation.py`
- [Answer prompts](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/prompts.py): `backend/app/prompts.py`
- [Extractive fallback](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/llm/extractive.py): `backend/app/llm/extractive.py`
- [Model providers](https://github.com/vedlegendary/gdg-askutd/tree/main/backend/app/llm): `backend/app/llm`

### Corpus and records

- [SQLite records](https://github.com/vedlegendary/gdg-askutd/blob/main/backend/app/db.py): `backend/app/db.py`
- [PDF ingestion](https://github.com/vedlegendary/gdg-askutd/blob/main/add_documents.py): `add_documents.py`
- [PDF text extraction](https://github.com/vedlegendary/gdg-askutd/blob/main/pdf_to_text.py): `pdf_to_text.py`

### Other components

- **Student**

## Connections

- Student → AskUTD interface: asks (evidence: `README.md`)
- AskUTD interface → Web API client: submits questions (evidence: `components/ask-utd-app.tsx`)
- Web API client → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Chat route: routes requests (evidence: `backend/app/main.py`)
- FastAPI app → Catalog route: routes requests (evidence: `backend/app/main.py`)
- FastAPI app → Feedback route: routes requests (evidence: `backend/app/main.py`)
- FastAPI app → Health route: routes requests (evidence: `backend/app/main.py`)
- FastAPI app → Rate limiter: configures (evidence: `backend/app/main.py`)
- FastAPI app → SQLite records: initializes (evidence: `backend/app/main.py`)
- Chat route → Retrieval service: requests passages (evidence: `README.md`)
- Chat route → Answer generator: requests answer (evidence: `README.md`)
- Retrieval service → Lexical index: searches chunks (evidence: `backend/app/retrieval.py`)
- Retrieval service → Query resolution: resolves and checks (evidence: `backend/app/retrieval.py`)
- Retrieval service → Evidence checks: reranks evidence (evidence: `backend/app/retrieval.py`)
- Query resolution → Intent and scope: uses intent rules (evidence: `backend/app/retrieval_support/query.py`)
- Evidence checks → Intent and scope: uses scope rules (evidence: `backend/app/retrieval_support/precision.py`)
- Answer generator → Answer prompts: uses prompts (evidence: `backend/app/generation.py`)
- Answer generator → Extractive fallback: selects fallback (evidence: `backend/app/generation.py`)
- Answer generator → Model providers: selects provider (evidence: `README.md`)
- Answer generator → Intent and scope: checks answer focus (evidence: `backend/app/generation.py`)
- Answer generator → Evidence checks: checks evidence (evidence: `backend/app/generation.py`)
- Chat route → Shared answer types: uses shared types (evidence: `backend/app/routes/chat.py`)
- Retrieval service → Shared answer types: returns passages (evidence: `backend/app/retrieval.py`)
- Answer generator → Shared answer types: returns answer (evidence: `backend/app/generation.py`)
- Feedback route → SQLite records: stores feedback (evidence: `README.md`)
- Chat route → SQLite records: records requests (evidence: `README.md`)
- AskUTD interface → Feedback route: sends ratings (evidence: `components/ask-utd-app.tsx`)
- Catalog route → SQLite records: reads catalog
- PDF ingestion → PDF text extraction: extracts text (evidence: `add_documents.py`)