API Documentation

Documentation for the BattleScore backend API, shared infrastructure, and endpoint groups.
API Backend Endpoint Driven
/public_html/api/

The BattleScore API is the backend surface that supports the main app, tournament organiser functionality, authentication, gameplay, scoring, army management, and supporting administrative operations. It is organised as a file-based endpoint layer with shared bootstrap and authentication utilities.

Overview

This documentation section covers the current API areas that support:

  • runtime/bootstrap infrastructure
  • authentication and session/token flows
  • user and profile operations
  • army, unit, and import management
  • game setup, play-state, and scoring flows
  • tournament and entrant operations
  • admin and maintenance utilities

Current architecture

Shared Infrastructure
├── _bootstrap.php
├── _auth.php
├── _mail.php
└── shared support utilities

Authentication
├── auth/login.php
├── auth/signup.php
├── auth/logout.php
├── auth/me.php
├── auth/verify.php
├── auth/forgot.php
└── auth/reset.php

App Domain Areas
├── armies/...
├── units/...
├── imports/...
├── games/...
├── tournaments/...
└── profile/...

Operational / Restricted Areas
└── admin/...

API categories

Category Description Examples
Infrastructure Shared runtime, configuration, auth, and support services used by endpoint groups _bootstrap, _auth, _mail
Authentication Handles account access, verification, password reset, and current-user identity auth/login, auth/signup, auth/me
Gameplay Supports game creation, turn flow, play state, event capture, and scoring games, scores, play_state, finalise
Armies & Units Manages army lists, unit records, imports, and related reference logic armies, units, imports
Tournaments Supports tournament setup, entrants, linking, and event-specific flows tournaments, entrants, claim flows
Admin Restricted maintenance and data-management endpoints for operational control admin/races, admin/factions, admin/users

Functional model

Client UI
├── App pages
├── TO pages
└── Future admin UI

        │
        ▼

BattleScore API
├── Shared infrastructure
├── Auth endpoints
├── Domain endpoints
└── Restricted/admin endpoints

        │
        ▼

Database
└── Core BattleScore data model

The API acts as the central integration layer between frontend pages and the underlying BattleScore data model.

Key characteristics

  • file-based PHP endpoint architecture
  • shared bootstrap and auth patterns across endpoint groups
  • supports both user-facing and organiser-facing functionality
  • mix of public, authenticated, and restricted operational surfaces
  • well-suited to incremental expansion without requiring a full framework rewrite

Current risks

  • inconsistent separation between standard authenticated surfaces and restricted operational ones
  • limited auditability for high-impact write operations
  • some lifecycle behaviours are still evolving across entities
  • multiple endpoint groups depend on shared response and auth conventions, increasing change sensitivity

Recommended next steps

  • formalise API area boundaries between app, TO, and admin concerns
  • add stronger role and permission enforcement where needed
  • expand audit logging for sensitive write operations
  • continue documenting endpoint contracts and shared conventions consistently

How to use this documentation

  • start with shared infrastructure and authentication conventions
  • then review the endpoint group relevant to the feature area you are changing
  • check request/response expectations before altering existing endpoints
  • treat write and restricted endpoints as high-impact operational surfaces