Skip to main content

Morphee — Developer & AI Agent Guide

What Is Morphee​

A canvas-first conversational AI agent for groups (families, classrooms, teams). Self-hosted, privacy-first, offline-capable. The primary interface is a spatial canvas — UI components appear dynamically and persist as the AI responds. Chat is available as a collapsible drawer.

Built on Tauri v2 — a React frontend with a Rust backend for local ML inference (ONNX/GGUF), embedded memory (LanceDB + Git), and audio/video processing. The Python backend handles cloud services and orchestration. The app aims to run fully offline.

Current focus: V0.9 through V1.5 all shipped (Feb 19–22, 2026). Now targeting V2.0 — Production Platform: monitoring (PostHog/Grafana), channel adapters (WhatsApp, Telegram), browser extension, desktop polish. Remaining pre-V2.0 work: V0.9 tech debt (38 code items + branding), mobile App Store submission, SSO Tier 2. Architecture unified by Knowledge Pipeline (USE→EXTRACT→COMPILE→SHARE→INSTALL→USE) and Runtime Hierarchy (VectorRouter → WasmRuntime → PythonRuntime → JSRuntime → LLMRuntime). See docs/ROADMAP.md for full vision and docs/status.md for progress.

Codebase Map​

morphee-beta/
├── backend/                  # Python 3.12 + FastAPI (async)
│   ├── main.py               # App entry point, startup/shutdown, route registration
│   ├── config.py             # Environment config (DATABASE_URL, REDIS_URL, JWT_SECRET, etc.)
│   ├── api/                  # Route handlers (FastAPI routers)
│   │   ├── acl.py            # /api/acl/* — ACL grant, revoke, check, list, preferences, monitoring
│   │   ├── auth.py           # /api/auth/* — signup, signin, signout, refresh, me, profile, consent, export, delete-account, parental-consent
│   │   ├── chat.py           # /api/chat/* — SSE streaming chat, conversation CRUD, message pinning
│   │   ├── onboarding.py     # /api/onboarding/* — SSE onboarding chat (no group required)
│   │   ├── groups.py          # /api/groups/* — group CRUD
│   │   ├── members.py         # /api/groups/me/* — group invites + member management
│   │   ├── spaces.py          # /api/spaces/* — space CRUD
│   │   ├── tasks.py          # /api/tasks/* — task CRUD + state machine
│   │   ├── interfaces.py     # /api/interfaces/* — list integrations, execute actions, config CRUD
│   │   ├── notifications.py  # /api/notifications/* — list, mark-read, unread count
│   │   ├── oauth.py          # /api/oauth/google/* — OAuth2 flow (authorize, callback, status, disconnect)
│   │   ├── skills.py         # /api/skills/* — skill CRUD
│   │   ├── search.py         # /api/search/* — global search across conversations, tasks, spaces
│   │   ├── sso.py            # /api/auth/sso/* — SSO providers, authorize, callback (+ morphee:// deep link)
│   │   ├── push.py           # /api/push/* — register/unregister device push tokens
│   │   ├── extensions.py     # /api/extensions/* — catalog, install, manage, execute, audit WASM extensions
│   │   ├── identity.py       # /api/identity/* — child identities, auth methods, Morphee sessions
│   │   └── websocket.py      # /ws — WebSocket with JWT auth, group-based event filtering
│   ├── acl/                  # Generic resource-based access control system
│   │   ├── service.py        # ACLService — grant, revoke, check, list, preferences, monitoring
│   │   └── models.py         # ACL Pydantic models (permissions, preferences, monitoring)
│   ├── auth/                 # Auth: GoTrue + multi-modal identity (child sessions, PIN auth)
│   │   ├── service.py        # AuthService — signup, signin, signout, dual-path verify_token (GoTrue + Morphee)
│   │   ├── dependencies.py   # FastAPI dependencies (get_current_user, require_group_access)
│   │   ├── models.py         # Auth Pydantic models — AuthUser.email is Optional[str]
│   │   ├── identity_models.py # AuthMethodType, ChildIdentityCreate, MorpheeAuthResponse
│   │   ├── identity_service.py # IdentityService — child CRUD, PIN auth (bcrypt), auth methods
│   │   ├── session_service.py  # SessionService — Morphee JWT issuance/verification, session CRUD
│   │   ├── age_verification.py # Regional age thresholds (EU 16, US 13), minor detection
│   │   ├── parental_consent.py # Parental consent email workflow + verification
│   │   ├── consent_service.py  # Consent tracking (llm_data_sharing, memory_extraction, etc.)
│   │   └── export_formatter.py # GDPR data export formatting (JSON + Markdown)
│   ├── db/                   # Database connection, helpers
│   ├── groups/               # Group service + models + invite/member services
│   │   ├── models.py         # Group Pydantic models
│   │   ├── service.py        # GroupService — CRUD + member management
│   │   ├── invite_models.py  # GroupInvite Pydantic models
│   │   ├── invite_service.py # GroupInviteService — create, accept, revoke invites
│   │   └── member_service.py # GroupMemberService — add, remove, role management
│   ├── spaces/               # Space service + models
│   ├── tasks/                # Task service + models + state machine
│   ├── chat/                 # Chat system (Phase 1a + 1b)
│   │   ├── models.py         # Conversation, Message, MessageCreate, MessageRole
│   │   ├── service.py        # ChatService — CRUD for conversations + messages
│   │   ├── llm.py            # LLMIntegration(BaseInterface) — Anthropic SDK streaming + tool support
│   │   ├── orchestrator.py   # AgentOrchestrator — agentic loop (LLM → tools → loop)
│   │   ├── tools.py          # Tool Bridge — ActionDefinition → Anthropic tool format
│   │   ├── prompts.py        # System prompt builder
│   │   └── onboarding_prompts.py  # Onboarding system prompt + persona-space mapping
│   ├── memory/               # Memory & Knowledge system (Phase 2)
│   │   ├── embeddings.py     # EmbeddingProvider ABC, OpenAI + FastEmbed providers
│   │   ├── embedding_manager.py # Singleton manager, consistency validation
│   │   ├── vector_store.py   # pgvector wrapper (insert, search, delete)
│   │   ├── rag.py            # RAG pipeline — context injection into system prompt
│   │   ├── git_store.py      # Per-space git repos (1 repo = 1 space), Markdown + YAML frontmatter
│   │   ├── sync.py           # Background sync scheduler (hourly git push/pull)
│   │   └── summarizer.py     # Auto-extract facts/preferences/events from conversations
│   ├── scheduler/            # Cron scheduling system (Phase 3a)
│   │   ├── models.py         # Schedule Pydantic models
│   │   ├── service.py        # ScheduleService — CRUD + next_run calculation (croniter)
│   │   └── runner.py         # ScheduleRunner — async polling loop
│   ├── notifications/        # Notification system (Phase 3a) + push (APNs/FCM, Phase 3d M2)
│   │   ├── models.py         # Notification Pydantic models
│   │   └── service.py        # NotificationService — CRUD + EventBus publishing
│   ├── google/               # Google OAuth + API client (Phase 3a)
│   │   ├── oauth.py          # OAuth2 helpers (HMAC state, token exchange, scopes)
│   │   └── client.py         # GoogleApiClient (auto token refresh, retry)
│   ├── emails/               # Email service (transactional emails)
│   │   ├── email_service.py  # Email sending via SMTP + re-engagement templates
│   │   └── reengagement.py   # Re-engagement email scheduler (day-2, week-1, dormant)
│   ├── crypto/               # Encryption at rest (C-STORE-002)
│   │   └── encryption_service.py # Fernet encryption/decryption, ENC: prefix, singleton
│   ├── vault/                # VaultProvider implementations
│   │   ├── provider.py       # VaultProvider ABC
│   │   └── env_provider.py   # EnvVaultProvider (env vars)
│   ├── i18n/                 # Internationalization module
│   │   ├── errors.py         # Localized error messages
│   │   ├── websocket.py      # WebSocket i18n strings
│   │   └── integrations.py   # Integration i18n strings
│   ├── extensions/           # WASM Extension system (V1.2)
│   │   ├── models.py         # ExtensionPermission, ResourceLimits, ExtensionManifest, InstalledExtension
│   │   ├── runtime.py        # BaseMorphRuntime ABC, WasmRuntime (wasmtime-py), module cache
│   │   ├── host_functions.py # Host function implementations (http, vault, events, data, log)
│   │   ├── manager.py        # ExtensionManager (install/uninstall/enable/disable), WasmExtensionInterface
│   │   ├── permissions.py    # PermissionEnforcer (host function ACL, SSRF protection, domain allowlists)
│   │   ├── resource_limiter.py # ResourceLimiter, ExecutionTracker (fuel, memory, HTTP rate, timeout)
│   │   ├── signing.py        # ExtensionSigner (RSA-PSS + SHA-256, sign/verify WASM binaries)
│   │   ├── audit.py          # ExtensionAuditService (execution logging, stats, buffered writes)
│   │   ├── registry.py       # RegistryClient (OCI Distribution Spec, search/pull/manifest/versions)
│   │   └── oauth.py          # ExtensionOAuthHandler (generic OAuth for WASM, vault token storage)
│   ├── filesystem/           # Filesystem service (Phase 3a)
│   │   └── file_store.py     # Sandboxed file operations per group
│   ├── skills/               # Dynamic Skills system (Phase 3b.1)
│   │   ├── models.py         # Skill, SkillDefinition, SkillStep, SkillParameter
│   │   ├── service.py        # SkillService — CRUD + list_all_enabled
│   │   ├── engine.py         # SkillEngine — validate + execute step sequences
│   │   └── dynamic.py        # DynamicSkillInterface — runtime interface per skill
│   ├── interfaces/           # Integration/Interface system (MCP-style)
│   │   ├── models.py         # BaseInterface, ActionDefinition, AIAccess, SideEffect, ExecutionContext
│   │   ├── manager.py        # InterfaceManager — registry + action execution orchestration
│   │   ├── executor.py       # InterfaceExecutor — action execution + approval workflow
│   │   ├── config_service.py # InterfaceConfigService — CRUD + vault wiring for interface configs
│   │   └── integrations/     # 17 built-in integrations: echo, webhook, llm (in chat/llm.py), tasks, spaces, frontend, onboarding, memory, cron, notifications, google_calendar, gmail, filesystem, skills, slack, conversations, settings, jira
│   ├── utils/                # Shared utilities
│   │   ├── logger.py         # Structured logging setup (JSON format in prod)
│   │   ├── cache.py          # In-memory cache with TTL (Redis-compatible interface)
│   │   ├── rate_limit.py     # Redis-backed rate limiter (fail-open on Redis unavailable)
│   │   └── retry.py          # Exponential backoff retry decorator
│   └── tests/                # pytest + pytest-asyncio
│       ├── conftest.py       # Shared fixtures
│       ├── test_*.py         # Unit tests
│       └── integration/      # API endpoint tests
│
├── frontend/                 # Vite 6 + React 19 + TypeScript + Tauri 2.0
│   ├── src/
│   │   ├── main.tsx          # App entry point
│   │   ├── App.tsx           # Routes, auth guard, layout
│   │   ├── components/       # React components
│   │   │   ├── ui/           # shadcn/ui components (24 installed, Radix-based)
│   │   │   ├── auth/         # AuthForm, SSOIcons
│   │   │   ├── layout/       # Sidebar, Header, BottomNav, Breadcrumbs, MobileSidebar, NotificationBell, FeatureTour
│   │   │   ├── chat/         # ChatBubble, ConversationList, ToolCallCard, ApprovalCard, PinnedMessages, ConversationSettingsDialog, ComponentRegistry, renderers/
│   │   │   ├── tasks/        # TaskList, TaskDetail, CreateTaskDialog, ConnectionStatus
│   │   │   ├── spaces/       # SpaceList, SpaceDetail, SpaceCard, CreateSpaceDialog
│   │   │   ├── search/       # SearchDialog (Cmd+K global search)
│   │   │   └── settings/     # GoogleConnect, InterfaceConfigCard
│   │   ├── pages/            # Route pages (Chat, Dashboard, Tasks, Spaces, Login, Onboarding, AuthCallback, AcceptInvite, ParentConsentPending, ParentConsentVerify)
│   │   │   └── settings/     # Settings sub-pages (9 tabs)
│   │   │       ├── ProfileTab.tsx          # User profile, language, appearance
│   │   │       ├── NotificationsTab.tsx    # Notification preferences
│   │   │       ├── IntegrationsTab.tsx     # OAuth connections, API integrations
│   │   │       ├── MembersTab.tsx          # Group member management, invites
│   │   │       ├── DataPrivacyTab.tsx      # GDPR consents, data export, account deletion
│   │   │       ├── ParentalControlsTab.tsx # Age verification, parental consent
│   │   │       ├── SchedulesTab.tsx        # Cron schedules for skills
│   │   │       ├── FilesTab.tsx            # File storage management
│   │   │       └── PermissionsTab.tsx      # ACL permissions viewer
│   │   ├── store/            # Zustand stores (authStore, taskStore, spaceStore, chatStore, notificationStore, componentStore)
│   │   ├── hooks/            # Custom hooks (useAuth, useTasks, useSpaces, useChat, useOnboarding, useNotifications, useDocumentTitle, useDateLocale, usePullToRefresh, use-toast)
│   │   ├── lib/              # Utilities (api.ts, auth.ts, component-events.ts, download.ts, fs-client.ts, haptics.ts, memory-client.ts, push-notifications.ts, runtime.ts [isTauri/isMobile/isDesktop/isIOS/hasLocalML], sse.ts, tauri.ts, utils.ts, websocket.ts)
│   │   ├── i18n/             # Internationalization (en/fr locales)
│   │   ├── types/            # TypeScript type definitions
│   │   └── styles/           # Global CSS, Tailwind config
│   ├── e2e/                  # Playwright E2E tests
│   ├── vitest.config.ts      # Unit test config
│   └── playwright.config.ts  # E2E test config
│
├── frontend/src-tauri/        # Tauri v2 Rust backend (local compute)
│   └── src/                   # Rust source — 76 Tauri IPC commands, 165 tests (desktop) + 9 mobile-ml
│       ├── lib.rs             # Tauri builder, startup init, command registration
│       ├── state.rs           # AppState (Mutex/AsyncMutex for subsystems)
│       ├── error.rs           # MorpheeError enum (thiserror + Serialize)
│       ├── error_codes.rs     # Structured error codes (E_LLM_*, E_AUD_*, E_BIO_*, E_VAULT_*, E_DL_*) with EN+FR locales
│       ├── embeddings.rs      # EmbeddingProvider: fastembed/ONNX (desktop), candle/BERT (mobile via mobile-ml)
│       ├── vector_store.rs    # VectorStore: LanceDB (desktop), SQLite/rusqlite (mobile via mobile-ml)
│       ├── vector_router.rs   # VectorRouter: local vector-first routing (mirrors backend VectorRouter)
│       ├── tokenizer.rs       # Pure-Rust BERT WordPiece tokenizer (mobile-ml embeddings; LLM uses HF tokenizers with unstable_wasm)
│       ├── git_store.rs       # GitStore (git2, Markdown + YAML frontmatter, all platforms, OpenMorph entity API)
│       ├── vault.rs           # VaultProvider: keyring (macOS/Win/Linux/iOS), SQLite (Android via mobile-ml)
│       ├── file_store.rs      # FileStore (sandboxed fs, per-group, path traversal prevention)
│       ├── action_queue.rs    # ActionQueue: offline action queue (JSON-file-backed, drain on reconnect)
│       ├── llm.rs             # LLMRuntime: candle/GGUF inference (Phi-4, Llama 3B, Mistral 7B), Metal/CPU
│       ├── model_manager.rs   # ModelManager: download, switch, delete GGUF models with progress + cancellation
│       ├── tts.rs             # Text-to-speech for voice responses (local, offline)
│       ├── whisper.rs         # Speech-to-text via ONNX Whisper (on-device transcription)
│       ├── liveness.rs        # Liveness detection (face: pixel variance; voice: spectral flatness, pitch)
│       ├── face_encoder.rs    # FaceEncoderProvider: candle MobileFaceNet (biometrics feature, 128-dim)
│       ├── voice_encoder.rs   # VoiceEncoderProvider: candle d-vector CNN (biometrics feature, 192-dim)
│       ├── extensions/        # WASM Extension runtime (V1.2)
│       │   ├── mod.rs         # Module declarations
│       │   ├── models.rs      # Serde models (ExtensionManifest, ExtensionPermission, ResourceLimits)
│       │   ├── permissions.rs # Permission checking (check_permission, check_permissions)
│       │   └── wasm_runtime.rs # WasmRuntime struct (wasmer stub, module cache, WASM validation)
│       └── commands/          # embedding, memory, git, vault, health, fs, session, extension, biometric, llm, audio, queue, morph, vector, screenshot commands
│
├── sdk/                       # Extension SDKs
│   ├── morphee-sdk-rust/      # Rust WASM extension SDK (Extension trait, export_extension! macro)
│   └── morphee-ext-cli/       # Python CLI tool (init, build, test, sign, publish)
├── extensions/                # WASM extensions (5 built-in + echo proof-of-concept)
│   ├── echo/                  # Echo extension — proof-of-concept (echo + reverse actions)
│   ├── jira/                  # JIRA Integration (6 actions, OAuth via Atlassian)
│   ├── github/                # GitHub Integration (6 actions, issues + PRs)
│   ├── notion/                # Notion Integration (4 actions, pages + search)
│   ├── linear/                # Linear Integration (4 actions, GraphQL)
│   └── slack/                 # Slack Integration (3 actions, messaging)
├── wit/                       # WIT interface definitions
│   └── morphee-extension.wit  # Host imports (http, vault, events, data, log) + extension exports
├── supabase/                  # Supabase config and migrations
├── .github/workflows/         # CI/CD (ci.yml, release.yml, rust-tests.yml, www-deploy.yml)
├── audits/                    # All audits (8 types)
│   ├── code/                 # Code quality audits
│   ├── docs/                 # Documentation audits
│   ├── product/              # Product reviews
│   ├── legal/                # Legal & compliance audits (GDPR)
│   ├── security/             # Security audits (adversarial, OWASP)
│   ├── a11y/                 # Accessibility audits (WCAG 2.1 AA)
│   ├── performance/          # Performance audits (measurement-based)
│   └── i18n/                 # Internationalization audits (locales, strings, formatting)
├── scripts/                   # Operational scripts
│   ├── encrypt_existing_data.py  # Batch encrypt existing plaintext data (C-STORE-002 migration)
│   └── backup-morphee.sh        # Database backup script
├── docker-compose.dev.yml     # Dev environment (backend, PostgreSQL, Redis, Supabase Auth)
├── docker-compose.yml         # Production compose
├── Dockerfile.backend         # Backend container
├── docs/                      # All documentation
│   ├── ROADMAP.md            # Vision, core concepts, all phases
│   ├── status.md             # ✅ Progress tracker — update after each task
│   ├── architecture.md       # System architecture
│   ├── interfaces.md         # Integration/Interface system design
│   ├── api.md                # API reference
│   ├── testing.md            # Testing guide
│   ├── test-results.md       # Test results snapshot
│   ├── deployment.md         # Production deployment
│   ├── COOLIFY_DEPLOYMENT.md # Coolify-specific production deployment guide
│   ├── V1.0_DEPLOYMENT_TASKLIST.md # V1.0 release tracking checklist
│   ├── RUNBOOK.md            # Operations manual (monitoring, incidents)
│   ├── troubleshooting.md    # Common issues
│   ├── features/             # Feature design docs
│   ├── impl-guides/          # Implementation guides for specific features
│   ├── user-guide/           # User-facing docs (getting started, features, privacy)
│   ├── errors/               # Error code catalog and reference
│   ├── legal/                # Legal documents (PRIVACY_POLICY.md)
│   ├── stories/              # Persona-based user stories (9 personas)
│   └── archive/              # Old design docs (historical reference only)
├── CONTRIBUTING.md            # Contributor guide
└── CLAUDE.md                 # This file

