Emberfall/docs/ARCHITECTURE.md

ARCHITECTURE.md

Layering (strict, one-way)

routes  →  services  →  game (pure rules)
   ↓          ↓
middleware    db (prepared statements)

• routes/: parse + validate request, call a service, shape the response. No business logic. No SQL.
• services/: orchestrate. Open transactions, read/write DB, call game/ functions, return plain objects.
• game/: pure functions. No require of db/express. Deterministic given inputs (RNG is passed in).
• db/: connection, migrations, seeds. Only services import db.
• middleware/: auth guard, rate limiting, error handler, request validation helper.
• utils/: tiny helpers (rng, time, ids, logger).

Dependencies only point downward. game/ never imports from services/.

Folder structure

emberfall/
├── NOTES.md  STATUS.md  README.md
├── package.json  .env  .env.example  .gitignore
├── docs/                      # specs (this folder)
├── data/                      # SQLite file lives here (gitignored)
├── scripts/
│   ├── migrate.js             # runs src/db/migrations/*.sql in order
│   ├── seed.js                # runs src/db/seeds/*.js (idempotent)
│   └── seed-dev.js            # demo account + hero
├── src/
│   ├── server.js              # listen()
│   ├── app.js                 # builds express app (exported for tests)
│   ├── config/index.js
│   ├── db/
│   │   ├── index.js           # better-sqlite3 handle
│   │   ├── migrations/        # 001_users.sql, 002_characters.sql ...
│   │   └── seeds/             # zones.js, monsters.js, items.js, expeditions.js
│   ├── middleware/
│   │   ├── requireAuth.js
│   │   ├── rateLimiters.js
│   │   ├── validate.js        # zod wrapper
│   │   └── errorHandler.js
│   ├── routes/
│   │   ├── index.js           # mounts all routers under /api
│   │   ├── auth.js  character.js  hunt.js  inventory.js
│   │   ├── shop.js  expeditions.js  leaderboard.js  heroes.js
│   ├── services/
│   │   ├── authService.js  characterService.js  huntService.js
│   │   ├── inventoryService.js  shopService.js
│   │   ├── expeditionService.js  leaderboardService.js
│   ├── game/
│   │   ├── constants.js       # ALL tunable numbers live here
│   │   ├── classes.js  stats.js  energy.js  combat.js
│   │   ├── rewards.js  leveling.js  loot.js
│   └── utils/
│       ├── rng.js  time.js  errors.js  logger.js
├── public/
│   ├── index.html  login.html  register.html
│   ├── create-hero.html  game.html  shop.html  leaderboard.html
│   ├── css/  (base.css, theme.css, layout.css, components.css)
│   ├── js/   (api.js, auth.js, game.js, ui.js, ...)
│   └── img/
└── tests/
    ├── unit/          # src/game/* and utils
    └── integration/   # HTTP-level tests using a temp DB

Module format

Use CommonJS (require / module.exports) everywhere on the server, to keep tooling simple. Frontend JS uses plain <script> tags or ES modules (type="module") — pick one and stay consistent (log in DECISIONS.md).

Request lifecycle

1. helmet → JSON parser → session → static files
2. /api/* routers; protected routers use requireAuth
3. Route validates body/query with zod
4. Service runs (transaction for anything that writes more than one row)
5. Route sends { ok: true, data: ... }
6. Any thrown AppError → errorHandler → { ok: false, error: {code, message} }

Transactions

Any action that spends a resource AND grants a result (hunt, buy, claim) is ONE db.transaction(() => { ... })(). better-sqlite3 is synchronous, so this also prevents double-spend races from parallel requests.

Time

All timestamps are integer milliseconds since epoch (UTC), stored as INTEGER. src/utils/time.js exports now() so tests can stub it. Never call Date.now() directly in services or game code.

Config

Gameplay numbers → src/game/constants.js. Environment/infra → src/config/index.js. Never hardcode magic numbers inline.