Component Interactions

How the database, backend endpoints, user interface, TO area and admin layer depend on one another.

Architecture Interactions Cross-Layer

Standard interaction pattern

User action
  ↓
Frontend page / script
  ↓
Shared API helper
  ↓
PHP endpoint
  ↓
Database read/write
  ↓
JSON response
  ↓
Frontend render/update

This is the dominant pattern across both the main App UI and the TO UI.

App ↔ API interaction

The App frontend calls backend endpoints for all meaningful state changes. The UI does not own business truth; it renders and orchestrates. Examples:

Armies calls army CRUD and import endpoints
Game Setup coordinates games, armies and tournament selection
Game Play depends on play-state and event endpoints
Auth pages depend on auth endpoints

TO ↔ API interaction

The TO area uses a similar pattern but calls TO-specific endpoints and some shared army/user/tournament endpoints. The TO surface is effectively a specialised operational client over the same core data model.

Events reads tournament/event records
Event Entrants manages entrant rows and claim flow
Entrant Armies bridges entrant rows to general army tables

Admin ↔ SQL interaction

The Admin area is much closer to the data model. It changes reference data and configuration directly through targeted endpoints. Because of that, admin changes often have wider downstream effects than app/TO changes.

Editing races/factions/units affects army creation and imports
Editing tournaments or scoring affects standings behaviour
Editing users affects identity and access across every surface

SQL ↔ API interaction

The SQL layer defines the real component boundaries. Most API folders map naturally to one or more schema domains:

API area	Main SQL domains touched
auth	users, user_sessions, password_resets, email_verifications
armies / units	army_lists, army_units, units, unit_aliases, import_issues
games / turns / events	games, game_sides, game_turns, game_player_turns, game_units, game_events
tournaments / to	tournaments, tournament_entrants, tournament_entrant_armies, tournament scoring tables
admin	core data, tournaments, users

Cross-cutting interaction hotspots

Some parts of the system are unusually cross-linked and therefore deserve extra care:

Canonical units affect imports, armies, TO, gameplay reporting and admin
Games sit between app UI, SQL runtime state, tournaments and stats
Users affect auth, ownership, TO operations, admin and subscriptions
Tournament scoring systems affect event setup and standings calculations

Interaction style summary

Interaction	Primary style
App → API	Request/response, page-level orchestration
TO → API	Operational workflow orchestration
API → SQL	Validation + write/read orchestration
Admin → SQL via API	High-impact maintenance/configuration
Docs → all	Human-readable system map