Key Terminology​

NameCodeMeaning
Groupgroup / groupsCollection of people sharing Morphee
Spacespace / spacesIsolated context for conversations, tasks, memory. Can be nested (sub-Spaces inherit parent Interfaces)
Integrationinterface (partially)Definition of a service/capability (LLM, Memory, Gmail, etc.)
Interfaceinterface (partially)Configured instance of an Integration with credentials
Skillskills/Composable AI capability combining Interface calls. Stored definitions with step sequences, template interpolation, dynamic interface registration
Memory(not yet in code)LanceDB vectors + Git-backed Markdown, per-Space
VaultProvidervault/Pluggable secure storage for credentials. NOT an Integration — lower-level system service. EnvVaultProvider (Python) + KeychainVaultProvider (Tauri Rust) implemented. Future: 1Password, mobile keystore, cloud KMS

Everything is an Integration — the LLM, Memory, and Frontend use the same contract as Gmail or Calendar. Credentials for Interfaces are stored in a VaultProvider (never in the database). See docs/interfaces.md — Vault.

Development Commands​

# Start backend (Docker)
docker compose -f docker-compose.dev.yml up -d
curl http://localhost:8000/health

# Start frontend (dev server, port 5173)
cd frontend && npm run dev

# Start as desktop app (Tauri)
cd frontend && npm run tauri:dev

