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/             # 15 screen categories
    widgets/             # Reusable UI components
  config/                # Routes, theme, API configs
  core/                  # Utils (SM-2), extensions, error handling

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

First-connection onboarding (Plan 49) routes freshly-signed-up users through display name → persona → pending invitations → Socratic learner tour (5 steps) → org admin wizard (4 steps) before the home screen. Replayable from Settings.

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.

Content can 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

Three native-only dependencies are isolated behind conditional-import barrels so the JS bundle never includes dart:io or native FFI code:

• flutter_onnxruntime → no-op stub on web (local embeddings disabled)
• sqlite3 / sqlite_vector → no-op stub on web (local vector store disabled)
• flutter_local_notifications → no-op stub on web (push via FCM still works)

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, Edge 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: bundle → commit drift → sync prod Supabase → bump → push → web → TestFlight → Firebase
./dto release --staging              # Staging apps only: staging iOS TestFlight + staging Android Firebase

The prod pipeline regenerates bundled assets, commits any drift, 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; 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 schema bundle, ./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.

Bring your own Supabase

The app ships with a setup screen that connects to a user-provided Supabase project. On first connect to a blank project, DuTaTo bootstraps the schema and the ai-proxy Edge Function automatically via Supabase's Management API using a one-time Personal (or Organization) Access Token — no CLI, no SQL Editor, no manual secret paste. The same PAT handles every step in one click:

1. Apply the bundled schema (POST /v1/projects/<ref>/database/query)
2. Fetch the project's anon + service role keys (GET /v1/projects/<ref>/api-keys)
3. Deploy ai-proxy (POST /v1/projects/<ref>/functions/deploy?slug=ai-proxy)
4. Set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (POST /v1/projects/<ref>/secrets)
5. Record the bundle hash in _schema_meta.functions_hash for drift detection

The token is never persisted; only the project URL and anon key are stored in flutter_secure_storage. Users who prefer not to create a token can use the manual fallback for schema (copy schema.sql to clipboard + deep-link to the Supabase SQL Editor); Edge Functions still require a one-time token.

Subsequent schema migrations apply silently on sign-in via the _apply_migration() RPC. Subsequent Edge Function updates surface as a "Dutato updates available" banner in the Settings screen — tapping it reopens the PAT dialog in "functions only" mode and redeploys just the function without touching the schema.

Licence revocation is contractual, not technical. See section 10 of the in-app Terms & Conditions (mirrored in docs/TERMS_OF_USE.md) for the scope of your licence and the Dutato operators' right to revoke.

See docs/SELF_HOST.md for the full walkthrough.

