Armies feature

Files covered

File	Role
/public_html/app/armies.html	Defines the page layout, visual regions, inputs, panels and action buttons.
/public_html/app/scripts/armies.js	Implements page behaviour, API calls, import logic, selection logic and edit flows.

Purpose

The Armies feature is the primary user-facing area for army management. It allows the authenticated user to:

• view their armies
• import new armies from supported roster formats
• inspect and select an army
• rename or update the selected army
• navigate to the unit-management flow for that army

HTML page structure

Top bar

The page includes the standard user top bar with logo, page title, help link, main navigation links and logout action.

Main layout

The page is structured as a two-panel experience:

• Left side: import workflow and existing army list
• Right side: selected army details and edit actions

Import region

The import region contains the full roster import UX, including:

• format selector
• format hint text
• race selector where required
• faction selector where required
• optional army name override
• scaling factor input
• file upload control
• paste-text input area
• import / clear actions
• message area
• debug panel for unmatched units

Army list region

The left panel also contains the list of existing armies belonging to the current user.

Selected army region

The right panel provides the selected-army editor, including:

• selected army summary
• rename field
• save/update action
• manage units link
• status/error messaging

JavaScript responsibilities

The paired script app/scripts/armies.js acts as the controller for the page and is responsible for:

• enforcing authenticated access
• loading the user’s current armies on startup
• reacting to import-format changes
• loading races and factions when required
• reading uploaded roster files into text
• submitting import requests to backend APIs
• rendering unmatched-unit debug information
• handling army selection
• loading army details into the edit panel
• saving updates to the selected army
• routing to the units page for the selected army

User flow

1. User opens /app/armies.html.
2. Authentication guard runs.
3. Existing armies are loaded and rendered.
4. User chooses an import format or selects an existing army.
5. If importing, the page may load race/faction metadata depending on format.
6. User uploads or pastes roster text.
7. Import is submitted to the relevant backend endpoint.
8. On success, the armies list refreshes.
9. User selects an army.
10. The selected army appears in the right-side editor and can be updated or opened in unit management.

Supported import modes

Mode	Frontend expectation
Old World Builder	Import can proceed without manual race/faction selection.
New Recruit	Frontend requires user-selected race and faction before commit import.
2nd in Command	Frontend requires user-selected race and faction before commit import.

Likely backend dependencies

This feature relies on shared frontend API helpers and calls backend endpoints such as:

• armies/list.php
• armies/get.php
• armies/update.php
• armies/import_oldworldbuilder_text_commit.php
• armies/import_newrecruit_text_commit.php
• armies/import_2ndincommand_text_commit.php
• meta/races_list.php
• meta/factions_list.php

Frontend dependencies

File	Purpose
/app/styles.css	Shared application styling.
/app/app_config.js	Environment-specific frontend configuration.
/app/_api.js	Shared API wrapper, auth handling and request helpers.
/app/scripts/armies.js	Feature controller for the page.

Maintenance notes

• Keep HTML and JavaScript changes aligned — this feature should be treated as one unit.
• When adding new DOM ids or buttons in the page, document the corresponding JS behaviour here.
• When changing backend import contracts, update both the API docs and this UX feature doc.
• The debug panel is important and should not be silently removed without replacement troubleshooting support.