Skip to content

Backend Architecture

Last Verified: February 2026
Service: FastAPI backend (this repo)

This document describes the current backend architecture and how it connects to: - ../archety-edge (Mac mini iMessage edge relay) - ../archety-web (Next.js onboarding + dashboard + MiniApp UI)

High-level flow (iMessage)

iMessage (user)
  → Mac mini edge relay (../archety-edge)
    → POST /edge/message (filtered/redacted)
      → MessageHandler (routing + tools + response)
    ← HTTP response (multi-bubble fallback)
    ← WebSocket /edge/ws (optional: reflex bubble immediately)
  → iMessage (user)

Core backend subsystems

1) Orchestrator (conversation engine)

  • Main class: app/orchestrator/message_handler.py::MessageHandler
  • Responsibilities:
  • persona selection
  • context build (history + memory + relationship)
  • unified routing decision (MiniApp vs workflow/tools vs conversation)
  • multi-bubble generation + delivery hints

2) Routing

  • Message routing: app/orchestrator/smart_message_router.py
  • Tool/web routing: app/orchestrator/smart_router.py + app/orchestrator/query_analyzer.py

3) Memory

  • Factory: app/memory/__init__.py::get_memory_service()
  • Default: Supermemory (if configured)
  • Legacy fallback: mem0 (if configured)

4) MiniApps

  • UI config + actions: app/api/miniapp_ui_routes.py
  • Session storage/routing: app/miniapps/routing/
  • Real-time browser sync: app/api/websocket_routes.py (see docs/architecture/WEBSOCKET_PROTOCOL.md)

5) Workflows

  • Engine: app/workflows/engine.py
  • Nodes/catalog: app/workflows/nodes/, app/workflows/catalog/
  • Optional proactive scheduler: app/scheduler/ (enabled via env var)

6) Identity, payments, support

  • Auth + sessions + CSRF: app/api/auth_routes.py, app/security/csrf.py, app/middleware.py
  • Account management: app/api/account_routes.py
  • Payments (Stripe): app/api/payment_routes.py
  • Support/feedback: app/api/support_routes.py

7) Edge integration

  • HTTP + WebSocket endpoints: app/api/edge_routes.py
  • WebSocket manager: app/edge/websocket_manager.py
  • Edge schemas/auth: app/edge/schemas.py, app/edge/auth.py

API surface (by router)

Routers are mounted in app/main.py and live in app/api/*_routes.py.

Common prefixes: - /auth/* — OTP, sessions, CSRF - /onboarding/* — photo onboarding + trait profile - /user/* — profile/settings - /payment/* — checkout + webhooks - /miniapps/* — UI config + action endpoint - /ws/* — browser MiniApp WebSocket - /edge/* — edge relay HTTP + WebSocket

Authentication model (current)

  • Web dashboard (browser):
  • HTTP-only cookies (withCredentials: true)
  • CSRF token required for mutating requests (X-CSRF-Token)

  • CSRF token endpoint: GET /auth/csrf-token

  • Edge relay:

  • Authorization: Bearer <edge_token> (see app/edge/auth.py)

  • Optional admin endpoints gated by X-Admin-Key

  • Legacy relay (/orchestrator/message):

  • Authorization: Bearer <RELAY_WEBHOOK_SECRET> if configured

Observability

  • Structured JSON logs: app/main.py middleware + formatter
  • Sentry: initialized in app/main.py if SENTRY_DSN is set
  • LLM tracing (Keywords.AI): app/utils/tracing.py