architecture

AGENTS.md

@@ -9,15 +9,6 @@
 - PHP entry points live under `legacy/` and `legacy/hwe/` (for example `legacy/index.php`, `legacy/hwe/index.php`).
 - `legacy/` is mostly a shell; `legacy/src/` is largely unused.
 - Core PHP domain logic lives under `legacy/hwe/sammo/` (PSR-4 `sammo\\` namespace).
-- `legacy/hwe/sammo/` is the game engine core, organized by domain concerns rather than endpoints.
-  - `Command/` contains turn actions (general/nation commands) and their resolution rules.
-  - `API/` exposes engine operations for UI and automation (general, nation, command, message, auction, etc.).
-  - `Event/` and `StaticEvent/` implement dynamic and scheduled event processing.
-  - `General*`, `Nation*`, `WarUnit*`, `City*` classes model game entities and combat/city state.
-  - `Action*` and `Special*` capture traits, personalities, special actions, and scenario effects.
-  - `Trigger*` and `*Trigger` manage conditional logic for units, generals, and state changes.
-  - `Scenario/` and `Scenario.php` define scenario loading and rulesets.
-  - `DTO/`, `VO/`, `Enums/`, `Constraint/` are shared types and validation rules.
 - Frontend TypeScript/Vue sources are in `legacy/hwe/ts/` with shared components in `legacy/hwe/ts/components/`.
 - Styles are split between `legacy/css/` and SCSS in `legacy/hwe/scss/`.
 - Tests: PHPUnit in `legacy/tests/`, TypeScript tests in `legacy/hwe/test-ts/`.
@@ -96,3 +87,9 @@ These are placeholders to align teams; adjust once packages exist.
 ## Commit & Pull Request Guidelines
 - Git history is minimal and does not define a strict convention; use short, imperative messages (e.g., "Fix map cache loading").
 - PRs should include a concise description, testing notes/commands, and screenshots for UI changes.
+
+## Architecture References
+- Overview: `docs/architecture/overview.md`.
+- Legacy engine map: `docs/architecture/legacy-engine.md`.
+- TypeScript rewrite plan: `docs/architecture/rewrite-plan.md`.
+- Runtime and build profiles: `docs/architecture/runtime.md`.

docs/architecture/legacy-engine.md

@@ -0,0 +1,36 @@
+# Legacy Engine Map
+
+The legacy engine lives in `legacy/hwe/sammo/` and follows domain-first
+organization rather than endpoint-first routing.
+
+## Core Domains
+
+- `Command/`: turn actions (general/nation commands) and resolution rules
+- `API/`: engine operations for UI and automation
+- `Event/`, `StaticEvent/`: dynamic and scheduled event processing
+- `General*`, `Nation*`, `WarUnit*`, `City*`: entities and combat/city state
+- `Action*`, `Special*`: traits, personalities, special actions, scenario effects
+- `Trigger*`, `*Trigger`: conditional logic and state transitions
+- `Scenario/`, `Scenario.php`: scenario loading and rulesets
+- `DTO/`, `VO/`, `Enums/`, `Constraint/`: shared types and validation
+
+## Endpoint Patterns
+
+- JSON APIs: `legacy/hwe/j_*.php`
+- Vue multi-entry pages: `legacy/hwe/v_*.php`
+- PHP + jQuery pages: `legacy/hwe/b_*.php` and handlers `legacy/hwe/c_*.php`
+- Modern router: `legacy/hwe/api.php` dispatches into `legacy/hwe/API/`
+
+## Frontend and Assets
+
+- Vue/TypeScript UI: `legacy/hwe/ts/`
+- Shared components: `legacy/hwe/ts/components/`
+- Styles: `legacy/css/` and `legacy/hwe/scss/`
+- Templates: `legacy/hwe/templates/`
+
+## Trigger Composition for Generals (Outline)
+
+- Trigger evaluation order and priority rules
+- "attempt" then "execute" phases
+- Common trigger categories (traits, specials, scenario effects)
+- How triggers combine when multiple sources apply

