# alaa13/dobby-core architecture

> Architecture diagram of the GitHub repository alaa13/dobby-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alaa13/dobby-core
- Repository: https://github.com/alaa13/dobby-core

## Overview

Dobby is a Kotlin/Spring backend for Discord and web clients: it accepts roast and fact requests, enriches asynchronous roast jobs with PostgreSQL facts, calls OpenAI, and publishes results through Redis for consumers. It also provides Discord OAuth/account support, dashboard data, API-key rate limiting, and JWT-protected live log streaming. The README documents these product flows; source excerpts were not provided, so implementation-level call ownership and finer wiring cannot be verified.

Main entry points: [`src/main/kotlin/com/example/dobby/service/AiRoastService.kt`](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/AiRoastService.kt) (AI roast generation), [`src/main/kotlin/com/example/dobby/controller/discord/RoastController.kt`](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/controller/discord/RoastController.kt) (Roast endpoint), [`src/main/kotlin/com/example/dobby/service/FactService.kt`](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/FactService.kt) (Fact service), [`src/main/kotlin/com/example/dobby/controller/discord/FactController.kt`](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/controller/discord/FactController.kt) (Fact endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_roast_api["Roast endpoint<br/>[RoastController.kt]"]
  node_fact_api["Fact endpoint<br/>[FactController.kt]"]
  node_auth_filter["API key access<br/>[ApiKeyFilter.kt]"]
  node_rate_limit["Rate limiter"]
  node_log_api["Log stream<br/>[LogController.kt]"]
  node_jwt_filter["JWT access"]
end

subgraph group_roast["Roast generation"]
  node_roast_service["Roast orchestration<br/>[RoastService.kt]"]
  node_ai_roast["AI roast generation<br/>[AiRoastService.kt]"]
  node_prompt_loader["Prompt loading"]
  node_llm_adapter["OpenAI adapter"]
end

subgraph group_accounts["Accounts and dashboard"]
  node_discord_oauth["Discord OAuth"]
  node_discord_accounts["Discord accounts"]
  node_dashboard["Dashboard data"]
end

subgraph group_runtime["Persistence and delivery"]
  node_facts["Fact service<br/>[FactService.kt]"]
  node_postgres[("PostgreSQL")]
  node_redis_publisher["Redis publisher<br/>[RedisPublisher.kt]"]
  node_redis["Redis Pub/Sub"]
  node_log_emitter["Log events<br/>[LogEmitter.kt]"]
end

node_discord_client(("Discord bot"))
node_web_client(("Web dashboard"))
node_openai{{"OpenAI"}}

node_discord_client -->|"submits roast"| node_roast_api
node_web_client -->|"submits roast"| node_roast_api
node_roast_api -->|"queues job"| node_roast_service
node_roast_service -->|"generates asynchronously"| node_ai_roast
node_ai_roast -->|"fetches context"| node_facts
node_facts -->|"reads facts"| node_postgres
node_ai_roast -->|"requests generation"| node_openai
node_ai_roast -->|"publishes result"| node_redis_publisher
node_redis_publisher -->|"publishes message"| node_redis
node_discord_client -->|"stores fact"| node_fact_api
node_fact_api -->|"stores fact"| node_facts
node_discord_client -->|"provides API key"| node_auth_filter
node_auth_filter -->|"enforces limit"| node_rate_limit
node_web_client -.->|"authenticates"| node_discord_oauth
node_discord_oauth -.->|"manages account"| node_discord_accounts
node_web_client -.->|"views dashboard"| node_dashboard
node_web_client -->|"provides JWT"| node_jwt_filter
node_web_client -->|"opens SSE stream"| node_log_api
node_log_api -.->|"streams events"| node_log_emitter
node_discord_client -->|"subscribes"| node_redis

click node_roast_api "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/controller/discord/RoastController.kt"
click node_fact_api "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/controller/discord/FactController.kt"
click node_auth_filter "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/security/ApiKeyFilter.kt"
click node_rate_limit "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/RateLimitingService.kt"
click node_log_api "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/controller/LogController.kt"
click node_jwt_filter "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/security/JwtAuthenticationFilter.kt"
click node_roast_service "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/RoastService.kt"
click node_ai_roast "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/AiRoastService.kt"
click node_prompt_loader "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/PromptLoaderService.kt"
click node_llm_adapter "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/llm/OpenAiApiAdapter.kt"
click node_discord_oauth "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/DiscordAuthService.kt"
click node_discord_accounts "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/DiscordAccountService.kt"
click node_dashboard "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/DashboardService.kt"
click node_facts "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/FactService.kt"
click node_redis_publisher "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/queue/RedisPublisher.kt"
click node_log_emitter "https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/logging/LogEmitter.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_roast_api,node_fact_api,node_auth_filter,node_rate_limit,node_log_api,node_jwt_filter toneBlue
class node_roast_service,node_ai_roast,node_prompt_loader,node_llm_adapter toneAmber
class node_discord_oauth,node_discord_accounts,node_dashboard toneMint
class node_facts,node_postgres,node_redis_publisher,node_redis,node_log_emitter toneRose
class node_discord_client,node_web_client,node_openai toneIndigo
```

## Components

### API and access

- [Roast endpoint](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/controller/discord/RoastController.kt): `src/main/kotlin/com/example/dobby/controller/discord/RoastController.kt`
- [Fact endpoint](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/controller/discord/FactController.kt): `src/main/kotlin/com/example/dobby/controller/discord/FactController.kt`
- [API key access](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/security/ApiKeyFilter.kt): `src/main/kotlin/com/example/dobby/security/ApiKeyFilter.kt`
- [Rate limiter](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/RateLimitingService.kt): `src/main/kotlin/com/example/dobby/service/RateLimitingService.kt`
- [Log stream](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/controller/LogController.kt): `src/main/kotlin/com/example/dobby/controller/LogController.kt`
- [JWT access](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/security/JwtAuthenticationFilter.kt): `src/main/kotlin/com/example/dobby/security/JwtAuthenticationFilter.kt`

### Roast generation

- [Roast orchestration](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/RoastService.kt): `src/main/kotlin/com/example/dobby/service/RoastService.kt`
- [AI roast generation](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/AiRoastService.kt): `src/main/kotlin/com/example/dobby/service/AiRoastService.kt`
- [Prompt loading](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/PromptLoaderService.kt): `src/main/kotlin/com/example/dobby/service/PromptLoaderService.kt`
- [OpenAI adapter](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/llm/OpenAiApiAdapter.kt): `src/main/kotlin/com/example/dobby/llm/OpenAiApiAdapter.kt`

### Accounts and dashboard

- [Discord OAuth](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/DiscordAuthService.kt): `src/main/kotlin/com/example/dobby/service/DiscordAuthService.kt`
- [Discord accounts](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/DiscordAccountService.kt): `src/main/kotlin/com/example/dobby/service/DiscordAccountService.kt`
- [Dashboard data](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/DashboardService.kt): `src/main/kotlin/com/example/dobby/service/DashboardService.kt`

### Persistence and delivery

- [Fact service](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/service/FactService.kt): `src/main/kotlin/com/example/dobby/service/FactService.kt`
- **PostgreSQL**
- [Redis publisher](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/queue/RedisPublisher.kt): `src/main/kotlin/com/example/dobby/queue/RedisPublisher.kt`
- **Redis Pub/Sub**
- [Log events](https://github.com/alaa13/dobby-core/blob/main/src/main/kotlin/com/example/dobby/logging/LogEmitter.kt): `src/main/kotlin/com/example/dobby/logging/LogEmitter.kt`

### Other components

- **Discord bot**
- **Web dashboard**
- **OpenAI**

## Connections

- Discord bot → Roast endpoint: submits roast (evidence: `README.md`)
- Web dashboard → Roast endpoint: submits roast (evidence: `README.md`)
- Roast endpoint → Roast orchestration: queues job (evidence: `README.md`)
- Roast orchestration → AI roast generation: generates asynchronously (evidence: `README.md`)
- AI roast generation → Fact service: fetches context (evidence: `README.md`)
- Fact service → PostgreSQL: reads facts (evidence: `README.md`)
- AI roast generation → OpenAI: requests generation (evidence: `README.md`)
- AI roast generation → Redis publisher: publishes result (evidence: `README.md`)
- Redis publisher → Redis Pub/Sub: publishes message (evidence: `README.md`)
- Discord bot → Fact endpoint: stores fact (evidence: `README.md`)
- Fact endpoint → Fact service: stores fact (evidence: `README.md`)
- Discord bot → API key access: provides API key (evidence: `README.md`)
- API key access → Rate limiter: enforces limit (evidence: `README.md`)
- Web dashboard → Discord OAuth: authenticates
- Discord OAuth → Discord accounts: manages account
- Web dashboard → Dashboard data: views dashboard
- Web dashboard → JWT access: provides JWT (evidence: `README.md`)
- Web dashboard → Log stream: opens SSE stream (evidence: `README.md`)
- Log stream → Log events: streams events
- Discord bot → Redis Pub/Sub: subscribes (evidence: `README.md`)
