# appleorange/fluently architecture

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

- Interactive diagram: https://gitdiagram.com/appleorange/fluently
- Repository: https://github.com/appleorange/fluently

## Overview

1. **Top-level shape**
   - This is a **Next.js 14 App Router** application with a browser UI, a small set of server API routes, and a Redis-backed persistence/recommendation layer.
   - The system’s core is an **oral reading fluency assessment pipeline**: record audio, transcribe with timestamps, align against the expected passage, compute metrics, generate a diagnostic report, and recommend the next passage.

2. **Browser-facing app**
   - The main user flow lives in `src/app/practice/page.tsx`, with supporting pages for the landing page (`/`) and progress view (`/progress`).
   - UI is assembled from components like `AudioRecorder`, `PassageDisplay`, `PassageMap`, `DiagnosticReport`, `MetricsDashboard`, and `Nav`.
   - The practice page is the primary orchestration point for the assessment experience.

3. **Client-side recording and playback boundary**
   - `AudioRecorder` is the key boundary between the browser and external speech services.
   - The presence of `src/app/api/deepgram-token/route.ts` strongly suggests the browser first requests a short-lived Deepgram token from the server, then streams audio or transcription data using that token.
   - This keeps API credentials off the client while allowing low-latency speech capture.

4. **Server API layer**
   - The app exposes four focused API routes:
     - `deepgram-token` for authentication bootstrap
     - `diagnose` for generating the plain-language assessment report
     - `generate-passage` for selecting or creating the next practice passage
     - `session` for persisting and retrieving session history
   - These routes form the main backend surface; the browser talks to them, and they in turn call external services or Redis.

5. **Deterministic scoring pipeline**
   - The `src/lib/alignment.ts` and `src/lib/metrics.ts` modules implement the core grading logic.
   - The flow described in the README is:
     1. Deepgram returns word-level transcript data with timestamps
     2. The expected passage is aligned to the transcript using a deterministic Levenshtein-style process
     3. Metrics are derived from the alignment, including WCPM, error counts, pause placement, and self-corrections
   - This is the main “truth layer” of the system: it produces structured results before any AI-generated narrative is added.

6. **Passage generation and recommendation**
   - `src/lib/generatePassage.ts`, `src/lib/passageVectors.ts`, and `src/lib/sessionVector.ts` implement the passage-selection subsystem.
   - The app maintains a library of passages and uses **vector search in Redis Stack** to find the next passage that matches a reader’s inferred skill profile.
   - If no sufficiently close passage exists, a new one can be generated via the AI passage-generation route.

7. **Redis as the longitudinal memory**
   - `src/lib/redis.ts` backs persistence and search.
   - Redis Stack is doing two distinct jobs:
     - storing session history over time
     - supporting vector similarity search for passage recommendation
   - This is the long-term memory boundary of the system, distinct from the transient per-session assessment pipeline.

8. **Skill profile over time**
   - The README describes a per-reader skill vector with dimensions like complexity handling, register handling, WCPM, pause placement, and self-correction.
   - `progress/page.tsx` and `MetricsDashboard` likely visualize this longitudinal state.
   - This means the app is not just scoring a single reading; it is modeling improvement across sessions and feeding that history back into future recommendations and diagnostics.

9. **AI-generated narrative layer**
   - `src/app/api/diagnose/route.ts` and `src/app/api/generate-passage/route.ts` are the primary Anthropic integration points.
   - Claude is used only after deterministic analysis has produced structured data.
   - The README emphasizes a strong boundary: Claude sees metrics, tiers, and prior-session summaries, but **not raw audio or raw transcript**.

10. **External services and infrastructure**
   - **Deepgram** provides speech transcription with word timestamps.
   - **Anthropic** generates the diagnostic report and likely passage text when needed.
   - **Redis Stack** is required, not plain Redis, because RediSearch/vector search is part of the architecture.
   - These are all runtime dependencies, not optional add-ons.

11. **Data flow summary**
   - A typical practice session flows like this:
     - user selects or is assigned a passage
     - browser records reading
     - transcription data is obtained through Deepgram
     - alignment and metrics are computed in the app backend
     - session data is stored in Redis
     - passage recommendation is computed from the session vector
     - Claude produces the human-readable report
   - The browser then presents both the scorecard and the recommended next step.

12. **Important architectural boundary**
   - The repository cleanly separates:
     - **interactive UI** in React components
     - **deterministic scoring and vector logic** in `src/lib`
     - **server orchestration** in App Router route handlers
     - **external AI/speech services** behind the server boundary
   - That separation is what makes the system diagram straightforward: client UI, Next.js server, Redis, Deepgram, Anthropic.

