# congminh204/storyloop architecture

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

- Interactive diagram: https://gitdiagram.com/congminh204/storyloop
- Repository: https://github.com/congminh204/storyloop

## Overview

StoryLoop teaches Chinese through branching story conversations, with staged review, flashcards, a story library, and learning-progress tracking. Learners enter through the React app, choose a learning activity, and can review progress; when the API is enabled, authentication and progress sync use the Express server and Postgres. The graph retains the README’s major learning and account capabilities. Some feature wiring is unsampled, so those capabilities are shown without guessed call chains; edges cite the README or source evidence available in the index and excerpts.

Main entry points: [`server/src/app.ts`](https://github.com/congminh204/storyloop/blob/main/server/src/app.ts) (HTTP application), [`server/src/db.ts`](https://github.com/congminh204/storyloop/blob/main/server/src/db.ts) (Postgres store), [`server/src/auth/routes.ts`](https://github.com/congminh204/storyloop/blob/main/server/src/auth/routes.ts) (Authentication routes), [`server/src/stats.ts`](https://github.com/congminh204/storyloop/blob/main/server/src/stats.ts) (Activity statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning activities"]
  node_library["Story library"]
  node_story["Story conversation"]
  node_review["Stage review"]
  node_flashcards["HSK flashcards"]
  node_home["Home challenges"]
  node_celebration["Lesson celebration"]
end

subgraph group_client["Web application"]
  node_app["App navigation<br/>[App.tsx]"]
  node_layouts["Responsive layouts"]
  node_landing["Welcome screen"]
end

subgraph group_identity["Accounts and identity"]
  node_authui["Sign-in forms<br/>[AuthForms.tsx]"]
  node_authstate["Session state<br/>[useAuth.ts]"]
  node_authroutes["Authentication routes<br/>[routes.ts]"]
  node_tokens["Session tokens<br/>[tokens.ts]"]
  node_users["User records<br/>[users.ts]"]
  node_meroutes["Account routes<br/>[routes.ts]"]
end

subgraph group_progress["Progress and insights"]
  node_profile["Learner profile"]
  node_progressui["Progress views<br/>[ProgressScreen.tsx]"]
  node_progressclient["Progress sync<br/>[progress.ts]"]
  node_statsclient["Learning statistics<br/>[learningStats.ts]"]
  node_progressroutes["Progress routes<br/>[routes.ts]"]
  node_progressservice["Progress service<br/>[service.ts]"]
  node_stats["Activity statistics<br/>[stats.ts]"]
end

subgraph group_platform["Server platform"]
  node_api["API client<br/>[api.ts]"]
  node_server["HTTP application<br/>[app.ts]"]
  node_admin["Admin routes<br/>[routes.ts]"]
  node_database[("Postgres store<br/>[db.ts]")]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"selects layout"| node_layouts
node_app -->|"uses library data"| node_library
node_learner -->|"enters through"| node_landing
node_learner -->|"browses stories"| node_library
node_learner -->|"plays stories"| node_story
node_learner -->|"reviews by stages"| node_review
node_learner -->|"reviews vocabulary"| node_flashcards
node_learner -->|"uses challenges"| node_home
node_story -->|"finishes with"| node_celebration
node_learner -.->|"views profile"| node_profile
node_learner -->|"views progress"| node_progressui
node_progressui -->|"uses statistics"| node_statsclient
node_progressui -->|"loads activity"| node_progressclient
node_authui -->|"uses session state"| node_authstate
node_authstate -->|"calls API"| node_api
node_progressclient -->|"sends progress"| node_api
node_api -.->|"requests endpoints"| node_server
node_server -->|"mounts routes"| node_authroutes
node_server -->|"mounts routes"| node_meroutes
node_server -->|"mounts routes"| node_progressroutes
node_server -->|"mounts routes"| node_admin
node_authroutes -->|"creates sessions"| node_tokens
node_authroutes -->|"looks up users"| node_users
node_authroutes -->|"queries users"| node_database
node_meroutes -->|"gets activity"| node_stats
node_meroutes -->|"updates account"| node_database
node_progressroutes -->|"delegates progress"| node_progressservice
node_progressservice -->|"reads and writes"| node_database
node_progressservice -->|"uses statistics"| node_stats
node_stats -->|"queries activity"| node_database
node_admin -->|"queries users"| node_database
node_admin -->|"computes streak"| node_stats

click node_app "https://github.com/congminh204/storyloop/blob/main/src/app/App.tsx"
click node_layouts "https://github.com/congminh204/storyloop/tree/main/src/app/layouts"
click node_landing "https://github.com/congminh204/storyloop/tree/main/src/app/features/landing"
click node_library "https://github.com/congminh204/storyloop/tree/main/src/app/features/library"
click node_story "https://github.com/congminh204/storyloop/tree/main/src/app/features/chat"
click node_review "https://github.com/congminh204/storyloop/tree/main/src/app/features/bloom"
click node_flashcards "https://github.com/congminh204/storyloop/tree/main/src/app/features/flashcard"
click node_home "https://github.com/congminh204/storyloop/tree/main/src/app/features/home"
click node_celebration "https://github.com/congminh204/storyloop/blob/main/src/app/features/celebrate/useLessonCelebration.tsx"
click node_profile "https://github.com/congminh204/storyloop/tree/main/src/app/features/profile"
click node_progressui "https://github.com/congminh204/storyloop/blob/main/src/app/components/ProgressScreen.tsx"
click node_progressclient "https://github.com/congminh204/storyloop/blob/main/src/app/lib/progress.ts"
click node_statsclient "https://github.com/congminh204/storyloop/blob/main/src/app/features/progress/learningStats.ts"
click node_authui "https://github.com/congminh204/storyloop/blob/main/src/app/features/auth/AuthForms.tsx"
click node_authstate "https://github.com/congminh204/storyloop/blob/main/src/app/features/auth/useAuth.ts"
click node_api "https://github.com/congminh204/storyloop/blob/main/src/app/lib/api.ts"
click node_server "https://github.com/congminh204/storyloop/blob/main/server/src/app.ts"
click node_authroutes "https://github.com/congminh204/storyloop/blob/main/server/src/auth/routes.ts"
click node_tokens "https://github.com/congminh204/storyloop/blob/main/server/src/auth/tokens.ts"
click node_users "https://github.com/congminh204/storyloop/blob/main/server/src/users.ts"
click node_meroutes "https://github.com/congminh204/storyloop/blob/main/server/src/me/routes.ts"
click node_progressroutes "https://github.com/congminh204/storyloop/blob/main/server/src/progress/routes.ts"
click node_progressservice "https://github.com/congminh204/storyloop/blob/main/server/src/progress/service.ts"
click node_stats "https://github.com/congminh204/storyloop/blob/main/server/src/stats.ts"
click node_admin "https://github.com/congminh204/storyloop/blob/main/server/src/admin/routes.ts"
click node_database "https://github.com/congminh204/storyloop/blob/main/server/src/db.ts"

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_library,node_story,node_review,node_flashcards,node_home,node_celebration toneBlue
class node_app,node_layouts,node_landing toneAmber
class node_authui,node_authstate,node_authroutes,node_tokens,node_users,node_meroutes toneMint
class node_profile,node_progressui,node_progressclient,node_statsclient,node_progressroutes,node_progressservice,node_stats toneRose
class node_api,node_server,node_admin,node_database,node_learner toneIndigo
```

## Components

### Learning activities

- [Story library](https://github.com/congminh204/storyloop/tree/main/src/app/features/library): `src/app/features/library`
- [Story conversation](https://github.com/congminh204/storyloop/tree/main/src/app/features/chat): `src/app/features/chat`
- [Stage review](https://github.com/congminh204/storyloop/tree/main/src/app/features/bloom): `src/app/features/bloom`
- [HSK flashcards](https://github.com/congminh204/storyloop/tree/main/src/app/features/flashcard): `src/app/features/flashcard`
- [Home challenges](https://github.com/congminh204/storyloop/tree/main/src/app/features/home): `src/app/features/home`
- [Lesson celebration](https://github.com/congminh204/storyloop/blob/main/src/app/features/celebrate/useLessonCelebration.tsx): `src/app/features/celebrate/useLessonCelebration.tsx`

### Web application

- [App navigation](https://github.com/congminh204/storyloop/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Responsive layouts](https://github.com/congminh204/storyloop/tree/main/src/app/layouts): `src/app/layouts`
- [Welcome screen](https://github.com/congminh204/storyloop/tree/main/src/app/features/landing): `src/app/features/landing`

### Accounts and identity

- [Sign-in forms](https://github.com/congminh204/storyloop/blob/main/src/app/features/auth/AuthForms.tsx): `src/app/features/auth/AuthForms.tsx`
- [Session state](https://github.com/congminh204/storyloop/blob/main/src/app/features/auth/useAuth.ts): `src/app/features/auth/useAuth.ts`
- [Authentication routes](https://github.com/congminh204/storyloop/blob/main/server/src/auth/routes.ts): `server/src/auth/routes.ts`
- [Session tokens](https://github.com/congminh204/storyloop/blob/main/server/src/auth/tokens.ts): `server/src/auth/tokens.ts`
- [User records](https://github.com/congminh204/storyloop/blob/main/server/src/users.ts): `server/src/users.ts`
- [Account routes](https://github.com/congminh204/storyloop/blob/main/server/src/me/routes.ts): `server/src/me/routes.ts`

### Progress and insights

- [Learner profile](https://github.com/congminh204/storyloop/tree/main/src/app/features/profile): `src/app/features/profile`
- [Progress views](https://github.com/congminh204/storyloop/blob/main/src/app/components/ProgressScreen.tsx): `src/app/components/ProgressScreen.tsx`
- [Progress sync](https://github.com/congminh204/storyloop/blob/main/src/app/lib/progress.ts): `src/app/lib/progress.ts`
- [Learning statistics](https://github.com/congminh204/storyloop/blob/main/src/app/features/progress/learningStats.ts): `src/app/features/progress/learningStats.ts`
- [Progress routes](https://github.com/congminh204/storyloop/blob/main/server/src/progress/routes.ts): `server/src/progress/routes.ts`
- [Progress service](https://github.com/congminh204/storyloop/blob/main/server/src/progress/service.ts): `server/src/progress/service.ts`
- [Activity statistics](https://github.com/congminh204/storyloop/blob/main/server/src/stats.ts): `server/src/stats.ts`

### Server platform

- [API client](https://github.com/congminh204/storyloop/blob/main/src/app/lib/api.ts): `src/app/lib/api.ts`
- [HTTP application](https://github.com/congminh204/storyloop/blob/main/server/src/app.ts): `server/src/app.ts`
- [Admin routes](https://github.com/congminh204/storyloop/blob/main/server/src/admin/routes.ts): `server/src/admin/routes.ts`
- [Postgres store](https://github.com/congminh204/storyloop/blob/main/server/src/db.ts): `server/src/db.ts`

### Other components

- **Learner**

## Connections

- Learner → App navigation: uses (evidence: `README.md`)
- App navigation → Responsive layouts: selects layout (evidence: `src/app/App.tsx`)
- App navigation → Story library: uses library data (evidence: `src/app/App.tsx`)
- Learner → Welcome screen: enters through (evidence: `README.md`)
- Learner → Story library: browses stories (evidence: `README.md`)
- Learner → Story conversation: plays stories (evidence: `README.md`)
- Learner → Stage review: reviews by stages (evidence: `README.md`)
- Learner → HSK flashcards: reviews vocabulary (evidence: `README.md`)
- Learner → Home challenges: uses challenges (evidence: `README.md`)
- Story conversation → Lesson celebration: finishes with (evidence: `src/app/features/chat/BranchingStoryEngine.tsx`)
- Learner → Learner profile: views profile
- Learner → Progress views: views progress (evidence: `README.md`)
- Progress views → Learning statistics: uses statistics (evidence: `src/app/components/ProgressScreen.tsx`)
- Progress views → Progress sync: loads activity (evidence: `src/app/components/ProgressScreen.tsx`)
- Sign-in forms → Session state: uses session state (evidence: `src/app/features/auth/AuthForms.tsx`)
- Session state → API client: calls API (evidence: `src/app/features/auth/useAuth.ts`)
- Progress sync → API client: sends progress (evidence: `src/app/lib/progress.ts`)
- API client → HTTP application: requests endpoints
- HTTP application → Authentication routes: mounts routes (evidence: `server/src/app.ts`)
- HTTP application → Account routes: mounts routes (evidence: `server/src/app.ts`)
- HTTP application → Progress routes: mounts routes (evidence: `server/src/app.ts`)
- HTTP application → Admin routes: mounts routes (evidence: `server/src/app.ts`)
- Authentication routes → Session tokens: creates sessions (evidence: `server/src/auth/routes.ts`)
- Authentication routes → User records: looks up users (evidence: `server/src/auth/routes.ts`)
- Authentication routes → Postgres store: queries users (evidence: `server/src/auth/routes.ts`)
- Account routes → Activity statistics: gets activity (evidence: `server/src/me/routes.ts`)
- Account routes → Postgres store: updates account (evidence: `server/src/me/routes.ts`)
- Progress routes → Progress service: delegates progress (evidence: `server/src/progress/routes.ts`)
- Progress service → Postgres store: reads and writes (evidence: `server/src/progress/service.ts`)
- Progress service → Activity statistics: uses statistics (evidence: `server/src/progress/service.ts`)
- Activity statistics → Postgres store: queries activity (evidence: `server/src/stats.ts`)
- Admin routes → Postgres store: queries users (evidence: `server/src/admin/routes.ts`)
- Admin routes → Activity statistics: computes streak (evidence: `server/src/admin/routes.ts`)