Running Tests​

See docs/test-results.md for current test counts and coverage.

# Backend tests — runs inside Docker
docker compose -f docker-compose.dev.yml exec -T backend pytest -q --cov=. --cov-report=term-missing

# Tauri Rust tests
cd frontend/src-tauri && cargo test

# Frontend unit tests
cd frontend && npx vitest run

# Frontend E2E tests (needs running backend)
cd frontend && npm run test:e2e

# Frontend build check
cd frontend && npm run build

Ports​

ServicePort
Backend API8000
Frontend (Vite)5173
PostgreSQL54322
Supabase Auth9999
Redis6379

Coding Standards​

Backend (Python)​

  • Async everywhere — all route handlers and services use async def
  • Pydantic models for request/response validation and serialization
  • Use model_dump(mode="json") when serializing Pydantic models (not .dict())
  • pytest + pytest-asyncio — use @pytest.mark.asyncio for async tests, asyncio_mode = auto in config
  • Group-based isolation — all data queries must filter by group_id
  • JWT auth — Supabase GoTrue tokens, validated in middleware
  • Event-driven — publish events via Redis pub/sub for real-time updates
  • Logging levels — use get_logger(__name__) everywhere. Levels: ERROR = unexpected failures that need attention; WARNING = recoverable issues (fallback paths, retries); INFO = significant operations (startup, shutdown, entity created/deleted); DEBUG = detailed flow (event emitted, cache hit/miss). Never log secrets, tokens, or full request bodies at any level.

