# rcy/annie architecture

> Architecture diagram of the GitHub repository rcy/annie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rcy/annie
- Repository: https://github.com/rcy/annie

## Overview

##### Main Components

a. Core Bot Engine
- To IRC handling component (bot/irc.go)
- Event system (events/events.go)

b. Handler System
- Handlers into categories:
- Utility (weather, time, seen)
- Entertainment (mlb, worldcup, epigram)
- Reminder System (remindme)
- Link Management (linkpool, anonlink)
- AI Integration (internal/ai)

c. Database Layer
- PostgreSQL database connection (db/db.go)
- Models and queries (db/model)
- Data flow for notes, reminders, and other persistent data

d. Web Interface
- Web server component (web/server.go)
- Template rendering system
- Authentication flow

e. External Services Integration
- Weather API integration
- MLB data integration
- Image generation service (image/runpod.go)
- AI completion service (internal/ai/complete.go)

##### Relationship Flows

- Command flow from IRC to handlers
- Data flow between handlers and database
- External API calls
- Web interface interactions
- Event propagation paths

##### Technical Details

a. Infrastructure Layer:
- Docker container boundary (Dockerfile)
- Deployment flow (.github/workflows)
- Configuration management (.env files)

b. Data Stores:
- PostgreSQL database
- Cache systems (handlers/day/cache.go)
- File-based storage (epigrams, weather testdata)

##### Specific Implementation Notes

Create subsections for:
- Command processing pipeline
- Event handling system
- Database schema overview
- Authentication flow
- External API integration points

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Core["Core Bot Engine"]
        Bot["IRC Bot"]:::core
        EventSystem["Event System"]:::core
        CmdProcessor["Command Processor"]:::core
    end

    subgraph Handlers["Handler System"]
        direction TB
        Weather["Weather Handler"]:::handler
        MLB["MLB Handler"]:::handler
        Reminder["Reminder System"]:::handler
        LinkMgmt["Link Management"]:::handler
        AI["AI Integration"]:::handler
    end

    subgraph Database["Database Layer"]
        DB[(PostgreSQL)]:::database
        Models["DB Models"]:::database
        Queries["DB Queries"]:::database
        Schema["Schema"]:::database
    end

    subgraph Web["Web Interface"]
        WebServer["Web Server"]:::web
        Templates["Templates"]:::web
        Login["Login Page"]:::web
        Index["Main Index"]:::web
    end

    subgraph External["External Services"]
        WeatherAPI["Weather API"]:::external
        MLBAPI["MLB API"]:::external
        ImageGen["Image Generation"]:::external
        AIComplete["AI Completion"]:::external
    end

    subgraph Infrastructure["Infrastructure"]
        Docker["Docker Container"]:::infra
        Deploy["Deployment"]:::infra
        EnvConfig["Environment Config"]:::infra
    end

    subgraph Utils["Utility Components"]
        Fetch["Fetch Utility"]:::util
        GenUtils["General Utilities"]:::util
        Shell["Shell Commands"]:::util
        IDStr["ID String Handler"]:::util
    end

    Bot --> EventSystem
    EventSystem --> CmdProcessor
    CmdProcessor --> Handlers
    Handlers --> DB
    WebServer --> Templates
    Templates --> Login
    Templates --> Index
    Weather --> WeatherAPI
    MLB --> MLBAPI
    AI --> AIComplete
    LinkMgmt --> DB
    Reminder --> DB
    Models --> DB
    Queries --> DB
    Schema --> DB

    classDef core fill:#2374ab
    classDef handler fill:#57a773
    classDef database fill:#ffc857
    classDef web fill:#7b4b94
    classDef external fill:#d64933
    classDef infra fill:#463f3a
    classDef util fill:#8d99ae

    click Bot "https://github.com/rcy/annie/blob/main/bot/irc.go"
    click EventSystem "https://github.com/rcy/annie/blob/main/events/events.go"
    click CmdProcessor "https://github.com/rcy/annie/blob/main/bot/handlers.go"
    click Weather "https://github.com/rcy/annie/blob/main/handlers/weather/weather.go"
    click MLB "https://github.com/rcy/annie/blob/main/handlers/mlb/mlb.go"
    click Reminder "https://github.com/rcy/annie/blob/main/handlers/remindme.go"
    click LinkMgmt "https://github.com/rcy/annie/blob/main/handlers/linkpool/linkpool.go"
    click AI "https://github.com/rcy/annie/blob/main/internal/ai/complete.go"
    click DB "https://github.com/rcy/annie/blob/main/db/db.go"
    click Models "https://github.com/rcy/annie/blob/main/db/model/models.go"
    click Queries "https://github.com/rcy/annie/blob/main/db/model/query.sql.go"
    click Schema "https://github.com/rcy/annie/blob/main/db/schema.sql"
    click WebServer "https://github.com/rcy/annie/blob/main/web/server.go"
    click Templates "https://github.com/rcy/annie/tree/main/web/templates"
    click Login "https://github.com/rcy/annie/blob/main/web/templates/login.gohtml"
    click Index "https://github.com/rcy/annie/blob/main/web/templates/index.gohtml"
    click WeatherAPI "https://github.com/rcy/annie/blob/main/handlers/weather/forecast.go"
    click MLBAPI "https://github.com/rcy/annie/blob/main/handlers/mlb/gameodds.go"
    click ImageGen "https://github.com/rcy/annie/blob/main/image/runpod.go"
    click AIComplete "https://github.com/rcy/annie/blob/main/internal/ai/complete.go"
    click Docker "https://github.com/rcy/annie/tree/main/Dockerfile"
    click Deploy "https://github.com/rcy/annie/blob/main/.github/workflows/deploy.yml"
    click EnvConfig "https://github.com/rcy/annie/blob/main/.env"
    click Fetch "https://github.com/rcy/annie/blob/main/fetch/fetch.go"
    click GenUtils "https://github.com/rcy/annie/blob/main/util/util.go"
    click Shell "https://github.com/rcy/annie/blob/main/shell/command.go"
    click IDStr "https://github.com/rcy/annie/blob/main/internal/idstr/idstr.go"
```
