# paughton/warfrontnations architecture

> Architecture diagram of the GitHub repository paughton/warfrontnations, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paughton/warfrontnations
- Repository: https://github.com/paughton/warfrontnations

## Overview

1. **Overall shape**
Warfront Nations is a single PHP/MySQL monolith for a browser-based nation simulation game. The architecture is page-driven rather than service-oriented: each top-level `.php` file corresponds to a screen or action, and state is persisted in MySQL. There is no separate API layer or frontend build system.

2. **Request/response flow**
A browser request typically lands on a PHP page such as `index.php`, `nation.php`, `city.php`, `trade.php`, or `battle.php`. Those pages render server-side HTML, usually by pulling in shared layout files from `system/` and querying/updating the database directly. User actions are handled by dedicated action pages like `createcity.php`, `createalliance.php`, `createtrade.php`, `confirmbattle.php`, and `editcity.php`.

3. **Shared application shell**
The `system/` directory contains the common UI and configuration boundary: `config.php` for database and app settings, plus `header.php`, `footer.php`, and `navigation.php` for the shared page frame. This is the main composition layer used across the site, so most pages likely include these files to stay consistent.

4. **Authentication and player lifecycle**
`register.php`, `login.php`, and `logout.php` form the account/auth boundary. `account.php` and `edit.php` suggest profile and player settings management. `redirect.php` likely handles post-login or action forwarding. Sessions are implied by the game flow, with the database storing persistent player state.

5. **Core game domains**
The main gameplay subsystems are represented directly by page names: nations, cities, alliances, military, trade, battles, flags, inbox, notifications, and world views. This is a classic simulation-game structure where each domain is a separate screen with its own CRUD-like operations and game mechanics.

6. **World and entity management**
`world.php`, `nation.php`, `city.php`, `cities.php`, and `editcity.php` suggest the core entity hierarchy is nation-centric, with cities as subordinate assets. `createcity.php` likely instantiates new cities, while `flag.php` handles nation identity/customization. These pages probably read from and write to related rows in the MySQL schema.

7. **Conflict and diplomacy**
`battle.php` and `confirmbattle.php` define the combat flow, likely involving a preview/confirmation step before committing battle results. `alliance.php`, `alliances.php`, and `createalliance.php` cover diplomatic grouping. `trade.php` and `createtrade.php` model non-combat interactions, so the game’s state changes are driven by a mix of war, commerce, and alliance actions.

8. **Messaging and notifications**
`inbox.php` and `notification.php` form the communication layer for player-to-player or system alerts. These pages are likely fed by database-backed message/notification tables and used to surface battle outcomes, trade events, alliance activity, and other asynchronous game events.

9. **Scheduled backend jobs**
The `cronjobs/` directory is the non-interactive backend subsystem. `cron_turn.php`, `cron_daily.php`, and `cron_score.php` indicate time-based game processing such as resource ticks, daily resets, and ranking/score recalculation. The presence of log files in `logs_turn`, `logs_daily`, and `logs_score` shows these jobs are operationally important and were tracked independently of web requests.

10. **Data model boundary**
`warfrontnations.sql` is the schema seed for the entire game state. This is the authoritative backend contract for players, cities, nations, alliances, trades, battles, messages, and scheduled job data. Because the application is hard-coded and early-stage, the database schema is likely tightly coupled to the PHP pages.

11. **Static assets and presentation**
`assets/` contains the full client-side presentation stack: Bootstrap for layout/components, jQuery for interactivity, Font Awesome for icons, plus custom `style.css` and `script.js`. The `assets/art/` folders hold game-specific imagery such as buildings and flags, which are part of the game UI rather than just decoration.

12. **Deployment/runtime assumptions**
The repository is meant to run as a traditional PHP site on a web server with MySQL. `.htaccess` suggests Apache-specific routing or access behavior, and the README explicitly calls out updating credentials in `system/config.php`. There are no signs of containers, background workers, or third-party services beyond the bundled frontend libraries and the database.

13. **How to diagram it**
A good architecture diagram would show: browser requests entering the PHP web app; shared layout/config files feeding all pages; MySQL as the central persistence layer; cron jobs modifying game state on a schedule; and static assets served alongside the app for rendering. The dominant boundary is between user-facing page scripts and the shared database-backed game state.

