# benargo/regrowth-website architecture

> Architecture diagram of the GitHub repository benargo/regrowth-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benargo/regrowth-website
- Repository: https://github.com/benargo/regrowth-website

## Overview

1. **Overall shape**
CompWatcher is a Laravel 11 monolith with an Inertia-style React frontend. The backend owns routing, domain logic, persistence, queues, caching, and API integrations; the `resources/js` layer is a UI shell for officer workflows rather than a separate frontend application.

2. **Primary domain boundaries**
The codebase is organized around four main business areas: raiding/attendance, loot council, guild roster/permissions, and Discord automation. Each area has its own controllers, models, policies, resources, jobs, and events, which keeps the architecture centered on domain workflows instead of generic CRUD.

3. **Web request flow**
Browser requests enter through `routes/web.php` and are handled by Laravel controllers in `app/Http/Controllers`. Requests are validated by dedicated form request classes, authorized by policies, and serialized through API resources before being rendered into React pages under `resources/js/Pages`.

4. **Front-end composition**
The UI is server-driven via Inertia, with reusable React components in `resources/js/Components`, shared layout in `resources/js/Layouts`, and page-specific features grouped by domain. This means the frontend mostly consumes backend-provided data models and permissions rather than maintaining its own independent API state layer.

5. **Persistence layer**
Data is stored in MySQL through Eloquent models in `app/Models`, with migrations showing the main schema: users/Discord identity, characters, guild ranks/tags, raids and reports, event assignments/groups, loot council items/comments/priorities, planned absences, spells/markers, and supporting lookup tables like zones and classes. Casts and custom Eloquent helpers are used heavily to normalize Warcraft/Discord-specific value shapes.

6. **Integration services**
External dependencies are abstracted behind service namespaces: Blizzard, Discord, RaidHelper, and Warcraft Logs. These services encapsulate authentication, API clients, payload/resource mapping, and domain-specific exceptions, so the rest of the app interacts with stable application services instead of raw HTTP calls.

7. **Background processing**
Non-interactive work is pushed to jobs in `app/Jobs` and executed via Laravel queues/Horizon. Examples include fetching guild rosters, syncing Discord roles/users, processing GRM uploads, fetching RaidHelper events, rebuilding loot council cache, and importing Warcraft Logs attendance/reports. This is a key boundary: user actions trigger jobs, and jobs later update domain models and cached projections.

8. **Event-driven side effects**
The app uses a sizable event/listener layer to decouple write operations from follow-up work. Domain events such as character updates, report changes, comment actions, and assignment changes fan out to listeners that flush caches, prefetch media, schedule addon builds, or trigger roster refreshes. That pattern keeps controllers and jobs focused on primary state changes.

9. **Caching and derived views**
Cache invalidation is treated as part of the architecture, not an implementation detail. Separate listeners and cache-flush contracts exist for attendance, permissions, raiding, reports, Warcraft Logs, and loot council, indicating that many screens are backed by computed or preprocessed data rather than direct database reads.

10. **Discord as an operational surface**
Discord is both an identity provider and an output channel. OAuth login goes through Discord auth controllers, Discord roles/users are synchronized from guild state, and a custom notification driver plus Discord-specific notification classes post updates to channels. This makes Discord an extension of the application’s workflow, not just an integration.

11. **Raid analytics pipeline**
Attendance and reporting features are built around a data pipeline from external logs into internal analytical views. Warcraft Logs data is fetched into reports/guild-tag structures, then attendance services transform that raw data into matrix, graph, scatter, and dashboard-friendly projections for the React views.

12. **Loot council subsystem**
Loot council is its own mini-domain with items, priorities, comments, reactions, notes, and raid-context views. It includes cache rebuilds, media prefetching, and resource classes for item/boss presentation, which suggests a write-heavy collaborative workflow with computed read models and UI-centric formatting.

13. **Addon/export and guild administration**
Administrative features include addon settings, phase/rank management, permissions, and export file generation. The `BuildAddonExportFile` command/job pair and related scheduling contract show that the app periodically produces guild-facing artifacts consumed outside the web UI.

14. **Tests as architecture signals**
The repo has broad feature, unit, and smoke coverage across controllers, jobs, listeners, services, policies, resources, and models. That test structure mirrors the production boundaries closely, reinforcing that the app is designed as a set of coordinated domains with clear seams between HTTP, async work, integrations, and persistence.

