# q-ai-adhd/q-ai_ai architecture

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

- Interactive diagram: https://gitdiagram.com/q-ai-adhd/q-ai_ai
- Repository: https://github.com/q-ai-adhd/q-ai_ai

## Overview

This is a small FastAPI application for Korean technical-interview question generation and answer feedback, using prompt templates and a locally loaded llama.cpp model. The principal workflows are POST question request → question prompt → model generation → question response, and POST feedback request → feedback prompt → model generation → feedback response. The README only documents llama-cpp-python installation; workflow links are evidenced by main.py. The feedback schema excerpt does not define the feedback classes imported there, so its precise request/response fields are uncertain.

Main entry points: [`main.py`](https://github.com/q-ai-adhd/q-ai_ai/blob/main/main.py) (FastAPI Handlers), [`prompt/question_prompt.py`](https://github.com/q-ai-adhd/q-ai_ai/blob/main/prompt/question_prompt.py) (Question Prompt), [`prompt/feedback_prompt.py`](https://github.com/q-ai-adhd/q-ai_ai/blob/main/prompt/feedback_prompt.py) (Feedback Prompt), [`schemas/questSchema.py`](https://github.com/q-ai-adhd/q-ai_ai/blob/main/schemas/questSchema.py) (Question Schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_api["FastAPI Handlers<br/>[main.py]"]
end

subgraph group_prompts["Prompt Templates"]
  node_question_prompt["Question Prompt<br/>[question_prompt.py]"]
  node_feedback_prompt["Feedback Prompt<br/>[feedback_prompt.py]"]
end

subgraph group_contracts["Request Contracts"]
  node_question_schema["Question Schema<br/>[questSchema.py]"]
  node_feedback_schema["Feedback Schema<br/>[feedbackSchema.py]"]
end

node_client(("API Client"))
node_llama["Local llama.cpp"]

node_client -->|"posts requests"| node_api
node_api -->|"validates and shapes"| node_question_schema
node_api -->|"uses feedback types"| node_feedback_schema
node_api -->|"builds question prompt"| node_question_prompt
node_api -->|"builds feedback prompt"| node_feedback_prompt
node_api -->|"generates output"| node_llama
node_api -->|"returns responses"| node_client

click node_api "https://github.com/q-ai-adhd/q-ai_ai/blob/main/main.py"
click node_question_prompt "https://github.com/q-ai-adhd/q-ai_ai/blob/main/prompt/question_prompt.py"
click node_feedback_prompt "https://github.com/q-ai-adhd/q-ai_ai/blob/main/prompt/feedback_prompt.py"
click node_question_schema "https://github.com/q-ai-adhd/q-ai_ai/blob/main/schemas/questSchema.py"
click node_feedback_schema "https://github.com/q-ai-adhd/q-ai_ai/blob/main/schemas/feedbackSchema.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_api,node_client toneBlue
class node_question_prompt,node_feedback_prompt toneAmber
class node_question_schema,node_feedback_schema toneMint
class node_llama toneIndigo
```

## Components

### API

- [FastAPI Handlers](https://github.com/q-ai-adhd/q-ai_ai/blob/main/main.py): `main.py`

### Prompt Templates

- [Question Prompt](https://github.com/q-ai-adhd/q-ai_ai/blob/main/prompt/question_prompt.py): `prompt/question_prompt.py`
- [Feedback Prompt](https://github.com/q-ai-adhd/q-ai_ai/blob/main/prompt/feedback_prompt.py): `prompt/feedback_prompt.py`

### Request Contracts

- [Question Schema](https://github.com/q-ai-adhd/q-ai_ai/blob/main/schemas/questSchema.py): `schemas/questSchema.py`
- [Feedback Schema](https://github.com/q-ai-adhd/q-ai_ai/blob/main/schemas/feedbackSchema.py): `schemas/feedbackSchema.py`

### Other components

- **API Client**
- **Local llama.cpp**

## Connections

- API Client → FastAPI Handlers: posts requests (evidence: `main.py`)
- FastAPI Handlers → Question Schema: validates and shapes (evidence: `main.py`)
- FastAPI Handlers → Feedback Schema: uses feedback types (evidence: `main.py`)
- FastAPI Handlers → Question Prompt: builds question prompt (evidence: `main.py`)
- FastAPI Handlers → Feedback Prompt: builds feedback prompt (evidence: `main.py`)
- FastAPI Handlers → Local llama.cpp: generates output (evidence: `main.py`)
- FastAPI Handlers → API Client: returns responses (evidence: `main.py`)
