# rroix/avenue-guard-gd-avenue architecture

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

- Interactive diagram: https://gitdiagram.com/rroix/avenue-guard-gd-avenue
- Repository: https://github.com/rroix/avenue-guard-gd-avenue

## Overview

Avenue Guard is a Discord-centered community operations system, with public website and private Staff Portal interfaces sharing durable workflows and records. The main journey is a member submitting a level request, staff reviewing it, and positive outcomes entering recommendation and outreach operations. The map also preserves documented appeals, applications, rewards, tickets, moderation, telemetry, and recovery capabilities. Some capabilities are represented by their documented subsystem directories because their implementation was not sampled; edges are limited to indexed references or README statements.

Main entry points: [`main.py`](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/main.py) (Discord Bot), [`services/staff_portal.py`](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/staff_portal.py) (Staff Portal API), [`cogs/RequestLevels.py`](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/RequestLevels.py) (Level Requests), [`services/priority_system.py`](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/priority_system.py) (Priority and Outreach)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Community Interfaces"]
  node_discord["Discord Bot<br/>[main.py]"]
  node_public_web["Public Website"]
  node_staff_portal["Staff Portal API<br/>[staff_portal.py]"]
end

subgraph group_workflows["Community Workflows"]
  node_level_requests["Level Requests<br/>[RequestLevels.py]"]
  node_request_rules["Request Validation"]
  node_reviews["Review Operations<br/>[request_reviews.py]"]
  node_priority["Priority and Outreach<br/>[priority_system.py]"]
  node_creator_points["Creator Points<br/>[creator_points.py]"]
  node_appeals["Punishment Appeals"]
  node_weekly_rewards["Weekly Rewards<br/>[Tracking.py]"]
  node_help_tickets["Help and Tickets<br/>[Help.py]"]
  node_moderation["Moderation and Forums<br/>[Mod.py]"]
end

subgraph group_staff["Staff Operations"]
  node_applications["Staff Applications<br/>[staff_portal.py]"]
  node_staff_operations["Staff Operations<br/>[Operations.py]"]
  node_telemetry["Telemetry and Audits<br/>[impact.py]"]
  node_public_status["Public Status Data<br/>[keepalive.py]"]
end

subgraph group_platform["Runtime and State"]
  node_database[("Turso / libSQL<br/>[db.py]")]
  node_worker["Database Worker<br/>[libsql_worker.py]"]
  node_outbox["Durable Delivery<br/>[outbox.py]"]
  node_workflow_state["Workflow State Rules<br/>[workflows.py]"]
  node_staff_auth["Staff Authorization<br/>[staff_auth.py]"]
  node_main["Application Startup<br/>[main.py]"]
end

node_members(("Members and Staff"))
node_gd_sources["Geometry Dash Data"]

node_members -->|"use commands"| node_discord
node_members -->|"use services"| node_public_web
node_members -->|"staff access"| node_staff_portal
node_discord -->|"routes requests"| node_level_requests
node_level_requests -->|"uses validation"| node_request_rules
node_level_requests -->|"uses review logic"| node_reviews
node_level_requests -->|"checks levels"| node_gd_sources
node_reviews -->|"positive outcomes queue"| node_priority
node_priority -->|"uses evidence"| node_creator_points
node_staff_portal -->|"manages queue"| node_priority
node_public_web -->|"submits appeals"| node_appeals
node_staff_portal -->|"supports review"| node_appeals
node_staff_portal -->|"supports applications"| node_applications
node_discord -->|"tracks activity"| node_weekly_rewards
node_discord -->|"handles support"| node_help_tickets
node_discord -->|"provides tools"| node_moderation
node_discord -->|"records activity"| node_telemetry
node_main -->|"initializes storage"| node_database
node_database -->|"delegates driver work"| node_worker
node_staff_portal -->|"checks capabilities"| node_staff_auth
node_staff_portal -->|"records workflows"| node_workflow_state
node_discord -->|"uses delivery queue"| node_outbox
node_discord -.->|"serves public status"| node_public_status
node_staff_operations -.->|"manages recovery"| node_database

