# ssmael14/math architecture

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

- Interactive diagram: https://gitdiagram.com/ssmael14/math
- Repository: https://github.com/ssmael14/math

## Overview

1. **What this repo is**
   - `Paskalito` is a Next.js application for children’s learning, with distinct experiences for the child, the parent, and the admin.
   - The UI is organized as a mobile-first app with lesson/play flows, profile management, shop/premium features, and gated parent/admin areas.

2. **Application shell and routing**
   - The app uses the Next.js App Router: `app/layout.tsx`, `app/page.tsx`, and many route folders under `app/`.
   - `app/globals.css` provides the global styling foundation.
   - `middleware.ts` likely enforces route-level access and redirects for auth/child selection/parental gating.

3. **Main product surfaces**
   - Child-facing flows: `home`, `subjects`, `units`, `paths`, `lesson/[id]`, `review`, `victory`, `game-over`, `level-up`, `shop`, `profile`, `settings`.
   - Account flows: `auth/login`, `auth/signup`, `auth/forgot`, `auth/reset`, and post-login routing.
   - Parent/admin flows: `parental`, `parental/gate`, `admin/assets`, `admin/audio`, `admin/premium`.

4. **Core learning runtime**
   - The lesson experience is centered on `app/lesson/[id]/LessonRunner.tsx` and the reusable exercise layer in `components/exercises/*`.
   - `lib/learning/*` is the domain engine: it generates exercises, evaluates answers, computes hints, difficulty, lesson access, ordering/matching state, trace scoring, and spaced repetition.
   - This is the main boundary between content/logic and presentation: the learning engine produces structured tasks, and the UI renders and collects interactions.

5. **Exercise system**
   - `components/exercises/types.ts` defines the common exercise shape.
   - `ExerciseRunner`, `ExerciseVisual`, `OptionsGrid`, `HintPanel`, `SpeakerButton`, `TraceCanvas`, and the input components under `components/exercises/inputs/` implement the actual interaction modes.
   - The repo supports many activity types: tapping, dragging, matching, ordering, numeric entry, number line, trace/writing, money, comparison, subitising, and more.

6. **Data and persistence**
   - Prisma is the persistence layer: `prisma/schema.prisma`, migrations, `lib/prisma.ts`, and `lib/queries.ts`.
   - The stored domain clearly includes children, enrollments, progress, attempts, shop/premium state, and parental controls.
   - Seed scripts (`prisma/seed.ts`, `prisma/seed-content.ts`) indicate the content model is partially generated and can be refreshed separately from user data.

7. **Authentication and access control**
   - Authentication is centralized in `lib/auth/*` and the NextAuth-style route at `app/api/auth/[...auth]/route.ts`.
   - Access is segmented by user context: child accounts, parent sessions, and admin users.
   - `app/parental/session.ts` and `app/api/parental-pin/route.ts` show an explicit parental gate, while `ADMIN_EMAILS` controls admin-only capabilities like Cloudinary signing and premium management.

8. **Parent and child profile flow**
   - The app supports multiple child profiles via `app/profile/*`, including create, edit, select, and child switching.
   - `app/api/children/*` and `app/api/children/select/route.ts` back this flow, so the visible profile changes are backed by server state.
   - This separation matters architecturally: most learning content depends on the currently selected child, not just the logged-in parent.

9. **Gamification and progression**
   - `lib/gamification/*` handles scoring, audio feedback, streaks, and animated count-up behavior.
   - User progression lives around `app/api/attempts`, `app/api/progress`, `app/game-over`, `app/level-up`, `app/victory`, and `app/review`.
   - The learning loop is: start lesson → submit attempts → record progress → reward via scoring/streak/level-up/victory screens.

10. **Subscriptions, shop, and premium**
   - Premium state is a first-class boundary: `lib/premium.ts`, `app/premium`, `app/api/admin/users/[userId]/plan`, and `app/admin/premium`.
   - The shop uses `app/shop`, `app/api/shop/buy`, and `app/api/shop/equip`, implying in-app collectible or cosmetic purchases tied to progression.
   - `app/achievements` and related gamification routes reinforce retention and status.

11. **Media, audio, and external services**
   - Cloudinary is used for dynamic image assets and admin uploads: `lib/cloudinary.ts`, `app/api/admin/cloudinary/sign-upload`, and `app/admin/assets`.
   - TTS/audio generation is handled through `lib/tts/*`, `app/api/admin/gen-audio`, and `scripts/gen-audio.ts`, likely backed by ElevenLabs or a similar service.
   - Brand and visual assets are split intentionally: stable shell assets live in `public/brand/` and dynamic/replaceable assets can be pushed to Cloudinary.