Frontend (TypeScript)​

  • Zustand for state management (not React Context) — stores in src/store/
  • shadcn/ui for components (Radix-based, in src/components/ui/)
  • Zod v4 for validation — use error (not required_error), z.number() (not z.coerce.number())
  • react-hook-form + zod for form validation
  • Vite proxy forwards /api and /ws to backend at port 8000
  • CSS variables for dark/light mode, auto-detects system preference
  • WebSocket for real-time updates — TaskWebSocket singleton with auto-reconnect
  • tsconfig.json excludes __tests__/ from build (vitest has its own config)

General​

  • Keep functions focused and small
  • Prefer editing existing files over creating new ones
  • No unused code, no backwards-compatibility shims — delete what's not needed
  • Tests are mandatory for new backend features (aim for >80% coverage)

Privacy & Data Protection (GDPR)​

  • Never log PII — no emails, names, passwords, or message content in log output at any level. Log only opaque identifiers (user_id, group_id, memory_id).
  • Never emit PII in events — EventBus payloads must not contain email, name, or message content. Use IDs only.
  • Data minimization — only collect and process personal data that is strictly necessary. Don't add new PII fields without justification.
  • Consent before processing — any new feature that sends personal data to a third party must check the relevant consent type via ConsentService.has_consent() before proceeding. Required consent types: llm_data_sharing, memory_extraction, google_calendar, google_gmail, push_notifications.
  • Group-based isolation — all queries must filter by group_id. Never return data from a group the user doesn't belong to.
  • Cascade deletes — when adding FK relationships, use ON DELETE CASCADE for user-scoped data so account deletion erases everything. Use ON DELETE SET NULL only for shared data where the record should survive.
  • Credentials in VaultProvider — never store API keys, OAuth tokens, or secrets in the database. Use VaultProvider (env vars in Python, keychain in Tauri Rust).
  • Local-first defaults — prefer local processing over cloud (e.g., fastembed over OpenAI for embeddings). Cloud features should be opt-in with consent.
  • Legal docs — governance documents are in docs/legal/ (Privacy Policy, DPIA, ROPA, Breach Response Plan, Transfer Impact Assessment). Update ROPA when adding new processing activities.