Main entry points: [`app/Http/Controllers`](https://github.com/benargo/regrowth-website/tree/main/app/Http/Controllers) (Controllers), [`app/Services`](https://github.com/benargo/regrowth-website/tree/main/app/Services) (Domain services), [`app/Jobs`](https://github.com/benargo/regrowth-website/tree/main/app/Jobs) (Jobs), [`app/Models`](https://github.com/benargo/regrowth-website/tree/main/app/Models) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Laravel backend"]
  node_routes_web["Web routes<br/>route map<br/>[web.php]"]
  node_http_controllers["Controllers"]
  node_form_requests["Form requests<br/>validation"]
  node_policies["Policies<br/>authorization"]
  node_api_resources["API resources<br/>serialization"]
  node_services_core["Domain services<br/>application services"]
  node_jobs["Jobs<br/>async work"]
  node_listeners["Listeners<br/>events side effects"]
  node_events(("Domain events<br/>event bus"))
  node_commands["Console commands<br/>artisan commands"]
end

subgraph group_integrations["External integrations"]
  node_discord_service["Discord adapter<br/>integration service"]
  node_blizzard_service["Blizzard adapter<br/>integration service"]
  node_raidhelper_service["RaidHelper adapter<br/>integration service"]
  node_wcl_service["WCL adapter<br/>integration service"]
end

subgraph group_frontend["Inertia UI"]
  node_inertia_shell["Inertia shell<br/>react app"]
  node_pages["Pages"]
  node_components["UI components<br/>react components"]
  node_layout["Master layout<br/>[Master.jsx]"]
end

subgraph group_data["Schema layer"]
  node_domain_models[("Models")]
  node_migrations["Migrations"]
end

node_routes_web -->|"dispatches"| node_http_controllers
node_http_controllers -->|"validates with"| node_form_requests
node_http_controllers -->|"authorizes via"| node_policies
node_http_controllers -->|"serializes with"| node_api_resources
node_http_controllers -->|"emits"| node_events
node_events -->|"fan out to"| node_listeners
node_listeners -->|"dispatches"| node_jobs
node_commands -->|"kicks off"| node_jobs
node_jobs -->|"updates"| node_domain_models
node_jobs -->|"calls"| node_services_core
node_services_core -->|"adapts"| node_discord_service
node_services_core -->|"adapts"| node_blizzard_service
node_services_core -->|"adapts"| node_raidhelper_service
node_services_core -->|"adapts"| node_wcl_service
node_domain_models -->|"persisted by"| node_migrations
node_http_controllers -->|"reads/writes"| node_domain_models
node_api_resources -->|"maps"| node_domain_models
node_inertia_shell -->|"renders"| node_pages
node_pages -->|"composes"| node_components
node_inertia_shell -->|"wraps with"| node_layout
node_http_controllers -->|"serves"| node_inertia_shell

click node_routes_web "https://github.com/benargo/regrowth-website/blob/main/routes/web.php"
click node_http_controllers "https://github.com/benargo/regrowth-website/tree/main/app/Http/Controllers"
click node_form_requests "https://github.com/benargo/regrowth-website/tree/main/app/Http/Requests"
click node_policies "https://github.com/benargo/regrowth-website/tree/main/app/Policies"
click node_api_resources "https://github.com/benargo/regrowth-website/tree/main/app/Http/Resources"
click node_domain_models "https://github.com/benargo/regrowth-website/tree/main/app/Models"
click node_migrations "https://github.com/benargo/regrowth-website/tree/main/database/migrations"
click node_services_core "https://github.com/benargo/regrowth-website/tree/main/app/Services"
click node_jobs "https://github.com/benargo/regrowth-website/tree/main/app/Jobs"
click node_listeners "https://github.com/benargo/regrowth-website/tree/main/app/Listeners"
click node_events "https://github.com/benargo/regrowth-website/tree/main/app/Events"
click node_commands "https://github.com/benargo/regrowth-website/tree/main/app/Console/Commands"
click node_discord_service "https://github.com/benargo/regrowth-website/tree/main/app/Services/Discord"
click node_blizzard_service "https://github.com/benargo/regrowth-website/tree/main/app/Services/Blizzard"
click node_raidhelper_service "https://github.com/benargo/regrowth-website/tree/main/app/Services/RaidHelper"
click node_wcl_service "https://github.com/benargo/regrowth-website/tree/main/app/Services/WarcraftLogs"
click node_inertia_shell "https://github.com/benargo/regrowth-website/tree/main/resources/js"
click node_pages "https://github.com/benargo/regrowth-website/tree/main/resources/js/Pages"
click node_components "https://github.com/benargo/regrowth-website/tree/main/resources/js/Components"
click node_layout "https://github.com/benargo/regrowth-website/blob/main/resources/js/Layouts/Master.jsx"

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_routes_web,node_http_controllers,node_form_requests,node_policies,node_api_resources,node_services_core,node_jobs,node_listeners,node_events,node_commands toneBlue
class node_discord_service,node_blizzard_service,node_raidhelper_service,node_wcl_service toneAmber
class node_inertia_shell,node_pages,node_components,node_layout toneMint
class node_domain_models,node_migrations toneRose
```

## Components

### Laravel backend

HTTP, domain logic, jobs, events, and persistence

- [Web routes](https://github.com/benargo/regrowth-website/blob/main/routes/web.php): route map · Browser entrypoints and page routing · `routes/web.php`
- [Controllers](https://github.com/benargo/regrowth-website/tree/main/app/Http/Controllers): http controllers · Main request handlers for raiding, loot council, dashboard, roster, auth, and reports · `app/Http/Controllers`
- [Form requests](https://github.com/benargo/regrowth-website/tree/main/app/Http/Requests): validation · Dedicated request validation and input shaping · `app/Http/Requests`
- [Policies](https://github.com/benargo/regrowth-website/tree/main/app/Policies): authorization · Access control for dashboard and domain actions · `app/Policies`
- [API resources](https://github.com/benargo/regrowth-website/tree/main/app/Http/Resources): serialization · Response transformers for characters, raids, reports, loot council, and permissions · `app/Http/Resources`
- [Domain services](https://github.com/benargo/regrowth-website/tree/main/app/Services): application services · Attendance, roster, Blizzard, Discord, RaidHelper, and Warcraft Logs service layers · `app/Services`
- [Jobs](https://github.com/benargo/regrowth-website/tree/main/app/Jobs): async work · Queued sync and import tasks for roster, logs, Discord, and addon exports · `app/Jobs`
- [Listeners](https://github.com/benargo/regrowth-website/tree/main/app/Listeners): events side effects · Cache flushes, follow-up sync, media prefetch, and scheduled exports · `app/Listeners`
- [Domain events](https://github.com/benargo/regrowth-website/tree/main/app/Events): event bus · Write-side signals for character, report, comment, assignment, and guild changes · `app/Events`
- [Console commands](https://github.com/benargo/regrowth-website/tree/main/app/Console/Commands): artisan commands · Operator commands for roster sync, logs refresh, raid helper fetches, and addon export build · `app/Console/Commands`

### External integrations

Service adapters for Blizzard, Discord, RaidHelper, and Warcraft Logs

- [Discord adapter](https://github.com/benargo/regrowth-website/tree/main/app/Services/Discord): integration service · OAuth, guild member/role sync, notifications, and message payloads · `app/Services/Discord`
- [Blizzard adapter](https://github.com/benargo/regrowth-website/tree/main/app/Services/Blizzard): integration service · Battle.net auth, media fetching, and playable class/race normalization · `app/Services/Blizzard`
- [RaidHelper adapter](https://github.com/benargo/regrowth-website/tree/main/app/Services/RaidHelper): integration service · Raid event fetching and composition payload mapping · `app/Services/RaidHelper`
- [WCL adapter](https://github.com/benargo/regrowth-website/tree/main/app/Services/WarcraftLogs): integration service · Warcraft Logs auth, guild tags, reports, and attendance retrieval · `app/Services/WarcraftLogs`

### Inertia UI

React pages and reusable UI shell

- [Inertia shell](https://github.com/benargo/regrowth-website/tree/main/resources/js): react app · Server-driven React entry, layouts, shared components, and permissions hook · `resources/js`
- [Pages](https://github.com/benargo/regrowth-website/tree/main/resources/js/Pages): react pages · UI pages for raiding, loot council, dashboard, roster, quests, and auth · `resources/js/Pages`
- [UI components](https://github.com/benargo/regrowth-website/tree/main/resources/js/Components): react components · Reusable controls, tables, loot widgets, event widgets, and charting pieces · `resources/js/Components`
- [Master layout](https://github.com/benargo/regrowth-website/blob/main/resources/js/Layouts/Master.jsx): layout · Shared application frame and navigation chrome · `resources/js/Layouts/Master.jsx`

### Schema layer

Database models, migrations, and seeders

- [Models](https://github.com/benargo/regrowth-website/tree/main/app/Models): eloquent models · Core domain entities for raids, loot council, roster, permissions, and logs · `app/Models`
- [Migrations](https://github.com/benargo/regrowth-website/tree/main/database/migrations): schema migrations · Database schema for users, characters, raids, reports, loot council, and supporting lookup tables · `database/migrations`

## Connections

- Web routes → Controllers: dispatches · Web routes resolve into Laravel controllers
- Controllers → Form requests: validates with · Controllers delegate validation to form requests
- Controllers → Policies: authorizes via · Domain actions are gated by policies
- Controllers → API resources: serializes with · Responses are shaped before reaching the UI
- Controllers → Domain events: emits · Primary state changes raise domain events
- Domain events → Listeners: fan out to · Listeners handle cache and follow-up side effects
- Listeners → Jobs: dispatches · Listeners can schedule async work
- Console commands → Jobs: kicks off · Console entrypoints often enqueue or run background tasks
- Jobs → Models: updates · Queued work persists synced state and projections
- Jobs → Domain services: calls · Jobs use application services for external data fetches
- Domain services → Discord adapter: adapts · Discord-specific workflows are isolated behind an adapter
- Domain services → Blizzard adapter: adapts · Blizzard data and media are normalized in one place
- Domain services → RaidHelper adapter: adapts · RaidHelper payloads and event sync are encapsulated
- Domain services → WCL adapter: adapts · Warcraft Logs sync and analytics are encapsulated
- Models → Migrations: persisted by · Models are backed by the schema layer
- Controllers → Models: reads/writes · Controllers operate on Eloquent entities
- API resources → Models: maps · Resources transform domain objects into view data
- Inertia shell → Pages: renders · The React shell loads domain pages
- Pages → UI components: composes · Pages reuse shared UI components
- Inertia shell → Master layout: wraps with · Shared layout frames all pages
- Controllers → Inertia shell: serves · Controllers return Inertia responses to the React shell