docs/architecture/overview.md

@@ -0,0 +1,30 @@
+# Architecture Overview
+
+This repository contains both the active legacy PHP game and an in-progress
+TypeScript rewrite. The legacy engine remains the source of truth while the
+monorepo plan is prepared alongside it.
+
+## Layers
+
+- Legacy runtime: PHP entry points under `legacy/` and `legacy/hwe/`
+- Legacy engine core: domain logic under `legacy/hwe/sammo/`
+- Legacy frontend: Vue/TypeScript under `legacy/hwe/ts/`
+- Rewrite (planned): pnpm workspace monorepo under `packages/` and `app/`
+
+## Data and State
+
+- PHP engine owns authoritative gameplay state today
+- Scenario and unit pack data are loaded from `legacy/hwe/scenario/`
+- Deterministic RNG is required for gameplay outcomes
+
+## Cross-Cutting Policies
+
+- No ad-hoc randomness for gameplay; use deterministic RNG
+- Keep domain logic independent of endpoints or UI
+- Prefer clear Korean comments in core gameplay logic for maintainers
+
+## Runtime Processing (Outline)
+
+This document links to detailed runtime behavior in `docs/architecture/runtime.md`.
+Use that document for turn daemon scheduling, API request handling, and
+persistence sequencing.

docs/architecture/rewrite-plan.md

@@ -0,0 +1,28 @@
+# TypeScript Rewrite Plan
+
+The rewrite targets a pnpm workspace-based monorepo with Node.js services and
+Vue 3 frontends.
+
+## Planned Layout
+
+- `/packages/common`: shared utilities and type definitions
+- `/packages/logic`: pure game logic with DI and interfaces
+- `/app/gateway-frontend`: gateway UI
+- `/app/gateway-api`: gateway service
+- `/app/game-frontend`: game UI
+- `/app/game-api`: game backend per server profile
+- `/app/game-engine`: turn daemon per server profile
+- `/tools/build-scripts`: build and deployment scripts
+
+## Runtime Stack (Planned)
+
+- Backend: Node.js + Fastify
+- API: tRPC + zod
+- ORM: Prisma
+- Frontend: Vue 3, Pinia, Vue Router, TailwindCSS, Vite
+- Data: PostgreSQL, Redis sessions
+- Testing: Vitest
+
+## Profiles (Planned)
+
+- `che`, `kwe`, `pwe`, `twe`, `nya`, `pya`

docs/architecture/runtime.md

@@ -0,0 +1,39 @@
+# Runtime and Build Profiles
+
+Build outputs should be emitted to `/dist/{serverName}` per profile to keep
+deployments predictable.
+
+## Suggested Build Pattern
+
+- Wrapper script under `tools/build-scripts`
+- `pnpm build:server --profile che`
+- CI-friendly: `PROFILE=che pnpm build:server`
+
+## Deterministic RNG Policy
+
+- Gameplay randomness must be reproducible from a deterministic seed
+- Prefer `legacy/hwe/ts/util/LiteHashDRBG.ts` and `legacy/hwe/ts/util/RNG.ts`
+- Seed composition should include hidden base seed plus action context
+
+## Turn Daemon and API Server Behavior (Outline)
+
+- Turn daemon responsibilities: scheduling, turn resolution, state persistence
+- API server responsibilities: query/command intake, validation, response shaping
+- Concurrency model between daemon and API server
+
+## Turn Daemon vs API Query Priority (Outline)
+
+- Expected priority order under load
+- Rules for preemption or deferral
+- Handling of write-heavy operations during turn resolution
+
+## In-Memory Processing and DBMS Flush (Outline)
+
+- When in-memory state is authoritative
+- Flush checkpoints and transactional boundaries
+- Recovery strategy after crash during flush
+
+## Testing and Observability (Outline)
+
+- Metrics and logs required to validate scheduling and flush behavior
+- Suggested test scenarios for concurrency and consistency