85 lines
4.9 KiB
Markdown
85 lines
4.9 KiB
Markdown
# 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, build, and deploy |
|
|
|
|
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.
|
|
|
|
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`.
|