elysia-architecture

Elysia Architecture

Portable house style for Elysia HTTP apps. Use this skill alone — it does not depend on other skills.

Job: where code lives, how folders/files are named, and ownership boundaries.

Not this skill: Elysia API quirks, plugin lifecycle details, Eden, adapters, or latest framework docs. Prefer current Elysia docs for those.

If the target repo already documents architecture (e.g. AGENTS.md) and it conflicts, repo wins unless the user asks to migrate toward this skill.

Stack defaults (core)

Piece	Default
Runtime	Bun (Node/adapters OK if the app already uses them)
HTTP	Elysia feature plugins under src/modules/<feature>/
Version	Elysia 1.4 at ≥ 1.4.30 (security floor; never build route schemas from untrusted input). Elysia 2 is beta — keep house-style code on 1.4 until it ships stable
Module layout	routes/ + schema/ + domain logic folder
Tests	Vitest under tests/ (unit / integration projects) when the repo uses Vitest

Domain logic may be plain TypeScript modules. Load matching with-* extensions when those stacks are present (see below).

Modes

1. Scaffold — new feature module from checklist.md + tree.md.
2. Apply — place new endpoints/schemas/services in the canonical spots.
3. Review — compare the tree to rules.md; propose moves; do not invent a parallel layout.

Hard rules (core)

1. Feature = src/modules/<feature>/. Group by domain (billing, users), not by technical layer at the app root.
2. One route file = one exported const Elysia plugin with a stable name, and typically one HTTP verb (or a tight related group). Do not pack unrelated verbs into one file. Do not export function makeXRoutes(...).
3. routes/index.ts is a mount table only — .use(child) (+ prefix). No handlers, no domain logic, no shared mappers.
4. Schemas live under schema/ (body, response, query, params as needed). Do not dump DTOs into route files or invent parallel hand-written response interfaces when schemas already define the contract.
5. Routes stay thin. HTTP concerns (auth guards, status mapping, request/response) in the route file; business rules in services (or plain domain modules).
6. No route factories / shared HTTP wrappers. Do not invent makeSyncGet, mapXToHttp, or utils/*-http.ts that wrap handlers. Inline the edge in each route file.
7. Import process resources. Do not inject them. Database, Effect runtime, env, queues: import { db } from "…", import { runtime } from "…". Forbidden: export function cmsRoutes(db: Db), .decorate("db", db) / .decorate("runtime", runtime) on feature routes, or passing those values through mount-table arguments. Shared-package plugins may take options (origins, prefix); apps still import their own singletons.
8. Map failures at the HTTP edge only. Public bodies stay small (e.g. { error: string } + status). Do not leak internal causes.
9. Do not grow utils/ for HTTP. Prefer schema/, services/domain, or inlined route edges.
10. Naming: folder = noun/domain; file = action or aspect (create.ts, status.ts). Do not repeat the parent folder in the leaf name (billing/billing-status.ts → billing/routes/status.ts).
11. Import direction: routes → schema + services; services must not import routes. Cross-feature deps go through services/shared packages, not route→route imports.
12. Mount feature trees from the app entry (or a parent feature’s mount table).

Details, anti-patterns, and examples: rules.md, tree.md, examples.md.

Progressive disclosure

Need	Read
Canonical trees + naming	references/tree.md
Enforce rules + anti-patterns	references/rules.md
Scaffold / review checklists	references/checklist.md
Good vs bad layouts	references/examples.md
Optional stack overlays	Extensions below

Extensions

Load an extension only when the matching stack is present (or the user asks). Extensions add rules; they do not replace the core tree.

When	Extension
Effect services / Layers / tagged errors	with-effect.md
T3 Env / packages must not read process.env	with-env.md
Session auth mount + { auth: true } macro	with-session-auth.md
Capabilities / grants / identity permissions	with-capability-authz.md
Bearer API keys on a jobs/public API	with-api-key-auth.md
Drizzle schema package + DB in services	with-drizzle.md
OpenAPI derived from route schemas	with-openapi.md
Request logs + OTEL + Effect tracer	with-observability.md
Stable public error body + edge mapping	with-http-errors.md
Domain in packages/*, HTTP in app modules	with-domain-packages.md
Shared vs app-local Elysia plugins	with-shared-plugins.md
In-process cron ticks	with-cron.md
Provider webhooks	with-webhooks.md
Internal shared-secret routes	with-service-auth.md
Vitest — Eden treaty(app) / what to test	with-vitest.md