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 (morphee-server on axum, wrapping morphee-core) for API, auth, knowledge, and AI orchestration. The Tauri desktop/mobile layer adds local ML inference (ONNX/GGUF), embedded memory (LanceDB + Git), and audio/video processing. The app aims to run fully offline.

Current focus: V2.0 complete (Feb 28, 2026). Fractal Brain actively benchmarked through Kaggle AIMO math competition — 26 brain files, 233 tests, 3-tier recognition stack (substrat clustering → tree recall → method neurons). Brain telemetry: SQLite + Prometheus + CLI + Dashboard. Bench infrastructure: Docker + remote runners + dashboard. Next: V2.1 — Knowledge Marketplace — AIMO-trained math brain as first shareable bundle. Open-source launch after tournament. See docs/features/fractal-brain.md for brain architecture and docs/ROADMAP.md for full vision.

---

Codebase Map

See docs/CODEBASE.md for the full codebase tree, integration inventory (18 integrations, 86 actions), Tauri command inventory (76 IPC commands), Rust crate table, and completed architectural changes.

Quick orientation:

Directory	What's there
crates/morphee-core/	Core pipeline library — compilation, federation, RL policy, fractal brain (600 tests / 714 with fractal-brain)
crates/morphee-core/src/brain/	Fractal Brain — 26 files, 233 tests, substrat index, method neurons, prediction, telemetry
crates/morphee-server/	Axum HTTP/WS server — auth, CRUD, knowledge, metrics (153 tests)
backend/	DEPRECATED — Legacy Python 3.12 + FastAPI backend (replaced by morphee-server)
frontend/src/	Vite 6 + React 19 + TypeScript — components, pages, stores, hooks
frontend/src-tauri/src/	Tauri v2 Rust backend — 76 IPC commands, embeddings, LLM, git, vault
bench/cli/	Benchmarking CLI for MATH/AIMO competitions (288 tests, 17 subcommands)
bench/dashboard/	Bench dashboard — PostgreSQL-backed, Brain visualization, Runners, run management
bench/migrations/	PostgreSQL schema migrations (auto-applied on first hub start)
bench/docker-compose.coolify.yml	Hub stack: PostgreSQL + Prometheus + Dashboard
bench/docker-compose.runner.yml	Independent runner (any machine with Docker)
bench/docker-compose.bench.yml	Local Docker benchmarking (SQLite)
sdk/	Rust WASM extension SDK + Python CLI tool
extensions/	5 built-in WASM extensions + echo proof-of-concept
e2e/	E2E simulation framework — 200+ persona-driven scenarios, 3 AI agents
e2e/dashboard/	Visual E2E dashboard (Vite + React + Express, cd e2e/dashboard && npm run dev)
docs/	All documentation (see Documentation Map below)
audits/	8 audit types (code, docs, product, legal, security, a11y, performance, i18n)
scripts/	Operational + doc-generation scripts

---

Key Terminology

Name	Code	Meaning
Group	group / groups	Collection of people sharing Morphee
Space	space / spaces	Isolated context for conversations, tasks, memory. Can be nested (sub-Spaces inherit parent Interfaces)
Integration	interface (partially)	Definition of a service/capability (LLM, Memory, Gmail, etc.)
Interface	interface (partially)	Configured instance of an Integration with credentials
Skill	skills/	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
VaultProvider	vault/	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 infrastructure + morphee-server (Docker)
docker compose -f docker-compose.dev.yml up -d
curl http://localhost:3000/health

# Or: start infrastructure only, run server natively
docker compose -f docker-compose.v2.yml up -d
source .env.v2 && cargo run -p morphee-server

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

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

# Start E2E Dashboard (browse test results, generate scenarios, AI co-pilot)
cd e2e/dashboard && npm run dev

Running Tests

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

# morphee-core tests (600 tests with rl-policy, 714 with fractal-brain)
cargo test -p morphee-core --features rl-policy
cargo test -p morphee-core --features fractal-brain

# morphee-server tests (153 tests)
cargo test -p morphee-server

# bench-cli tests (288 tests)
cargo test -p bench-cli

