polaris-task-force/README.md

# Polaris Task Force

Web operations and administration hub for the Arma 3 unit Polaris Task Force. Dark-themed dashboard built with Next.js, Payload CMS, and PostgreSQL.

## Tech stack

- **Framework**: Next.js 16 (App Router, webpack)
- **CMS / Admin**: Payload CMS 3.88.0 (`@payloadcms/db-postgres` + Drizzle)
- **Database**: PostgreSQL
- **Styling**: Tailwind CSS v4 (CSS-based, no config file) + shadcn/ui (New York style)
- **Package manager**: Bun (`bun.lock`, `bunfig.toml`). The package.json scripts use cross-env and reference pnpm — run everything via `bun run`.

## Features

- Unit roster with org chart, ranks, assignments, and qualifications
- Missions, campaigns, and factions with intel gating by assignment
- Logistics: structures with storage grids and whitelist rules, resources, vehicles, shipments with distance and fuel tracking, automated game tick
- Banking system: personal and treasury/faction accounts with full transaction ledger
- Trading marketplace with NPC vendors, haggling negotiations, patience meters, and buyer-to-seller offers
- Player lockers with loadouts, equipment, and wardrobe
- Profiles with rank progression, XP, awards, and qualifications
- In-app notification inbox (market offers, deal outcomes)
- Real-time event log tied to structures and game entities, SSE updates from game ticks
- Narrative event flowchart editor (React Flow) for GMs
- Full Payload admin panel for content and configuration management

## Quickstart

1. `bun install`
2. `cp .env.example .env`
3. **Edit `.env`**: the `DATABASE_URI` line in `.env.example` is outdated (MongoDB). Replace it with a PostgreSQL connection string:
   ```
   DATABASE_URI=postgres://user:password@localhost:5432/your_database
   ```
   Set `PAYLOAD_SECRET`, `APP_URL` (default `http://localhost:3000`), and `GAME_TICK_NOTIFY_SECRET`.
4. `bun run dev` — starts the dev server at `http://localhost:3000`.
   - Use `bun run devsafe` to wipe the `.next` cache before starting.

Dev credentials: `dev` / `Test123` (if seed data has been applied).

## Commands

| Command | Description |
|---|---|
| `bun run dev` | Dev server (webpack, localhost:3000) |
| `bun run devsafe` | Clear `.next` cache then start dev |
| `bun run devturbo` | Dev server with Turbopack |
| `bun run build` | Production build (webpack, increases memory limit) |
| `bun run start` | Run the production build |
| `bun run staging` | Start with `NODE_ENV=test` |
| `bun run test` | Run integration tests then E2E tests |
| `bun run test:int` | Vitest integration tests (requires live PostgreSQL) |
| `bun run test:e2e` | Playwright E2E tests (auto-starts dev server) |
| `bun run db` | Drizzle-kit wrapper (e.g. `bun run db migrate`) |
| `bun run generate:types` | Regenerate `payload-types.ts` |
| `bun run generate:importmap` | Regenerate admin import map |
| `bun run payload <bin>` | Run Payload binaries |
| `bun run payload game-tick` | Process shipment arrivals and fuel consumption |
| `bun run payload market-tick` | Expire listings and refresh NPC vendor stock |
| `bun run payload mission-tick` | Auto-complete missions whose scheduled day has passed |
| `bun run payload server-tick` | Mark game servers without a recent heartbeat offline |
| `bun run deploy` | Bump patch version and build; push to deploy via Coolify |
| `bun run version:bump -- --base <sha> --head <sha>` | Choose and apply a patch/minor bump from a git range |

Note: `game-tick` and `market-tick` are Payload bins registered in `payload.config.ts`, not npm scripts. Run via `bun run payload`.

All five bin scripts also log to daily files under `logs/<bin-key>/` (e.g. `logs/game-tick/2026-08-24.log`) so tick output can be tracked over time. Override the directory with the `BIN_LOG_DIR` env var.

For an Arma 3 unit deployment we self-host on **Coolify** with one container per environment (dev / stg / prod), a Coolify-managed PostgreSQL service per environment, a persistent volume for `/app/media`, and `docker exec` scheduled jobs for the game tick. The Dockerfile is Bun-based (multi-stage, Next.js standalone runtime + Payload CLI kept at runtime), and `docker-compose.yml` mirrors the same shape for local full-stack dev.

### CI version bumps

Run `bun run version:bump -- --base "$CI_PREVIOUS_SHA" --head "$CI_SHA"` before the production build. The script bumps minor for product changes under `src/app`, `src/components/frontend`, `src/lib`, `src/collections`, `src/bot`, `src/hooks`, `src/migrations`, or `src/utils`, and patch for other deployable changes. Use `--dry-run` to inspect the decision. Commit the changed `package.json` back to the deployment branch (for example, with a `[skip ci]` commit if your CI provider supports it); the existing `generate:version-info` build step will publish the new version to the app.

For the full setup — per-env Postgres provisioning, env vars, scheduled jobs, persistent media volume, SSE single-instance caveat, rollbacks, troubleshooting — see **[DEPLOYMENT.md](./DEPLOYMENT.md)**.

## Project structure

- `src/app/(frontend)/` — public-facing app pages (dashboard, logistics, banking, market)
- `src/app/(payload)/` — Payload admin panel and API routes
- `src/collections/` — Payload collections organized by domain (users, logistics, banking, market, game, etc.)
- `src/lib/` — shared utilities (storage rules, banking, shipping, market logic, realtime bus)
- `src/components/frontend/` — app UI components
- `src/components/ui/` — shadcn/ui primitives
- `src/tools/seed/` — seed scripts for initial data
- `src/scripts/` — game tick and utility scripts
- `tests/int/` — Vitest integration tests
- `tests/e2e/` — Playwright E2E tests

For full development notes (auth flow, access control, storage rules, event system, gotchas), see `AGENTS.md`.