# ejnburrows-rgb/cartilla-de-gretel architecture

> Architecture diagram of the GitHub repository ejnburrows-rgb/cartilla-de-gretel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ejnburrows-rgb/cartilla-de-gretel
- Repository: https://github.com/ejnburrows-rgb/cartilla-de-gretel

## Overview

La Cartilla de Gretel is a digital classroom edition of a Spanish literacy workbook. Learners enter through the book and lesson experience, practice with interactive activities—including a speaking piano and microphone-based syllable recognition—and can retain progress locally or sync it through student services. Teachers have a separate authenticated classroom and CRM experience. The graph emphasizes documented runtime links; several broader lesson, workbook, and teacher capabilities are represented by their source directories because their implementation was not sampled.

Main entry points: [`src/components/cartilla/piano/usePianoSession.ts`](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/components/cartilla/piano/usePianoSession.ts) (Speaking piano session), [`src/routes/cartilla`](https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/routes/cartilla) (Book and lesson routes), [`src/integrations/supabase/client.ts`](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/integrations/supabase/client.ts) (Supabase client), [`src/lib/student-session.ts`](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/lib/student-session.ts) (Student progress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_app["App entry<br/>[main.tsx]"]
  node_router["Route registry<br/>[router.tsx]"]
  node_lesson_routes["Book and lesson routes"]
  node_workbook["Workbook views"]
end

subgraph group_learning["Learning activities"]
  node_activity_ui["Interactive activities"]
  node_piano_session["Speaking piano session<br/>[usePianoSession.ts]"]
  node_piano_listening["Microphone listening"]
  node_lesson_content["Lesson content"]
  node_gretel_avatar["Gretel live avatar"]
  node_gretel_animation["Gretel animation"]
end

subgraph group_progress["Progress and teaching"]
  node_student_session["Student progress<br/>[student-session.ts]"]
  node_learner_storage[("Learner-scoped storage<br/>[learner-storage.ts]")]
  node_teacher_routes["Teacher routes"]
  node_teacher_crm["Teacher CRM"]
end

subgraph group_services["Shared services"]
  node_supabase_client["Supabase client<br/>[client.ts]"]
  node_speech_playback["Speech playback<br/>[speech-playback.ts]"]
  node_audio_engine["Audio engine<br/>[audio-engine.ts]"]
end

node_learner(("Learner"))
node_supabase[("Supabase service")]
node_speech_recognition["Browser speech recognition"]

node_app -->|"starts"| node_router
node_router -.->|"routes via registry"| node_lesson_routes
node_learner -.->|"opens lessons"| node_lesson_routes
node_lesson_routes -.->|"renders views"| node_workbook
node_workbook -.->|"offers activities"| node_activity_ui
node_piano_session -->|"starts listening"| node_piano_listening
node_piano_listening -->|"uses browser API"| node_speech_recognition
node_piano_session -->|"claims speech"| node_speech_playback
node_piano_session -.->|"uses word content"| node_lesson_content
node_gretel_avatar -->|"uses animation"| node_gretel_animation
node_gretel_animation -.->|"uses character states"| node_lesson_content
node_student_session -.->|"records locally"| node_learner_storage
node_student_session -->|"submits progress"| node_supabase_client
node_supabase_client -->|"connects when configured"| node_supabase
node_teacher_routes -->|"checks session"| node_supabase_client
node_teacher_routes -.->|"serves CRM pages"| node_teacher_crm
node_audio_engine -->|"stops picture speech"| node_speech_playback

click node_app "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/main.tsx"
click node_router "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/router.tsx"
click node_lesson_routes "https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/routes/cartilla"
click node_workbook "https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/components/cartilla"
click node_activity_ui "https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/cartilla/interactions"
click node_piano_session "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/components/cartilla/piano/usePianoSession.ts"
click node_piano_listening "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/hooks/usePianoListening.ts"
click node_lesson_content "https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/content"
click node_gretel_avatar "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/components/gretel/GretelLiveAvatar.tsx"
click node_gretel_animation "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/components/gretel/useGretelAnimation.ts"
click node_student_session "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/lib/student-session.ts"
click node_learner_storage "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/lib/learner-storage.ts"
click node_teacher_routes "https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/routes/cartilla/teacher"
click node_teacher_crm "https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/features/teacher-crm"
click node_supabase_client "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/integrations/supabase/client.ts"
click node_speech_playback "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/lib/speech-playback.ts"
click node_audio_engine "https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/lib/audio-engine.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,node_router,node_lesson_routes,node_workbook,node_speech_recognition toneBlue
class node_activity_ui,node_piano_session,node_piano_listening,node_lesson_content,node_gretel_avatar,node_gretel_animation,node_supabase toneAmber
class node_student_session,node_learner_storage,node_teacher_routes,node_teacher_crm toneMint
class node_supabase_client,node_speech_playback,node_audio_engine toneRose
class node_learner toneIndigo
```

## Components

### Learner experience

- [App entry](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/main.tsx): `src/main.tsx`
- [Route registry](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/router.tsx): `src/router.tsx`
- [Book and lesson routes](https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/routes/cartilla): `src/routes/cartilla`
- [Workbook views](https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/components/cartilla): `src/components/cartilla`

### Learning activities

- [Interactive activities](https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/cartilla/interactions): `src/cartilla/interactions`
- [Speaking piano session](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/components/cartilla/piano/usePianoSession.ts): `src/components/cartilla/piano/usePianoSession.ts`
- [Microphone listening](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/hooks/usePianoListening.ts): `src/hooks/usePianoListening.ts`
- [Lesson content](https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/content): `src/content`
- [Gretel live avatar](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/components/gretel/GretelLiveAvatar.tsx): `src/components/gretel/GretelLiveAvatar.tsx`
- [Gretel animation](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/components/gretel/useGretelAnimation.ts): `src/components/gretel/useGretelAnimation.ts`

### Progress and teaching

- [Student progress](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/lib/student-session.ts): `src/lib/student-session.ts`
- [Learner-scoped storage](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/lib/learner-storage.ts): `src/lib/learner-storage.ts`
- [Teacher routes](https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/routes/cartilla/teacher): `src/routes/cartilla/teacher`
- [Teacher CRM](https://github.com/ejnburrows-rgb/cartilla-de-gretel/tree/main/src/features/teacher-crm): `src/features/teacher-crm`

### Shared services

- [Supabase client](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/integrations/supabase/client.ts): `src/integrations/supabase/client.ts`
- [Speech playback](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/lib/speech-playback.ts): `src/lib/speech-playback.ts`
- [Audio engine](https://github.com/ejnburrows-rgb/cartilla-de-gretel/blob/main/src/lib/audio-engine.ts): `src/lib/audio-engine.ts`

### Other components

- **Learner**
- **Supabase service**
- **Browser speech recognition**

## Connections

- App entry → Route registry: starts (evidence: `src/main.tsx`)
- Route registry → Book and lesson routes: routes via registry
- Learner → Book and lesson routes: opens lessons
- Book and lesson routes → Workbook views: renders views
- Workbook views → Interactive activities: offers activities
- Speaking piano session → Microphone listening: starts listening (evidence: `src/components/cartilla/piano/usePianoSession.ts`)
- Microphone listening → Browser speech recognition: uses browser API (evidence: `src/hooks/usePianoListening.ts`)
- Speaking piano session → Speech playback: claims speech (evidence: `src/components/cartilla/piano/usePianoSession.ts`)
- Speaking piano session → Lesson content: uses word content
- Gretel live avatar → Gretel animation: uses animation (evidence: `src/components/gretel/GretelLiveAvatar.tsx`)
- Gretel animation → Lesson content: uses character states
- Student progress → Learner-scoped storage: records locally
- Student progress → Supabase client: submits progress (evidence: `src/lib/student-session.ts`)
- Supabase client → Supabase service: connects when configured (evidence: `src/integrations/supabase/client.ts`)
- Teacher routes → Supabase client: checks session (evidence: `src/routes/cartilla/teacher/route.tsx`)
- Teacher routes → Teacher CRM: serves CRM pages
- Audio engine → Speech playback: stops picture speech (evidence: `src/lib/audio-engine.ts`)
