# vervelak/lastwar-alliance-manager architecture

> Architecture diagram of the GitHub repository vervelak/lastwar-alliance-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vervelak/lastwar-alliance-manager
- Repository: https://github.com/vervelak/lastwar-alliance-manager

## Overview

#### Purpose and Entry Points
Last War Alliance Manager is a local/self-hosted Go application for alliance operations in *Last War: Survival*: membership, role-controlled administration, scheduling, rankings, awards, VS/storm tracking, and OCR-assisted screenshot ingestion. The server entry point and API/router implementation are centralized in `main.go`; OCR-specific logic is separated in `mg_ocr.go`. The browser UI is static vanilla JavaScript served by the Go process, beginning with `static/login.html` and `static/index.html`.

#### Backend and Persistence
`main.go` owns application bootstrap, SQLite schema/initialization, HTTP routes, authorization middleware, business operations, and static-file serving. SQLite is the sole durable store, located through `DATABASE_PATH` and persisted as a host-mounted `./data/alliance.db` in Compose deployments. Authentication uses bcrypt password hashes and Gorilla signed-cookie sessions, with `SESSION_KEY` determining session continuity.

#### Identity and Authorization Boundary
Users may be standalone admins or linked to alliance members, inheriting member rank permissions. Backend API handlers enforce role boundaries: Admin/R5 settings and account management; R4/R5 member and schedule changes; R3+ screenshot/upload workflows; lower ranks read-only. The frontend uses shared session/navigation behavior in `static/common.js` and `static/navigation.js`, but backend enforcement in `main.go` is the security boundary.

#### Alliance Operations Domain
The main operational model centers on members, ranks, schedules, awards, recommendations, rankings, conduct reports, deleted-member history, and event-specific tracking. Member management is driven from `static/index.html` / `static/app.js`; scheduling from `static/train.html` / `static/train.js`; configurable scoring and templates from `static/settings.html` / `static/settings.js`. These pages call protected JSON APIs exposed by `main.go`, which calculate and persist results in SQLite.

#### Ranking, Scheduling, and Messaging Flow
Awards, recommendations, rank bonuses, first-time boosts, and historical conductor penalties feed server-side performance ranking. Auto-scheduling selects weekly conductors and eligible R4/R5 backups, then persisted schedule entries drive generated weekly and daily alliance-chat messages. The primary UI consumers are `static/rankings.js`, `static/train.js`, and `static/awards.js`; authoritative calculations and message generation remain in `main.go`.

#### Screenshot Recognition Pipeline
Mobile-oriented uploads and manual entry originate in `static/upload.html` / `static/upload.js`, with adjacent VS workflows in `static/vs.html` / `static/vs.js`. Requests cross into Go OCR processing in `mg_ocr.go`, which uses Tesseract and image preprocessing/parsing to extract game data, fuzzy-match members, and store power or VS history. Marshal Guard image segmentation is independently deployable as `mg_segment/main.go`, with its own container definition at `mg_segment/Dockerfile`.

#### Runtime and Deployment
The primary runtime is Go 1.23 with SQLite and Tesseract/gosseract; OCR requires CGO plus native Tesseract libraries outside the supplied container. `Dockerfile` provides the application image, while `docker-compose.yml` runs it with persistent database storage. Production can sit behind Caddy via `Caddyfile`, or run as a systemd service using `lastwar.service`. Browser automation is external Playwright infrastructure under `playwright-tests/`.

