# khinyadanarmoe/jtrax-mobile-app architecture

> Architecture diagram of the GitHub repository khinyadanarmoe/jtrax-mobile-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khinyadanarmoe/jtrax-mobile-app
- Repository: https://github.com/khinyadanarmoe/jtrax-mobile-app

## Overview

This is a mobile chess-academy app for students and parents. Students sign in, view learning activity, and play computer, friend, or room games; parents review children’s progress and manage academy-related information, including tournament registration. The app also supports puzzles, Lichess-linked ratings, tournaments, and notifications. The graph emphasizes these product workflows and shared session/API layers. Some routes and integrations are represented from the file tree and SOURCE INDEX; edges are limited to relationships shown there or in excerpts.

Main entry points: [`src/lib/api.ts`](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/api.ts) (Backend client), [`src/components/parent/ParentData.tsx`](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/parent/ParentData.tsx) (Family data), [`src/lib/session.tsx`](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/session.tsx) (Session provider), [`src/app/student/index.tsx`](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/index.tsx) (Student home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_sign_in["Sign-in<br/>[index.tsx]"]
  node_session["Session provider<br/>[session.tsx]"]
  node_token[("Secure token store<br/>[token-store.ts]")]
  node_api["Backend client<br/>[api.ts]"]
  node_push["Push notifications<br/>[push.ts]"]
end

subgraph group_student["Student learning"]
  node_student_home["Student home<br/>[index.tsx]"]
  node_puzzles["Puzzle practice<br/>[puzzles.ts]"]
  node_lichess["Lichess connection<br/>[lichess.ts]"]
  node_challenge["Student challenges<br/>[challenge.tsx]"]
end

subgraph group_chess["Chess play"]
  node_play_entry["Play selection<br/>[index.tsx]"]
  node_ai_play["Computer game screen<br/>[ai.tsx]"]
  node_friend_play["Friend game<br/>[friend.tsx]"]
  node_room_play["Room game<br/>[&#91;roomId&#93;.tsx]"]
  node_ai_router["Opponent selection<br/>[useAiOpponent.ts]"]
  node_engines["Chess engines<br/>[maia-engine.ts]"]
  node_engine_views["Engine runtimes<br/>[OnnxWebView.tsx]"]
  node_board["Chess board<br/>[ChessBoard.tsx]"]
  node_chess_rules["Chess rules<br/>[chess-core.ts]"]
  node_room_hook["Room session<br/>[useRoom.ts]"]
  node_games["Game API<br/>[games.ts]"]
end

subgraph group_family["Parent portal"]
  node_parent_home["Parent dashboard<br/>[index.tsx]"]
  node_parent_data["Family data<br/>[ParentData.tsx]"]
  node_parent_models["Parent data transforms<br/>[parent-v2-data.ts]"]
  node_child_profile["Child progress<br/>[index.tsx]"]
  node_attendance["Attendance<br/>[attendance.tsx]"]
  node_tournaments["Tournament services<br/>[tournaments.ts]"]
  node_tournament_detail["Tournament detail<br/>[&#91;id&#93;.tsx]"]
end

node_user(("Student or parent"))
node_backend[("JTrax backend")]

node_user -->|"signs in"| node_sign_in
node_sign_in -->|"uses session"| node_session
node_session -->|"authenticates through"| node_api
node_session -->|"restores and stores"| node_token
node_session -->|"registers devices"| node_push
node_api -->|"sends API requests"| node_backend
node_student_home -->|"loads puzzle data"| node_puzzles
node_student_home -->|"loads rating"| node_lichess
node_student_home -->|"loads activity"| node_api
node_play_entry -.->|"offers computer play"| node_ai_play
node_play_entry -.->|"offers friend play"| node_friend_play
node_play_entry -.->|"offers room play"| node_room_play
node_ai_play -->|"requests opponent move"| node_ai_router
node_ai_router -->|"routes move request"| node_engines
node_ai_router -->|"uses mounted runtimes"| node_engine_views
node_ai_play -->|"renders game board"| node_board
node_board -->|"uses chess rules"| node_chess_rules
node_room_play -.->|"manages room session"| node_room_hook
node_room_hook -->|"uses game operations"| node_games
node_room_hook -->|"calls backend"| node_api
node_parent_home -->|"displays family data"| node_parent_data
node_parent_data -->|"loads and updates"| node_api
node_parent_data -->|"derives progress"| node_parent_models
node_child_profile -.->|"shows child details"| node_parent_data
node_attendance -.->|"shows attendance"| node_parent_data
node_parent_home -->|"shows tournament information"| node_tournaments
node_tournament_detail -->|"loads tournament"| node_tournaments
node_tournaments -.->|"uses backend"| node_api

click node_sign_in "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/index.tsx"
click node_session "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/session.tsx"
click node_token "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/token-store.ts"
click node_api "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/api.ts"
click node_student_home "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/index.tsx"
click node_puzzles "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/puzzles.ts"
click node_lichess "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/lichess.ts"
click node_challenge "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/challenge.tsx"
click node_play_entry "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/play/index.tsx"
click node_ai_play "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/play/ai.tsx"
click node_friend_play "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/play/friend.tsx"
click node_room_play "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/play/room/%5BroomId%5D.tsx"
click node_ai_router "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/game/useAiOpponent.ts"
click node_engines "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/engines/maia-engine.ts"
click node_engine_views "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/game/OnnxWebView.tsx"
click node_board "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/game/ChessBoard.tsx"
click node_chess_rules "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/chess-core.ts"
click node_room_hook "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/game/useRoom.ts"
click node_games "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/games.ts"
click node_parent_home "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/parent/index.tsx"
click node_parent_data "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/parent/ParentData.tsx"
click node_parent_models "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/parent-v2-data.ts"
click node_child_profile "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/parent/child/%5BchildId%5D/index.tsx"
click node_attendance "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/parent/attendance.tsx"
click node_tournaments "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/tournaments.ts"
click node_tournament_detail "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/tournament/%5Bid%5D.tsx"
click node_push "https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/push.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_sign_in,node_session,node_token,node_api,node_push toneBlue
class node_student_home,node_puzzles,node_lichess,node_challenge,node_backend toneAmber
class node_play_entry,node_ai_play,node_friend_play,node_room_play,node_ai_router,node_engines,node_engine_views,node_board,node_chess_rules,node_room_hook,node_games toneMint
class node_parent_home,node_parent_data,node_parent_models,node_child_profile,node_attendance,node_tournaments,node_tournament_detail toneRose
class node_user toneIndigo
```

## Components

### Identity and access

- [Sign-in](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/index.tsx): `src/app/index.tsx`
- [Session provider](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/session.tsx): `src/lib/session.tsx`
- [Secure token store](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/token-store.ts): `src/lib/token-store.ts`
- [Backend client](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/api.ts): `src/lib/api.ts`
- [Push notifications](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/push.ts): `src/lib/push.ts`

### Student learning

- [Student home](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/index.tsx): `src/app/student/index.tsx`
- [Puzzle practice](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/puzzles.ts): `src/lib/puzzles.ts`
- [Lichess connection](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/lichess.ts): `src/lib/lichess.ts`
- [Student challenges](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/challenge.tsx): `src/app/student/challenge.tsx`

### Chess play

- [Play selection](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/play/index.tsx): `src/app/student/play/index.tsx`
- [Computer game screen](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/play/ai.tsx): `src/app/student/play/ai.tsx`
- [Friend game](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/play/friend.tsx): `src/app/student/play/friend.tsx`
- [Room game](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/student/play/room/%5BroomId%5D.tsx): `src/app/student/play/room/[roomId].tsx`
- [Opponent selection](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/game/useAiOpponent.ts): `src/components/game/useAiOpponent.ts`
- [Chess engines](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/engines/maia-engine.ts): `src/lib/engines/maia-engine.ts`
- [Engine runtimes](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/game/OnnxWebView.tsx): `src/components/game/OnnxWebView.tsx`
- [Chess board](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/game/ChessBoard.tsx): `src/components/game/ChessBoard.tsx`
- [Chess rules](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/chess-core.ts): `src/lib/chess-core.ts`
- [Room session](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/game/useRoom.ts): `src/components/game/useRoom.ts`
- [Game API](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/games.ts): `src/lib/games.ts`

### Parent portal

- [Parent dashboard](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/parent/index.tsx): `src/app/parent/index.tsx`
- [Family data](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/components/parent/ParentData.tsx): `src/components/parent/ParentData.tsx`
- [Parent data transforms](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/parent-v2-data.ts): `src/lib/parent-v2-data.ts`
- [Child progress](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/parent/child/%5BchildId%5D/index.tsx): `src/app/parent/child/[childId]/index.tsx`
- [Attendance](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/parent/attendance.tsx): `src/app/parent/attendance.tsx`
- [Tournament services](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/lib/tournaments.ts): `src/lib/tournaments.ts`
- [Tournament detail](https://github.com/khinyadanarmoe/jtrax-mobile-app/blob/main/src/app/tournament/%5Bid%5D.tsx): `src/app/tournament/[id].tsx`

### Other components

- **Student or parent**
- **JTrax backend**

## Connections

- Student or parent → Sign-in: signs in (evidence: `src/app/index.tsx`)
- Sign-in → Session provider: uses session (evidence: `src/app/index.tsx`)
- Session provider → Backend client: authenticates through (evidence: `src/lib/session.tsx`)
- Session provider → Secure token store: restores and stores (evidence: `src/lib/session.tsx`)
- Session provider → Push notifications: registers devices (evidence: `src/lib/session.tsx`)
- Backend client → JTrax backend: sends API requests (evidence: `src/lib/api.ts`)
- Student home → Puzzle practice: loads puzzle data (evidence: `src/app/student/index.tsx`)
- Student home → Lichess connection: loads rating (evidence: `src/app/student/index.tsx`)
- Student home → Backend client: loads activity (evidence: `src/app/student/index.tsx`)
- Play selection → Computer game screen: offers computer play
- Play selection → Friend game: offers friend play
- Play selection → Room game: offers room play
- Computer game screen → Opponent selection: requests opponent move (evidence: `src/app/student/play/ai.tsx`)
- Opponent selection → Chess engines: routes move request (evidence: `src/components/game/useAiOpponent.ts`)
- Opponent selection → Engine runtimes: uses mounted runtimes (evidence: `src/components/game/useAiOpponent.ts`)
- Computer game screen → Chess board: renders game board (evidence: `src/app/student/play/ai.tsx`)
- Chess board → Chess rules: uses chess rules (evidence: `src/components/game/ChessBoard.tsx`)
- Room game → Room session: manages room session
- Room session → Game API: uses game operations (evidence: `src/components/game/useRoom.ts`)
- Room session → Backend client: calls backend (evidence: `src/components/game/useRoom.ts`)
- Parent dashboard → Family data: displays family data (evidence: `src/app/parent/index.tsx`)
- Family data → Backend client: loads and updates (evidence: `src/components/parent/ParentData.tsx`)
- Family data → Parent data transforms: derives progress (evidence: `src/components/parent/ParentData.tsx`)
- Child progress → Family data: shows child details (evidence: `src/app/parent/child/[childId]/index.tsx`)
- Attendance → Family data: shows attendance
- Parent dashboard → Tournament services: shows tournament information (evidence: `src/app/parent/index.tsx`)
- Tournament detail → Tournament services: loads tournament (evidence: `src/app/tournament/[id].tsx`)
- Tournament services → Backend client: uses backend
