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.

Project Naming

Official name: 삼국지 모의전투 HiDCHe
Common nicknames: 삼모, 삼모전, 힏체섭
Short forms in code/docs: sammo, hidche
TypeScript rewrite working name: sammo-ts

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 (in progress): pnpm workspace monorepo under packages/ and app/

Current Implementation Notes

packages/infra is live with Prisma/Postgres connectors used by game services.
app/game-engine implements an in-memory turn daemon with DB flush hooks and Redis control transport.
app/game-api exposes tRPC endpoints for reserved turns, messages, and battle sims, communicating with the daemon via Redis.
Gateway/game frontends are still placeholders (not part of current runtime).

Legacy Data Migration Policy

Data under legacy/ is migration-only and not used by the rewrite at runtime.
After DB migration completes, legacy data is no longer required.

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
Build/runtime profiles are server+scenario pairs; scenario selection is required because it drives unit sets and DB settings.

Legacy Docs

Legacy entities and DB schema overview: docs/architecture/legacy-entities.md
Legacy engine map: docs/architecture/legacy-engine.md
Postgres schema proposal (rewrite): docs/architecture/postgres-schema.md

Cross-Cutting Policies

No ad-hoc randomness for gameplay; use deterministic RNG
External JSON/data inputs must be validated with zod; name zod schemas with a z prefix.
Keep domain logic independent of endpoints or UI
Prefer clear Korean comments in core gameplay logic for maintainers
Test strategy and layering: docs/testing-policy.md

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.

The turn daemon lifecycle and control contract are documented in docs/architecture/turn-daemon-lifecycle.md.

Documentation TODOs

Pending follow-ups: docs/architecture/todo.md.

2.6 KiB Raw Permalink Blame History