# omnara-ai/omnara architecture

> Architecture diagram of the GitHub repository omnara-ai/omnara, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omnara-ai/omnara
- Repository: https://github.com/omnara-ai/omnara

## Overview

##### Project type and purpose
- **Type:** Full-stack, multi-platform orchestration system for AI “agents” with CLI, mobile, web, integrations, and backend services.
- **Purpose:** Provide a unified dashboard (web & mobile) and CLI wrapper to monitor, interact with, and route messages between AI agents (Claude Code, Codex CLI, n8n workflows, GitHub Actions, etc.).

##### File structure
- **Top-level dirs:**
- apps/mobile (React Native)
- apps/web (React/Vite)
- apps/packages/shared (design tokens, UI theme)
- src/backend (Python API service)
- src/relay_server (WebSocket gateway)
- src/servers/api & src/servers/mcp (auxiliary microprotocol servers)
- src/omnara (CLI entrypoint, SDK)
- src/integrations (n8n nodes, GitHub Action, headless wrappers)
- src/shared (database schemas, Alembic migrations, auth & config)
- infrastructure/docker & scripts
- **Architectural hints:**
- MVC/API service pattern in src/backend
- WebSocket relay for real-time sync
- Separate Notification service (push/email/SMS via Twilio & Supabase)
- CI/CD workflows and Docker Compose for local dev

##### README insights
- “Your AI Agents” → API → DB → Notification → Mobile/Web → back to API → Agents.
- Mentions Supabase for auth & real-time database sync in frontends.
- CLI (“omnara”) uses three modes (standard, headless, serve) that hook into the same backend.

##### Detail
- Drill into the WebSocket relay path, the Supabase real-time sync pipeline, and the notification triggers.
- Where shared modules (`src/shared`) are imported by multiple services.
- Build/deployment artifacts (Docker Compose) as a footnote or separate “Infrastructure” layer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Your AI Agents & CLI Wrappers
    subgraph "Your AI Agents & CLI Wrappers" 
        direction TB
        AgentsCLI["External AI Agents & CLI Wrappers"]:::external
        Headless["Headless Wrappers (Python)"]:::external
        Webhooks["Webhooks Integrations (Claude Code)"]:::external
        n8nNode["n8n Integration Node"]:::external
        GitHubAction["GitHub Action Integration"]:::external
    end

    %% Devices & Clients
    subgraph "Devices & Clients"
        direction TB
        OmnaraCLI["Omnara CLI & SDK"]:::client
        MCPInstaller["MCP Installer (TypeScript CLI)"]:::client
        WebDashboard["Web Dashboard (React/Vite)"]:::client
        MobileApp["Mobile App (React Native)"]:::client
    end

    %% Integrations Plane
    subgraph "Integrations"
        direction TB
        AgentsCLI -->|integrates via| APIService
        Headless -->|integrates via| APIService
        Webhooks -->|integrates via| APIService
        n8nNode -->|integrates via| APIService
        GitHubAction -->|integrates via| APIService
    end

    %% Omnara Platform Core
    subgraph "Omnara Platform" 
        direction TB
        RelayServer["Relay Server (WebSocket)"]:::service
        AuxMCP["Auxiliary MCP Server"]:::service
        AuxAPI["Auxiliary API Micro-server"]:::service
        APIService["API Service (FastAPI)"]:::service
        Notification["Notification Service (Twilio/Supabase)"]:::service
        PostgreSQL["PostgreSQL"]:::db
        SharedSchemas["Shared Schemas & Migrations"]:::db
    end

    %% Infrastructure
    subgraph "Infrastructure" 
        direction TB
        DockerCompose["Docker Compose & Scripts"]:::infra
    end

    %% Connections
    AgentsCLI -->|"ws_connect →"| RelayServer
    OmnaraCLI -->|"ws_connect →"| RelayServer
    MCPInstaller -->|"setup ws →"| RelayServer
    Headless -->|"ws_connect →"| RelayServer

    RelayServer -->|"http/ws →"| APIService
    AuxMCP -->|"microprotocol →"| RelayServer
    AuxAPI -->|"http →"| RelayServer

    APIService -->|"store →"| PostgreSQL
    SharedSchemas -->|"migrations →"| PostgreSQL

    APIService -->|"notify →"| Notification
    Notification -->|"push_notify →"| MobileApp

    APIService -->|"rest/graphql →"| WebDashboard
    APIService -->|"rest/graphql →"| MobileApp

    WebDashboard -->|"realtime subscribe →"| APIService
    MobileApp -->|"realtime subscribe →"| APIService

    DockerCompose -->|"deploy →"| RelayServer
    DockerCompose -->|"deploy →"| APIService
    DockerCompose -->|"deploy →"| AuxMCP
    DockerCompose -->|"deploy →"| AuxAPI
    DockerCompose -->|"deploy →"| Notification

    %% Click Events
    click AgentsCLI "https://github.com/omnara-ai/omnara/tree/main/src/integrations/cli_wrappers"
    click Headless "https://github.com/omnara-ai/omnara/tree/main/src/integrations/headless"
    click Webhooks "https://github.com/omnara-ai/omnara/tree/main/src/integrations/webhooks/claude_code"
    click n8nNode "https://github.com/omnara-ai/omnara/tree/main/src/integrations/n8n"
    click GitHubAction "https://github.com/omnara-ai/omnara/tree/main/src/integrations/github/claude-code-action"
    click OmnaraCLI "https://github.com/omnara-ai/omnara/tree/main/src/omnara"
    click MCPInstaller "https://github.com/omnara-ai/omnara/tree/main/src/mcp-installer/cli"
    click RelayServer "https://github.com/omnara-ai/omnara/tree/main/src/relay_server"
    click AuxMCP "https://github.com/omnara-ai/omnara/tree/main/src/servers/mcp"
    click AuxAPI "https://github.com/omnara-ai/omnara/tree/main/src/servers/api"
    click APIService "https://github.com/omnara-ai/omnara/tree/main/src/backend"
    click SharedSchemas "https://github.com/omnara-ai/omnara/tree/main/src/shared"
    click Notification "https://github.com/omnara-ai/omnara/tree/main/src/servers/shared"
    click WebDashboard "https://github.com/omnara-ai/omnara/tree/main/apps/web"
    click MobileApp "https://github.com/omnara-ai/omnara/tree/main/apps/mobile"
    click DockerCompose "https://github.com/omnara-ai/omnara/tree/main/infrastructure/docker"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#5B8CFF
    classDef external fill:#FFD59E,stroke:#FFAB00
    classDef service fill:#C6F7C5,stroke:#28A745
    classDef db fill:#E3D5F2,stroke:#6F42C1
    classDef integration fill:#FFE38F,stroke:#FF8C00
    classDef infra fill:#F0F0F0,stroke:#A0A0A0
```
