# basedhardware/omi architecture

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

- Interactive diagram: https://gitdiagram.com/basedhardware/omi
- Repository: https://github.com/basedhardware/omi
- Video tour (about a minute): https://gitdiagram.com/basedhardware/omi/video

## Overview

##### Main Components
- Backend API Layer: The “backend” folder is clearly a large, multi-module Python-based application (likely using frameworks such as FastAPI or similar). It is organized into several subdirectories:
- Routers: Defines numerous API endpoints (e.g., for agents, apps, chat, conversations, custom_auth, notifications, payment, plugins, speech_profile, sync, etc.).
- Models: Contains data schemas and domain models that describe entities like conversations, memories, notifications, and more.
- Database: Encapsulates logic for managing data persistence; notice files for Redis (redis_db.py), vector_db, memory_db, and other modules such as auth, conversations, etc.
- Services: Implements business logic for devices, notifications, sockets, and other integrations.
- Modal and Pusher: Modules that pertain to background job processing and push notifications (which are important for real-time updates).
- Utils: A collection of helper functions for processing (e.g., audio, conversations, plugins, and other operations).

##### Deployment & Configuration
- Deployment & Containerization: The backend has Dockerfiles (including a dedicated Dockerfile.datadog) and Helm charts (in the “charts” directory) that suggest a Kubernetes deployment, likely on GCP (as seen from the GitHub workflows named “gcp_backend” and other deployment workflows). Make sure to show the containerization layer and deployment orchestration.
- Environment & CI/CD: Include references to configuration files (.env.template) and GitHub workflows, which streamline the continuous deployment process.

##### Relationships & Interactions
- API Gateway/Endpoints: Represent the entry point into the backend API — this layer routes requests from the mobile app, web clients, or external plugins into the proper router modules.
- Messaging & Jobs: Include a segment for background job processing (modal services and pusher) which handle asynchronous processing for notifications and real-time updates.
- External Service Integrations: Indicate connections to third-party services and SDKs (like OpenAI, imaging services, or even third-party analytics) that the backend calls. Also, note the interface with the “plugins” which extend functionality and may require webhook calls.

##### Architectural Patterns & Design Principles
- Modular Structure: Emphasize the layered design – API (routers), business logic (services), data models (models), and persistence (database).
- Scalability & Deployment: The backend uses containerization and Helm charts, implying a microservices-like mindset even if currently packaged as a monolith.
- Integration with Other Systems: The backend integrates with the mobile app, web frontend, and even device firmware. Show these as external components interacting with the backend.

##### Final Representation
– Front Door/API Layer: Routers (agents, apps, chat, conversations, etc.)
– Business Logic Layer: Services and utilities.
– Data Layer: Database modules, including Redis, vector_db, etc.
– Async Processing: Modal jobs and Pusher component.
– Integration Layer: External calls (like 3rd party APIs, CLI scripts, and plugins).
– Deployment Tools: Docker, Helm/CI pipelines depicted outside the runtime flow but linked to the corresponding deployment blocks.

## Diagram (Mermaid)

```mermaid
flowchart TB
    extClients("External Clients"):::external

    subgraph "Backend Services"
        api("API Routers"):::api
        utils("Utility Functions"):::utils
        models("Data Models"):::models
        db[(Database Integration)]:::database
        modal("Modal Jobs"):::modal
        pusher("Push Notifications"):::pusher
    end

    subgraph "Deployment & Containerization"
        docker("Dockerfile"):::deployment
        dockerDatadog("Dockerfile Datadog"):::deployment
        charts("Helm Charts"):::deployment
    end

    extClients -->|"HTTP_request"| api
    api -->|"processes_via"| utils
    utils -->|"transforms_data"| models
    models -->|"persists_to"| db
    utils -->|"triggers_async"| modal
    modal -->|"sends_updates"| pusher

    docker ---|"builds"| api
    dockerDatadog ---|"monitors"| api
    charts ---|"deploys"| api

    click api "https://github.com/basedhardware/omi/tree/main/backend/routers/"
    click models "https://github.com/basedhardware/omi/tree/main/backend/models/"
    click db "https://github.com/basedhardware/omi/tree/main/backend/database/"
    click modal "https://github.com/basedhardware/omi/tree/main/backend/modal/"
    click pusher "https://github.com/basedhardware/omi/tree/main/backend/pusher/"
    click utils "https://github.com/basedhardware/omi/tree/main/backend/utils/"
    click docker "https://github.com/basedhardware/omi/tree/main/backend/Dockerfile"
    click dockerDatadog "https://github.com/basedhardware/omi/blob/main/backend/Dockerfile.datadog"
    click charts "https://github.com/basedhardware/omi/tree/main/backend/charts/"

    classDef external fill:#fce94f,stroke:#555,stroke-width:2px;
    classDef api fill:#8ec07c,stroke:#555,stroke-width:2px;
    classDef utils fill:#fabd2f,stroke:#555,stroke-width:2px;
    classDef models fill:#d3869b,stroke:#555,stroke-width:2px;
    classDef database fill:#ebdbb2,stroke:#555,stroke-width:2px;
    classDef modal fill:#83a598,stroke:#555,stroke-width:2px;
    classDef pusher fill:#fe8019,stroke:#555,stroke-width:2px;
    classDef deployment fill:#458588,stroke:#555,stroke-width:2px;
```