Task Completion Process​

After completing any task, follow this checklist:

  1. Run tests — all tests must pass before considering the task done

    # Backend
    docker compose -f docker-compose.dev.yml exec -T backend pytest -q --cov=. --cov-report=term-missing
    # Frontend
    cd frontend && npx vitest run
    cd frontend && npm run build

  2. Update docs/status.md — check off completed items in the current sprint checklist. This is the primary progress tracker.

  3. Update test counts if you added tests — update the counts in:

  4. Update docs/api.md if you added or changed API endpoints.

  5. Update this file (CLAUDE.md) if you changed the project structure, added new conventions, or discovered something important.

  6. Update docs/deployment.md if you added or changed docker-compose files or environment variables.

Documentation Map​

QuestionDocument
What's the vision? What are we building?docs/ROADMAP.md
What's done? What's next? What should I work on?docs/status.md
How does the system architecture work?docs/architecture.md
How do Integrations and Interfaces work?docs/interfaces.md
What API endpoints exist?docs/api.md
What Tauri IPC commands exist?docs/tauri-commands.md
How do I run tests?docs/testing.md
What are the latest test results?docs/test-results.md
How to deploy to production?docs/deployment.md
Something is broken, how do I fix it?docs/troubleshooting.md
Error codes and messages?docs/errors/
How to deploy with Coolify?docs/COOLIFY_DEPLOYMENT.md
What's the V0.9 release checklist?docs/V1.0_DEPLOYMENT_TASKLIST.md
Operations and incident response?docs/RUNBOOK.md
User stories and personas?docs/stories/
Feature design documents?docs/features/
Implementation guides?docs/impl-guides/
User-facing documentation?docs/user-guide/
How to contribute?CONTRIBUTING.md
E2E simulation framework?e2e/docs/
Audit framework and methodology?audits/AUDIT_FRAMEWORK.md
Audit health dashboard?audits/AUDITS_DASHBOARD.md
Coolify deployment test guide? (archived)docs/features/archive/COOLIFY_TEST_QUICK_REFERENCE.md
Deployment test suite? (archived)docs/features/archive/DEPLOYMENT_TEST_SUITE_README.md
High availability setup?docs/HIGH_AVAILABILITY.md
Alpha program?docs/alpha-program/

