# wuwangzhang1216/chinatextbookstudyfree architecture

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

- Interactive diagram: https://gitdiagram.com/wuwangzhang1216/chinatextbookstudyfree
- Repository: https://github.com/wuwangzhang1216/chinatextbookstudyfree

## Overview

ChinaStudyFree is a free, multi-subject elementary-learning product delivered as a web app and a native iOS app. Learners choose a grade/book, follow unit lessons or reading material, answer questions, and receive progress, review, and rewards. The README documents shared domain logic, TTS, offline iOS data, stories, cosmetics, and retention features. Source excerpts chiefly show iOS progress persistence and lesson/review behavior; several feature links below are documented capabilities rather than inspected call sites.

Main entry points: [`apps/mobile/ChinaTextbookStudy/Stores/ProgressStore.swift`](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Stores/ProgressStore.swift) (Progress store), [`packages/core/src/economy.ts`](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/packages/core/src/economy.ts) (Shared domain rules), [`apps/mobile/ChinaTextbookStudy/Features/Lesson/LessonRunnerView.swift`](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Lesson/LessonRunnerView.swift) (Lesson runner), [`apps/mobile/ChinaTextbookStudy/App/ChinaTextbookStudyApp.swift`](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/App/ChinaTextbookStudyApp.swift) (iOS app shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Learning clients"]
  node_webhome["Web home<br/>[HomeClient.tsx]"]
  node_iosapp["iOS app shell"]
  node_lesson["Lesson runner"]
  node_weblesson["Web lesson"]
  node_review["Mistake review"]
  node_webreview["Web review<br/>[ReviewClient.tsx]"]
  node_reader["Passage reader"]
  node_webreader["Web reading<br/>[page.tsx]"]
  node_guide["Knowledge guide"]
  node_jump["Placement test<br/>[JumpTestView.swift]"]
  node_league["League<br/>[LeagueView.swift]"]
  node_shop["Cosmetics shop<br/>[ShopView.swift]"]
  node_mascot["Panda mascot<br/>[MascotView.swift]"]
end

subgraph group_content["Learning content"]
  node_contentdata["Book and quiz data<br/>[DataLoader.swift]"]
end

subgraph group_domain["Progress and rewards"]
  node_core["Shared domain rules<br/>[economy.ts]"]
  node_progress["Progress store"]
  node_backup["Backup and restore<br/>[Backup.swift]"]
end

subgraph group_platform["Platform services"]
  node_audio["Audio and TTS<br/>[AudioPlayer.swift]"]
  node_persistence[("Local persistence")]
  node_notifications["Streak reminders"]
end

node_learner(("Learner"))
node_externaldata[("Release assets")]

node_learner -->|"opens learning"| node_webhome
node_learner -->|"opens learning"| node_iosapp
node_webhome -->|"starts unit quiz"| node_weblesson
node_webhome -->|"opens reading"| node_webreader
node_iosapp -.->|"routes to lesson"| node_lesson
node_iosapp -.->|"routes to reading"| node_reader
node_lesson -.->|"loads lesson"| node_contentdata
node_weblesson -->|"uses domain rules"| node_core
node_lesson -->|"records results"| node_progress
node_lesson -->|"plays prompts"| node_audio
node_lesson -->|"shows feedback"| node_mascot
node_review -->|"awards review XP"| node_progress
node_review -->|"reuses lesson flow"| node_lesson
node_webreview -->|"uses review rules"| node_core
node_reader -.->|"records reading"| node_progress
node_webreader -.->|"uses reading rules"| node_core
node_guide -->|"shows explanations"| node_contentdata
node_jump -->|"checks placement"| node_core
node_league -->|"settles league"| node_core
node_shop -->|"uses cosmetics rules"| node_core
node_progress -->|"saves snapshots"| node_persistence
node_progress -->|"applies reward rules"| node_core
node_progress -->|"schedules reminders"| node_notifications
node_progress -->|"imports progress"| node_backup
node_contentdata -.->|"loads book assets"| node_externaldata
node_externaldata -->|"downloads by book"| node_iosapp

click node_webhome "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/web/src/app/HomeClient.tsx"
click node_iosapp "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/App/ChinaTextbookStudyApp.swift"
click node_lesson "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Lesson/LessonRunnerView.swift"
click node_weblesson "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/web/src/app/lesson/%5Bbook%5D/%5Blesson%5D/LessonPageClient.tsx"
click node_review "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Review/MistakeReviewRunnerView.swift"
click node_webreview "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/web/src/app/review/ReviewClient.tsx"
click node_reader "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Reading/PassageReaderView.swift"
click node_webreader "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/web/src/app/reading/%5Bbook%5D/%5Bpassage%5D/page.tsx"
click node_guide "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Guide/UnitGuideView.swift"
click node_jump "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Jump/JumpTestView.swift"
click node_league "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/League/LeagueView.swift"
click node_shop "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Shop/ShopView.swift"
click node_core "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/packages/core/src/economy.ts"
click node_progress "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Stores/ProgressStore.swift"
click node_backup "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Domain/Backup.swift"
click node_contentdata "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Services/DataLoader.swift"
click node_audio "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Services/AudioPlayer.swift"
click node_persistence "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Services/PersistenceService.swift"
click node_notifications "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Services/NotificationService.swift"
click node_mascot "https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Components/MascotView.swift"

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_webhome,node_iosapp,node_lesson,node_weblesson,node_review,node_webreview,node_reader,node_webreader,node_guide,node_jump,node_league,node_shop,node_mascot toneBlue
class node_contentdata,node_externaldata toneAmber
class node_core,node_progress,node_backup toneMint
class node_audio,node_persistence,node_notifications toneRose
class node_learner toneIndigo
```

## Components

### Learning clients

- [Web home](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/web/src/app/HomeClient.tsx): `apps/web/src/app/HomeClient.tsx`
- [iOS app shell](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/App/ChinaTextbookStudyApp.swift): `apps/mobile/ChinaTextbookStudy/App/ChinaTextbookStudyApp.swift`
- [Lesson runner](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Lesson/LessonRunnerView.swift): `apps/mobile/ChinaTextbookStudy/Features/Lesson/LessonRunnerView.swift`
- [Web lesson](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/web/src/app/lesson/%5Bbook%5D/%5Blesson%5D/LessonPageClient.tsx): `apps/web/src/app/lesson/[book]/[lesson]/LessonPageClient.tsx`
- [Mistake review](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Review/MistakeReviewRunnerView.swift): `apps/mobile/ChinaTextbookStudy/Features/Review/MistakeReviewRunnerView.swift`
- [Web review](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/web/src/app/review/ReviewClient.tsx): `apps/web/src/app/review/ReviewClient.tsx`
- [Passage reader](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Reading/PassageReaderView.swift): `apps/mobile/ChinaTextbookStudy/Features/Reading/PassageReaderView.swift`
- [Web reading](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/web/src/app/reading/%5Bbook%5D/%5Bpassage%5D/page.tsx): `apps/web/src/app/reading/[book]/[passage]/page.tsx`
- [Knowledge guide](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Guide/UnitGuideView.swift): `apps/mobile/ChinaTextbookStudy/Features/Guide/UnitGuideView.swift`
- [Placement test](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Jump/JumpTestView.swift): `apps/mobile/ChinaTextbookStudy/Features/Jump/JumpTestView.swift`
- [League](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/League/LeagueView.swift): `apps/mobile/ChinaTextbookStudy/Features/League/LeagueView.swift`
- [Cosmetics shop](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Features/Shop/ShopView.swift): `apps/mobile/ChinaTextbookStudy/Features/Shop/ShopView.swift`
- [Panda mascot](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Components/MascotView.swift): `apps/mobile/ChinaTextbookStudy/Components/MascotView.swift`

### Learning content

- [Book and quiz data](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Services/DataLoader.swift): `apps/mobile/ChinaTextbookStudy/Services/DataLoader.swift`

### Progress and rewards

- [Shared domain rules](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/packages/core/src/economy.ts): `packages/core/src/economy.ts`
- [Progress store](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Stores/ProgressStore.swift): `apps/mobile/ChinaTextbookStudy/Stores/ProgressStore.swift`
- [Backup and restore](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Domain/Backup.swift): `apps/mobile/ChinaTextbookStudy/Domain/Backup.swift`

### Platform services

- [Audio and TTS](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Services/AudioPlayer.swift): `apps/mobile/ChinaTextbookStudy/Services/AudioPlayer.swift`
- [Local persistence](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Services/PersistenceService.swift): `apps/mobile/ChinaTextbookStudy/Services/PersistenceService.swift`
- [Streak reminders](https://github.com/wuwangzhang1216/chinatextbookstudyfree/blob/main/apps/mobile/ChinaTextbookStudy/Services/NotificationService.swift): `apps/mobile/ChinaTextbookStudy/Services/NotificationService.swift`

### Other components

- **Learner**
- **Release assets**

## Connections

- Learner → Web home: opens learning (evidence: `README.md`)
- Learner → iOS app shell: opens learning (evidence: `README.md`)
- Web home → Web lesson: starts unit quiz (evidence: `README.md`)
- Web home → Web reading: opens reading (evidence: `README.md`)
- iOS app shell → Lesson runner: routes to lesson
- iOS app shell → Passage reader: routes to reading
- Lesson runner → Book and quiz data: loads lesson (evidence: `apps/mobile/ChinaTextbookStudy/Features/Lesson/LessonRunnerView.swift`)
- Web lesson → Shared domain rules: uses domain rules (evidence: `README.md`)
- Lesson runner → Progress store: records results (evidence: `apps/mobile/ChinaTextbookStudy/Features/Lesson/LessonRunnerView.swift`)
- Lesson runner → Audio and TTS: plays prompts (evidence: `apps/mobile/ChinaTextbookStudy/Features/Lesson/LessonRunnerView.swift`)
- Lesson runner → Panda mascot: shows feedback (evidence: `apps/mobile/ChinaTextbookStudy/Features/Lesson/LessonRunnerView.swift`)
- Mistake review → Progress store: awards review XP (evidence: `apps/mobile/ChinaTextbookStudy/Features/Review/MistakeReviewRunnerView.swift`)
- Mistake review → Lesson runner: reuses lesson flow (evidence: `apps/mobile/ChinaTextbookStudy/Features/Review/MistakeReviewRunnerView.swift`)
- Web review → Shared domain rules: uses review rules (evidence: `README.md`)
- Passage reader → Progress store: records reading
- Web reading → Shared domain rules: uses reading rules
- Knowledge guide → Book and quiz data: shows explanations (evidence: `README.md`)
- Placement test → Shared domain rules: checks placement
- League → Shared domain rules: settles league
- Cosmetics shop → Shared domain rules: uses cosmetics rules
- Progress store → Local persistence: saves snapshots (evidence: `apps/mobile/ChinaTextbookStudy/Stores/ProgressStore.swift`)
- Progress store → Shared domain rules: applies reward rules (evidence: `apps/mobile/ChinaTextbookStudy/Stores/ProgressStore.swift`)
- Progress store → Streak reminders: schedules reminders (evidence: `apps/mobile/ChinaTextbookStudy/Stores/ProgressStore.swift`)
- Progress store → Backup and restore: imports progress (evidence: `apps/mobile/ChinaTextbookStudy/Stores/ProgressStore.swift`)
- Book and quiz data → Release assets: loads book assets
- Release assets → iOS app shell: downloads by book (evidence: `README.md`)