# sibycr18/roast-bob architecture

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

- Interactive diagram: https://gitdiagram.com/sibycr18/roast-bob
- Repository: https://github.com/sibycr18/roast-bob

## Overview

##### Project Type and Purpose
- This is a backend “bot” service written in Python that automates interactions on the Bluesky social network. It monitors trends, responds to mentions, generates content on a schedule, and persists memory via ChromaDB.
- Key use cases: trend analysis, mention handling, AI-driven content generation, memory storage, scheduled posting.

##### File‐Structure Analysis
- Top‐level:
- main.py: entry point and orchestrator
- mentions_service.py: script or helper for mention processing
- docker-compose.yml: container orchestration (Bluesky‐bot, ChromaDB)
- Directories:
- config/: application settings and constants (settings.py)
- clients/: adapters for external APIs (bluesky_client.py, openai_client.py)
- services/: core business logic broken out by responsibility
– trend_analyzer.py
– content_generator.py
– memory_service.py
– scheduler.py
- utils/: cross‐cutting concerns (logging)
- Persistence:
- chroma_db/chroma.sqlite3: ChromaDB backing store
- Dependencies in requirements.txt, environment variables in .env.

##### Architectural Patterns and Design Principles
- Modular service layer: each responsibility (trend analysis, content gen, memory) is isolated in its own module.
- Dependency injection via clients/ (so services call clients rather than embed HTTP logic).
- Single orchestrator (main.py) controls scheduling and event loops.
- External integrations: Bluesky API, OpenAI API, ChromaDB as a local datastore.

##### Main Components
- Orchestrator (main.py)
- Scheduler Service
- Mention Handler Service (mentions_service.py or services/mention_handler.py)
- Trend Analyzer Service
- Content Generator Service
- Memory Service (ChromaDB)
- API Clients
- BlueskyClient
- OpenAIClient
- External Dependencies
- Bluesky Platform
- OpenAI API
- Persistence Layer
- ChromaDB (SQLite file)
- Utility Layer
- Logging subsystem

##### Relationships and Data Flow
- Scheduler triggers:
- Trend Analyzer → fetch feed via BlueskyClient → analyze trends → Memory Service
- Content Generator → fetch trends from Memory → generate post via OpenAIClient → post via BlueskyClient
- Mention Handler (event‐driven):
- Listens for mention events via BlueskyClient → generates response via OpenAIClient → logs to Memory → replies via BlueskyClient
- Memory Service:
- CRUD operations on ChromaDB
- Shared by all services that need historical context
- Logging calls: all components write to logger via utils/logger.py

##### Architectural Patterns and Design Principles to Highlight
- Separation of concerns: service layer vs. client layer vs. orchestrator vs. utilities.
- Adapter pattern: clients/ folder abstracts Bluesky/OpenAI API details.
- Scheduler pattern: services/scheduler.py handles timing for automated posts.
- Repository pattern: memory_service.py encapsulates direct database interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration"
        Orchestrator["Main Orchestrator\n(main.py)"]:::orchestrator
    end

    %% Scheduler
    Scheduler["Scheduler Service\n(services/scheduler.py)"]:::service
    Scheduler -.->|"scheduled trigger"| Orchestrator

    %% Core Services
    subgraph "Core Services"
        TrendAnalyzer["Trend Analyzer Service\n(services/trend_analyzer.py)"]:::service
        ContentGenerator["Content Generator Service\n(services/content_generator.py)"]:::service
        MentionHandler["Mention Handler Service\n(mentions_service.py)"]:::service
    end
    Orchestrator -->|"invoke analyze"| TrendAnalyzer
    Orchestrator -->|"invoke generate"| ContentGenerator
    Orchestrator -->|"invoke handle"| MentionHandler

    %% Persistence Layer
    subgraph "Persistence"
        MemoryService["Memory Service\n(services/memory_service.py)"]:::service
        ChromaDB[(ChromaDB\nchroma.sqlite3)]:::persistence
    end
    TrendAnalyzer -->|"store/read context"| MemoryService
    ContentGenerator -->|"retrieve context"| MemoryService
    MentionHandler -->|"log interaction"| MemoryService
    MemoryService -->|"CRUD on DB"| ChromaDB

    %% Clients Layer
    subgraph "API Clients"
        BlueskyClient["BlueskyClient\n(clients/bluesky_client.py)"]:::client
        OpenAIClient["OpenAIClient\n(clients/openai_client.py)"]:::client
    end
    TrendAnalyzer -->|"fetch feed"| BlueskyClient
    ContentGenerator -->|"generate via"| OpenAIClient
    ContentGenerator -->|"post via"| BlueskyClient
    MentionHandler -->|"listen/respond via"| BlueskyClient
    MentionHandler -->|"respond via"| OpenAIClient

    %% External Systems
    subgraph "External Systems"
        BlueskyAPI["Bluesky API"]:::external
        OpenAIAPI["OpenAI API"]:::external
    end
    BlueskyClient -->|"HTTP requests"| BlueskyAPI
    OpenAIClient -->|"HTTP requests"| OpenAIAPI

    %% Utilities
    subgraph "Utilities"
        Logger["Logger\n(utils/logger.py)"]:::util
        DetailedLogger["Detailed Logger\n(utils/detailed_logger.py)"]:::util
        Settings["App Config\n(config/settings.py)"]:::util
    end
    Orchestrator --> Logger
    TrendAnalyzer --> Logger
    ContentGenerator --> Logger
    MentionHandler --> Logger
    MemoryService --> Logger
    Logger --> DetailedLogger

    %% Click Events
    click Orchestrator "https://github.com/sibycr18/roast-bob/blob/main/main.py"
    click Scheduler "https://github.com/sibycr18/roast-bob/blob/main/services/scheduler.py"
    click TrendAnalyzer "https://github.com/sibycr18/roast-bob/blob/main/services/trend_analyzer.py"
    click ContentGenerator "https://github.com/sibycr18/roast-bob/blob/main/services/content_generator.py"
    click MentionHandler "https://github.com/sibycr18/roast-bob/blob/main/mentions_service.py"
    click MemoryService "https://github.com/sibycr18/roast-bob/blob/main/services/memory_service.py"
    click ChromaDB "https://github.com/sibycr18/roast-bob/blob/main/chroma_db/chroma.sqlite3"
    click BlueskyClient "https://github.com/sibycr18/roast-bob/blob/main/clients/bluesky_client.py"
    click OpenAIClient "https://github.com/sibycr18/roast-bob/blob/main/clients/openai_client.py"
    click Settings "https://github.com/sibycr18/roast-bob/blob/main/config/settings.py"
    click Logger "https://github.com/sibycr18/roast-bob/blob/main/utils/logger.py"
    click DetailedLogger "https://github.com/sibycr18/roast-bob/blob/main/utils/detailed_logger.py"

    %% Styles
    classDef orchestrator fill:#cce5ff,stroke:#036,stroke-width:1px
    classDef service fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef client fill:#ffe5b4,stroke:#aa5500,stroke-width:1px
    classDef persistence fill:#f5e1da,stroke:#d2691e,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px,stroke-dasharray:5 5
    classDef util fill:#f3e5f5,stroke:#6a1b9a,stroke-width:1px
```