Completed Architectural Changes​

All prerequisite architectural cleanup items are done (tracked in docs/status.md):

  1. Remove PostgREST — replaced with direct asyncpg connection pool (db/client.py)
  2. Rename family → group — DONE
  3. Rename project → space — DONE
  4. Evolve BaseInterface — added config_schema, config dict, vault: VaultProvider param
  5. Implement VaultProvider — EnvVaultProvider (Python) + KeychainVaultProvider (Tauri Rust, Phase 2b)

Hybrid Architecture: Python + Rust​

The app has two backends — the frontend talks to both:

  • Python backend (HTTP, api.morphee.app) — auth, groups, cloud LLM (Anthropic SDK), external integrations, orchestration, PostgreSQL, Redis
  • Tauri Rust backend (IPC, local) — embedded LanceDB, Git (libgit2), ONNX models (ort crate), GGUF models (candle crate), audio/video processing

Key Rust crates:

CratePurposePhase
fastembedONNX embeddings (AllMiniLML6V2, 384 dims)2b
lancedbEmbedded vector DB (native Rust, cosine search)2b
git2Local Git for memory (libgit2, vendored)2b
keyringOS keychain (macOS/Windows/Linux)2b
candleGGUF LLM inference (Hugging Face, pure Rust)3

Design principle: The Integration/Interface abstraction means the orchestrator doesn't care which backend handles an action. A "Cloud Claude" Interface calls Python; a "Local Llama" Interface calls Tauri Rust. Same contract.

