# mr-meetpatel/guesszilla architecture

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

- Interactive diagram: https://gitdiagram.com/mr-meetpatel/guesszilla
- Repository: https://github.com/mr-meetpatel/guesszilla

## Overview

Wordle Control combines a Slack bot with a super-admin console for managing workspaces, participation rules, reports, schedules, and operations. The main runtime path is Slack event → verified HTTP ingress → durable job queue → worker → Wordle processing and participation storage; the console configures and inspects these services through the API. The README documents additional platform capabilities not shown in sampled implementation excerpts. Edges use those documented relationships or source-index references; unsampled internals are not inferred beyond them.

Main entry points: [`apps/backend/src/wordle_bot/http.py`](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/http.py) (HTTP application), [`apps/backend/src/wordle_bot/worker.py`](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/worker.py) (Job worker), [`apps/admin/src/shell.tsx`](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/admin/src/shell.tsx) (Admin shell), [`apps/backend/src/wordle_bot/services.py`](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/services.py) (Wordle service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Admin console"]
  node_console["Admin shell<br/>[shell.tsx]"]
  node_login["Admin login<br/>[auth.tsx]"]
  node_admin_pages["Management pages"]
  node_admin_api["API client<br/>[api.ts]"]
end

subgraph group_platform["Platform services"]
  node_http["HTTP application<br/>[http.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_platform_api["Platform endpoints<br/>[api.py]"]
  node_oauth["Slack OAuth<br/>[oauth.py]"]
  node_observability["Operations and audit<br/>[observability.py]"]
end

subgraph group_bot["Slack bot"]
  node_ingress["Slack ingress<br/>[ingress.py]"]
  node_queue["Durable job queue<br/>[postgres.py]"]
  node_worker["Job worker<br/>[worker.py]"]
  node_service["Wordle service<br/>[services.py]"]
end

subgraph group_data["Reports and data"]
  node_domain["Game and report rules<br/>[domain.py]"]
  node_repository["Participation repository<br/>[postgres.py]"]
  node_reports["Reports and delivery<br/>[reports.py]"]
  node_scheduler["Report scheduler<br/>[scheduler.py]"]
end

node_admin_actor(("Administrator"))
node_slack(("Slack workspace"))
node_slack_api{{"Slack API"}}
node_browser(("Admin browser"))
node_database[("PostgreSQL")]

node_admin_actor -->|"uses"| node_browser
node_browser -->|"loads"| node_console
node_console -->|"renders"| node_login
node_login -->|"requests login"| node_admin_api
node_console -->|"fetches data"| node_admin_api
node_console -->|"routes pages"| node_admin_pages
node_admin_pages -->|"manages platform"| node_admin_api
node_admin_api -->|"calls API"| node_http
node_slack -->|"sends events"| node_http
node_http -->|"routes events"| node_ingress
node_ingress -->|"enqueues jobs"| node_queue
node_worker -->|"claims jobs"| node_queue
node_worker -->|"dispatches platform jobs"| node_ingress
node_worker -->|"processes messages"| node_service
node_service -->|"parses and renders"| node_domain
node_service -->|"records and counts"| node_repository
node_service -->|"reacts to submissions"| node_slack_api
node_worker -->|"posts reports"| node_slack_api
node_http -->|"registers platform auth"| node_auth
node_http -->|"registers endpoints"| node_platform_api
node_slack -->|"authorizes workspace"| node_oauth
node_platform_api -.->|"supports report actions"| node_reports
node_scheduler -.->|"schedules deliveries"| node_reports
node_worker -->|"dispatches report jobs"| node_reports
node_repository -->|"persists participation"| node_database
node_reports -->|"stores reports and receipts"| node_database
node_auth -->|"stores sessions"| node_database
node_http -->|"records requests"| node_observability

click node_console "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/admin/src/shell.tsx"
click node_login "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/admin/src/auth.tsx"
click node_admin_pages "https://github.com/mr-meetpatel/guesszilla/tree/main/apps/admin/src/pages"
click node_admin_api "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/admin/src/api.ts"
click node_http "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/http.py"
click node_auth "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/auth.py"
click node_platform_api "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/api.py"
click node_oauth "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/oauth.py"
click node_ingress "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/ingress.py"
click node_queue "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/repositories/postgres.py"
click node_worker "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/worker.py"
click node_service "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/services.py"
click node_domain "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/domain.py"
click node_repository "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/repositories/postgres.py"
click node_reports "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/reports.py"
click node_scheduler "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/scheduler.py"
click node_observability "https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/observability.py"

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_console,node_login,node_admin_pages,node_admin_api,node_browser toneBlue
class node_http,node_auth,node_platform_api,node_oauth,node_observability,node_database toneAmber
class node_ingress,node_queue,node_worker,node_service,node_slack_api toneMint
class node_domain,node_repository,node_reports,node_scheduler toneRose
class node_admin_actor,node_slack toneIndigo
```

## Components

### Admin console

- [Admin shell](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/admin/src/shell.tsx): `apps/admin/src/shell.tsx`
- [Admin login](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/admin/src/auth.tsx): `apps/admin/src/auth.tsx`
- [Management pages](https://github.com/mr-meetpatel/guesszilla/tree/main/apps/admin/src/pages): `apps/admin/src/pages`
- [API client](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/admin/src/api.ts): `apps/admin/src/api.ts`

### Platform services

- [HTTP application](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/http.py): `apps/backend/src/wordle_bot/http.py`
- [Authentication](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/auth.py): `apps/backend/src/wordle_bot/platform/auth.py`
- [Platform endpoints](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/api.py): `apps/backend/src/wordle_bot/platform/api.py`
- [Slack OAuth](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/oauth.py): `apps/backend/src/wordle_bot/platform/oauth.py`
- [Operations and audit](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/observability.py): `apps/backend/src/wordle_bot/platform/observability.py`

### Slack bot

- [Slack ingress](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/ingress.py): `apps/backend/src/wordle_bot/platform/ingress.py`
- [Durable job queue](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/repositories/postgres.py): `apps/backend/src/wordle_bot/repositories/postgres.py`
- [Job worker](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/worker.py): `apps/backend/src/wordle_bot/worker.py`
- [Wordle service](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/services.py): `apps/backend/src/wordle_bot/services.py`

### Reports and data

- [Game and report rules](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/domain.py): `apps/backend/src/wordle_bot/domain.py`
- [Participation repository](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/repositories/postgres.py): `apps/backend/src/wordle_bot/repositories/postgres.py`
- [Reports and delivery](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/reports.py): `apps/backend/src/wordle_bot/platform/reports.py`
- [Report scheduler](https://github.com/mr-meetpatel/guesszilla/blob/main/apps/backend/src/wordle_bot/platform/scheduler.py): `apps/backend/src/wordle_bot/platform/scheduler.py`

### Other components

- **Administrator**
- **Slack workspace**
- **Slack API**
- **Admin browser**
- **PostgreSQL**

## Connections

- Administrator → Admin browser: uses
- Admin browser → Admin shell: loads
- Admin shell → Admin login: renders (evidence: `apps/admin/src/shell.tsx`)
- Admin login → API client: requests login (evidence: `apps/admin/src/auth.tsx`)
- Admin shell → API client: fetches data (evidence: `apps/admin/src/shell.tsx`)
- Admin shell → Management pages: routes pages (evidence: `apps/admin/src/shell.tsx`)
- Management pages → API client: manages platform (evidence: `apps/admin/src/pages/workspaces.tsx`)
- API client → HTTP application: calls API
- Slack workspace → HTTP application: sends events
- HTTP application → Slack ingress: routes events (evidence: `apps/backend/src/wordle_bot/http.py`)
- Slack ingress → Durable job queue: enqueues jobs (evidence: `apps/backend/src/wordle_bot/http.py`)
- Job worker → Durable job queue: claims jobs (evidence: `apps/backend/src/wordle_bot/worker.py`)
- Job worker → Slack ingress: dispatches platform jobs (evidence: `apps/backend/src/wordle_bot/worker.py`)
- Job worker → Wordle service: processes messages (evidence: `apps/backend/src/wordle_bot/worker.py`)
- Wordle service → Game and report rules: parses and renders (evidence: `apps/backend/src/wordle_bot/services.py`)
- Wordle service → Participation repository: records and counts (evidence: `apps/backend/src/wordle_bot/services.py`)
- Wordle service → Slack API: reacts to submissions (evidence: `apps/backend/src/wordle_bot/services.py`)
- Job worker → Slack API: posts reports (evidence: `apps/backend/src/wordle_bot/worker.py`)
- HTTP application → Authentication: registers platform auth (evidence: `apps/backend/src/wordle_bot/http.py`)
- HTTP application → Platform endpoints: registers endpoints (evidence: `apps/backend/src/wordle_bot/http.py`)
- Slack workspace → Slack OAuth: authorizes workspace
- Platform endpoints → Reports and delivery: supports report actions
- Report scheduler → Reports and delivery: schedules deliveries
- Job worker → Reports and delivery: dispatches report jobs (evidence: `apps/backend/src/wordle_bot/worker.py`)
- Participation repository → PostgreSQL: persists participation
- Reports and delivery → PostgreSQL: stores reports and receipts
- Authentication → PostgreSQL: stores sessions (evidence: `apps/backend/src/wordle_bot/platform/auth.py`)
- HTTP application → Operations and audit: records requests (evidence: `apps/backend/src/wordle_bot/http.py`)