click node_discord "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/main.py"
click node_staff_portal "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/staff_portal.py"
click node_level_requests "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/RequestLevels.py"
click node_request_rules "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/request_validation.py"
click node_reviews "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/request_reviews.py"
click node_priority "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/priority_system.py"
click node_creator_points "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/creator_points.py"
click node_appeals "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/punishment_appeals.py"
click node_weekly_rewards "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/Tracking.py"
click node_help_tickets "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/Help.py"
click node_moderation "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/Mod.py"
click node_applications "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/staff_portal.py"
click node_staff_operations "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/Operations.py"
click node_telemetry "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/impact.py"
click node_public_status "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/keepalive.py"
click node_database "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/db.py"
click node_worker "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/libsql_worker.py"
click node_outbox "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/outbox.py"
click node_workflow_state "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/workflows.py"
click node_staff_auth "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/staff_auth.py"
click node_main "https://github.com/rroix/avenue-guard-gd-avenue/blob/main/main.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_discord,node_public_web,node_staff_portal toneBlue
class node_level_requests,node_request_rules,node_reviews,node_priority,node_creator_points,node_appeals,node_weekly_rewards,node_help_tickets,node_moderation toneAmber
class node_applications,node_staff_operations,node_telemetry,node_public_status toneMint
class node_database,node_worker,node_outbox,node_workflow_state,node_staff_auth,node_main toneRose
class node_members,node_gd_sources toneIndigo
```

## Components

### Community Interfaces

- [Discord Bot](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/main.py): `main.py`
- **Public Website**
- [Staff Portal API](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/staff_portal.py): `services/staff_portal.py`

### Community Workflows

- [Level Requests](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/RequestLevels.py): `cogs/RequestLevels.py`
- [Request Validation](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/request_validation.py): `services/request_validation.py`
- [Review Operations](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/request_reviews.py): `services/request_reviews.py`
- [Priority and Outreach](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/priority_system.py): `services/priority_system.py`
- [Creator Points](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/creator_points.py): `services/creator_points.py`
- [Punishment Appeals](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/punishment_appeals.py): `services/punishment_appeals.py`
- [Weekly Rewards](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/Tracking.py): `cogs/Tracking.py`
- [Help and Tickets](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/Help.py): `cogs/Help.py`
- [Moderation and Forums](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/Mod.py): `cogs/Mod.py`

### Staff Operations

- [Staff Applications](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/staff_portal.py): `services/staff_portal.py`
- [Staff Operations](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/cogs/Operations.py): `cogs/Operations.py`
- [Telemetry and Audits](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/services/impact.py): `services/impact.py`
- [Public Status Data](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/keepalive.py): `utils/keepalive.py`

### Runtime and State

- [Turso / libSQL](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/db.py): `utils/db.py`
- [Database Worker](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/libsql_worker.py): `utils/libsql_worker.py`
- [Durable Delivery](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/outbox.py): `utils/outbox.py`
- [Workflow State Rules](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/workflows.py): `utils/workflows.py`
- [Staff Authorization](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/utils/staff_auth.py): `utils/staff_auth.py`
- [Application Startup](https://github.com/rroix/avenue-guard-gd-avenue/blob/main/main.py): `main.py`

### Other components

- **Members and Staff**
- **Geometry Dash Data**

## Connections

- Members and Staff → Discord Bot: use commands (evidence: `README.md`)
- Members and Staff → Public Website: use services (evidence: `README.md`)
- Members and Staff → Staff Portal API: staff access (evidence: `README.md`)
- Discord Bot → Level Requests: routes requests (evidence: `README.md`)
- Level Requests → Request Validation: uses validation (evidence: `cogs/RequestLevels.py`)
- Level Requests → Review Operations: uses review logic (evidence: `cogs/RequestLevels.py`)
- Level Requests → Geometry Dash Data: checks levels (evidence: `README.md`)
- Review Operations → Priority and Outreach: positive outcomes queue (evidence: `README.md`)
- Priority and Outreach → Creator Points: uses evidence (evidence: `services/priority_system.py`)
- Staff Portal API → Priority and Outreach: manages queue (evidence: `services/staff_portal.py`)
- Public Website → Punishment Appeals: submits appeals (evidence: `README.md`)
- Staff Portal API → Punishment Appeals: supports review (evidence: `services/staff_portal.py`)
- Staff Portal API → Staff Applications: supports applications (evidence: `README.md`)
- Discord Bot → Weekly Rewards: tracks activity (evidence: `README.md`)
- Discord Bot → Help and Tickets: handles support (evidence: `README.md`)
- Discord Bot → Moderation and Forums: provides tools (evidence: `README.md`)
- Discord Bot → Telemetry and Audits: records activity (evidence: `README.md`)
- Application Startup → Turso / libSQL: initializes storage (evidence: `main.py`)
- Turso / libSQL → Database Worker: delegates driver work (evidence: `utils/db.py`)
- Staff Portal API → Staff Authorization: checks capabilities (evidence: `services/staff_portal.py`)
- Staff Portal API → Workflow State Rules: records workflows (evidence: `services/staff_portal.py`)
- Discord Bot → Durable Delivery: uses delivery queue (evidence: `main.py`)
- Discord Bot → Public Status Data: serves public status (evidence: `main.py`)
- Staff Operations → Turso / libSQL: manages recovery
