Solution Components

1. Database layer

The database is the authoritative source of truth for the platform. It does more than just store data: it encodes the major domain boundaries and some of the critical business rules of the solution.

What it owns

• Identity and access records
• Reference data for races, factions, canonical units and aliases
• User armies and units
• Gameplay state, turns, events and final scores
• Tournament structures, entrants, army links and scoring systems
• Operational support data such as import diagnostics

Why it matters

Every other layer is built on the structure defined here. When the schema changes, the API, UI, TO and admin layers usually need to change with it.

2. API layer

The API is implemented as a file-per-endpoint PHP layer. It is the main location for validation, business rules, and transaction coordination.

What it owns

• Authentication and session lifecycle
• Validation of request payloads and ownership
• CRUD operations over armies, units, games, tournaments and users
• Import parsing and commit logic
• Gameplay event creation, deletion and scoring logic

How it is structured

• auth – signup/login/verification/reset
• armies – army CRUD and imports
• games – game lifecycle and play state
• events – gameplay event creation/deletion
• tournaments – standings, rounds, claims
• to – TO-owned workflows

3. App frontend

The App frontend is the normal user-facing surface. It is responsible for presenting gameplay, armies, performance and account operations in a browser-friendly way.

Key page groups

• Armies / Units
• Games / Game Setup / Game Play
• Tournaments / Stats / Performance
• Profile and auth pages

What it does well

• Presents complex game state in a usable way
• Splits most features by page/responsibility
• Uses shared API helpers rather than ad hoc fetch logic on every page

4. TO frontend

The TO area is a distinct operational frontend for tournament organisers. It shares auth and backend services with the main app but is organised around event workflow rather than player workflow.

Main TO flow

Events
 └── Event Edit
 └── Entrants
      └── Entrant Armies

Why TO exists separately

• Tournament operations have different priorities than normal player usage
• Entrant/claim/army-linking flows are operational, not gameplay-first
• It keeps organiser workflow complexity out of the main user UI

5. Admin layer

The Admin area is currently backend-heavy rather than UI-heavy. It manages reference data, configuration, and identity-sensitive operations.

Main admin categories

• Infrastructure: bootstrap/auth/login
• Core data: races, factions, faction units
• Configuration: tournaments
• Identity: users

Why it matters

Admin edits can have a large blast radius because they often modify root reference data or high-impact configuration. This is one of the reasons why the admin docs emphasise risk classification.

6. Documentation system

The docs site is now a real subsystem in its own right. It provides a shared shell, navigation, and structured pages for SQL, API, App, TO, Admin and Reference.

This has two practical outcomes:

• new developers can understand the system faster
• future changes can be made with lower risk because cross-area impacts are easier to see

Component ownership summary