Main entry points: [`system/header.php`](https://github.com/paughton/warfrontnations/blob/main/system/header.php) (Shell), [`warfrontnations.sql`](https://github.com/paughton/warfrontnations/blob/main/warfrontnations.sql) (Schema), [`city.php`](https://github.com/paughton/warfrontnations/blob/main/city.php) (City), [`index.php`](https://github.com/paughton/warfrontnations/blob/main/index.php) (Home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser<br/>client"))
end

subgraph group_web["Web App"]
  node_index["Home<br/>screen<br/>[index.php]"]
  node_auth["Auth<br/>account flow<br/>[login.php]"]
  node_profile["Profile<br/>player settings<br/>[account.php]"]
  node_world["World<br/>overview screen<br/>[world.php]"]
  node_nation["Nation<br/>core entity screen<br/>[nation.php]"]
  node_city["City<br/>core entity screen<br/>[city.php]"]
  node_diplomacy["Diplomacy<br/>alliance system<br/>[alliance.php]"]
  node_combat["Combat<br/>battle flow<br/>[battle.php]"]
  node_trade["Trade<br/>commerce system<br/>[trade.php]"]
  node_comms["Inbox<br/>messages<br/>[inbox.php]"]
  node_military["Military<br/>forces screen<br/>[military.php]"]
end

subgraph group_shared["Shared Shell"]
  node_shell["Shell<br/>shared layout<br/>[header.php]"]
  node_config["Config<br/>[config.php]"]
end

subgraph group_backend["Backend Jobs"]
  node_cron["Cron<br/>scheduled jobs<br/>[cron_turn.php]"]
end

subgraph group_storage["Data Layer"]
  node_schema[("Schema")]
end

subgraph group_assets["Assets"]
  node_assets_core["Assets<br/>static ui<br/>[style.css]"]
  node_art["Game Art<br/>image assets"]
end

node_browser -->|"opens"| node_index
node_browser -->|"auth"| node_auth
node_browser -->|"manages"| node_profile
node_browser -->|"views"| node_world
node_browser -->|"plays"| node_nation
node_browser -->|"manages"| node_city
node_browser -->|"coordinates"| node_diplomacy
node_browser -->|"initiates"| node_combat
node_browser -->|"trades"| node_trade
node_browser -->|"reads"| node_comms
node_browser -->|"controls"| node_military
node_index -->|"includes"| node_shell
node_auth -->|"includes"| node_shell
node_profile -->|"includes"| node_shell
node_world -->|"includes"| node_shell
node_nation -->|"includes"| node_shell
node_city -->|"includes"| node_shell
node_diplomacy -->|"includes"| node_shell
node_combat -->|"includes"| node_shell
node_trade -->|"includes"| node_shell
node_comms -->|"includes"| node_shell
node_military -->|"includes"| node_shell
node_shell -->|"loads"| node_config
node_nation -->|"reads/writes"| node_schema
node_city -->|"reads/writes"| node_schema
node_diplomacy -->|"reads/writes"| node_schema
node_combat -->|"reads/writes"| node_schema
node_trade -->|"reads/writes"| node_schema
node_comms -->|"reads/writes"| node_schema
node_cron -->|"updates"| node_schema
node_cron -.->|"reuses"| node_shell
node_index -->|"renders with"| node_assets_core
node_world -->|"renders with"| node_assets_core
node_city -->|"renders with"| node_assets_core
node_shell -->|"serves"| node_art

click node_index "https://github.com/paughton/warfrontnations/blob/main/index.php"
click node_auth "https://github.com/paughton/warfrontnations/blob/main/login.php"
click node_profile "https://github.com/paughton/warfrontnations/blob/main/account.php"
click node_world "https://github.com/paughton/warfrontnations/blob/main/world.php"
click node_nation "https://github.com/paughton/warfrontnations/blob/main/nation.php"
click node_city "https://github.com/paughton/warfrontnations/blob/main/city.php"
click node_diplomacy "https://github.com/paughton/warfrontnations/blob/main/alliance.php"
click node_combat "https://github.com/paughton/warfrontnations/blob/main/battle.php"
click node_trade "https://github.com/paughton/warfrontnations/blob/main/trade.php"
click node_comms "https://github.com/paughton/warfrontnations/blob/main/inbox.php"
click node_military "https://github.com/paughton/warfrontnations/blob/main/military.php"
click node_shell "https://github.com/paughton/warfrontnations/blob/main/system/header.php"
click node_config "https://github.com/paughton/warfrontnations/blob/main/system/config.php"
click node_cron "https://github.com/paughton/warfrontnations/blob/main/cronjobs/cron_turn.php"
click node_schema "https://github.com/paughton/warfrontnations/blob/main/warfrontnations.sql"
click node_assets_core "https://github.com/paughton/warfrontnations/blob/main/assets/style.css"
click node_art "https://github.com/paughton/warfrontnations/tree/main/assets/art"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser toneBlue
class node_index,node_auth,node_profile,node_world,node_nation,node_city,node_diplomacy,node_combat,node_trade,node_comms,node_military toneAmber
class node_shell,node_config toneMint
class node_cron toneRose
class node_schema toneIndigo
class node_assets_core,node_art toneTeal
```

## Components

### Client

Browser entry points and rendered UI

- **Browser**: client · Player-facing HTTP entry point

### Web App

Page-driven PHP game screens and actions

- [Home](https://github.com/paughton/warfrontnations/blob/main/index.php): screen · Landing and main entry page · `index.php`
- [Auth](https://github.com/paughton/warfrontnations/blob/main/login.php): account flow · Register, login, logout · `login.php`
- [Profile](https://github.com/paughton/warfrontnations/blob/main/account.php): player settings · Account and profile editing · `account.php`
- [World](https://github.com/paughton/warfrontnations/blob/main/world.php): overview screen · Global map and game overview · `world.php`
- [Nation](https://github.com/paughton/warfrontnations/blob/main/nation.php): core entity screen · Nation state and identity · `nation.php`
- [City](https://github.com/paughton/warfrontnations/blob/main/city.php): core entity screen · City management and details · `city.php`
- [Diplomacy](https://github.com/paughton/warfrontnations/blob/main/alliance.php): alliance system · Alliances and coalition management · `alliance.php`
- [Combat](https://github.com/paughton/warfrontnations/blob/main/battle.php): battle flow · Battle preview and resolution · `battle.php`
- [Trade](https://github.com/paughton/warfrontnations/blob/main/trade.php): commerce system · Player trading and offers · `trade.php`
- [Inbox](https://github.com/paughton/warfrontnations/blob/main/inbox.php): messages · Messages and notifications · `inbox.php`
- [Military](https://github.com/paughton/warfrontnations/blob/main/military.php): forces screen · Army and war-related management · `military.php`

### Shared Shell

Common config and page frame included across screens

- [Shell](https://github.com/paughton/warfrontnations/blob/main/system/header.php): shared layout · Common header, footer, navigation, and config · `system/header.php`
- [Config](https://github.com/paughton/warfrontnations/blob/main/system/config.php): app config · Database and application settings · `system/config.php`

### Backend Jobs

Scheduled game processing and logs

- [Cron](https://github.com/paughton/warfrontnations/blob/main/cronjobs/cron_turn.php): scheduled jobs · Turn, daily, and score processing · `cronjobs/cron_turn.php`

### Data Layer

MySQL schema and persistent game state

- [Schema](https://github.com/paughton/warfrontnations/blob/main/warfrontnations.sql): mysql schema · Authoritative game database definition · `warfrontnations.sql`

### Assets

Static presentation resources and game art

- [Assets](https://github.com/paughton/warfrontnations/blob/main/assets/style.css): static ui · Styles, scripts, Bootstrap, and icons · `assets/style.css`
- [Game Art](https://github.com/paughton/warfrontnations/tree/main/assets/art): image assets · Buildings and flag artwork · `assets/art`

## Connections

- Browser → Home: opens · Primary landing request
- Browser → Auth: auth · Login and registration entry points
- Browser → Profile: manages · Account settings and profile edits
- Browser → World: views · Global game overview
- Browser → Nation: plays · Nation-centric gameplay screen
- Browser → City: manages · City management screens
- Browser → Diplomacy: coordinates · Alliance and diplomacy screens
- Browser → Combat: initiates · Battle flow entry points
- Browser → Trade: trades · Commerce interactions
- Browser → Inbox: reads · Messages and alerts
- Browser → Military: controls · Military management
- Home → Shell: includes · Shared page frame and config
- Auth → Shell: includes · Uses shared layout and settings
- Profile → Shell: includes · Uses shared layout and settings
- World → Shell: includes · Uses shared layout and settings
- Nation → Shell: includes · Uses shared layout and settings
- City → Shell: includes · Uses shared layout and settings
- Diplomacy → Shell: includes · Uses shared layout and settings
- Combat → Shell: includes · Uses shared layout and settings
- Trade → Shell: includes · Uses shared layout and settings
- Inbox → Shell: includes · Uses shared layout and settings
- Military → Shell: includes · Uses shared layout and settings
- Shell → Config: loads · Database and site configuration
- Nation → Schema: reads/writes · Persistent nation and city state
- City → Schema: reads/writes · Persistent city state
- Diplomacy → Schema: reads/writes · Alliance state and membership
- Combat → Schema: reads/writes · Battle outcomes and combat state
- Trade → Schema: reads/writes · Trade offers and transactions
- Inbox → Schema: reads/writes · Messages and notifications
- Cron → Schema: updates · Scheduled state progression and scoring
- Cron → Shell: reuses · Shared configuration for background processing
- Home → Assets: renders with · Shared frontend libraries and custom UI
- World → Assets: renders with · Shared frontend libraries and custom UI
- City → Assets: renders with · Shared frontend libraries and custom UI
- Shell → Game Art: serves · Game imagery used by the UI
