Skip to content

Query / Message Processing Architecture

Last Verified: February 2026
Scope: Backend message ingest + orchestration pipeline (this repo)

This backend processes user messages primarily via the Mac mini edge relay (../archety-edge) and optionally via a legacy relay integration.

1) Ingress entry points

A. Edge relay (recommended): POST /edge/message

  • Who calls it: Mac mini edge relay (../archety-edge)
  • Auth: Authorization: Bearer <edge_token> (see app/edge/auth.py)
  • Input: FilteredMessage (supports both legacy + modern shapes; see app/edge/schemas.py)
  • Why it exists: the edge relay pre-filters/redacts and can maintain local context/scheduling.

Implementation: app/api/edge_routes.py

B. Legacy relay: POST /orchestrator/message

  • Who calls it: older relay integration
  • Auth: Authorization: Bearer <RELAY_WEBHOOK_SECRET> (if configured)
  • Input: OrchestratorRequest (see app/models/schemas.py)

Implementation: app/main.py

2) Core orchestrator: MessageHandler

Both ingress paths ultimately route into: - app/orchestrator/message_handler.py::MessageHandler.handle_message_async()

At a high level:

  1. Fast reflex (optional): regex/deterministic “ack” to reduce perceived latency
  2. app/messaging/fast_reflex_detector.py

  3. app/messaging/reflex_library.py

  4. Safety + gating

  5. Subscription/message limits: app/services/subscription_access_service.py

  6. Output moderation: app/safety/ (called from ingress handlers)

  7. Context build

  8. Conversation history: app/orchestrator/conversation_history_service.py
  9. Memory retrieval: app/memory/ (SupermemoryService default; mem0 fallback via get_memory_service())

  10. Relationship state: app/orchestrator/relationship_service_sql.py

  11. Routing (single decision point)

  12. app/orchestrator/smart_message_router.py

  13. Note: the router model is configurable; in current code it’s instantiated with gemini-2.5-flash-lite.

  14. Tool execution (when needed)

  15. app/orchestrator/tool_executor.py
  16. Web/current-info routing: app/orchestrator/smart_router.py + app/orchestrator/query_analyzer.py

  17. Search providers: app/orchestrator/providers/ (Perplexity / Parallel)

  18. Response generation

  19. app/orchestrator/response_generator.py (persona-styled, multi-bubble)

  20. LLM wrapper: app/utils/llm_client.py (OpenAI GPT‑5 + optional Gemini)

  21. Persistence + analytics

  22. DB models: app/models/database.py
  23. Analytics: app/orchestrator/analytics_tracker.py, app/analytics/

3) Edge WebSocket “reflex first” delivery

When the edge relay maintains a WebSocket connection (/edge/ws), the backend can push the first bubble immediately:

  • Edge WebSocket manager: app/edge/websocket_manager.py
  • Protocol + auth details: docs/architecture/WEBSOCKET_PROTOCOL.md

This is used to deliver a fast first bubble (reflex) while the full response is still generating.

4) Key schemas

  • Orchestrator (legacy): app/models/schemas.py::OrchestratorRequest, OrchestratorResponse
  • Edge relay: app/edge/schemas.py::FilteredMessage, EdgeCommand, CommandAck

5) Quick debugging map

  • Ingress logic: app/api/edge_routes.py and app/main.py
  • Routing decisions: app/orchestrator/smart_message_router.py
  • Tool routing (Perplexity/Parallel/Free APIs): app/orchestrator/smart_router.py
  • Memory selection: app/memory/__init__.py