# iskesss/readysetread architecture

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

- Interactive diagram: https://gitdiagram.com/iskesss/readysetread
- Repository: https://github.com/iskesss/readysetread

## Overview

ReadySetRead is a children’s reading app: students choose books, take quizzes, and earn or spend coins on rewards; adults manage children and review progress. The React routes lead into feature pages and typed API clients, which call the FastAPI service. The backend owns authentication, data access, quiz generation, and reward operations. README capabilities help identify subsystems not fully represented in the sampled source; their exact internal wiring is therefore omitted where it is not evidenced.

Main entry points: [`frontend/src/main.tsx`](https://github.com/iskesss/readysetread/blob/main/frontend/src/main.tsx) (App routes), [`frontend/src/api/client.ts`](https://github.com/iskesss/readysetread/blob/main/frontend/src/api/client.ts) (HTTP client), [`frontend/src/pages/StudentLanding.tsx`](https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/StudentLanding.tsx) (Student dashboard), [`frontend/src/pages/ParentProgress.tsx`](https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/ParentProgress.tsx) (Parent progress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_routes["App routes<br/>[main.tsx]"]
  node_auth_pages["Sign in and signup"]
  node_student_home["Student dashboard<br/>[StudentLanding.tsx]"]
  node_library_page["Book library<br/>[library.tsx]"]
  node_quiz_page["Quiz taking<br/>[Quiz.tsx]"]
  node_results_page["Quiz results<br/>[QuizResults.tsx]"]
  node_rewards_page["Rewards and skins<br/>[Rewards.tsx]"]
  node_parent_pages["Parent progress<br/>[ParentProgress.tsx]"]
end

subgraph group_clients["API clients"]
  node_api_client["HTTP client<br/>[client.ts]"]
  node_student_api["Student API<br/>[students.ts]"]
  node_parent_api["Parent API<br/>[parents.ts]"]
  node_books_api["Books API<br/>[books.ts]"]
  node_quiz_api["Quiz API<br/>[quiz.ts]"]
  node_rewards_api["Rewards API<br/>[rewards.ts]"]
end

subgraph group_service["Backend service"]
  node_service_app["FastAPI app<br/>[main.py]"]
  node_service_api["API routes<br/>[api.py]"]
  node_quiz_logic["Quiz generation and feedback<br/>[quiz_llm.py]"]
  node_database_access["Database access<br/>[db.py]"]
end

subgraph group_integrations["Data and AI"]
  node_postgres[("PostgreSQL")]
  node_openai["OpenAI"]
end

node_student(("Student"))
node_adult(("Parent or tutor"))

node_student -->|"uses app"| node_routes
node_adult -->|"uses app"| node_routes
node_routes -->|"routes to"| node_auth_pages
node_routes -->|"routes to"| node_student_home
node_routes -->|"routes to"| node_library_page
node_routes -->|"routes to"| node_quiz_page
node_routes -->|"routes to"| node_results_page
node_routes -->|"routes to"| node_rewards_page
node_routes -->|"routes to"| node_parent_pages
node_student_home -->|"loads assignments"| node_student_api
node_student_home -->|"loads books"| node_books_api
node_student_home -->|"loads skin"| node_rewards_api
node_student_home -->|"requests quiz"| node_quiz_api
node_parent_pages -->|"loads children"| node_parent_api
node_parent_pages -->|"loads assignments"| node_student_api
node_parent_pages -->|"loads books"| node_books_api
node_parent_pages -->|"creates reward"| node_rewards_api
node_auth_pages -->|"auth requests"| node_student_api
node_auth_pages -->|"auth requests"| node_parent_api
node_library_page -->|"loads books"| node_books_api
node_quiz_page -->|"submits answers"| node_quiz_api
node_results_page -->|"loads results"| node_quiz_api
node_rewards_page -->|"manages rewards"| node_rewards_api
node_student_api -->|"sends requests"| node_api_client
node_parent_api -->|"sends requests"| node_api_client
node_books_api -->|"sends requests"| node_api_client
node_quiz_api -->|"sends requests"| node_api_client
node_rewards_api -->|"sends requests"| node_api_client
node_api_client -->|"HTTP requests"| node_service_app
node_service_app -->|"mounts router"| node_service_api
node_service_app -->|"initializes pool"| node_database_access
node_service_api -->|"queries and updates"| node_database_access
node_service_api -->|"generates quiz"| node_quiz_logic
node_quiz_logic -->|"requests generation"| node_openai
node_database_access -->|"reads and writes"| node_postgres

click node_routes "https://github.com/iskesss/readysetread/blob/main/frontend/src/main.tsx"
click node_auth_pages "https://github.com/iskesss/readysetread/tree/main/frontend/src/pages"
click node_student_home "https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/StudentLanding.tsx"
click node_library_page "https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/library.tsx"
click node_quiz_page "https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/Quiz.tsx"
click node_results_page "https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/QuizResults.tsx"
click node_rewards_page "https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/Rewards.tsx"
click node_parent_pages "https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/ParentProgress.tsx"
click node_api_client "https://github.com/iskesss/readysetread/blob/main/frontend/src/api/client.ts"
click node_student_api "https://github.com/iskesss/readysetread/blob/main/frontend/src/api/students.ts"
click node_parent_api "https://github.com/iskesss/readysetread/blob/main/frontend/src/api/parents.ts"
click node_books_api "https://github.com/iskesss/readysetread/blob/main/frontend/src/api/books.ts"
click node_quiz_api "https://github.com/iskesss/readysetread/blob/main/frontend/src/api/quiz.ts"
click node_rewards_api "https://github.com/iskesss/readysetread/blob/main/frontend/src/api/rewards.ts"
click node_service_app "https://github.com/iskesss/readysetread/blob/main/backend/app/main.py"
click node_service_api "https://github.com/iskesss/readysetread/blob/main/backend/app/api.py"
click node_quiz_logic "https://github.com/iskesss/readysetread/blob/main/backend/app/quiz_llm.py"
click node_database_access "https://github.com/iskesss/readysetread/blob/main/backend/app/db.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_routes,node_auth_pages,node_student_home,node_library_page,node_quiz_page,node_results_page,node_rewards_page,node_parent_pages toneBlue
class node_api_client,node_student_api,node_parent_api,node_books_api,node_quiz_api,node_rewards_api toneAmber
class node_service_app,node_service_api,node_quiz_logic,node_database_access toneMint
class node_postgres,node_openai toneRose
class node_student,node_adult toneIndigo
```

## Components

### Web experience

- [App routes](https://github.com/iskesss/readysetread/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Sign in and signup](https://github.com/iskesss/readysetread/tree/main/frontend/src/pages): `frontend/src/pages`
- [Student dashboard](https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/StudentLanding.tsx): `frontend/src/pages/StudentLanding.tsx`
- [Book library](https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/library.tsx): `frontend/src/pages/library.tsx`
- [Quiz taking](https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/Quiz.tsx): `frontend/src/pages/Quiz.tsx`
- [Quiz results](https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/QuizResults.tsx): `frontend/src/pages/QuizResults.tsx`
- [Rewards and skins](https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/Rewards.tsx): `frontend/src/pages/Rewards.tsx`
- [Parent progress](https://github.com/iskesss/readysetread/blob/main/frontend/src/pages/ParentProgress.tsx): `frontend/src/pages/ParentProgress.tsx`

### API clients

- [HTTP client](https://github.com/iskesss/readysetread/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Student API](https://github.com/iskesss/readysetread/blob/main/frontend/src/api/students.ts): `frontend/src/api/students.ts`
- [Parent API](https://github.com/iskesss/readysetread/blob/main/frontend/src/api/parents.ts): `frontend/src/api/parents.ts`
- [Books API](https://github.com/iskesss/readysetread/blob/main/frontend/src/api/books.ts): `frontend/src/api/books.ts`
- [Quiz API](https://github.com/iskesss/readysetread/blob/main/frontend/src/api/quiz.ts): `frontend/src/api/quiz.ts`
- [Rewards API](https://github.com/iskesss/readysetread/blob/main/frontend/src/api/rewards.ts): `frontend/src/api/rewards.ts`

### Backend service

- [FastAPI app](https://github.com/iskesss/readysetread/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/iskesss/readysetread/blob/main/backend/app/api.py): `backend/app/api.py`
- [Quiz generation and feedback](https://github.com/iskesss/readysetread/blob/main/backend/app/quiz_llm.py): `backend/app/quiz_llm.py`
- [Database access](https://github.com/iskesss/readysetread/blob/main/backend/app/db.py): `backend/app/db.py`

### Data and AI

- **PostgreSQL**
- **OpenAI**

### Other components

- **Student**
- **Parent or tutor**

## Connections

- Student → App routes: uses app
- Parent or tutor → App routes: uses app
- App routes → Sign in and signup: routes to
- App routes → Student dashboard: routes to
- App routes → Book library: routes to
- App routes → Quiz taking: routes to
- App routes → Quiz results: routes to
- App routes → Rewards and skins: routes to
- App routes → Parent progress: routes to
- Student dashboard → Student API: loads assignments
- Student dashboard → Books API: loads books
- Student dashboard → Rewards API: loads skin
- Student dashboard → Quiz API: requests quiz
- Parent progress → Parent API: loads children
- Parent progress → Student API: loads assignments
- Parent progress → Books API: loads books
- Parent progress → Rewards API: creates reward
- Sign in and signup → Student API: auth requests
- Sign in and signup → Parent API: auth requests
- Book library → Books API: loads books
- Quiz taking → Quiz API: submits answers
- Quiz results → Quiz API: loads results
- Rewards and skins → Rewards API: manages rewards
- Student API → HTTP client: sends requests
- Parent API → HTTP client: sends requests
- Books API → HTTP client: sends requests
- Quiz API → HTTP client: sends requests
- Rewards API → HTTP client: sends requests
- HTTP client → FastAPI app: HTTP requests
- FastAPI app → API routes: mounts router
- FastAPI app → Database access: initializes pool
- API routes → Database access: queries and updates
- API routes → Quiz generation and feedback: generates quiz
- Quiz generation and feedback → OpenAI: requests generation
- Database access → PostgreSQL: reads and writes