# johnhuangyijun2002-cloud/english-reading-tutor architecture

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

- Interactive diagram: https://gitdiagram.com/johnhuangyijun2002-cloud/english-reading-tutor
- Repository: https://github.com/johnhuangyijun2002-cloud/english-reading-tutor

## Overview

Contextia is an article-based language-learning application: users import reading material, annotate words or passages with AI, save notes, and revisit them through review and study tools. The web UI and Capacitor apps use the FastAPI backend, which provides account-scoped data and integrations. README documents additional capabilities not visible in the sampled source; those are shown at the subsystem level, with uncertain internal wiring omitted.

Main entry points: [`frontend/app.js`](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js) (Reader UI), [`backend/main.py`](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py) (FastAPI service), [`apps_script/Code.gs`](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/apps_script/Code.gs) (Sheets sync), [`mobile/ios/App/App/AppDelegate.swift`](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/mobile/ios/App/App/AppDelegate.swift) (Capacitor app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reading["Reading"]
  node_webapp["Reader UI<br/>[app.js]"]
  node_article_ingest["Article import<br/>[main.py]"]
  node_article_reader["Reading view<br/>[app.js]"]
  node_news["News discovery<br/>[main.py]"]
  node_immersion["Immersion mode<br/>[app.js]"]
end

subgraph group_learning["Learning"]
  node_annotation["Word and sentence notes<br/>[app.js]"]
  node_ai_explain["AI explanations<br/>[main.py]"]
  node_notebook["Notebook and history<br/>[app.js]"]
  node_review["Spaced review<br/>[app.js]"]
  node_learning_stats["Learning statistics<br/>[app.js]"]
end

subgraph group_services["Accounts and services"]
  node_api["FastAPI service<br/>[main.py]"]
  node_auth["Accounts and auth<br/>[main.py]"]
  node_postgres[("Postgres")]
  node_ai_providers["AI providers"]
  node_sheets_sync["Sheets sync<br/>[Code.gs]"]
  node_notion["Notion integration<br/>[main.py]"]
end

subgraph group_mobile["Mobile app"]
  node_mobile_shell["Capacitor app<br/>[AppDelegate.swift]"]
  node_iap["Apple purchases<br/>[app.js]"]
end

node_learner(("Learner"))
node_article_sites["Article and news sites"]
node_google_sheet[("Google Sheet")]
node_apple_store["Apple App Store"]

node_learner -->|"uses"| node_webapp
node_webapp -->|"calls API"| node_api
node_webapp -->|"submits content"| node_article_ingest
node_article_ingest -->|"fetches URL content"| node_article_sites
node_article_ingest -->|"uploads documents"| node_api
node_api -->|"reads and writes"| node_postgres
node_api -->|"dispatches AI tasks"| node_ai_explain
node_ai_explain -.->|"requests explanations"| node_ai_providers
node_webapp -->|"selects text"| node_annotation
node_annotation -->|"saves notes"| node_api
node_webapp -->|"opens notes"| node_notebook
node_notebook -->|"loads and edits"| node_api
node_webapp -->|"reviews vocabulary"| node_review
node_review -->|"updates review state"| node_api
node_webapp -->|"views study stats"| node_learning_stats
node_learning_stats -->|"requests statistics"| node_api
node_webapp -->|"requests recommendations"| node_news
node_news -->|"fetches headlines"| node_article_sites
node_news -.->|"ranks recommendations"| node_ai_providers
node_webapp -->|"configures reading"| node_immersion
node_immersion -->|"requests substitutions"| node_ai_explain
node_api -->|"authenticates"| node_auth
node_auth -->|"reads and writes accounts"| node_postgres
node_api -.->|"posts note updates"| node_sheets_sync
node_sheets_sync -.->|"writes rows"| node_google_sheet
node_api -.->|"handles connection flow"| node_notion
node_learner -->|"uses"| node_mobile_shell
node_mobile_shell -->|"hosts reader"| node_webapp
node_webapp -->|"calls configured backend"| node_api
node_webapp -.->|"starts subscription flow"| node_iap
node_iap -.->|"purchases subscription"| node_apple_store

click node_webapp "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js"
click node_article_ingest "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py"
click node_article_reader "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js"
click node_news "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py"
click node_immersion "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js"
click node_annotation "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js"
click node_ai_explain "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py"
click node_notebook "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js"
click node_review "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js"
click node_learning_stats "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js"
click node_api "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py"
click node_auth "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py"
click node_sheets_sync "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/apps_script/Code.gs"
click node_notion "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py"
click node_mobile_shell "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/mobile/ios/App/App/AppDelegate.swift"
click node_iap "https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js"

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_article_ingest,node_article_reader,node_news,node_immersion toneBlue
class node_annotation,node_ai_explain,node_notebook,node_review,node_learning_stats,node_google_sheet toneAmber
class node_api,node_auth,node_postgres,node_ai_providers,node_sheets_sync,node_notion toneMint
class node_mobile_shell,node_iap toneRose
class node_learner,node_article_sites,node_apple_store toneIndigo
```

## Components

### Reading

- [Reader UI](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js): `frontend/app.js`
- [Article import](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py): `backend/main.py`
- [Reading view](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js): `frontend/app.js`
- [News discovery](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py): `backend/main.py`
- [Immersion mode](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js): `frontend/app.js`

### Learning

- [Word and sentence notes](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js): `frontend/app.js`
- [AI explanations](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py): `backend/main.py`
- [Notebook and history](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js): `frontend/app.js`
- [Spaced review](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js): `frontend/app.js`
- [Learning statistics](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js): `frontend/app.js`

### Accounts and services

- [FastAPI service](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py): `backend/main.py`
- [Accounts and auth](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py): `backend/main.py`
- **Postgres**
- **AI providers**
- [Sheets sync](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/apps_script/Code.gs): `apps_script/Code.gs`
- [Notion integration](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/backend/main.py): `backend/main.py`

### Mobile app

- [Capacitor app](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/mobile/ios/App/App/AppDelegate.swift): `mobile/ios/App/App/AppDelegate.swift`
- [Apple purchases](https://github.com/johnhuangyijun2002-cloud/english-reading-tutor/blob/master/frontend/app.js): `frontend/app.js`

### Other components

- **Learner**
- **Article and news sites**
- **Google Sheet**
- **Apple App Store**

## Connections

- Learner → Reader UI: uses
- Reader UI → FastAPI service: calls API
- Reader UI → Article import: submits content
- Article import → Article and news sites: fetches URL content
- Article import → FastAPI service: uploads documents
- FastAPI service → Postgres: reads and writes
- FastAPI service → AI explanations: dispatches AI tasks
- AI explanations → AI providers: requests explanations
- Reader UI → Word and sentence notes: selects text
- Word and sentence notes → FastAPI service: saves notes
- Reader UI → Notebook and history: opens notes
- Notebook and history → FastAPI service: loads and edits
- Reader UI → Spaced review: reviews vocabulary
- Spaced review → FastAPI service: updates review state
- Reader UI → Learning statistics: views study stats
- Learning statistics → FastAPI service: requests statistics
- Reader UI → News discovery: requests recommendations
- News discovery → Article and news sites: fetches headlines
- News discovery → AI providers: ranks recommendations
- Reader UI → Immersion mode: configures reading
- Immersion mode → AI explanations: requests substitutions
- FastAPI service → Accounts and auth: authenticates
- Accounts and auth → Postgres: reads and writes accounts
- FastAPI service → Sheets sync: posts note updates
- Sheets sync → Google Sheet: writes rows
- FastAPI service → Notion integration: handles connection flow
- Learner → Capacitor app: uses
- Capacitor app → Reader UI: hosts reader
- Reader UI → FastAPI service: calls configured backend
- Reader UI → Apple purchases: starts subscription flow
- Apple purchases → Apple App Store: purchases subscription