Main entry points: [`main.go`](https://github.com/vervelak/lastwar-alliance-manager/blob/main/main.go) (HTTP API and router), [`mg_ocr.go`](https://github.com/vervelak/lastwar-alliance-manager/blob/main/mg_ocr.go) (OCR extraction and matching), [`docker-compose.yml`](https://github.com/vervelak/lastwar-alliance-manager/blob/main/docker-compose.yml) (Compose deployment), [`Dockerfile`](https://github.com/vervelak/lastwar-alliance-manager/blob/main/Dockerfile) (Application container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser UI"]
  node_member_ui["Member operations<br/>vanilla JS page<br/>[index.html]"]
  node_schedule_ui["Schedule UI<br/>vanilla JS page<br/>[train.html]"]
  node_ranking_ui["Rankings and awards UI<br/>vanilla JS<br/>[rankings.js]"]
  node_settings_ui["Settings UI<br/>vanilla JS page<br/>[settings.html]"]
  node_upload_ui["Screenshot upload UI<br/>vanilla JS page<br/>[upload.html]"]
  node_vs_ui["VS workflow UI<br/>vanilla JS page<br/>[vs.html]"]
  node_session_ui["Session navigation<br/>shared browser JS<br/>[common.js]"]
end

subgraph group_backend["Go application"]
  node_http_api["HTTP API and router<br/>Go server<br/>[main.go]"]
  node_authz["Session and authorization<br/>Go middleware<br/>[main.go]"]
  node_operations["Alliance operations<br/>Go domain logic<br/>[main.go]"]
  node_sqlite[("Alliance database<br/>SQLite")]
end

subgraph group_ocr["Recognition pipeline"]
  node_ocr_processor["OCR extraction and matching<br/>Go OCR<br/>[mg_ocr.go]"]
  node_tesseract{{"Tesseract native OCR<br/>native dependency"}}
  node_mg_segment["Marshal Guard segmentation<br/>independent Go service<br/>[main.go]"]
end

subgraph group_runtime["Deployment"]
  node_app_image["Application container<br/>Docker image"]
  node_compose["Compose deployment<br/>Docker Compose<br/>[docker-compose.yml]"]
  node_caddy["Reverse proxy<br/>Caddy"]
  node_playwright["Browser automation<br/>external Playwright"]
end

node_member_ui -->|"protected JSON API"| node_http_api
node_schedule_ui -->|"protected JSON API"| node_http_api
node_ranking_ui -->|"read rankings"| node_http_api
node_settings_ui -->|"admin API"| node_http_api
node_upload_ui -->|"upload and manual entry"| node_http_api
node_vs_ui -->|"VS API"| node_http_api
node_session_ui -->|"session requests"| node_http_api
node_http_api -->|"authorizes requests"| node_authz
node_authz -->|"permits role-scoped actions"| node_operations
node_http_api -->|"routes operations"| node_operations
node_operations -->|"persists operational data"| node_sqlite
node_http_api -->|"screenshot processing"| node_ocr_processor
node_ocr_processor -->|"recognizes text"| node_tesseract
node_ocr_processor -->|"stores power and VS history"| node_sqlite
node_mg_segment -.->|"segmented images"| node_ocr_processor
node_app_image -->|"runs"| node_http_api
node_compose -->|"deploys"| node_app_image
node_compose -->|"mounts data volume"| node_sqlite
node_caddy -->|"proxies requests"| node_http_api
node_playwright -.->|"automates browser flows"| node_http_api

click node_member_ui "https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/index.html"
click node_schedule_ui "https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/train.html"
click node_ranking_ui "https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/rankings.js"
click node_settings_ui "https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/settings.html"
click node_upload_ui "https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/upload.html"
click node_vs_ui "https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/vs.html"
click node_session_ui "https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/common.js"
click node_http_api "https://github.com/vervelak/lastwar-alliance-manager/blob/main/main.go"
click node_authz "https://github.com/vervelak/lastwar-alliance-manager/blob/main/main.go"
click node_operations "https://github.com/vervelak/lastwar-alliance-manager/blob/main/main.go"
click node_ocr_processor "https://github.com/vervelak/lastwar-alliance-manager/blob/main/mg_ocr.go"
click node_mg_segment "https://github.com/vervelak/lastwar-alliance-manager/blob/main/mg_segment/main.go"
click node_app_image "https://github.com/vervelak/lastwar-alliance-manager/blob/main/Dockerfile"
click node_compose "https://github.com/vervelak/lastwar-alliance-manager/blob/main/docker-compose.yml"
click node_caddy "https://github.com/vervelak/lastwar-alliance-manager/blob/main/Caddyfile"

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_member_ui,node_schedule_ui,node_ranking_ui,node_settings_ui,node_upload_ui,node_vs_ui,node_session_ui toneBlue
class node_http_api,node_authz,node_operations,node_sqlite toneAmber
class node_ocr_processor,node_tesseract,node_mg_segment toneMint
class node_app_image,node_compose,node_caddy,node_playwright toneRose
```

## Components

### Browser UI

- [Member operations](https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/index.html): vanilla JS page · Membership and role administration UI. · `static/index.html`
- [Schedule UI](https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/train.html): vanilla JS page · `static/train.html`
- [Rankings and awards UI](https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/rankings.js): vanilla JS · `static/rankings.js`
- [Settings UI](https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/settings.html): vanilla JS page · Scoring and template configuration. · `static/settings.html`
- [Screenshot upload UI](https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/upload.html): vanilla JS page · `static/upload.html`
- [VS workflow UI](https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/vs.html): vanilla JS page · `static/vs.html`
- [Session navigation](https://github.com/vervelak/lastwar-alliance-manager/blob/main/static/common.js): shared browser JS · `static/common.js`

### Go application

- [HTTP API and router](https://github.com/vervelak/lastwar-alliance-manager/blob/main/main.go): Go server · Serves static UI and protected JSON APIs. · `main.go`
- [Session and authorization](https://github.com/vervelak/lastwar-alliance-manager/blob/main/main.go): Go middleware · Backend role enforcement is the security boundary. · `main.go`
- [Alliance operations](https://github.com/vervelak/lastwar-alliance-manager/blob/main/main.go): Go domain logic · Members, ranks, schedules, awards, rankings, and messages. · `main.go`
- **Alliance database**: SQLite · Sole durable store for operational and history data.

### Recognition pipeline

- [OCR extraction and matching](https://github.com/vervelak/lastwar-alliance-manager/blob/main/mg_ocr.go): Go OCR · Preprocesses images, parses game data, and fuzzy-matches members. · `mg_ocr.go`
- **Tesseract native OCR**: native dependency · Used through CGO and gosseract.
- [Marshal Guard segmentation](https://github.com/vervelak/lastwar-alliance-manager/blob/main/mg_segment/main.go): independent Go service · Independently deployable image segmentation stage. · `mg_segment/main.go`

### Deployment

- [Application container](https://github.com/vervelak/lastwar-alliance-manager/blob/main/Dockerfile): Docker image · Go 1.23 application runtime. · `Dockerfile`
- [Compose deployment](https://github.com/vervelak/lastwar-alliance-manager/blob/main/docker-compose.yml): Docker Compose · Mounts persistent database storage. · `docker-compose.yml`
- [Reverse proxy](https://github.com/vervelak/lastwar-alliance-manager/blob/main/Caddyfile): Caddy · Optional production proxy. · `Caddyfile`
- **Browser automation**: external Playwright · External browser automation infrastructure.

## Connections

- Member operations → HTTP API and router: protected JSON API
- Schedule UI → HTTP API and router: protected JSON API
- Rankings and awards UI → HTTP API and router: read rankings
- Settings UI → HTTP API and router: admin API
- Screenshot upload UI → HTTP API and router: upload and manual entry
- VS workflow UI → HTTP API and router: VS API
- Session navigation → HTTP API and router: session requests
- HTTP API and router → Session and authorization: authorizes requests
- Session and authorization → Alliance operations: permits role-scoped actions
- HTTP API and router → Alliance operations: routes operations
- Alliance operations → Alliance database: persists operational data
- HTTP API and router → OCR extraction and matching: screenshot processing
- OCR extraction and matching → Tesseract native OCR: recognizes text
- OCR extraction and matching → Alliance database: stores power and VS history
- Marshal Guard segmentation → OCR extraction and matching: segmented images
- Application container → HTTP API and router: runs
- Compose deployment → Application container: deploys
- Compose deployment → Alliance database: mounts data volume
- Reverse proxy → HTTP API and router: proxies requests
- Browser automation → HTTP API and router: automates browser flows