Architecture Overview

Clara Core is architected as a modular, decoupled framework designed for cognitive agent workflows, external service integrations, and real-time client communication.

High-Level System Architecture

+-------------------------------------------------------------------------+
|                              Clara Client                               |
|               (Mobile Flutter App, Web Dashboard, CLI)                  |
+-------------------------------------------------------------------------+
                                    |
                                    |  JSON / WebSocket Protocol
                                    v
+-------------------------------------------------------------------------+
|                           clara.api (FastAPI)                           |
|  - ConnectionManager: Socket tracking & heartbeat                       |
|  - EventStreamer: Real-time broadcast & typing events                   |
|  - APIRouter (/ws/chat, /health): Request dispatching                   |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
|                          clara.agent & Skills                           |
|  - OpenRouterClient: LLM model prompting & completion                   |
|  - Skill Registry & Router: Intent classification & entity extraction   |
|  - Cognitive CRUD Loop: Ambiguity check & safety guardrails             |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
|                       clara.connections (Adapters)                      |
|  - ConnectionRegistry: Dynamic service resolution                       |
|  - BaseConnection: Standardized authentication lifecycle                |
|  - Google Workspace Adapters: Gmail, Calendar, Drive                    |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
|                          External APIs & Services                       |
|          (Google APIs, OpenRouter, Notion, Slack, GitHub)               |
+-------------------------------------------------------------------------+

The Request Lifecycle

When a user interacts with Clara (e.g. typing “Draft an email to Alex about the budget review”), the request moves through five distinct lifecycle stages:

[1. Ingestion]  -->  [2. Orchestration]  -->  [3. Skill Dispatch]  -->  [4. Execution]  -->  [5. Streaming]
   WebSocket             OpenRouter /             Email Assistant          Gmail Connection       EventStreamer
    Payload                Intents                  Cognitive Loop           API Calls             Broadcast

  1. Ingestion (clara.api.ws):

    • The client initiates a persistent WebSocket connection to /ws/chat.

    • ConnectionManager accepts and registers the socket in the active pool.

    • Incoming messages are decoded and sanitized, separating prompt text, OAuth bearer tokens, and session context.

  2. Agent Orchestration (clara.agent):

    • The prompt is evaluated against skill triggers or submitted to the OpenRouterClient for intent classification and tool selection.

    • The conversation history is maintained and formatted according to the model’s chat schema.

  3. Skill Selection & Guardrails (clara.skills):

    • The resolved skill workflow (e.g. EmailAssistantWorkflow) receives the prompt.

    • Entities such as recipients, subject, body, and dates are parsed.

    • Safety Guardrails: If the action has high blast radius (permanent deletion, emailing >5 recipients), execution pauses and emits a pending_confirmation status back to the user.

  4. Connection Execution (clara.connections):

    • Once validated, the skill requests an active connection adapter from the ConnectionRegistry.

    • The connection adapter executes the concrete API calls (e.g., send_email, create_event, list_files) using the user’s OAuth credentials.

  5. Streamed Response (clara.api.ws.event_streamer):

    • The action result is formatted into human-readable markdown and a structured JSON payload.

    • EventStreamer publishes the chat_response event back over the WebSocket to the client frontend.

Skills vs Connections: Key Architectural Distinction

A core design principle of Clara is the strict separation between Skills and Connections:

Concept

Layer

Primary Responsibility

Example

Connections

clara.connections

Raw API protocol adapters, authentication token management, HTTP calls, payload serialization.

GmailConnection.send_email(), CalendarConnection.list_events()

Skills

clara.skills

Business logic, prompt engineering, intent parsing, safety guardrails, user confirmations, markdown formatting.

EmailAssistantWorkflow.execute(), skill.yaml, prompt.md

Why This Separation Matters

  • Swappable Providers: Skills do not care about the underlying API implementation. An email skill could route to Gmail, Microsoft Graph, or Fastmail simply by targeting a different connection adapter.

  • Security & Testing: Connection adapters can be mocked or unit-tested independently without running LLM inference.

  • Modularity: Developers can write custom skills without modifying the core API server or low-level connection classes.