When adding a new migration under supabase/migrations/ or modifying supabase/functions/ai-proxy/, run ./dto schema bundle to regenerate assets/schema/schema.sql, assets/migrations/NNN.sql, assets/functions/ai-proxy/**, and lib/data/services/schema_version.g.dart. The CI lint job fails if the bundled artifacts are stale.

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)
./dto ci --docs        # Full CI + manifest drift check (run when touching public API)

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                  # 43-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 × 16 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 checklist (format → analyze → test → coverage)
./dto ci --rls                        # CI + RLS tests
./dto ci --responsive --visual        # CI + the local-only UI gates dropped from remote (responsive audit + pixelmatch)

# 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 (schema + Edge Functions)
./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>
./dto curriculum setup-db --db-url postgresql://... --apply-migrations

Testing

CI runs 8 parallel jobs on PRs to main:

1. Lint & Format — dart format + flutter analyze (~1min)
2. Unit Tests — unit/widget tests with 70% coverage gate (~3min)
3. Integration Tests — datasource tests against local Supabase with 80% coverage gate (~3min)
4. RLS & RPC Tests — Dockerized PostgreSQL running RLS assertions and RPC smoke tests (~2min)
5. BYO E2E Tests — Dockerized Supabase provisioner end-to-end smoke (~3min)
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 — contributors must invoke them before pushing UI changes.

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 — contributors must run them locally before pushing native-config changes:

./dto ci --android-deeplink   # boot an Android emulator in another terminal first
./dto ci --ios                # requires Xcode

CLAUDE.md's pre-push checklist documents this contract.

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, certifications, XP/badges, notifications, and enterprise config 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 / DemoPass123!. 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
    SELF_HOST.md        # Self-hosting guide
  plans/                # Development milestones (plan-1 through plan-32)
  supabase/migrations/  # Database schema (60 migrations)
  assets/
    schema/             # Bundled schema.sql + version.txt (generated by ./dto schema bundle)
    migrations/         # Per-migration SQL used by SchemaMigrator at sign-in
  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)
  test/                 # 204 test files
    helpers/            # Shared mocks & Supabase test init
    visual/baseline/    # Committed PNG baselines for ./dto visual diff (local check)
    integration/        # 37 integration test files (tagged, require Supabase)
    rls/                # RLS policy + RPC smoke tests (Docker + PostgreSQL)
    platform/           # Native config guardrails (OAuth deep-link, bundle IDs)

Database

Supabase PostgreSQL with 62 migrations. Key table groups:

• Content: domains (with owner_id, visibility), books, topics (hierarchical), content_chunks, curriculum_levels, curriculum_shares, domain_variants, reading_questions, reading_responses
• User progress: profiles (with target_retention, fsrs_parameters, onboarding_step / onboarding_completed_at, admin_onboarding_step / admin_onboarding_completed_at, seen_tooltips), 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
• Organizations: organizations, org_members, org_invitations, org_verified_domains, teams, team_members, curriculum_assignments (with status tracking), manager_assignments, platform_admins
• Enterprise: certifications, user_certificates, compliance_requirements, skills, role_profiles, role_skill_expectations, member_role_assignments, org_sso_configs, org_api_keys, org_webhooks, webhook_deliveries, learning_paths, learning_path_steps, learning_path_enrollments
• Native integrations: org_integrations (Slack / Notion / Lucca OAuth tokens, AES-GCM encrypted + REVOKE'd from PostgREST), org_integration_oauth_states (CSRF), integration_events (async delivery queue drained by pg_cron → slack-notify / notion-sync / lucca-sync). See docs/integrations/.
• Billing: subscriptions (per-user or per-org, Stripe or RevenueCat), admin_grants (platform-admin overrides), billing_events (webhook receipts, append-only)
• Gamification: user_xp, xp_events, badges, user_badges
• Infrastructure: device_tokens, rate_limits (per-plan), sanitization_logs, user_quotas, audit_log (append-only visibility/share events for legal compliance)

Schema defined in supabase/migrations/. Row-Level Security (RLS) policies enforce access control — see test/rls/ for smoke tests, including rls_entitlements_test.sql which covers the per-plan gates on SSO, SCIM, webhooks, certifications, compliance, and learning paths.

Monetization & Plans

DuTaTo is a B2B learning platform with four plan tiers, resolved server-side by current_entitlements() (migrations 052/057/058):

Entitlements are a flat key/value map (org.teams, org.sso, org.webhooks, org.integrations, ai.daily_cap, ai.total_cap, etc.). RLS policies on enterprise tables use org_has_entitlement() (migration 053) to gate writes, while SELECT policies remain permissive so downgraded users keep read access to their existing data.

AI usage is metered per user by the ai-proxy Edge Function against ai_limits_for_user() (migration 055, updated by 058 to include total_cap); usage meters and remaining-quota badges surface this state to the UI (lib/presentation/widgets/usage_meter_badge.dart). Trial users see a total-messages counter (e.g. "23/50") rather than daily/weekly quotas.

Billing architecture

• Mobile (iOS/Android) → purchases_flutter → StoreKit 2 / Google Play Billing → RevenueCat → revenuecat-webhook Edge Function → subscriptions table
• Web (orgs & solo) → Stripe Checkout → stripe-webhook Edge Function → subscriptions table
• Client entitlement provider reads current_entitlements() and invalidates on auth state change
• Platform admins can comp users/orgs, extend trials, and boost AI caps via admin_grants rows (backoffice screens at /backoffice/users and the Billing & grants panel on the org detail screen)

BYOK AI: users supply their own Anthropic/OpenAI/Gemini key (existing architecture). The subscription monetizes the platform, not AI tokens.

Edge Functions in supabase/functions/:

• stripe-webhook — processes Stripe events (signature-verified, idempotent via billing_events)
• create-checkout-session — returns a Stripe Checkout URL (JWT-authenticated, org-admin-gated for org plans)
• create-portal-session — returns a Stripe Billing Portal URL
• revenuecat-webhook — processes RevenueCat events (shared-secret auth)