Data Flow

Three data categories

BattleScore works best when understood as three connected data categories:

Main flow through the platform

Reference Data
(race / faction / canonical units)
        ↓
Army Construction
(army_lists / army_units)
        ↓
Game Setup
(games / game_sides)
        ↓
Game Runtime
(game_turns / game_player_turns / game_units / game_events)
        ↓
Results / Stats / Standings

Reference data flow

The reference hierarchy begins with race, flows into factions, and then into canonical units documented as faction units.

This reference model is used during:

• manual army creation
• import parsing and matching
• TO entrant-army management
• stats and grouping by race/faction/unit

Army data flow

Armies are where reference data becomes player-specific data.

• army_lists stores the army header
• army_units stores unit rows and flags
• Optional master links preserve connection to canonical units
• Legacy/free-text support is still present in parts of the model

This layer is also where imported text is converted into structured rows.

Gameplay data flow

When a game starts, army-level data is copied into game-level data:

army_units
  ↓ instantiate
game_units
  ↓ events modify meaning/state
game_events

This is a critical design choice. Gameplay does not operate directly on army rows; it operates on instantiated runtime copies so the original army remains unchanged.

Turn and event flow

Gameplay is structured in nested temporal layers:

• game_turns stores the overall turn sequence
• game_player_turns stores per-side actions inside each turn
• game_events stores the scoring/action ledger

State is partly event-driven and partly denormalized onto game_units.

Tournament data flow

Tournament data wraps around the core game model rather than replacing it:

tournaments
  ↓
tournament_entrants
  ↓
tournament_entrant_armies
  ↓
games linked by round / entrant
  ↓
standings

This means tournament standings are ultimately derived from game outcomes plus tournament scoring-system configuration.

Support / diagnostics flow

Not all data exists to drive features directly. Some exists to support operations. For example, import_issues captures evidence when imports fail or partially resolve.

Why this model works well

• Reference data stays reusable
• Player armies remain editable without rewriting gameplay history
• Gameplay uses runtime snapshots, which reduces corruption of original army data
• Tournament logic can sit above core gameplay rather than duplicating it

Main flow risks

• Bad reference data propagates into armies and imports
• Weakly linked army/runtime rows can increase complexity
• Event deletion/replay must keep denormalized unit state consistent
• Tournament reconfiguration can change interpretation of existing games