Offline goal: The app should eventually run fully offline — local LLM, local memory, queued sync. The server becomes a sync hub, not a hard dependency.

See docs/ROADMAP.md for the full phased rollout and docs/architecture.md for the system diagram.

Auth Flow​

Dual JWT path: GoTrue JWTs for adults (unchanged), Morphee-issued JWTs for kids (iss=morphee).

  1. User signs up/in via Supabase Auth (email/password or SSO) → gets GoTrue JWT
  2. SSO flow: frontend → backend /api/auth/sso/{provider} → GoTrue authorize → provider consent → /auth/callback#access_token=... → backend /api/auth/sso/callback (find-or-create user)
  3. JWT sent in Authorization: Bearer <token> header
  4. Backend verify_token peeks at JWT iss claim → routes to GoTrue or Morphee verification
  5. New user has group_id=null → frontend redirects to /onboarding (AI-guided conversation)
  6. Onboarding creates group + spaces via tool calls → user can access chat
  7. 401 responses trigger automatic token refresh (frontend interceptor with shared promise)
  8. WebSocket auth: ws://host/ws?token=<jwt>
  9. Child auth: Parent creates child identity (no email) → switches to child session in-app → Morphee JWT issued with iss=morphee, aud=morphee_child
  10. AuthUser.email is Optional[str] — all downstream code handles None (kids have no email)