jason/polaris-task-force
1
0
Fork 0
Code Issues Wiki Activity
polaris-task-force/README.md

4.9 KiB
Raw Blame History

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.

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.