# Architecture Overview

Realm of Forgotten Souls uses a three-tier monorepo:

| Tier | Technology | Responsibility |
|------|------------|----------------|
| Web client | TypeScript/Vite PWA | UI, input, rendering |
| API | PHP Slim 4 | Auth exchange, accounts, admin, economy CRUD |
| World server | Go | WebSocket gateway, authoritative simulation |

Shared infrastructure: MySQL (durable truth), Redis (presence, pub/sub, cache).

## Service boundaries

- **PHP API** owns HTTP request/response flows: registration, login, menus, shops, bank, mail, clans, leaderboards, donations, admin.
- **Go world server** owns all in-world real-time actions: movement, combat, chat broadcast, monster AI, regen ticks, hazards.
- **Web client** is untrusted; all game rules enforced server-side.

## Zone model

One goroutine per zone with an ordered command channel (single-writer). Launch uses one zone (`hammerfall_world`). Zone partitioning boundaries are defined up front for future distribution.

## Error handling and DEBUG mode

- Structured JSON logs with correlation IDs across all tiers.
- `APP_DEBUG=true` enables verbose logging, stack traces, and message tracing.
- Production defaults to info/warn/error; debug is env-flag or admin-gated.

See [RealmCreationPlan.md](../plans/RealmCreationPlan.md) for the full implementation plan.