# seolha314/my-fedi-bot architecture

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

- Interactive diagram: https://gitdiagram.com/seolha314/my-fedi-bot
- Repository: https://github.com/seolha314/my-fedi-bot

## Overview

##### Project type and purpose
- This is “my-fedi-bot,” a Bun-based federated-social-media bot. It runs entirely on Bun (a fast JS runtime), loads “modules” at run-time, connects to a Fediverse server (e.g. Mastodon), optionally calls an AI API, persists state in a database, and caches media locally.

##### File structure
- Top-level container/build files: Dockerfile, docker-compose.yml (dev & prod variants), .dockerignore, CONTAINER_DEPLOYMENT.md.
- Config: .env.example, config.example.json, src/config.ts.
- Core runtime: src/index.ts (entry), src/bot.ts (bot logic), src/module.ts (module loader).
- Services: src/database.ts, src/mediacache.ts, src/ai.ts.
- Extensions: src/modules/*.ts (e.g. aichat.ts).
- Tests: test/*.ts.
- Package management: package.json, bun.lockb, tsconfig.json, ESLint/Prettier configs.

##### README
- Minimal: “bun install” to install, “bun run index.ts” to start. No further architecture docs.

##### Detail
- How config.ts is consumed by bot.ts and module.ts.
- Module loader reading the file system (src/modules).
- Environment (DEV vs PROD) via separate docker-compose overlays or labels.
- That all modules share the same Bun process, but each may independently call sub-services.

Putting it all together:

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker / Bun Runtime"
        direction TB
        subgraph "Container Files"
            direction TB
            DF["Dockerfile"]:::file
            DC["docker-compose.yml"]:::file
            DCD["docker-compose.dev.yml"]:::file
            DCP["docker-compose.prod.yml"]:::file
        end

        subgraph "Configuration Service"
            direction TB
            ENV[".env.example"]:::file
            CFGJSON["config.example.json"]:::file
            ConfigLoader["src/config.ts"]:::internal
        end

        subgraph "Bot Core"
            direction TB
            Entry["src/index.ts"]:::internal
            BotLogic["src/bot.ts"]:::internal
        end

        ModuleLoader["src/module.ts"]:::internal

        subgraph "Modules"
            direction TB
            ModulesDir["src/modules/"]:::internal
            Aichat["src/modules/aichat.ts"]:::internal
        end

        subgraph "Services"
            direction TB
            AIService["src/ai.ts"]:::service
            DBService["src/database.ts"]:::storage
            CacheService["src/mediacache.ts"]:::storage
        end
    end

    subgraph "External Systems"
        direction TB
        Fediverse["Fediverse API"]:::external
        AIProvider["AI Provider API"]:::external
    end

    subgraph "Tests"
        direction TB
        AITest["test/ai.test.ts"]:::test
        DBTest["test/database.test.ts"]:::test
    end

    %% Flow
    Fediverse -->|"stream events"| Entry
    Entry -->|"initializes"| BotLogic
    ConfigLoader -->|provides config| Entry
    ConfigLoader -->|provides config| ModuleLoader
    BotLogic -->|loads modules| ModuleLoader
    ModuleLoader -->|reads files| ModulesDir
    ModulesDir -->|loads| Aichat

    Aichat -->|calls| AIService
    AIService -->|"HTTP requests"| AIProvider
    Aichat -->|reads/writes| DBService
    Aichat -->|caches media via| CacheService

    Aichat -->|returns response| BotLogic
    BotLogic -->|posts response| Fediverse

    %% Click Events
    click DF "https://github.com/seolha314/my-fedi-bot/tree/main/Dockerfile"
    click DC "https://github.com/seolha314/my-fedi-bot/blob/main/docker-compose.yml"
    click DCD "https://github.com/seolha314/my-fedi-bot/blob/main/docker-compose.dev.yml"
    click DCP "https://github.com/seolha314/my-fedi-bot/blob/main/docker-compose.prod.yml"
    click ENV "https://github.com/seolha314/my-fedi-bot/blob/main/.env.example"
    click CFGJSON "https://github.com/seolha314/my-fedi-bot/blob/main/config.example.json"
    click ConfigLoader "https://github.com/seolha314/my-fedi-bot/blob/main/src/config.ts"
    click Entry "https://github.com/seolha314/my-fedi-bot/blob/main/src/index.ts"
    click BotLogic "https://github.com/seolha314/my-fedi-bot/blob/main/src/bot.ts"
    click ModuleLoader "https://github.com/seolha314/my-fedi-bot/blob/main/src/module.ts"
    click ModulesDir "https://github.com/seolha314/my-fedi-bot/tree/main/src/modules/"
    click Aichat "https://github.com/seolha314/my-fedi-bot/blob/main/src/modules/aichat.ts"
    click AIService "https://github.com/seolha314/my-fedi-bot/blob/main/src/ai.ts"
    click DBService "https://github.com/seolha314/my-fedi-bot/blob/main/src/database.ts"
    click CacheService "https://github.com/seolha314/my-fedi-bot/blob/main/src/mediacache.ts"
    click AITest "https://github.com/seolha314/my-fedi-bot/blob/main/test/ai.test.ts"
    click DBTest "https://github.com/seolha314/my-fedi-bot/blob/main/test/database.test.ts"

    classDef internal fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px,shape:roundrect
    classDef service fill:#D5F5E3,stroke:#145A32,stroke-width:1px,shape:roundrect
    classDef storage fill:#FCF3CF,stroke:#7D6608,stroke-width:1px,shape:cylinder
    classDef external fill:#F2F3F4,stroke:#566573,stroke-width:1px,shape:cloud
    classDef file fill:#EBDEF0,stroke:#8E44AD,stroke-width:1px,shape:rect
    classDef test fill:#FADBD8,stroke:#922B21,stroke-width:1px,shape:rect
```
