# AGENTS.md — Shared Business Logic

> **Parent**: `../../AGENTS.md` — Payload config, server actions pattern, env vars.

## Overview

63 files across 17 domain subdirectories plus root modules. Contains pure business logic and Payload-dependent service modules. Server actions in route directories delegate here; these modules hold the actual domain rules.

## Structure

```
lib/
  utils.ts              # cn() class merger (Tailwind)
  storageRules.ts       # Storage validation (prohibited → whitelist → per-item cap)
  shipping.ts           # Fuel cost, transit time, vehicle effective speed
  distance.ts           # Haversine distance calculation
  logistics.ts          # Shared logistics helpers
  aim-trainer.ts        # Pure aim-trainer game rules (difficulties, scoring, XP)
  impersonation.ts      # Admin impersonation cookie helpers
  redaction.ts          # Text redaction helper
  versionInfo.ts        # Build version display

  arma-bridge/          # Arma server sync: auth, heartbeat/presence, commands, sync events
  attendance/           # Mission attendance service (single write path)
  awards/               # Award grant eligibility + diff/notify/cleanup
  banking/              # Transaction engine, account creation, currency config, formatting
  base/                 # Staffing (hire/fire/headcount), structure upgrades, storage, base tick
  evaluations/          # Evaluation levels + bot reminder plan (reminders.ts)
  locker/               # Grid logic, placement validation, loadouts, attachments/skins
  logistics/            # Mission lifecycle + mission reminder logic
  market/               # Buy/sell, NPC negotiation, dialogue, vendor resolution
  notifications/        # User notification helper + muteable types
  projects/             # Project ticket-type metadata (projectMeta.ts)
  realtime/             # In-process SSE bus + presence tracking (single-instance only)
  session/              # Session token expiry helpers
  shims/                # Shim audience/path evaluation (djb2 hash matching)
  tickets/              # Ticket vocabulary, Lexical helpers, staff resolution
  transfers/            # Assignment transfer workflow (request/decide/appeal) + notification types
  wiki/                 # Slugify, templates, wikilinks, markdown pipeline, page service
```

## Dependency graph

```
Server actions ──┬── storageRules.ts
                 ├── lib/banking/index.ts ──┬── format.ts (CurrencyConfig)
                 │                          └── ui.ts
                 ├── lib/market/index.ts ──┬── negotiations.ts
                 │                         ├── npcs.ts
                 │                         ├── npcDialogue.ts (pure, client-safe)
                 │                         └── chatBubbles.ts (pure, client-safe)
                 ├── lib/base/ (staffing.ts, upgrade.ts, tick.ts, storage.ts)
                 ├── lib/wiki/service.ts + prepare.ts (markdown.tsx is pure, client-safe)
                 ├── lib/locker/index.ts ── search.ts
                 ├── lib/tickets/, lib/transfers/, lib/awards/
                 ├── lib/attendance/index.ts
                 ├── lib/evaluations/ (reminders.ts drives the bot's evaluation DMs)
                 └── lib/notifications/index.ts

game-tick script ── shipping.ts, distance.ts, storageRules.ts
market-tick script ── lib/market/index.ts (autoPrice, autoQuantity, npc vendor logic)
base-tick script ── lib/base/tick.ts (processBaseTick: salaries, maintenance, upkeep)
```

## Pure vs Payload-dependent

- **Pure modules** (no Payload import, safe for client + server): `npcDialogue.ts`, `chatBubbles.ts`, `ticketMeta.ts`, `distance.ts`, `aim-trainer.ts`, `wiki/markdown.tsx`, `wiki/prepare.ts`, `wiki/templates.ts`, `wiki/wikilinks.ts`, `shims/evaluate.ts`, `storageRules.ts` (logic only)
- **Payload-dependent** (import `@payload-config`, server-only): everything else

## Key modules

### `storageRules.ts`
Enforcement order: **prohibited → whitelist → per-item cap**. Functions: `checkStorageDeposit`, `isResourceProhibited`, `isResourceWhitelisted`, `getResourceStorageCap`, `storageViolationMessage`. Used in structure actions, shipment creation, and arrival processing.

### `banking/index.ts`
`applyTransaction()` — single source of truth for balance math. Validates accounts, creates transaction + ledger entries, updates balances. `ensurePersonalAccount()` — dedup find-or-create. `getMainCurrencyId()` — resolves Game Rules main currency. `currencyConfigFromGameRules()` builds the `CurrencyConfig` threaded through banking/market UI.

### `base/`
Staffing/upkeep engine for structures: `staffing.ts` (`hireStaff`/`fireStaff`/`setLaborHeadcount`/`assertStaffHiringEnabled`), `upgrade.ts` (`upgradeStructure` — consumes stored materials, swaps type via `upgradesInto`), `storage.ts` (`consumeStorage`/`storedAmount`), `tick.ts` (`processBaseTick` — salaries, maintenance, upkeep flags).

### `market/index.ts`
`buyListing()` — validates, debits buyer, credits locker, marks sold. Supports partial buys via `quantity` parameter. `creditLockerQuantity()` — merges stackables or fills empty grid spots; throws if no space.

### `market/negotiations.ts`
NPC vendor pricing engine: stance starts at asking price, only moves down. Offers ≥ stance accepted; within 2% with 85% chance; well-below draw concession (30% of gap). Patience meter increments per round, closes at cap.

### `realtime/bus.ts`
Module-level subscriber Set. SSE endpoint `GET /api/realtime` subscribes; game tick POST `/api/game-tick/notify` broadcasts. **Single-instance only** — will not work across multiple server processes.

## Where to look

| Task | Path |
|------|------|
| Add storage rule logic | `storageRules.ts` (pure functions) |
| Modify transaction flow | `lib/banking/index.ts` — `applyTransaction()` |
| Change NPC pricing | `lib/market/negotiations.ts` — NPC_ACCEPT constants |
| Add staffing/upkeep logic | `lib/base/` (hire/fire/upgrade/tick) |
| Modify minigame rules | `aim-trainer.ts` (pure) or the game's components dir |
| Add notification type | `lib/notifications/notificationTypes.ts` |
| Add pure client+server logic | Verify no Payload import; place in appropriate domain dir |

## Anti-patterns

- **NEVER** import `@payload-config` in files under `market/npcDialogue.ts` or `market/chatBubbles.ts` — they must stay client-safe
- **NEVER** duplicate business logic in server actions — always delegate to `lib/{domain}/`
- **NEVER** use module-level state in `realtime/bus.ts` for cross-instance scenarios — use external pub/sub (Redis) instead
- **NEVER** mutate `storageRules.ts` enforcement order without updating all 3 call sites (structure actions, shipment creation, arrival processing)