# lixiny-code/chaincue-ielts architecture

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

- Interactive diagram: https://gitdiagram.com/lixiny-code/chaincue-ielts
- Repository: https://github.com/lixiny-code/chaincue-ielts
- Video tour (about a minute): https://gitdiagram.com/lixiny-code/chaincue-ielts/video

## Overview

Chaincue is an IELTS Speaking Part 2 practice app that turns a learner’s real experience into reusable, topic-specific speaking scripts. The documented workflow runs from topic selection and experience entry through AI story analysis, topic matching, and script generation, then supports review and saving. The README also describes custom topic imports, read-aloud, copying, ratings, and history. Frontend orchestration is documented but its source was not sampled, so those links reflect the README; other endpoint wiring is shown only where supported by sampled code.

Main entry points: [`index.html`](https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html) (Practice interface), [`supabase/migrations/01_init.sql`](https://github.com/lixiny-code/chaincue-ielts/blob/main/supabase/migrations/01_init.sql) (Supabase database), [`lib/ai-request.js`](https://github.com/lixiny-code/chaincue-ielts/blob/main/lib/ai-request.js) (AI request client), [`api/generate-answer.js`](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/generate-answer.js) (Single answer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_practice["Practice workflow"]
  node_frontend["Practice interface<br/>[index.html]"]
  node_topicbank["Topic selection<br/>[index.html]"]
  node_customtopics["Custom topic import<br/>[index.html]"]
  node_studytools["Read, copy, rate<br/>[index.html]"]
  node_storyinput["Experience entry<br/>[index.html]"]
end

subgraph group_generation["AI generation"]
  node_decompose["Story decomposition<br/>[decompose.js]"]
  node_categorymap["Category mapping<br/>[map-categories.js]"]
  node_recommend["Topic recommendations"]
  node_weave["Multi-topic scripts<br/>[generate.js]"]
  node_singleanswer["Single answer<br/>[generate-answer.js]"]
  node_aihelper["AI request client<br/>[ai-request.js]"]
end

subgraph group_account["Accounts and history"]
  node_stories["Story library<br/>[stories.js]"]
  node_histories["History list<br/>[histories.js]"]
  node_historydetail["History detail<br/>[&#91;id&#93;.js]"]
  node_archive["Save archive<br/>[save-archive.js]"]
  node_redeem["Redeem credits<br/>[redeem-code.js]"]
  node_supabasehelper["REST data helpers<br/>[supabase.js]"]
end

subgraph group_platform["External services"]
  node_auth{{"Supabase auth"}}
  node_ai{{"AI completion API"}}
  node_db[("Supabase database<br/>[01_init.sql]")]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_frontend
node_frontend -->|"selects topics"| node_topicbank
node_frontend -->|"imports topics"| node_customtopics
node_frontend -->|"reviews scripts"| node_studytools
node_frontend -->|"enters experience"| node_storyinput
node_storyinput -->|"submits story"| node_decompose
node_decompose -->|"requests analysis"| node_aihelper
node_aihelper -->|"sends prompt"| node_ai
node_decompose -->|"validates user"| node_auth
node_decompose -->|"logs decomposition"| node_db
node_frontend -->|"maps categories"| node_categorymap
node_categorymap -->|"requests mapping"| node_aihelper
node_categorymap -->|"validates user"| node_auth
node_categorymap -->|"logs mapping"| node_db
node_frontend -->|"requests recommendations"| node_recommend
node_recommend -->|"requests matches"| node_aihelper
node_recommend -->|"validates user"| node_auth
node_recommend -->|"logs recommendations"| node_db
node_frontend -->|"generates scripts"| node_weave
node_weave -->|"requests scripts"| node_aihelper
node_weave -->|"validates user"| node_auth
node_frontend -->|"generates answer"| node_singleanswer
node_singleanswer -->|"requests answer"| node_aihelper
node_singleanswer -->|"validates user"| node_auth
node_singleanswer -->|"logs answer"| node_db
node_singleanswer -->|"updates credits"| node_db
node_frontend -->|"manages stories"| node_stories
node_stories -->|"verifies token"| node_auth
node_stories -->|"calls data helpers"| node_supabasehelper
node_frontend -->|"views history"| node_histories
node_histories -->|"reads records"| node_db
node_frontend -->|"opens record"| node_historydetail
node_historydetail -->|"queries record"| node_supabasehelper
node_historydetail -->|"verifies token"| node_auth
node_frontend -->|"saves result"| node_archive
node_archive -->|"stores archive"| node_db
node_frontend -->|"redeems code"| node_redeem
node_redeem -->|"validates user"| node_auth
node_redeem -->|"updates credits"| node_db
node_supabasehelper -->|"queries and writes"| node_db

click node_frontend "https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html"
click node_topicbank "https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html"
click node_customtopics "https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html"
click node_studytools "https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html"
click node_storyinput "https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html"
click node_decompose "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/decompose.js"
click node_categorymap "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/map-categories.js"
click node_recommend "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/recommend-topics.js"
click node_weave "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/generate.js"
click node_singleanswer "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/generate-answer.js"
click node_aihelper "https://github.com/lixiny-code/chaincue-ielts/blob/main/lib/ai-request.js"
click node_db "https://github.com/lixiny-code/chaincue-ielts/blob/main/supabase/migrations/01_init.sql"
click node_stories "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/stories.js"
click node_histories "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/histories.js"
click node_historydetail "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/history/%5Bid%5D.js"
click node_archive "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/save-archive.js"
click node_redeem "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/redeem-code.js"
click node_supabasehelper "https://github.com/lixiny-code/chaincue-ielts/blob/main/api/lib/supabase.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_frontend,node_topicbank,node_customtopics,node_studytools,node_storyinput toneBlue
class node_decompose,node_categorymap,node_recommend,node_weave,node_singleanswer,node_aihelper toneAmber
class node_stories,node_histories,node_historydetail,node_archive,node_redeem,node_supabasehelper toneMint
class node_auth,node_ai,node_db toneRose
class node_learner toneIndigo
```

## Components

### Practice workflow

- [Practice interface](https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html): `index.html`
- [Topic selection](https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html): `index.html`
- [Custom topic import](https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html): `index.html`
- [Read, copy, rate](https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html): `index.html`
- [Experience entry](https://github.com/lixiny-code/chaincue-ielts/blob/main/index.html): `index.html`

### AI generation

- [Story decomposition](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/decompose.js): `api/decompose.js`
- [Category mapping](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/map-categories.js): `api/map-categories.js`
- [Topic recommendations](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/recommend-topics.js): `api/recommend-topics.js`
- [Multi-topic scripts](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/generate.js): `api/generate.js`
- [Single answer](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/generate-answer.js): `api/generate-answer.js`
- [AI request client](https://github.com/lixiny-code/chaincue-ielts/blob/main/lib/ai-request.js): `lib/ai-request.js`

### Accounts and history

- [Story library](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/stories.js): `api/stories.js`
- [History list](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/histories.js): `api/histories.js`
- [History detail](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/history/%5Bid%5D.js): `api/history/[id].js`
- [Save archive](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/save-archive.js): `api/save-archive.js`
- [Redeem credits](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/redeem-code.js): `api/redeem-code.js`
- [REST data helpers](https://github.com/lixiny-code/chaincue-ielts/blob/main/api/lib/supabase.js): `api/lib/supabase.js`

### External services

- **Supabase auth**
- **AI completion API**
- [Supabase database](https://github.com/lixiny-code/chaincue-ielts/blob/main/supabase/migrations/01_init.sql): `supabase/migrations/01_init.sql`

### Other components

- **Learner**

## Connections

- Learner → Practice interface: uses
- Practice interface → Topic selection: selects topics
- Practice interface → Custom topic import: imports topics
- Practice interface → Read, copy, rate: reviews scripts
- Practice interface → Experience entry: enters experience
- Experience entry → Story decomposition: submits story
- Story decomposition → AI request client: requests analysis
- AI request client → AI completion API: sends prompt
- Story decomposition → Supabase auth: validates user
- Story decomposition → Supabase database: logs decomposition
- Practice interface → Category mapping: maps categories
- Category mapping → AI request client: requests mapping
- Category mapping → Supabase auth: validates user
- Category mapping → Supabase database: logs mapping
- Practice interface → Topic recommendations: requests recommendations
- Topic recommendations → AI request client: requests matches
- Topic recommendations → Supabase auth: validates user
- Topic recommendations → Supabase database: logs recommendations
- Practice interface → Multi-topic scripts: generates scripts
- Multi-topic scripts → AI request client: requests scripts
- Multi-topic scripts → Supabase auth: validates user
- Practice interface → Single answer: generates answer
- Single answer → AI request client: requests answer
- Single answer → Supabase auth: validates user
- Single answer → Supabase database: logs answer
- Single answer → Supabase database: updates credits
- Practice interface → Story library: manages stories
- Story library → Supabase auth: verifies token
- Story library → REST data helpers: calls data helpers
- Practice interface → History list: views history
- History list → Supabase database: reads records
- Practice interface → History detail: opens record
- History detail → REST data helpers: queries record
- History detail → Supabase auth: verifies token
- Practice interface → Save archive: saves result
- Save archive → Supabase database: stores archive
- Practice interface → Redeem credits: redeems code
- Redeem credits → Supabase auth: validates user
- Redeem credits → Supabase database: updates credits
- REST data helpers → Supabase database: queries and writes