How ssmael14/math works
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: schema.prisma Prisma Data · generators.ts Learning Core · page.tsx Home · LessonRunner.tsx Lesson Runner
Components 21
App Shell
Next.js routing, layout, middleware, and route-level surfaces.
- Layout · Global app shell and routing entrypoints.
app/layout.tsx - Landing · Top-level landing or post-login entry route.
app/page.tsx - Middleware · Cross-route access control and redirects.
middleware.ts
Learning Engine
Lesson runtime, exercise system, and pedagogical logic.
- Lesson Runner · Orchestrates a lesson session and exercise progression.
app/lesson/[id]/LessonRunner.tsx - Exercises · Reusable interaction components for learning tasks.
components/exercises/ExerciseRunner.tsx - Input Modes · Tap, drag, match, order, numeric, trace, and comparison inputs.
components/exercises/inputs/CountTapInput.tsx - Learning Core · Exercise generation, evaluation, hints, difficulty, and spacing.
lib/learning/generators.ts - Trace Scoring · Gesture handling, trace templates, and writing evaluation.
lib/learning/trace-scoring.ts
Data & Services
Persistence, auth, media, premium, and external service boundaries.
- Progress API · Attempts and progress recording used by lesson flows.
app/api/progress/route.ts - Prisma Data · Schema, queries, and Prisma client for app state.
prisma/schema.prisma - Auth · Central authentication configuration and server/client helpers.
lib/auth/server.ts - Premium · Premium state and admin-managed plan changes.
lib/premium.ts - Media Services · Cloudinary uploads and TTS/audio generation.
lib/cloudinary.ts - Offline/PWA · Installable app shell and offline queue handling.
components/pwa/PwaProvider.tsx - Analytics · Meta pixel and parent-insights reporting.
components/analytics/MetaPixel.tsx
Client Surfaces
Child, parent, admin, and support experiences.
- Home · Main child-facing starting point.
app/home/page.tsx - Curriculum · Subjects, units, and paths used to navigate lessons.
app/subjects/page.tsx - Parental Gate · Parental session state and PIN verification boundary.
app/parental/session.ts - Profiles · Create, edit, and switch between child profiles.
app/profile/page.tsx - Shop · In-app purchases, equips, and premium surface.
app/shop/page.tsx - Admin Tools · Asset, audio, and premium administration surfaces.
app/admin/assets/page.tsx
Connections 23
- 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.