# small-fish-qaq/hy3-study-clinic architecture

> Architecture diagram of the GitHub repository small-fish-qaq/hy3-study-clinic, 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/small-fish-qaq/hy3-study-clinic
- Repository: https://github.com/small-fish-qaq/hy3-study-clinic

## Overview

Hy3 Study Clinic is a local, course-centred learning app: learners import their own material, confirm a course plan, study generated explanations and exercises, ask a tutor follow-ups, and revisit mistakes or formal results. The graph follows that documented workflow and includes source-grounding, model-provider, persistence, and review capabilities. README statements support the product-level flow; sampled server excerpts establish app route registration. Most service internals and route-to-service calls were not sampled, so those links are omitted rather than inferred.

Main entry points: [`apps/server/src/services/curriculum.ts`](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/curriculum.ts) (Curriculum planning), [`apps/server/src/repositories`](https://github.com/small-fish-qaq/hy3-study-clinic/tree/main/apps/server/src/repositories) (Learning repositories), [`apps/web/src/App.tsx`](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/web/src/App.tsx) (Course interface), [`apps/server/src/llm/prompts.ts`](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/llm/prompts.ts) (Teaching generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_webapp["Course interface<br/>[App.tsx]"]
  node_webapi["Web API client<br/>[api.ts]"]
  node_studyui["Study session UI"]
end

subgraph group_course["Course preparation"]
  node_ingestion["Material ingestion<br/>[ingest.ts]"]
  node_curriculum["Curriculum planning<br/>[curriculum.ts]"]
  node_evidence["Curriculum evidence"]
  node_sourceauthority["Source authority<br/>[sourceAuthority.ts]"]
end

subgraph group_instruction["Teaching and assessment"]
  node_teaching["Teaching generation<br/>[prompts.ts]"]
  node_provider["Model provider<br/>[provider.ts]"]
  node_lessons["Lessons and practice<br/>[lessons.ts]"]
  node_tutor["Tutor support<br/>[tutor.ts]"]
  node_repair["Practice recovery"]
  node_formal["Formal assessment"]
  node_review["Spaced review<br/>[reviewSuccessor.ts]"]
end

subgraph group_platform["Server platform"]
  node_server["HTTP application<br/>[app.ts]"]
  node_routes["API routes"]
  node_repositories["Learning repositories"]
  node_sqlite[("SQLite database<br/>[database.ts]")]
end

subgraph group_contracts["Shared domain"]
  node_domain["Shared domain contracts"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_webapp
node_webapp -->|"requests data"| node_webapi
node_webapp -.->|"presents study"| node_studyui
node_webapi -.->|"calls API"| node_server
node_server -->|"registers routes"| node_routes
node_learner -->|"provides materials"| node_ingestion
node_ingestion -.->|"prepares course"| node_curriculum
node_learner -->|"confirms plan"| node_curriculum
node_curriculum -.->|"grounds selection"| node_evidence
node_evidence -.->|"uses authority"| node_sourceauthority
node_curriculum -->|"prepares instruction"| node_teaching
node_teaching -.->|"generates content"| node_provider
node_learner -->|"studies lessons"| node_lessons
node_learner -->|"asks follow-ups"| node_tutor
node_learner -->|"retries mistakes"| node_repair
node_learner -->|"submits assessment"| node_formal
node_learner -->|"resumes learning"| node_review
node_lessons -.->|"saves learning"| node_repositories
node_formal -->|"records results"| node_repositories
node_repositories -.->|"persists state"| node_sqlite
node_review -->|"updates review"| node_repositories
node_teaching -.->|"uses contracts"| node_domain

click node_webapp "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/web/src/App.tsx"
click node_webapi "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/web/src/api.ts"
click node_studyui "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/web/src/views/StudySessionView.tsx"
click node_ingestion "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/ingestion/ingest.ts"
click node_curriculum "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/curriculum.ts"
click node_evidence "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/curriculumEvidence.ts"
click node_sourceauthority "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/packages/shared/src/domain/sourceAuthority.ts"
click node_teaching "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/llm/prompts.ts"
click node_provider "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/llm/provider.ts"
click node_lessons "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/lessons.ts"
click node_tutor "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/tutor.ts"
click node_repair "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/practiceRecovery.ts"
click node_formal "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/formalAssessments.ts"
click node_review "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/reviewSuccessor.ts"
click node_server "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/app.ts"
click node_routes "https://github.com/small-fish-qaq/hy3-study-clinic/tree/main/apps/server/src/routes"
click node_repositories "https://github.com/small-fish-qaq/hy3-study-clinic/tree/main/apps/server/src/repositories"
click node_sqlite "https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/db/database.ts"
click node_domain "https://github.com/small-fish-qaq/hy3-study-clinic/tree/main/packages/shared/src/domain"

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_webapi,node_studyui toneBlue
class node_ingestion,node_curriculum,node_evidence,node_sourceauthority toneAmber
class node_teaching,node_provider,node_lessons,node_tutor,node_repair,node_formal,node_review toneMint
class node_server,node_routes,node_repositories,node_sqlite toneRose
class node_domain,node_learner toneIndigo
```

## Components

### Learner experience

- [Course interface](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Web API client](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`
- [Study session UI](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/web/src/views/StudySessionView.tsx): `apps/web/src/views/StudySessionView.tsx`

### Course preparation

- [Material ingestion](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/ingestion/ingest.ts): `apps/server/src/ingestion/ingest.ts`
- [Curriculum planning](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/curriculum.ts): `apps/server/src/services/curriculum.ts`
- [Curriculum evidence](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/curriculumEvidence.ts): `apps/server/src/services/curriculumEvidence.ts`
- [Source authority](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/packages/shared/src/domain/sourceAuthority.ts): `packages/shared/src/domain/sourceAuthority.ts`

### Teaching and assessment

- [Teaching generation](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/llm/prompts.ts): `apps/server/src/llm/prompts.ts`
- [Model provider](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/llm/provider.ts): `apps/server/src/llm/provider.ts`
- [Lessons and practice](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/lessons.ts): `apps/server/src/services/lessons.ts`
- [Tutor support](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/tutor.ts): `apps/server/src/services/tutor.ts`
- [Practice recovery](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/practiceRecovery.ts): `apps/server/src/services/practiceRecovery.ts`
- [Formal assessment](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/formalAssessments.ts): `apps/server/src/services/formalAssessments.ts`
- [Spaced review](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/services/reviewSuccessor.ts): `apps/server/src/services/reviewSuccessor.ts`

### Server platform

- [HTTP application](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/app.ts): `apps/server/src/app.ts`
- [API routes](https://github.com/small-fish-qaq/hy3-study-clinic/tree/main/apps/server/src/routes): `apps/server/src/routes`
- [Learning repositories](https://github.com/small-fish-qaq/hy3-study-clinic/tree/main/apps/server/src/repositories): `apps/server/src/repositories`
- [SQLite database](https://github.com/small-fish-qaq/hy3-study-clinic/blob/main/apps/server/src/db/database.ts): `apps/server/src/db/database.ts`

### Shared domain

- [Shared domain contracts](https://github.com/small-fish-qaq/hy3-study-clinic/tree/main/packages/shared/src/domain): `packages/shared/src/domain`

### Other components

- **Learner**

## Connections

- Learner → Course interface: uses (evidence: `README.md`)
- Course interface → Web API client: requests data (evidence: `apps/web/src/App.tsx`)
- Course interface → Study session UI: presents study
- Web API client → HTTP application: calls API
- HTTP application → API routes: registers routes (evidence: `apps/server/src/app.ts`)
- Learner → Material ingestion: provides materials (evidence: `README.md`)
- Material ingestion → Curriculum planning: prepares course
- Learner → Curriculum planning: confirms plan (evidence: `README.md`)
- Curriculum planning → Curriculum evidence: grounds selection
- Curriculum evidence → Source authority: uses authority
- Curriculum planning → Teaching generation: prepares instruction (evidence: `README.md`)
- Teaching generation → Model provider: generates content (evidence: `apps/server/src/llm/prompts.ts`)
- Learner → Lessons and practice: studies lessons (evidence: `README.md`)
- Learner → Tutor support: asks follow-ups (evidence: `README.md`)
- Learner → Practice recovery: retries mistakes (evidence: `README.md`)
- Learner → Formal assessment: submits assessment (evidence: `README.md`)
- Learner → Spaced review: resumes learning (evidence: `README.md`)
- Lessons and practice → Learning repositories: saves learning
- Formal assessment → Learning repositories: records results (evidence: `README.md`)
- Learning repositories → SQLite database: persists state (evidence: `apps/server/src/repositories/reviewSuccessor.ts`)
- Spaced review → Learning repositories: updates review (evidence: `apps/server/src/services/reviewSuccessor.ts`)
- Teaching generation → Shared domain contracts: uses contracts