12. **Offline and PWA behavior**
   - The app is installable/PWA-capable via `public/manifest.webmanifest`, `public/sw.js`, and `components/pwa/PwaProvider.tsx`.
   - `lib/offline-queue.ts` and `app/offline` indicate queued behavior when connectivity is poor, which is especially relevant for a child learning app.
   - This creates a clear client-side resilience layer around the lesson/progress flow.

13. **Observability and analytics**
   - `components/analytics/MetaPixel.tsx` and `lib/analytics/parent-insights.ts` suggest product analytics and parent-facing reporting.
   - The architecture keeps analytics as a separate concern from lesson logic, so usage tracking can inform parent insights without coupling to the exercise engine.

14. **Tooling and architecture constraints**
   - The repo is TypeScript-heavy, tested with Vitest (`tests/*`, `vitest.config.ts`), and built with Prisma migrations plus seed scripts.
   - `docker-compose.yml` suggests a local environment for dependencies like the database.
   - The repository is designed so content/learning logic can be tested independently from the UI, which is important for the number-heavy pedagogy and exercise generation code.

Main entry points: [`prisma/schema.prisma`](https://github.com/ssmael14/math/blob/main/prisma/schema.prisma) (Prisma Data), [`lib/learning/generators.ts`](https://github.com/ssmael14/math/blob/main/lib/learning/generators.ts) (Learning Core), [`app/home/page.tsx`](https://github.com/ssmael14/math/blob/main/app/home/page.tsx) (Home), [`app/lesson/[id]/LessonRunner.tsx`](https://github.com/ssmael14/math/blob/main/app/lesson/[id]/LessonRunner.tsx) (Lesson Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app_shell["App Shell"]
  node_n_layout["Layout<br/>nextjs shell<br/>[layout.tsx]"]
  node_n_page["Landing<br/>entry page<br/>[page.tsx]"]
  node_n_middleware["Middleware<br/>route guard<br/>[middleware.ts]"]
end

subgraph group_group_learning["Learning Engine"]
  node_n_lesson_runner["Lesson Runner<br/>lesson runtime<br/>[LessonRunner.tsx]"]
  node_n_exercises["Exercises<br/>exercise ui<br/>[ExerciseRunner.tsx]"]
  node_n_inputs["Input Modes<br/>exercise inputs<br/>[CountTapInput.tsx]"]
  node_n_learning_core["Learning Core<br/>pedagogy engine<br/>[generators.ts]"]
  node_n_trace["Trace Scoring<br/>writing logic<br/>[trace-scoring.ts]"]
end

subgraph group_group_data["Data & Services"]
  node_n_progress["Progress API<br/>progress service<br/>[route.ts]"]
  node_n_db[("Prisma Data<br/>database layer<br/>[schema.prisma]")]
  node_n_auth["Auth<br/>[server.ts]"]
  node_n_premium["Premium<br/>subscription gate<br/>[premium.ts]"]
  node_n_media["Media Services<br/>asset pipeline<br/>[cloudinary.ts]"]
  node_n_pwa["Offline/PWA<br/>resilience layer<br/>[PwaProvider.tsx]"]
  node_n_analytics["Analytics<br/>insights layer<br/>[MetaPixel.tsx]"]
end

subgraph group_group_clients["Client Surfaces"]
  node_n_home["Home<br/>child dashboard<br/>[page.tsx]"]
  node_n_curriculum["Curriculum<br/>browse flows<br/>[page.tsx]"]
  node_n_parental["Parental Gate<br/>parent session<br/>[session.ts]"]
  node_n_profiles["Profiles<br/>child selector<br/>[page.tsx]"]
  node_n_shop["Shop<br/>reward economy<br/>[page.tsx]"]
  node_n_admin["Admin Tools<br/>admin console<br/>[page.tsx]"]
end

node_n_layout -->|"renders"| node_n_page
node_n_layout -->|"routes to"| node_n_home
node_n_middleware -->|"enforces"| node_n_auth
node_n_middleware -->|"guards"| node_n_parental
node_n_home -->|"navigates"| node_n_curriculum
node_n_curriculum -->|"starts lessons"| node_n_lesson_runner
node_n_lesson_runner -->|"renders"| node_n_exercises
node_n_exercises -->|"uses"| node_n_inputs
node_n_lesson_runner -->|"requests tasks"| node_n_learning_core
node_n_exercises -->|"consumes"| node_n_learning_core
node_n_learning_core -->|"supports"| node_n_trace
node_n_learning_core -->|"emits results"| node_n_progress
node_n_progress -->|"persists"| node_n_db
node_n_auth -->|"reads users"| node_n_db
node_n_profiles -->|"updates child state"| node_n_db
node_n_parental -->|"reads gate state"| node_n_db
node_n_shop -->|"checks entitlement"| node_n_premium
node_n_premium -->|"stores plans"| node_n_db
node_n_admin -->|"manages assets"| node_n_media
node_n_media -.->|"references content"| node_n_db
node_n_pwa -->|"supports"| node_n_home
node_n_analytics -.->|"tracks usage"| node_n_home
node_n_analytics -.->|"reports insights"| node_n_parental

click node_n_layout "https://github.com/ssmael14/math/blob/main/app/layout.tsx"
click node_n_page "https://github.com/ssmael14/math/blob/main/app/page.tsx"
click node_n_middleware "https://github.com/ssmael14/math/blob/main/middleware.ts"
click node_n_home "https://github.com/ssmael14/math/blob/main/app/home/page.tsx"
click node_n_curriculum "https://github.com/ssmael14/math/blob/main/app/subjects/page.tsx"
click node_n_lesson_runner "https://github.com/ssmael14/math/blob/main/app/lesson/[id]/LessonRunner.tsx"
click node_n_exercises "https://github.com/ssmael14/math/blob/main/components/exercises/ExerciseRunner.tsx"
click node_n_inputs "https://github.com/ssmael14/math/blob/main/components/exercises/inputs/CountTapInput.tsx"
click node_n_learning_core "https://github.com/ssmael14/math/blob/main/lib/learning/generators.ts"
click node_n_trace "https://github.com/ssmael14/math/blob/main/lib/learning/trace-scoring.ts"
click node_n_progress "https://github.com/ssmael14/math/blob/main/app/api/progress/route.ts"
click node_n_db "https://github.com/ssmael14/math/blob/main/prisma/schema.prisma"
click node_n_auth "https://github.com/ssmael14/math/blob/main/lib/auth/server.ts"
click node_n_parental "https://github.com/ssmael14/math/blob/main/app/parental/session.ts"
click node_n_profiles "https://github.com/ssmael14/math/blob/main/app/profile/page.tsx"
click node_n_shop "https://github.com/ssmael14/math/blob/main/app/shop/page.tsx"
click node_n_premium "https://github.com/ssmael14/math/blob/main/lib/premium.ts"
click node_n_admin "https://github.com/ssmael14/math/blob/main/app/admin/assets/page.tsx"
click node_n_media "https://github.com/ssmael14/math/blob/main/lib/cloudinary.ts"
click node_n_pwa "https://github.com/ssmael14/math/blob/main/components/pwa/PwaProvider.tsx"
click node_n_analytics "https://github.com/ssmael14/math/blob/main/components/analytics/MetaPixel.tsx"

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_n_layout,node_n_page,node_n_middleware toneBlue
class node_n_lesson_runner,node_n_exercises,node_n_inputs,node_n_learning_core,node_n_trace toneAmber
class node_n_progress,node_n_db,node_n_auth,node_n_premium,node_n_media,node_n_pwa,node_n_analytics toneMint
class node_n_home,node_n_curriculum,node_n_parental,node_n_profiles,node_n_shop,node_n_admin toneRose
```

## Components

### App Shell

Next.js routing, layout, middleware, and route-level surfaces.

- [Layout](https://github.com/ssmael14/math/blob/main/app/layout.tsx): nextjs shell · Global app shell and routing entrypoints. · `app/layout.tsx`
- [Landing](https://github.com/ssmael14/math/blob/main/app/page.tsx): entry page · Top-level landing or post-login entry route. · `app/page.tsx`
- [Middleware](https://github.com/ssmael14/math/blob/main/middleware.ts): route guard · Cross-route access control and redirects. · `middleware.ts`

### Learning Engine

Lesson runtime, exercise system, and pedagogical logic.

- [Lesson Runner](https://github.com/ssmael14/math/blob/main/app/lesson/[id]/LessonRunner.tsx): lesson runtime · Orchestrates a lesson session and exercise progression. · `app/lesson/[id]/LessonRunner.tsx`
- [Exercises](https://github.com/ssmael14/math/blob/main/components/exercises/ExerciseRunner.tsx): exercise ui · Reusable interaction components for learning tasks. · `components/exercises/ExerciseRunner.tsx`
- [Input Modes](https://github.com/ssmael14/math/blob/main/components/exercises/inputs/CountTapInput.tsx): exercise inputs · Tap, drag, match, order, numeric, trace, and comparison inputs. · `components/exercises/inputs/CountTapInput.tsx`
- [Learning Core](https://github.com/ssmael14/math/blob/main/lib/learning/generators.ts): pedagogy engine · Exercise generation, evaluation, hints, difficulty, and spacing. · `lib/learning/generators.ts`
- [Trace Scoring](https://github.com/ssmael14/math/blob/main/lib/learning/trace-scoring.ts): writing logic · Gesture handling, trace templates, and writing evaluation. · `lib/learning/trace-scoring.ts`

### Data & Services

Persistence, auth, media, premium, and external service boundaries.

- [Progress API](https://github.com/ssmael14/math/blob/main/app/api/progress/route.ts): progress service · Attempts and progress recording used by lesson flows. · `app/api/progress/route.ts`
- [Prisma Data](https://github.com/ssmael14/math/blob/main/prisma/schema.prisma): database layer · Schema, queries, and Prisma client for app state. · `prisma/schema.prisma`
- [Auth](https://github.com/ssmael14/math/blob/main/lib/auth/server.ts): session auth · Central authentication configuration and server/client helpers. · `lib/auth/server.ts`
- [Premium](https://github.com/ssmael14/math/blob/main/lib/premium.ts): subscription gate · Premium state and admin-managed plan changes. · `lib/premium.ts`
- [Media Services](https://github.com/ssmael14/math/blob/main/lib/cloudinary.ts): asset pipeline · Cloudinary uploads and TTS/audio generation. · `lib/cloudinary.ts`
- [Offline/PWA](https://github.com/ssmael14/math/blob/main/components/pwa/PwaProvider.tsx): resilience layer · Installable app shell and offline queue handling. · `components/pwa/PwaProvider.tsx`
- [Analytics](https://github.com/ssmael14/math/blob/main/components/analytics/MetaPixel.tsx): insights layer · Meta pixel and parent-insights reporting. · `components/analytics/MetaPixel.tsx`

### Client Surfaces

Child, parent, admin, and support experiences.

- [Home](https://github.com/ssmael14/math/blob/main/app/home/page.tsx): child dashboard · Main child-facing starting point. · `app/home/page.tsx`
- [Curriculum](https://github.com/ssmael14/math/blob/main/app/subjects/page.tsx): browse flows · Subjects, units, and paths used to navigate lessons. · `app/subjects/page.tsx`
- [Parental Gate](https://github.com/ssmael14/math/blob/main/app/parental/session.ts): parent session · Parental session state and PIN verification boundary. · `app/parental/session.ts`
- [Profiles](https://github.com/ssmael14/math/blob/main/app/profile/page.tsx): child selector · Create, edit, and switch between child profiles. · `app/profile/page.tsx`
- [Shop](https://github.com/ssmael14/math/blob/main/app/shop/page.tsx): reward economy · In-app purchases, equips, and premium surface. · `app/shop/page.tsx`
- [Admin Tools](https://github.com/ssmael14/math/blob/main/app/admin/assets/page.tsx): admin console · Asset, audio, and premium administration surfaces. · `app/admin/assets/page.tsx`

## Connections

- Layout → Landing: renders · Global shell wraps the landing/entry route.
- Layout → Home: routes to · The shell leads into the child dashboard experience.
- Middleware → Auth: enforces · Route access depends on authenticated session context.
- Middleware → Parental Gate: guards · Parent-only and gated areas are protected here.
- Home → Curriculum: navigates · Home links into subjects, units, and paths.
- Curriculum → Lesson Runner: starts lessons · Curriculum browsing leads into lesson sessions.
- Lesson Runner → Exercises: renders · The lesson runner mounts the reusable exercise UI.
- Exercises → Input Modes: uses · The exercise layer delegates to specialized interaction modes.
- Lesson Runner → Learning Core: requests tasks · Lesson flow is driven by generated exercises and feedback.
- Exercises → Learning Core: consumes · Inputs and visuals follow the learning engine contracts.
- Learning Core → Trace Scoring: supports · Core pedagogy includes trace/writing evaluation and scoring.
- Learning Core → Progress API: emits results · Answer evaluation and progression are persisted through APIs.
- Progress API → Prisma Data: persists · Attempts, progress, and state land in Prisma-backed storage.
- Auth → Prisma Data: reads users · Authentication and user context are backed by stored records.
- Profiles → Prisma Data: updates child state · Profile selection and switching are stored server-side.
- Parental Gate → Prisma Data: reads gate state · Parental sessions and related controls depend on persisted data.
- Shop → Premium: checks entitlement · Shop and premium experiences depend on current plan state.
- Premium → Prisma Data: stores plans · Subscription and premium grants are recorded in the database.
- Admin Tools → Media Services: manages assets · Admin tooling signs uploads and generates audio assets.
- Media Services → Prisma Data: references content · Asset and audio workflows are coordinated with app records.
- Offline/PWA → Home: supports · Offline-ready shell supports the main learning journey.
- Analytics → Home: tracks usage · Analytics observe product engagement from the client surface.
- Analytics → Parental Gate: reports insights · Parent-facing reporting is separated from lesson logic.
