Z8MB1E
b9999fceff
# Conflicts: # TODO.md # src/components/frontend/eod/MinesweeperBoard.tsx # src/migrations/index.ts |
||
|---|---|---|
| .archived | ||
| .todo | ||
| .vscode | ||
| docs | ||
| public | ||
| src | ||
| tests | ||
| Writerside | ||
| .dockerignore | ||
| .env.development | ||
| .env.example | ||
| .gitignore | ||
| .npmrc | ||
| .prettierrc.json | ||
| .yarnrc | ||
| AGENTS.md | ||
| bun.lock | ||
| bunfig.toml | ||
| components.json | ||
| DEPLOYMENT.md | ||
| DESIGN.md | ||
| docker-compose.yml | ||
| docker-entrypoint.sh | ||
| Dockerfile | ||
| drizzle.config.ts | ||
| eslint.config.mjs | ||
| next.config.mjs | ||
| package.json | ||
| playwright.config.ts | ||
| pnpm-lock.yaml.bk | ||
| postcss.config.mjs | ||
| README.md | ||
| reset-seq.sql | ||
| review_summary.md | ||
| test.env | ||
| TODO.md | ||
| tsconfig.json | ||
| vitest.config.mts | ||
| vitest.setup.ts | ||
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 viabun 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
bun installcp .env.example .env- Edit
.env: theDATABASE_URIline in.env.exampleis outdated (MongoDB). Replace it with a PostgreSQL connection string:
SetDATABASE_URI=postgres://user:password@localhost:5432/your_databasePAYLOAD_SECRET,APP_URL(defaulthttp://localhost:3000), andGAME_TICK_NOTIFY_SECRET. bun run dev— starts the dev server athttp://localhost:3000.- Use
bun run devsafeto wipe the.nextcache before starting.
- Use
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.
Project structure
src/app/(frontend)/— public-facing app pages (dashboard, logistics, banking, market)src/app/(payload)/— Payload admin panel and API routessrc/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 componentssrc/components/ui/— shadcn/ui primitivessrc/tools/seed/— seed scripts for initial datasrc/scripts/— game tick and utility scriptstests/int/— Vitest integration teststests/e2e/— Playwright E2E tests
For full development notes (auth flow, access control, storage rules, event system, gotchas), see AGENTS.md.