DuTaTo

Active learning app that prevents cognitive debt by using Claude as a Socratic AI tutor. Instead of giving direct answers, the AI enforces reflection, asks probing questions, and gates advanced features by mastery level.

Stack

Core Concepts

• Cognitive debt prevention — AI never gives direct answers; learners must think first
• Mastery levels (0-5) — gate features by demonstrated knowledge
• Kolb's learning cycle — track CE, RO, AC, AE phases per session
• Mandatory reflection — sessions can't complete without it
• 8 Claude interaction modes — Socratic dialogue, quiz, gated explanation, code review, practice problems, confused student (role reversal), review card generation, assessment

Architecture

Clean Architecture with 3 layers:

lib/
  domain/entities/       # Pure Dart classes, no dependencies
  data/
    models/              # JSON-serializable models (freezed)
    datasources/         # Supabase & Claude API clients
  presentation/
    providers/           # Riverpod providers
    screens/             # 14 screen categories
    widgets/             # Reusable UI components
  config/                # Routes, theme, API configs
  core/                  # Utils (SM-2), extensions, error handling

Screen categories: admin_onboarding, auth, backoffice, bookmarks, domains, goals, home, lesson, notes, org, progress, review, settings, tutor.

Notes and bookmarks are under Library: the Notes list (/notes) shows the latest notes, pinned first, with a server-side search over every note's title, content and tags (up to 50 matches, with a caption when there are more), and /notes?topicId=… (the lesson's notes action) narrows it to one topic; /bookmarks lists bookmarked topics, lesson parts and tutor sessions. The Terms and the Privacy Policy are linked from the sign-up form, the sign-in screen, the terms acceptance screen and Settings; those links open the hosted pages (web/terms.html, web/privacy.html, or their French copies web/fr/terms.html, web/fr/privacy.html when the app's language is French) on the site of the build's environment (dutato-staging.pages.dev for staging builds, dutato.pages.dev for prod), whose Markdown mirrors live in docs/ (*.fr.md for French).

New users land straight on Home after sign-up and the terms gate — there is no learner onboarding tour. OnboardingGate only shows the pending-invitations modal and sends org admins through the 4-step admin onboarding wizard.

Writes (chat sessions and messages, notes, review logs) go straight to Supabase; there is no offline queue. Client-generated UUIDs keep retries idempotent, and failures surface through the normal error states (a failed review-log write is only logged, since the card's new schedule is already saved).

Content

The app is a platform for structured learning — it does not ship with pre-loaded content for all users. Domain owners create curricula (domains, books, topics, lessons) and control access via visibility settings (private, shared, public) and curriculum shares.

Getting content in

Three paths, in ascending order of effort:

The import and CLI paths share one insert path (createDomain → insertTopics → insertChunks), so a curriculum behaves identically whichever produced it.

Content can also be populated using the tooling in tools/:

• pdf_pipeline/ — extracts and structures lessons from PDF textbooks
• curriculum_creator/ — AI agent pipeline supporting PDFs, web pages, and code repos

Platforms

Web-specific behavior

Native-only dependencies are isolated behind conditional-import barrels so the JS bundle never includes dart:io or the Firebase SDKs:

• flutter_local_notifications → no-op stub on web (notification_service_barrel.dart)
• firebase_core / firebase_messaging → no-op stubs on web (fcm_setup_barrel.dart, fcm_service_barrel.dart), so FCM push is native-only
• AI providers → browsers block direct calls to the provider APIs (CORS), so web routes every AI call through the ai-proxy Edge Function; native calls the provider directly

On wide screens (≥800px), the bottom NavigationBar is replaced by a side NavigationRail.

Android setup

The Android build requires a real google-services.json from Firebase Console placed at android/app/google-services.json (gitignored). Without it, Firebase initialization fails at runtime (caught gracefully — the app runs but push notifications are disabled).

Getting Started

# Install dependencies
flutter pub get

# Set up environment variables
cp .env.example .env  # Add your Supabase URL, anon key, and Claude API key

# Run the app (iOS)
flutter run

# Run the app (Web)
flutter run -d chrome

# Run the app (Android)
flutter run -d android

# Run code generation (after modifying models)
dart run build_runner build --delete-conflicting-outputs

Staging vs production

The app has two environments that ship side-by-side with separate bundle IDs (com.alienard.dutato for prod, com.alienard.dutato.staging for staging) and separate Supabase projects:

• Staging auto-deploys on every merge to main via .github/workflows/ci.yml: schema migrations, every Edge Function folder in supabase/functions/, and web (→ dutato-staging.pages.dev) against the staging Supabase project. No local command needed.
• Production deploys via ./dto release on your machine — web (→ dutato.pages.dev), iOS (TestFlight), Android (Firebase App Distribution), all tied to a git tag.

Both apps coexist on the same device so you can compare behavior side-by-side. Internal testers get the staging build first; once you're happy, ./dto release promotes the same commit to production.

Local release workflow

Releases run entirely from your machine — no GitHub Actions minutes consumed:

./dto release                        # Prod: codegen → clean-tree check → pre-flight → sync prod Supabase → bump → push → web → TestFlight → Firebase
./dto release --staging              # Staging apps only: staging iOS TestFlight + staging Android Firebase

The prod pipeline regenerates Dart code, refuses to run on a dirty working tree, pre-flights every downstream track (iOS/Android/web file + env-var checks), syncs the prod Supabase schema + Edge Functions, bumps pubspec.yaml, tags, pushes, deploys prod web to Cloudflare Pages, builds iOS for TestFlight, and builds Android for Firebase App Distribution. Each step aborts on failure; the pre-flight step catches missing Firebase configs / signing keys / env vars before any state mutation so a fixable misconfiguration never publishes an orphan tag; Supabase sync happens before the version bump so a broken sync never tags a release the prod instance can't serve; web/iOS/Android uploads happen after the tag is pushed so partial failures are recoverable with the individual ./dto deploy … commands.

The staging pipeline is lighter: it only builds and uploads the mobile apps because staging web + Supabase were already deployed by CI on merge to main.

Flags: --bump {patch,minor,major}, --skip-supabase, --skip-web, --skip-ios, --skip-android, --staging.

The underlying sub-commands (./dto deploy supabase [--env staging], ./dto version --push, ./dto deploy ios --testflight [--env staging], ./dto deploy android --distribute [--env staging], ./dto deploy web [--env staging]) are still available for debugging or one-off operations. The fallback .github/workflows/release.yml accepts an env input (prod/staging) and is manual-only (workflow_dispatch) so pushing tags never triggers an unused CI run.

The app always talks to the Supabase project baked in at build time (--dart-define=SUPABASE_URL / SUPABASE_ANON_KEY). A build without credentials, or one whose Supabase init fails, shows a "Service unavailable" screen at /unavailable. Hosted projects are migrated with supabase db push (CI for staging, ./dto release / ./dto deploy supabase for prod).

Documentation

The generated Dart API reference is published at dutato-docs.pages.dev on every merge to main (Cloudflare Pages, auto-deployed from CI). It covers the Flutter client (lib/) and is grouped into five categories: Overview, Architecture, Data Sources, Providers, Screens & Widgets. Category intros live in doc/categories/; the site is built with dart doc and configured via dartdoc_options.yaml.

./dto docs             # Build HTML into doc/api/ (gitignored)
./dto docs serve       # Serve doc/api/ on http://localhost:8081
./dto docs manifest    # Regenerate committed doc/api-manifest.json (CI drift gate)
                       # On macOS: defaults to running dartdoc in a Linux Docker
                       # image so the manifest is byte-identical to CI's
                       # ubuntu-latest output. Pass --no-docker to fall back
                       # to host dartdoc.
./dto ci               # Full CI; auto-enables --docs when lib/ changes

The full HTML is never committed — only the lightweight doc/api-manifest.json, a deterministically-sorted list of every public symbol. When a PR changes the public surface, CI's docs-check job fails until the author regenerates and commits the manifest. The deploy job rebuilds HTML from scratch for every push to main.

Developer CLI (dto)

All project tooling is unified under the ./dto CLI (Python/Click, managed by uv). No manual install needed — uv auto-creates the venv on first run.

./dto --help          # List all commands
./dto <command> --help  # Command-specific help

Commands

Quick Reference

# Build & serve web locally
./dto serve                           # local Supabase + demo seed + serve :8080 (default)
./dto serve --prod                    # use prod credentials from .env instead
./dto serve --skip-build              # Just serve existing build

# Screenshots (default: local Supabase + Acme demo seed for populated screens)
./dto screen --all                    # Full pipeline (build + all screenshots)
./dto screen --audit                  # 40-screen audit (desktop + mobile)
./dto screen --b2b                    # 12 B2B pitch screenshots
./dto screen --audit --multi-role     # + role-gated variants as manager/member
./dto screen --audit --demo-user=manager  # Screenshot as a specific role

# Opt out of demo seed (build against remote Supabase from .env — gives empty/loader screens)
./dto screen --all --no-demo

# Audits (responsiveness, accessibility, performance) — demo mode default
./dto audit responsive                # 9 viewports × 30 routes, overflow + touch targets
./dto audit responsive --strict       # Same, but exits 1 on overflow / sub-44px tap targets (local-only gate; bundled into ./dto ci --responsive)
./dto audit a11y                      # Flutter semantics + axe + tab order + focus rings
./dto audit perf                      # Core Web Vitals + Flutter first-frame + Lighthouse
./dto audit all                       # Run all 3 with single build + seed
./dto audit perf --cold-only --skip-lighthouse  # Fastest perf run (no warm, no Lighthouse)

# Visual regression (baseline at test/visual/baseline/{desktop,mobile}/)
./dto visual diff                     # Re-capture + pixelmatch vs baseline (local check, exits 1 on regression)
./dto visual capture                  # First-time baseline capture (refuses if baseline exists)
./dto visual bless                    # Overwrite baseline after a deliberate UI change (alias for capture --force)
./dto visual diff --tolerance=0.01    # Loosen the 0.5% default fail threshold

# Testing
./dto test                            # Unit/widget tests
./dto test --integration              # Integration tests (starts local Supabase)
./dto test --all                      # Unit + integration
./dto test --rls                      # RLS Docker smoke tests
./dto test --coverage                 # Unit tests + 70% coverage gate
./dto ci                              # Full CI; auto-detects gates from the diff vs origin/main
./dto ci --no-auto                    # Base steps only (no auto-detect)
./dto ci --rls                        # Force --rls on top of auto-detection
./dto ci --responsive --visual        # Force the local-only UI gates (auto-enabled when lib/, assets/, or web/ change)
./dto ci --goldens --web-build        # Force the closed-gap remote-mirror gates
                                      #   (also auto-enabled by lib/, assets/, web/, pubspec.* changes)

# Build & deploy (prod is default; append `--env staging` for staging builds)
./dto deploy ios                      # Build prod IPA + install on device
./dto deploy ios --testflight         # Build + upload to prod TestFlight
./dto deploy ios --testflight --env staging  # Build + upload to staging TestFlight
./dto deploy android                  # Build prod APK + install via ADB
./dto deploy android --env staging    # Build staging APK + install via ADB
./dto deploy android --distribute     # Build prod APK + upload to Firebase App Distribution
./dto deploy web                      # Build prod web release (local)
./dto deploy web --env staging        # Build staging web release (local)
./dto deploy supabase                 # Sync prod Supabase (migrations + every Edge Function folder)
./dto deploy supabase --env staging   # Sync staging Supabase (rarely needed — CI handles this)

# Version management
./dto version                         # Patch bump (0.1.3 → 0.1.4)
./dto version --minor                 # Minor bump
./dto version --push                  # Bump + push to origin

# Demo data
./dto seed                            # Seed Acme Learning Corp (17 users, 3 teams)

# Database
./dto db backup                       # Dump public schema + auth.users
./dto db restore                      # List available backups
./dto db restore backups/<timestamp>  # Restore specific backup

# User management
./dto user delete --email user@example.com
./dto user delete --email user@example.com --dry-run

# Content pipeline
./dto pipeline                        # Process all PDF books
./dto pipeline --file book.pdf --domain code --title "Clean Code" --author "R. Martin"
./dto pipeline extract book.pdf       # Extract text only
./dto pipeline upload --domain code   # Upload to Supabase
./dto pipeline embeddings             # Generate vector embeddings

# Curriculum creator
./dto curriculum status output/postgresql/
./dto curriculum upload --input output/postgresql/ --owner org --org-id <uuid>
./dto curriculum condense --input output/postgresql/ --plan <plan.json>

Testing

CI runs 8 parallel jobs on PRs to main:

1. Lint & Format — dart format + flutter analyze + the dto CLI pytest suite (~1min)
2. Edge Function Check — deno check across every Edge Function + deno test across supabase/functions/ (the ai-proxy suites: prompt-injection corpus, prompts, sanitize, validate, model-id guard, hourly rate-limit cap; send-push's opt-in rule; export-user-data's payload; the _shared DB helpers) (~30s)
3. Unit Tests — unit/widget tests with 70% coverage gate (~3min)
4. Integration Tests — datasource tests against local Supabase with 80% coverage gate (~3min)
5. RLS & RPC Tests — Dockerized PostgreSQL running RLS assertions and RPC smoke tests (~2min)
6. Widget Goldens — Alchemist visual-regression snapshots for shared widgets (~1min)
7. Docs Manifest Drift — fails if doc/api-manifest.json is stale (~2min)
8. Web Build (staging) — Flutter web release build with staging Supabase secrets, uploaded as the deploy artifact (~3min)

The responsive audit (./dto audit responsive --strict, 9-viewport Playwright run) and the pixelmatch visual-diff (./dto visual diff) are intentionally not in PR CI: they hang unpredictably on GHA's headless Chromium and would burn ~22 runner minutes per PR. They run locally only — auto-detected by ./dto ci when lib/, assets/, or web/ changes.

The goldens and web-build PR jobs are mirrored locally (auto-fired on the same triggers): --goldens runs Alchemist's golden suite inside the Linux Flutter Docker image (so macOS skia drift doesn't break the gate), and --web-build runs flutter build web --release natively with placeholder --dart-define values for the staging secrets — the build embeds them as compile-time constants but doesn't actually call out to Supabase, so placeholders catch every build-time error CI catches without needing real credentials.

Native-config regressions (Android manifest intent-filter, iOS Info.plist OAuth scheme, project.pbxproj bundle-ID drift, xcconfig flavor wiring) are caught at the unit-test layer by test/platform/oauth_deep_link_config_test.dart, which parses the native files and cross-checks them against EnvConfig.deepLinkScheme. The full end-to-end Android APK + emulator smoke and iOS xcodebuild flavor build would add ~54min per PR (macOS minutes bill at 10× Linux) so they're not run in PR CI — ./dto ci auto-detects native-config changes and runs the local gates:

./dto ci   # auto-runs --android-deeplink when android/ changes (needs an emulator running)
./dto ci   # auto-runs --ios when ios/ changes (needs Xcode)

If a gate's preconditions are missing (no emulator, no Xcode, no Docker), ./dto ci aborts with an actionable message — silent skipping is exactly the bug auto-detection exists to prevent. The path → gate trigger table lives in tools/dto/dto_cli/auto_gates.py.

On push to main, Deploy to Cloudflare Pages downloads the web-build artifact (no rebuild). Stale CI runs are auto-cancelled when new commits are pushed (concurrency.cancel-in-progress).

Demo Data (Sales Demos)

Seeds a realistic org ("Acme Learning Corp") with 17 users, 3 teams, manager hierarchy, assignments, learning paths, skills and role profiles, certifications and compliance requirements, XP/badges, and notifications against local Supabase.

./dto seed   # One command — starts Supabase if needed

Data persists across supabase stop/start. After supabase db reset, re-run ./dto seed. Login: alice.morgan@acme-demo.test / DemoPass-Acme-123!. See tools/demo_seed/README.md for all accounts.

Project Structure

dutato/
  lib/                  # Flutter app source
  docs/                 # Methodology documentation
    methodology.md      # Learning theory, cognitive debt, mastery gating
    content-structure.md # Content inventory and topic tree design
    claude-prompts.md   # 8 Claude system prompts
    spaced-repetition.md # SM-2 algorithm and review card types
    RELEASE.md          # Release process
    PRIVACY_POLICY.md   # Mirror of web/privacy.html (kept identical by test/legal/)
    PRIVACY_POLICY.fr.md # French mirror of web/fr/privacy.html
    TERMS_OF_USE.md     # Mirror of the in-app terms and web/terms.html
    TERMS_OF_USE.fr.md  # French mirror of the in-app terms and web/fr/terms.html
  plans/                # Development milestones (plan-1 through plan-52)
  supabase/
    migrations/         # Database schema (98 migrations)
    functions/          # Edge Functions: ai-proxy, send-push, export-user-data
  assets/splash/        # Splash-screen images
  dto                   # CLI wrapper (run ./dto --help)
  tools/
    dto/                # CLI package (Python/Click)
    pdf_pipeline/       # Content extraction and processing
    curriculum_creator/ # AI agent-operated curriculum pipeline
    db_backup/          # Database backup and restore utilities
    demo_seed/          # Sales demo org (Acme Learning Corp, 17 users)
    visual/             # pixelmatch + diff.js (./dto visual harness)
  web/                  # Flutter web platform (index.html, manifest, icons) + the hosted privacy.html and terms.html (French copies in web/fr/)
  test/                 # 277 test files
    helpers/            # Shared mocks & Supabase test init
    visual/baseline/    # Committed PNG baselines for ./dto visual diff (local check)
    integration/        # 39 integration test files (tagged, require Supabase)
    rls/                # RLS policy + RPC smoke tests (Docker + PostgreSQL)
    platform/           # Native config guardrails (OAuth deep-link, bundle IDs)
    legal/              # In-app terms, web pages and Markdown mirrors stay identical, in English and French; translation_sources.json pins each French section to the English it translates

Database

Supabase PostgreSQL with 98 migrations. Key table groups:

• Content: domains (with owner_id, visibility, is_starter), books, topics (hierarchical), content_chunks, curriculum_levels, curriculum_shares, domain_variants, reading_questions, reading_responses, user_starter_enrollments (opt-in reference to a curated starter)
• User progress: profiles (with target_retention, fsrs_parameters, admin_onboarding_step / admin_onboarding_completed_at, seen_tooltips; the learner onboarding_step / onboarding_completed_at columns are no longer used), user_topic_progress, learning_sessions, conversation_messages, learning_objectives
• Review system: review_cards (FSRS + SM-2 dual-algorithm), review_log (immutable per-event history), quizzes, assessments, mastery_overrides
• Calibration: confidence_events, topic_retention_stats
• Prerequisites: topic_prerequisites (required/recommended strength)
• Goals & annotations: learning_goals, user_annotations, user_notes, user_bookmarks
• Organizations: organizations, org_members, org_invitations, org_verified_domains (an org admin's domain stays pending until a platform admin verifies it from the back office; public mailbox domains are refused, migration 083), teams, team_members, curriculum_assignments (with status tracking), manager_assignments, platform_admins. Members read each other's profiles only while both are active members (migration 085). The Settings → Privacy switches for organization invitations and curriculum sharing are enforced by the database (migration 088), and a refusal names the switch (096). People who leave an organization lose access to it, and the organization stops seeing their progress, XP and badges; the certificates it issued them stay on its records (migrations 093, 097). People join only by invitation or a verified domain; admins manage roles up to admin, only owners grant or revoke ownership, and an organization always keeps one owner (migration 098)
• Enterprise: certifications, user_certificates, compliance_requirements, skills, role_profiles, role_skill_expectations, member_role_assignments, learning_paths, learning_path_steps, learning_path_enrollments. Migration 074 removed the plan gates from certifications, compliance_requirements and learning_paths, so their writes are role-gated only (org owner/admin/manager).
• Gamification: user_xp, xp_events, badges, user_badges (XP is recorded by the server only: record_xp_event is service-role only, migration 082)
• Infrastructure: device_tokens, rate_limits (ai-proxy hourly cap), sanitization_logs, audit_log (append-only visibility/share events for legal compliance), user_ai_settings (per-user AI provider/key/model, RLS-scoped to owner; writes require profiles.ai_sync_consent_at, so "Stop syncing" is enforced by the database, migration 081; clearing the consent deletes the synced rows in the same transaction and a racing upload waits for it, migrations 084, 087 and 095)
• Dropped in migration 075 (plan 52): the billing tables and entitlement functions, the SSO / API-key / webhook / Slack-Notion-Lucca integration tables, and _schema_meta (bring-your-own Supabase). plans/plan-52-poc-cut.md has the re-add map. ai_limits_for_user is back as a service-role-only stub with no caps (migration 089), so the pre-cut ai-proxy keeps answering until the new one is deployed.

Schema defined in supabase/migrations/. Row-Level Security (RLS) policies enforce access control — see test/rls/ for smoke tests, including rls_enterprise_test.sql (which asserts that an org admin with no plan can write learning paths, certifications and compliance requirements), rls_starter_test.sql (which pins the platform-admin-only is_starter flag and the starter-enrolment policies), rls_bookmarks_test.sql (per-user bookmark isolation, one bookmark per topic / part / session since migration 076, and resolve_bookmark_targets since migration 092, which resolves the Bookmarks screen in one request: only the caller's bookmarks, parts numbered in the lesson's reading order, and a target the caller can no longer read resolved to NULLs) and rls_account_deletion_test.sql (no foreign key on a delete path from auth.users may be NO ACTION/RESTRICT, and no ON DELETE SET NULL may land on a NOT NULL or CHECK-constrained column; deleting an account or a curriculum succeeds and keeps organization and starter curricula, migration 078; an organization curriculum then goes to the organization's most senior member (highest role, then earliest to join), who also becomes owner if the deleted user was the only one, migration 086; deleting a learning path or curriculum a certification targets keeps the certification and the certificates issued for it, migration 080; and every foreign key a curriculum deletion reaches is pinned, because the privacy policy and the account-deletion dialog describe exactly what it removes). rpc_smoke_test.sql also pins that only an org owner/admin/manager can run team_progress_report and compliance_status (migration 077), and fails on any SECURITY DEFINER function a client role can execute without its body checking the caller (migration 079: XP, badges, certificates, org notifications, email lookup, domain auto-join; the ai-proxy rate-limit functions and, since migration 082, record_xp_event are service-role only). It also pins search_user_notes (migration 091: every one of the caller's notes, by plain-text substring over title, content and tags) and the ai_limits_for_user stub. rls_smoke_test.sql checks that only a curriculum's owner can share it (migration 094) and that sessions written before the app sent UTC are marked as such (migration 090). The container's auth stub grants functions to anon, authenticated and service_role the way hosted Supabase does, so a function revoked only FROM PUBLIC is still caught (RPC-GRANTS).

AI and Edge Functions

The learner brings their own AI access: a Claude API key, a ChatGPT sign-in (OpenAI OAuth), or a Google sign-in (Gemini). The provider and model chosen in Settings → AI are persisted in secure storage (per-provider credentials and model also sync to user_ai_settings once the user consents to cloud sync) and are the only ones any AI call uses until the learner changes them there. Native builds call the provider directly; web builds go through ai-proxy, because browsers block direct calls to the provider APIs (CORS). In-app curriculum import is the exception: it always uses ai-proxy's structure mode, on every platform, because its prompt and input cap live server-side.

Edge Functions in supabase/functions/:

• ai-proxy — AI relay for web builds and for curriculum import: JWT check, mode whitelist, server-side prompt assembly (get_tutor_context), prompt-injection input scoring and response validation, a model-id shape guard, one JSON answer per request (a request asking to stream gets a 400), and a 500 requests/hour per-user abuse cap on rate_limits (calls run on the learner's own credentials, so this is not a usage quota)
• send-push — sends the overdue-cards and streak FCM reminders, only to users who turned that reminder on in Settings → Notifications (opt-in: a switch never saved is off, as the app shows it); service-role only; on prod it is driven by the send-push-morning / send-push-evening pg_cron jobs
• export-user-data — GDPR data export (Article 20) of the signed-in user's data as a JSON download. test/data/export_user_data_columns_test.dart replays the migrations and fails when a column of an exported table is neither exported nor excluded with a reason