# cryptonomikhan/theo-ai architecture

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

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

## Overview

##### Main Components
- API Service: Located under the “api” directory. This is the backend server that exposes endpoints, handles configuration, and processes external requests.
- Telegram Bot: Implemented in the “telegram” directory. This component listens for incoming messages in Telegram group chats, forwards them as requests to the API, and processes responses.
- Agents: Found in the “agents” directory. These encapsulate the business logic and smart “agno” agent functionalities. They’re responsible for performing research and determining which AI model (Formation Cloud or OpenAI) to use.
- Models: The “models” directory contains custom model implementations. This is where you’d define how data or requests are handled before reaching the agent.
- Integrations & Services:
- The “integrations” directory includes external integrations like Google Calendar.
- The “services” directory may hold modules for other external service integrations.
- Utilities: The “utils” directory provides helper resources that support configuration, logging, and system prompts.
- Deployment & Configuration:
- Files like Dockerfile, docker-compose.yml, .env.example, and environment variable instructions show that the system is containerized and configured for both local and cloud (Formation Cloud) deployments.
- Documentation & Project Flow: The “documentation” and “.cursor” directories include detailed design, flow, and architectural decisions which further suggest a planned modular design.

##### Relationships and Interactions
- Within the API server, the request is dispatched to the appropriate agent (within “agents/”) that handles business logic, including model selection (from “models/”) and invoking research or scheduling functions.
- The Agent then interacts with external integrations, such as calling functions in “integrations/googleCalendar.py” for scheduling or contacting Formation Cloud / OpenAI via the logic embedded in “utils” and “services”.
- Logging and configuration management is centralized through the “utils” module.

##### Architectural Patterns and Design Principles
- Stateless and Serverless Design: The agents are designed to be stateless (leveraging external context management). Emphasize how the components interact without holding persistent state.
- Modular Separation: The project divides responsibilities across distinct directories – separating API logic, agent processing, external integrations, and utility functions. This mirrors a microservices or modular monolith approach.
- Integration-Focused: Note how external API integrations (Telegram, Google Calendar, Formation Cloud, and OpenAI) are clearly isolated into their respective modules.
- Extensibility: The modular structure (especially in agents, integrations, and services) makes it easy to extend functionality or integrate further services.

##### Technologies and Frameworks
- Python (primary development language)
- agno Framework (for building AI agents)
- Docker and docker-compose (for containerization and deployment)
- Telegram Bot API (for chat integration)
- Google Calendar API, Formation Cloud, and OpenAI API (for external service integration)

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interaction
    subgraph "User Interaction"
        TB("Telegram Bot"):::bot
    end

    %% Backend Processing
    subgraph "Backend Processing"
        AP("API Server"):::backend
        AG("Agents"):::agents
        MD("Models"):::models
        IN("Integrations: Google Calendar"):::integration
        SR("Services"):::services
        UT("Utils & Config"):::utils
    end

    %% External APIs
    subgraph "External APIs"
        FC("Formation Cloud API"):::external
        OA("OpenAI API"):::external
    end

    %% Deployment & Configuration
    subgraph "Deployment & Configuration"
        DP("Deployment & Configuration"):::deploy
    end

    %% Documentation & Project Flow
    subgraph "Documentation & Project Flow"
        DOC("Documentation"):::doc
        CR(".cursor (Project Flow)"):::doc
    end

    %% Data flow
    TB -->|"chat_command_sent"| AP
    AP -->|"processes_request"| AG
    AG -->|"selects_model"| MD
    AG -->|"schedules_event"| IN
    AG -->|"calls_external"| SR
    AG -->|"calls_api"| FC
    AG -->|"calls_api"| OA
    AP -->|"logs&config"| UT
    AG -->|"logs&config"| UT

    %% Click Events
    click AP "https://github.com/cryptonomikhan/theo-ai/blob/main/api/main.py"
    click TB "https://github.com/cryptonomikhan/theo-ai/blob/main/telegram/bot.py"
    click AG "https://github.com/cryptonomikhan/theo-ai/blob/main/agents/theoAgent.py"
    click MD "https://github.com/cryptonomikhan/theo-ai/blob/main/models/formation.py"
    click IN "https://github.com/cryptonomikhan/theo-ai/blob/main/integrations/googleCalendar.py"
    click SR "https://github.com/cryptonomikhan/theo-ai/tree/main/services/"
    click UT "https://github.com/cryptonomikhan/theo-ai/tree/main/utils/"
    click DP "https://github.com/cryptonomikhan/theo-ai/blob/main/Dockerfile, docker-compose.yml, .env.example"
    click DOC "https://github.com/cryptonomikhan/theo-ai/tree/main/documentation/"
    click CR "https://github.com/cryptonomikhan/theo-ai/tree/main/.cursor/"

    %% Styles
    classDef bot fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef backend fill:#d1ffd1,stroke:#006600,stroke-width:2px;
    classDef agents fill:#ffebcc,stroke:#996600,stroke-width:2px;
    classDef models fill:#ffe6e6,stroke:#990000,stroke-width:2px;
    classDef integration fill:#e6ccff,stroke:#663399,stroke-width:2px;
    classDef services fill:#e6f9ff,stroke:#0099cc,stroke-width:2px;
    classDef utils fill:#e0e0e0,stroke:#666666,stroke-width:2px;
    classDef deploy fill:#fff2cc,stroke:#cc9900,stroke-width:2px;
    classDef doc fill:#f0d9ff,stroke:#9933ff,stroke-width:2px;
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
```
