# iamedisonu/tools architecture

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

- Interactive diagram: https://gitdiagram.com/iamedisonu/tools
- Repository: https://github.com/iamedisonu/tools

## Overview

Language Lab is a browser-based adaptive ELA learning platform for students and classroom staff. The main learner path is account/session selection, curriculum practice and studio work, SmartScore and review updates, then local persistence; linked school devices can synchronize records. Staff also plan assignments, review submissions, and use classroom reporting tools. The graph preserves documented reading, writing, typing, AI, and classroom capabilities. Some subsystems are represented by exact tree paths because their implementation was not sampled; edges are limited to shown references or README statements.

Main entry points: [`src/App.tsx`](https://github.com/iamedisonu/tools/blob/main/src/App.tsx) (Application Shell), [`src/services/aiService.ts`](https://github.com/iamedisonu/tools/blob/main/src/services/aiService.ts) (Adaptive Questions), [`src/services/writingCoach.ts`](https://github.com/iamedisonu/tools/blob/main/src/services/writingCoach.ts) (Writing Studio), [`src/engine/storage.ts`](https://github.com/iamedisonu/tools/blob/main/src/engine/storage.ts) (Learner Records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and Accounts"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_accounts["Accounts<br/>[accounts.ts]"]
  node_routes["View Routing<br/>[routes.ts]"]
end

subgraph group_learning["ELA Learning"]
  node_curriculum["ELA Curriculum<br/>[elaCurriculum.ts]"]
  node_exercise_types["Exercise Models<br/>[ela.ts]"]
  node_question_service["Adaptive Questions<br/>[aiService.ts]"]
  node_practice_arena["Practice Arena"]
  node_smartscore["SmartScore Progress<br/>[elaSmartScore.ts]"]
  node_review["Adaptive Review<br/>[adaptiveReview.ts]"]
end

subgraph group_studios["Learning Studios"]
  node_reading["Reading Studio"]
  node_writing["Writing Studio<br/>[writingCoach.ts]"]
  node_typing["Typing Studio"]
  node_stories["Story Content<br/>[storyPool.ts]"]
end

subgraph group_classroom["Classroom Tools"]
  node_classroom_work["Assignments and Classes<br/>[weeklyPackages.ts]"]
  node_class_reports["Class Reports<br/>[classReports.ts]"]
end

subgraph group_platform["Platform Services"]
  node_local_storage[("Learner Records<br/>[storage.ts]")]
  node_scope["User Storage Scope<br/>[userScope.ts]"]
  node_cloud_link["School Link<br/>[cloudLink.ts]"]
  node_sync["Cloud Sync<br/>[cloudSync.ts]"]
  node_gemini_api["Gemini Proxy<br/>[gemini.ts]"]
  node_speech_scoring["Speech Scoring<br/>[app.py]"]
  node_integrity["Writing Integrity<br/>[app.py]"]
end

node_learner(("Learner or Staff"))

node_learner -->|"uses"| node_app
node_app -->|"loads session"| node_accounts
node_app -->|"loads progress"| node_local_storage
node_app -->|"parses routes"| node_routes
node_app -->|"renders studio"| node_reading
node_app -->|"prefetches questions"| node_question_service
node_practice_arena -->|"uses skills"| node_curriculum
node_practice_arena -.->|"requests questions"| node_question_service
node_question_service -->|"produces questions"| node_exercise_types
node_question_service -->|"calls proxy"| node_gemini_api
node_review -->|"loads and saves"| node_local_storage
node_local_storage -->|"scopes keys"| node_scope
node_local_storage -->|"reads review state"| node_review
node_writing -->|"uses AI service"| node_question_service
node_writing -->|"checks integrity"| node_integrity
node_writing -->|"uses story pool"| node_stories
node_accounts -->|"loads and saves link"| node_cloud_link
node_sync -->|"reads link"| node_cloud_link
node_sync -->|"syncs packages"| node_classroom_work
node_learner -.->|"uses read-aloud scoring"| node_speech_scoring
node_learner -->|"practices typing"| node_typing
node_learner -->|"writes and revises"| node_writing
node_learner -->|"completes assignments"| node_classroom_work

click node_app "https://github.com/iamedisonu/tools/blob/main/src/App.tsx"
click node_accounts "https://github.com/iamedisonu/tools/blob/main/src/engine/accounts.ts"
click node_routes "https://github.com/iamedisonu/tools/blob/main/src/engine/routes.ts"
click node_curriculum "https://github.com/iamedisonu/tools/blob/main/src/data/elaCurriculum.ts"
click node_exercise_types "https://github.com/iamedisonu/tools/blob/main/src/types/ela.ts"
click node_question_service "https://github.com/iamedisonu/tools/blob/main/src/services/aiService.ts"
click node_practice_arena "https://github.com/iamedisonu/tools/blob/main/src/views/ElaPracticeArena.tsx"
click node_smartscore "https://github.com/iamedisonu/tools/blob/main/src/engine/elaSmartScore.ts"
click node_review "https://github.com/iamedisonu/tools/blob/main/src/engine/adaptiveReview.ts"
click node_reading "https://github.com/iamedisonu/tools/blob/main/src/views/ReadingStudioView.tsx"
click node_writing "https://github.com/iamedisonu/tools/blob/main/src/services/writingCoach.ts"
click node_typing "https://github.com/iamedisonu/tools/blob/main/src/views/TypingStudioView.tsx"
click node_stories "https://github.com/iamedisonu/tools/blob/main/src/data/storyPool.ts"
click node_classroom_work "https://github.com/iamedisonu/tools/blob/main/src/engine/weeklyPackages.ts"
click node_class_reports "https://github.com/iamedisonu/tools/blob/main/src/engine/classReports.ts"
click node_local_storage "https://github.com/iamedisonu/tools/blob/main/src/engine/storage.ts"
click node_scope "https://github.com/iamedisonu/tools/blob/main/src/engine/userScope.ts"
click node_cloud_link "https://github.com/iamedisonu/tools/blob/main/src/engine/cloudLink.ts"
click node_sync "https://github.com/iamedisonu/tools/blob/main/src/engine/cloudSync.ts"
click node_gemini_api "https://github.com/iamedisonu/tools/blob/main/api/gemini.ts"
click node_speech_scoring "https://github.com/iamedisonu/tools/blob/main/server/speech-scorer/app.py"
click node_integrity "https://github.com/iamedisonu/tools/blob/main/server/writing-integrity/app.py"

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_app,node_accounts,node_routes toneBlue
class node_curriculum,node_exercise_types,node_question_service,node_practice_arena,node_smartscore,node_review toneAmber
class node_reading,node_writing,node_typing,node_stories toneMint
class node_classroom_work,node_class_reports toneRose
class node_local_storage,node_scope,node_cloud_link,node_sync,node_gemini_api,node_speech_scoring,node_integrity,node_learner toneIndigo
```

## Components

### App and Accounts

- [Application Shell](https://github.com/iamedisonu/tools/blob/main/src/App.tsx): `src/App.tsx`
- [Accounts](https://github.com/iamedisonu/tools/blob/main/src/engine/accounts.ts): `src/engine/accounts.ts`
- [View Routing](https://github.com/iamedisonu/tools/blob/main/src/engine/routes.ts): `src/engine/routes.ts`

### ELA Learning

- [ELA Curriculum](https://github.com/iamedisonu/tools/blob/main/src/data/elaCurriculum.ts): `src/data/elaCurriculum.ts`
- [Exercise Models](https://github.com/iamedisonu/tools/blob/main/src/types/ela.ts): `src/types/ela.ts`
- [Adaptive Questions](https://github.com/iamedisonu/tools/blob/main/src/services/aiService.ts): `src/services/aiService.ts`
- [Practice Arena](https://github.com/iamedisonu/tools/blob/main/src/views/ElaPracticeArena.tsx): `src/views/ElaPracticeArena.tsx`
- [SmartScore Progress](https://github.com/iamedisonu/tools/blob/main/src/engine/elaSmartScore.ts): `src/engine/elaSmartScore.ts`
- [Adaptive Review](https://github.com/iamedisonu/tools/blob/main/src/engine/adaptiveReview.ts): `src/engine/adaptiveReview.ts`

### Learning Studios

- [Reading Studio](https://github.com/iamedisonu/tools/blob/main/src/views/ReadingStudioView.tsx): `src/views/ReadingStudioView.tsx`
- [Writing Studio](https://github.com/iamedisonu/tools/blob/main/src/services/writingCoach.ts): `src/services/writingCoach.ts`
- [Typing Studio](https://github.com/iamedisonu/tools/blob/main/src/views/TypingStudioView.tsx): `src/views/TypingStudioView.tsx`
- [Story Content](https://github.com/iamedisonu/tools/blob/main/src/data/storyPool.ts): `src/data/storyPool.ts`

### Classroom Tools

- [Assignments and Classes](https://github.com/iamedisonu/tools/blob/main/src/engine/weeklyPackages.ts): `src/engine/weeklyPackages.ts`
- [Class Reports](https://github.com/iamedisonu/tools/blob/main/src/engine/classReports.ts): `src/engine/classReports.ts`

### Platform Services

- [Learner Records](https://github.com/iamedisonu/tools/blob/main/src/engine/storage.ts): `src/engine/storage.ts`
- [User Storage Scope](https://github.com/iamedisonu/tools/blob/main/src/engine/userScope.ts): `src/engine/userScope.ts`
- [School Link](https://github.com/iamedisonu/tools/blob/main/src/engine/cloudLink.ts): `src/engine/cloudLink.ts`
- [Cloud Sync](https://github.com/iamedisonu/tools/blob/main/src/engine/cloudSync.ts): `src/engine/cloudSync.ts`
- [Gemini Proxy](https://github.com/iamedisonu/tools/blob/main/api/gemini.ts): `api/gemini.ts`
- [Speech Scoring](https://github.com/iamedisonu/tools/blob/main/server/speech-scorer/app.py): `server/speech-scorer/app.py`
- [Writing Integrity](https://github.com/iamedisonu/tools/blob/main/server/writing-integrity/app.py): `server/writing-integrity/app.py`

### Other components

- **Learner or Staff**

## Connections

- Learner or Staff → Application Shell: uses (evidence: `README.md`)
- Application Shell → Accounts: loads session (evidence: `src/App.tsx`)
- Application Shell → Learner Records: loads progress (evidence: `src/App.tsx`)
- Application Shell → View Routing: parses routes (evidence: `src/App.tsx`)
- Application Shell → Reading Studio: renders studio (evidence: `src/App.tsx`)
- Application Shell → Adaptive Questions: prefetches questions (evidence: `src/App.tsx`)
- Practice Arena → ELA Curriculum: uses skills
- Practice Arena → Adaptive Questions: requests questions
- Adaptive Questions → Exercise Models: produces questions (evidence: `src/services/aiService.ts`)
- Adaptive Questions → Gemini Proxy: calls proxy (evidence: `src/services/aiService.ts`)
- Adaptive Review → Learner Records: loads and saves (evidence: `src/components/AdaptiveReviewSession.tsx`)
- Learner Records → User Storage Scope: scopes keys (evidence: `src/engine/storage.ts`)
- Learner Records → Adaptive Review: reads review state (evidence: `src/engine/storage.ts`)
- Writing Studio → Adaptive Questions: uses AI service (evidence: `src/services/writingCoach.ts`)
- Writing Studio → Writing Integrity: checks integrity (evidence: `src/services/writingCoach.ts`)
- Writing Studio → Story Content: uses story pool (evidence: `src/services/writingCoach.ts`)
- Accounts → School Link: loads and saves link (evidence: `src/engine/accounts.ts`)
- Cloud Sync → School Link: reads link (evidence: `src/engine/cloudSync.ts`)
- Cloud Sync → Assignments and Classes: syncs packages (evidence: `src/engine/cloudSync.ts`)
- Learner or Staff → Speech Scoring: uses read-aloud scoring
- Learner or Staff → Typing Studio: practices typing (evidence: `README.md`)
- Learner or Staff → Writing Studio: writes and revises (evidence: `README.md`)
- Learner or Staff → Assignments and Classes: completes assignments (evidence: `README.md`)