building-api-modules
/building-api-modules
Adds or changes an Elysia 2 + Effect v4 API module following the controller/service/error/mapper split, the ok/fail response envelope, and the Effect-at-the-boundary rules. Use when creating or editing a domain module under apps/api.
- Author
- SyahrulBhudiF ↗
- Repository
- ai-interview ↗
- Licence
- MIT
- Last repository change
- 29.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Adds or changes an Elysia 2 + Effect v4 API module following the controller/service/error/mapper split, the ok/fail response envelope, and the Effect-at-the-boundary rules. Use when creating or editing a domain module under apps/api.
Original author description
Adds or changes an Elysia 2 + Effect v4 API module following the controller/service/error/mapper split, the ok/fail response envelope, and the Effect-at-the-boundary rules. Use when creating or editing a domain module under apps/api.
How it works
- Module layout
- Steps for a new module
- Rules that are easy to miss
SKILL.md preview
---
name: building-api-modules
description: Adds or changes an Elysia 2 + Effect v4 API module following the controller/service/error/mapper split, the ok/fail response envelope, and the Effect-at-the-boundary rules. Use when creating or editing a domain module under apps/api.
---
# Building API modules
Elysia 2 (Kiana) + Effect v4 backend. Read `apps/api/AGENTS.md` first — it is the
authoritative rule set. This skill is the step-by-step path.
## Module layout
One directory per domain under `apps/api/src/modules/<name>/`:
```text
modules/<name>/
├── index.ts Elysia controller — HTTP only, thin
├── service.ts business logic (Effect service when it has deps/errors)
├── error.ts domain errors (Schema.TaggedError)
├── mapper.ts database row → shared wire type
```
Reference implementations: `modules/session/progression.ts` (pure logic, plain
function) and `modules/interview` (real dependency + typed error, full Effect
service).
## Steps for a new module
1. Add the request/response schemas to `packages/shared/src/schemas/` as Effect
`Schema.Struct` (wire timestamps are ISO strings). Re-export from the index.
2. Write `service.ts`:
- **Pure logic** → a plain function (`modules/session/progression.ts`). Do NOT
wrap it in `Context.Service`/`Layer`/`ManagedRuntime`.
- **Real effect** (async, typed error, resource, dependency) → `Context.Service`
- `Layer` + `Schema.TaggedError` (`modules/interview/service.ts` + `error.ts`).
3. Write `error.ts` for domain failures with `Schema.TaggedError`.
4. Write `mapper.ts` mapping the Drizzle `$inferSelect` row to the shared wire type.
5. Write `index.ts`: a thin Elysia controller. Return `ok(...)`, declare `response`
with `Schema.toStandardSchemaV1(ApiSuccessSchema(...))` and OpenAPI `detail`.
Run effects at the boundary: `runtime.runPromise` (async) or `runtime.runSync`
(sync) from `src/runtime.ts`, via `Service.use((s) => s.method(...))`.
6. If the module has a service layer, add it to the single runtime in
`src/runtime.ts` (`ManagedRuntime.make(Layer.mergeAll(...))`).
7. If it has new errors, map them in `plugins/logger.ts` `resolveErrorDefinition`
(by `_tag`/`code`) to the envelope.
## Rules that are easy to miss
- Every response is `{ ok: true, data }` or `{ ok: false, error, requestId }`.
Never return a bare payload.
- `yield*` inside Effect, `await` only at the controller boundary.
- `Layer.succeed` for stateless services, `Layer.effect` for stateful/dependent,
`Effect.acquireRelease` for resources.
- Never leak internal error details; `resolveErrorDefinition` maps everything to a
stable code/message.
Versions
The database has no other skills named building-api-modules.
Database snapshot: 13.11.2026 · package version 82bfcb5cd522 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 86add-resource
Add a REST resource to this NestJS API end to end, as a feature module with its controller, service, DTOs, unit spec and contract tests. Use when asked for a new resource, endpoint, route or feature module. - 91effect-development
Effect development guidance. Use when implementing or reviewing code that composes Effect APIs or patterns, or that adds or changes API signatures. - 100elysiajs
Build, debug, or migrate Elysia v2 TypeScript backends with validation, plugins, typed clients, and deployment. Use for Elysia projects or explicit Elysia requests. - 95effect-service-design
Design Effect services. Use when designing a new Effect service module or auditing an existing codebase for service, Layer, and composition improvements. - 100java-crud-module
Use when scaffolding a new CRUD business module in a Spring Boot + MyBatis-Plus layered project. Covers the full 9-file flow: migration, entity, mapper, DTOs, converter, service, facade, and controller. - 100effect-v3-to-v4
Use this skill when migrating a codebase from Effect v3 to Effect v4, upgrading `effect` or any `@effect/*` package across the v3/v4 boundary.