From 79819c4a1bff6c4aaba918c7dfd5abfc2eff7edc Mon Sep 17 00:00:00 2001 From: Hide_D Date: Tue, 30 Dec 2025 13:39:43 +0000 Subject: [PATCH] feat: update documentation with current implementation details and planned monorepo layout --- AGENTS.md | 1 + README.md | 3 ++- docs/architecture/overview.md | 9 ++++++++- docs/architecture/rewrite-plan.md | 6 ++++++ docs/architecture/runtime.md | 10 ++++++++++ docs/architecture/turn-daemon-lifecycle.md | 11 ++++++++++- 6 files changed, 37 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 94b9a67..6da623d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,7 @@ ## Planned Monorepo Layout (TypeScript Rewrite) - `/packages/common`: shared utilities and type definitions. +- `/packages/infra`: Prisma/Redis connectors and other runtime infra. - `/packages/logic`: pure game logic with DI/interfaces for external dependencies. - `/app/gateway-frontend`: Gateway UI application. - `/app/gateway-api`: Gateway backend service. diff --git a/README.md b/README.md index 88445d6..6e34260 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ ## 구조 - `legacy/`: 현재 운영 중인 PHP 런타임 - `packages/common`: 공유 유틸 및 타입 정의 +- `packages/infra`: Prisma/Redis 커넥터 등 런타임 인프라 - `packages/logic`: 순수 게임 로직 (DI/인터페이스 기반) - `app/gateway-frontend`: 게이트웨이 UI - `app/gateway-api`: 게이트웨이 API @@ -40,7 +41,7 @@ ## 난수 정책 (Verifiable RNG) 게임 로직에 영향을 주는 모든 난수는 재현 가능해야 합니다. -가능하면 기존 구현을 재사용합니다: `legacy/hwe/ts/util/LiteHashDRBG.ts`, `legacy/hwe/ts/util/RNG.ts`. +현 구현을 사용합니다: `packages/common/src/util/LiteHashDRBG.ts`, `packages/common/src/util/RNG.ts`. ## 문서 - `docs/architecture/overview.md` diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 3306824..2642589 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -16,7 +16,14 @@ monorepo plan is prepared alongside it. - 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/` +- 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. +- `app/game-api` exposes tRPC endpoints for reserved turns, messages, and battle sims. +- Gateway/game frontends are still placeholders (not part of current runtime). ## Legacy Data Migration Policy diff --git a/docs/architecture/rewrite-plan.md b/docs/architecture/rewrite-plan.md index 279f161..cbbb49d 100644 --- a/docs/architecture/rewrite-plan.md +++ b/docs/architecture/rewrite-plan.md @@ -15,6 +15,12 @@ Vue 3 frontends. - `/app/game-engine`: turn daemon per server+scenario profile - `/tools/build-scripts`: build and deployment scripts +## Current Implementation Notes + +- `packages/infra` is live and used by game-api/game-engine services. +- `app/game-api` and `app/game-engine` have initial implementations (tRPC endpoints, turn daemon loop). +- Frontend apps remain placeholders while backend/runtime stabilizes. + ## Runtime Stack (Planned) - Backend: Node.js + Fastify diff --git a/docs/architecture/runtime.md b/docs/architecture/runtime.md index e6ecc69..030ff53 100644 --- a/docs/architecture/runtime.md +++ b/docs/architecture/runtime.md @@ -17,6 +17,13 @@ selection is required because it drives unit sets and DB settings. - Prefer `legacy/hwe/ts/util/LiteHashDRBG.ts` and `legacy/hwe/ts/util/RNG.ts` - Seed composition should include hidden base seed plus action context +## Current Implementation Status + +- Turn daemon lifecycle + in-memory state live in `app/game-engine` with DB flush hooks. +- Control queue is in-process only; Redis transport exists on API side but is not wired into the daemon. +- API server already exposes turn-daemon commands (run/pause/resume/status) via tRPC. +- API server writes reserved turns and messages directly to the DB; daemon focuses on world state/logs. + ## Turn Daemon and API Server Behavior (Outline) - Turn daemon responsibilities: scheduling, turn resolution, state persistence @@ -98,6 +105,9 @@ also supports local ID/password login for users who cannot use Kakao. immediately even if requests remain queued. - While the daemon is resolving a turn, the API server queues incoming requests. +Note: the current implementation does not yet process API mutation requests +between turns; only control commands are handled by the in-process queue. + ### Daemon Control Contract (Draft) API server commands are delivered to the daemon over the control channel diff --git a/docs/architecture/turn-daemon-lifecycle.md b/docs/architecture/turn-daemon-lifecycle.md index b713d0e..4122562 100644 --- a/docs/architecture/turn-daemon-lifecycle.md +++ b/docs/architecture/turn-daemon-lifecycle.md @@ -8,7 +8,14 @@ from the API server. - One daemon process per server+scenario profile. - API server is the only ingress for user/admin requests. -- The daemon is the only component that mutates gameplay state. +- The daemon owns world-state mutations; the API server mutates reserved turns and messages. + +## Current Implementation Status + +- The daemon loop handles scheduled runs plus in-process control queue commands + (run/pause/resume/shutdown). It does not drain API mutation requests between turns. +- `getStatus` is supported by API transports but not yet handled by the daemon loop. +- API server currently writes reserved turns and messages directly to the DB. ## Responsibilities @@ -39,6 +46,8 @@ Idle -> Running -> Flushing -> Idle The daemon interleaves API request handling between scheduled turn executions. API requests are drained until the next turn time is reached; once the turn starts, incoming requests are queued and processed after the run. +Current implementation does not yet drain API requests between turns; this +section is the intended target behavior. ```ts while (!stopping) {