# Bench Docker (remote benchmarking)
docker compose -f bench/docker-compose.bench.yml build
docker compose -f bench/docker-compose.bench.yml run bench bench --model qwen2.5-math-1.5b --suite math-dataset --limit 500 --dream

# Bench Dashboard (brain visualization + runner monitoring)
docker compose -f bench/docker-compose.coolify.yml up -d

# Tauri Rust tests (165 desktop + 9 mobile)
cd frontend/src-tauri && cargo test

# Frontend unit tests (3,465 tests)
cd frontend && npx vitest run

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

# Frontend build check
cd frontend && npm run build

Ports

Service	Port
Morphee Server (Rust/axum)	3000
Frontend (Vite)	5173
E2E Dashboard	5174
E2E Dashboard API	3939
Bench Dashboard (API + frontend)	3940
Bench Prometheus metrics	9090
PostgreSQL	54322
Supabase Auth	9999
Redis	6379

---

Coding Standards

Backend (Rust — morphee-server + morphee-core)

• Axum handlers — use extractors (State, Json, Path, Query), return Result<Json<T>, AppError>
• sqlx for persistence — compile-time checked queries where possible, sqlx::FromRow for models
• Group-based isolation — all data queries must filter by group_id
• JWT auth — Supabase GoTrue tokens + Morphee-issued child tokens, validated in middleware
• Feature gates — use Cargo features for optional dependencies (e.g., rl-policy, cloud-llm)
• Logging — use tracing crate. RUST_LOG=info default. Never log secrets or tokens.
• Error handling — AppError enum with impl IntoResponse, proper HTTP status codes
• Tests — #[tokio::test] for async tests, integration tests use test fixtures

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 /v1 to morphee-server (includes WebSocket at /v1/ws)
• 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

   # Rust crates
   cargo test -p morphee-core --features rl-policy
   cargo test -p morphee-server
   # 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:

   • docs/status.md (completed section)
   • docs/test-results.md

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

Question	Document
What's the vision? What are we building?	docs/ROADMAP.md
What's done? What's next?	docs/status.md
What shipped in each version?	docs/CHANGELOG.md
Full codebase tree + integration/command inventory	docs/CODEBASE.md
System architecture + diagrams	docs/architecture.md
Integration/Interface system design	docs/interfaces.md
API endpoints	docs/api.md
Tauri IPC commands	docs/tauri-commands.md
How to run tests	docs/testing.md
Latest test results	docs/test-results.md
Production deployment	docs/deployment.md
Architecture decisions (ADRs)	docs/decisions/
How docs work (meta-documentation)	docs/DOCUMENTATION.md
Troubleshooting	docs/troubleshooting.md
Error codes	docs/errors/
Bench hub + swarm deployment	docs/BENCH_DEPLOYMENT.md
Coolify deployment	docs/COOLIFY_DEPLOYMENT.md
App Store / Google Play deployment	docs/STORE_DEPLOYMENT.md
Store automation (screenshots, ASO)	fastlane/STORE_AUTOMATION.md
Release checklist	docs/V1.0_DEPLOYMENT_TASKLIST.md
Operations / incidents	docs/RUNBOOK.md
User stories / personas	docs/stories/
Feature design docs	docs/features/
V2.0 Unified Rust Engine design	docs/features/unified-rust-engine.md
Fractal Brain (26 files, 233 tests)	docs/features/fractal-brain.md
Brain Telemetry (SQLite + Prometheus + CLI)	docs/features/brain-telemetry.md
Brain Critical Analysis (strengths/gaps)	docs/features/brain-critical-analysis.md
Digital Brain Vision (next evolution)	docs/features/digital-brain-vision.md
Feature ideas lab (10 explorations)	docs/ideas/
Implementation guides	docs/impl-guides/
User-facing docs	docs/user-guide/
Contributing	CONTRIBUTING.md
E2E simulation framework	e2e/docs/
E2E visual dashboard	e2e/dashboard/README.md
Audit framework	audits/AUDIT_FRAMEWORK.md
Audit dashboard	audits/AUDITS_DASHBOARD.md
High availability	docs/HIGH_AVAILABILITY.md

---

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 /v1/auth/sso/{provider} → GoTrue authorize → provider consent → /auth/callback#access_token=... → backend /v1/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/v1/ws with first-message auth {"type":"auth","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)