13. **Implementation style**
   - The stack is TypeScript-first with Tailwind styling and Next.js App Router conventions.
   - `globals.css`, `layout.tsx`, and component CSS like `DotGrid.css` support the UI layer, while the “brains” live in library modules.
   - Overall, this is a **productized assessment pipeline** rather than a generic CRUD app or a pure front-end demo.

Main entry points: [`src/app/practice/page.tsx`](https://github.com/appleorange/fluently/blob/main/src/app/practice/page.tsx) (Practice flow), [`src/app/api/diagnose/route.ts`](https://github.com/appleorange/fluently/blob/main/src/app/api/diagnose/route.ts) (Diagnose API), [`src/app/api/generate-passage/route.ts`](https://github.com/appleorange/fluently/blob/main/src/app/api/generate-passage/route.ts) (Passage API), [`src/lib/redis.ts`](https://github.com/appleorange/fluently/blob/main/src/lib/redis.ts) (Redis stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_app_shell["App shell<br/>next app<br/>[layout.tsx]"]
  node_home_page["Landing page<br/>route page<br/>[page.tsx]"]
  node_practice_page["Practice flow<br/>route page<br/>[page.tsx]"]
  node_progress_page["Progress view<br/>route page<br/>[page.tsx]"]
  node_nav["Nav<br/>ui component<br/>[Nav.tsx]"]
  node_recorder["Audio recorder<br/>capture component<br/>[AudioRecorder.tsx]"]
  node_passage_display["Passage display<br/>reading component<br/>[PassageDisplay.tsx]"]
  node_passage_map["Passage map<br/>feedback component<br/>[PassageMap.tsx]"]
  node_metrics_dash["Metrics dashboard<br/>analytics component"]
  node_diagnostic_report["Diagnostic report<br/>report component"]
end

subgraph group_api["Server API"]
  node_deepgram_token_api["Token API<br/>route handler<br/>[route.ts]"]
  node_diagnose_api["Diagnose API<br/>route handler<br/>[route.ts]"]
  node_generate_passage_api["Passage API<br/>route handler<br/>[route.ts]"]
  node_session_api["Session API<br/>route handler<br/>[route.ts]"]
end

subgraph group_core["Core Logic"]
  node_alignment["Alignment<br/>scoring logic<br/>[alignment.ts]"]
  node_metrics["Metrics<br/>scoring logic<br/>[metrics.ts]"]
  node_passage_vectors["Passage vectors<br/>recommendation logic<br/>[passageVectors.ts]"]
  node_session_vector["Session vector<br/>reader model<br/>[sessionVector.ts]"]
  node_generate_passage_lib["Passage generator<br/>generation logic<br/>[generatePassage.ts]"]
  node_types["Types<br/>[types.ts]"]
end

subgraph group_infra["Infrastructure"]
  node_redis[("Redis stack<br/>storage adapter<br/>[redis.ts]")]
  node_deepgram["Deepgram<br/>speech service<br/>[deepgram.ts]"]
end

node_home_page -->|"uses"| node_nav
node_practice_page -->|"uses"| node_nav
node_practice_page -->|"orchestrates"| node_recorder
node_practice_page -->|"shows"| node_passage_display
node_practice_page -->|"renders"| node_passage_map
node_practice_page -->|"renders"| node_metrics_dash
node_practice_page -->|"renders"| node_diagnostic_report
node_progress_page -->|"reuses"| node_metrics_dash
node_recorder -->|"auth bootstrap"| node_deepgram_token_api
node_recorder -->|"streams"| node_deepgram
node_deepgram_token_api -->|"authenticates"| node_deepgram
node_diagnose_api -->|"consumes"| node_alignment
node_diagnose_api -->|"consumes"| node_metrics
node_diagnose_api -->|"reads history"| node_redis
node_diagnose_api -->|"feeds"| node_diagnostic_report
node_generate_passage_api -->|"profiles reader"| node_session_vector
node_generate_passage_api -->|"searches"| node_passage_vectors
node_generate_passage_api -->|"falls back to"| node_generate_passage_lib
node_generate_passage_api -->|"queries"| node_redis
node_session_api -->|"stores"| node_redis
node_alignment -->|"uses"| node_types
node_metrics -->|"uses"| node_types
node_session_vector -->|"derives from"| node_metrics
node_session_vector -->|"reads"| node_redis
node_passage_vectors -->|"indexes"| node_redis
node_generate_passage_lib -->|"uses"| node_types
node_diagnose_api -.->|"narrates"| node_metrics
node_generate_passage_api -.->|"informs"| node_session_api
node_practice_page -.->|"syncs"| node_session_api

click node_app_shell "https://github.com/appleorange/fluently/blob/main/src/app/layout.tsx"
click node_home_page "https://github.com/appleorange/fluently/blob/main/src/app/page.tsx"
click node_practice_page "https://github.com/appleorange/fluently/blob/main/src/app/practice/page.tsx"
click node_progress_page "https://github.com/appleorange/fluently/blob/main/src/app/progress/page.tsx"
click node_nav "https://github.com/appleorange/fluently/blob/main/src/components/Nav.tsx"
click node_recorder "https://github.com/appleorange/fluently/blob/main/src/components/AudioRecorder.tsx"
click node_passage_display "https://github.com/appleorange/fluently/blob/main/src/components/PassageDisplay.tsx"
click node_passage_map "https://github.com/appleorange/fluently/blob/main/src/components/PassageMap.tsx"
click node_metrics_dash "https://github.com/appleorange/fluently/blob/main/src/components/MetricsDashboard.tsx"
click node_diagnostic_report "https://github.com/appleorange/fluently/blob/main/src/components/DiagnosticReport.tsx"
click node_deepgram_token_api "https://github.com/appleorange/fluently/blob/main/src/app/api/deepgram-token/route.ts"
click node_diagnose_api "https://github.com/appleorange/fluently/blob/main/src/app/api/diagnose/route.ts"
click node_generate_passage_api "https://github.com/appleorange/fluently/blob/main/src/app/api/generate-passage/route.ts"
click node_session_api "https://github.com/appleorange/fluently/blob/main/src/app/api/session/route.ts"
click node_alignment "https://github.com/appleorange/fluently/blob/main/src/lib/alignment.ts"
click node_metrics "https://github.com/appleorange/fluently/blob/main/src/lib/metrics.ts"
click node_passage_vectors "https://github.com/appleorange/fluently/blob/main/src/lib/passageVectors.ts"
click node_session_vector "https://github.com/appleorange/fluently/blob/main/src/lib/sessionVector.ts"
click node_generate_passage_lib "https://github.com/appleorange/fluently/blob/main/src/lib/generatePassage.ts"
click node_types "https://github.com/appleorange/fluently/blob/main/src/lib/types.ts"
click node_redis "https://github.com/appleorange/fluently/blob/main/src/lib/redis.ts"
click node_deepgram "https://github.com/appleorange/fluently/blob/main/src/lib/deepgram.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_app_shell,node_home_page,node_practice_page,node_progress_page,node_nav,node_recorder,node_passage_display,node_passage_map,node_metrics_dash,node_diagnostic_report toneBlue
class node_deepgram_token_api,node_diagnose_api,node_generate_passage_api,node_session_api toneAmber
class node_alignment,node_metrics,node_passage_vectors,node_session_vector,node_generate_passage_lib,node_types toneMint
class node_redis,node_deepgram toneRose
```

## Components

### Browser UI

React pages and components for the practice and progress experience.

- [App shell](https://github.com/appleorange/fluently/blob/main/src/app/layout.tsx): next app · Root layout and landing page composition for the application. · `src/app/layout.tsx`
- [Landing page](https://github.com/appleorange/fluently/blob/main/src/app/page.tsx): route page · Public entry page for the product. · `src/app/page.tsx`
- [Practice flow](https://github.com/appleorange/fluently/blob/main/src/app/practice/page.tsx): route page · Main orchestration page for recording, scoring, and feedback. · `src/app/practice/page.tsx`
- [Progress view](https://github.com/appleorange/fluently/blob/main/src/app/progress/page.tsx): route page · Longitudinal reader progress and history view. · `src/app/progress/page.tsx`
- [Nav](https://github.com/appleorange/fluently/blob/main/src/components/Nav.tsx): ui component · Primary navigation shared across pages. · `src/components/Nav.tsx`
- [Audio recorder](https://github.com/appleorange/fluently/blob/main/src/components/AudioRecorder.tsx): capture component · Browser recording boundary that initiates speech capture. · `src/components/AudioRecorder.tsx`
- [Passage display](https://github.com/appleorange/fluently/blob/main/src/components/PassageDisplay.tsx): reading component · Shows the target passage during practice. · `src/components/PassageDisplay.tsx`
- [Passage map](https://github.com/appleorange/fluently/blob/main/src/components/PassageMap.tsx): feedback component · Visualizes alignment or reading flow against the passage. · `src/components/PassageMap.tsx`
- [Metrics dashboard](https://github.com/appleorange/fluently/blob/main/src/components/MetricsDashboard.tsx): analytics component · Displays scoring metrics and reader skill indicators. · `src/components/MetricsDashboard.tsx`
- [Diagnostic report](https://github.com/appleorange/fluently/blob/main/src/components/DiagnosticReport.tsx): report component · Presents the narrative assessment output. · `src/components/DiagnosticReport.tsx`

### Server API

Next.js route handlers that orchestrate authentication, scoring, storage, and generation.

- [Token API](https://github.com/appleorange/fluently/blob/main/src/app/api/deepgram-token/route.ts): route handler · Issues short-lived Deepgram credentials to the browser. · `src/app/api/deepgram-token/route.ts`
- [Diagnose API](https://github.com/appleorange/fluently/blob/main/src/app/api/diagnose/route.ts): route handler · Creates the plain-language assessment report from structured results. · `src/app/api/diagnose/route.ts`
- [Passage API](https://github.com/appleorange/fluently/blob/main/src/app/api/generate-passage/route.ts): route handler · Selects or creates the next practice passage. · `src/app/api/generate-passage/route.ts`
- [Session API](https://github.com/appleorange/fluently/blob/main/src/app/api/session/route.ts): route handler · Persists and retrieves session history and progress. · `src/app/api/session/route.ts`

### Core Logic

Deterministic alignment, metrics, recommendation, and shared types.

- [Alignment](https://github.com/appleorange/fluently/blob/main/src/lib/alignment.ts): scoring logic · Deterministic passage-to-transcript alignment using timestamps and edit distance. · `src/lib/alignment.ts`
- [Metrics](https://github.com/appleorange/fluently/blob/main/src/lib/metrics.ts): scoring logic · Derives WCPM, errors, pauses, and self-corrections from alignment. · `src/lib/metrics.ts`
- [Passage vectors](https://github.com/appleorange/fluently/blob/main/src/lib/passageVectors.ts): recommendation logic · Represents passage library features for similarity search. · `src/lib/passageVectors.ts`
- [Session vector](https://github.com/appleorange/fluently/blob/main/src/lib/sessionVector.ts): reader model · Builds the reader skill profile used for future recommendations. · `src/lib/sessionVector.ts`
- [Passage generator](https://github.com/appleorange/fluently/blob/main/src/lib/generatePassage.ts): generation logic · Fallback passage creation and recommendation support. · `src/lib/generatePassage.ts`
- [Types](https://github.com/appleorange/fluently/blob/main/src/lib/types.ts): shared types · Shared domain types for transcripts, metrics, and sessions. · `src/lib/types.ts`

### Infrastructure

Redis-backed persistence and external service adapters.

- [Redis stack](https://github.com/appleorange/fluently/blob/main/src/lib/redis.ts): storage adapter · Persistence and vector search boundary for sessions and passage matching. · `src/lib/redis.ts`
- [Deepgram](https://github.com/appleorange/fluently/blob/main/src/lib/deepgram.ts): speech service · External transcription service with word-level timestamps. · `src/lib/deepgram.ts`

## Connections

- Landing page → Nav: uses · Landing page includes shared navigation.
- Practice flow → Nav: uses · Practice experience uses shared navigation.
- Practice flow → Audio recorder: orchestrates · Main practice flow starts recording from the browser.
- Practice flow → Passage display: shows · Displays the current target passage.
- Practice flow → Passage map: renders · Shows reading alignment feedback.
- Practice flow → Metrics dashboard: renders · Surfaces computed performance metrics.
- Practice flow → Diagnostic report: renders · Shows the assessment narrative.
- Progress view → Metrics dashboard: reuses · Progress view reuses longitudinal metrics presentation.
- Audio recorder → Token API: auth bootstrap · Browser fetches a short-lived speech token before capture.
- Audio recorder → Deepgram: streams · Uses the speech service for transcription and timestamps.
- Token API → Deepgram: authenticates · Server-side token flow protects Deepgram credentials.
- Diagnose API → Alignment: consumes · Narrative generation is based on deterministic alignment outputs.
- Diagnose API → Metrics: consumes · Uses scoring metrics as structured input.
- Diagnose API → Redis stack: reads history · Pulls session context for report generation.
- Diagnose API → Diagnostic report: feeds · Produces the report data shown in the UI.
- Passage API → Session vector: profiles reader · Uses the reader skill profile to choose the next passage.
- Passage API → Passage vectors: searches · Matches against the passage library vector space.
- Passage API → Passage generator: falls back to · Can create a new passage when no close match exists.
- Passage API → Redis stack: queries · Uses Redis Stack for vector similarity and stored passages.
- Session API → Redis stack: stores · Persists session history and longitudinal progress.
- Alignment → Types: uses · Alignment works over shared domain data structures.
- Metrics → Types: uses · Metrics are computed on shared transcript and alignment types.
- Session vector → Metrics: derives from · Reader skill profile is built from prior performance metrics.
- Session vector → Redis stack: reads · Loads historical session data for the reader model.
- Passage vectors → Redis stack: indexes · Passage vectors are stored and queried in Redis Stack.
- Passage generator → Types: uses · Passage generation works with shared domain types.
- Diagnose API → Metrics: narrates · Structured metrics are converted into plain-language feedback.
- Passage API → Session API: informs · Recommendation results feed the persisted session record.
- Practice flow → Session API: syncs · Practice flow saves and restores session state.
