api module blueprint

README.md

@@ -1,6 +1,11 @@
 # ourKairos
 
-## Shared contracts
+## Repository scaffolding
+
+The repository includes merge-safe implementation templates for work that will land incrementally.
+
+- `tooling/api-module-template` contains the baseline Express module structure for future API features.
+- `docs/api-architecture.md` documents the intended module registration pattern.
 
 The repository includes a framework-agnostic contracts package in `packages/contracts` for request and response payload definitions shared across future apps and services.
 

docs/api-architecture.md

@@ -0,0 +1,45 @@
+# API Architecture
+
+This repository uses a feature-module pattern for the Express API.
+
+## Proposed structure
+
+When `apps/api` is added, use this layout:
+
+- `src/app`
+  - `create-app.ts`
+  - `register-routes.ts`
+- `src/middleware`
+  - shared middleware and error handling
+- `src/modules`
+  - one folder per feature
+
+Example:
+
+- `src/modules/health`
+- `src/modules/auth`
+- `src/modules/capsules`
+
+Each feature module should contain:
+
+- routes
+- controller
+- service
+- types
+
+## Registration flow
+
+1. App bootstrap creates the Express app.
+2. Shared middleware is attached.
+3. Feature routers are mounted from a single module registry.
+4. Error middleware is mounted last.
+
+## Why this is merge-safe
+
+- New features can add a module without editing unrelated business logic.
+- Routing stays centralized while implementation remains feature-scoped.
+- Services can evolve independently from controllers and middleware.
+
+## Template
+
+Use `tooling/api-module-template` as the starting point for new modules.

tooling/api-module-template/README.md

@@ -0,0 +1,24 @@
+# API Module Template
+
+This template provides a minimal Express module layout that can be copied into `apps/api/src/modules/<feature>` when the API app exists.
+
+## Layout
+
+- `index.ts`: module exports
+- `<feature>.routes.ts`: route registration
+- `<feature>.controller.ts`: request handlers
+- `<feature>.service.ts`: business logic
+- `<feature>.types.ts`: module-local types
+
+## Design goals
+
+- Route files only compose middleware and handlers
+- Controllers translate HTTP requests into service calls
+- Services own business rules and persistence orchestration
+- Types stay close to the module until they become shared contracts
+
+## Integration notes
+
+- Register modules from a single `src/modules/index.ts`
+- Keep middleware in `src/middleware`
+- Keep app bootstrap and shared Express concerns in `src/app`

tooling/api-module-template/index.ts

@@ -0,0 +1,4 @@
+export * from "./template.types";
+export { createTemplateController } from "./template.controller";
+export { createTemplateRouter } from "./template.routes";
+export { createTemplateService } from "./template.service";

tooling/api-module-template/template.controller.ts

@@ -0,0 +1,9 @@
+import type { Request, Response } from "express";
+import type { TemplateService } from "./template.types";
+
+export const createTemplateController = (service: TemplateService) => ({
+  list: async (_request: Request, response: Response) => {
+    const records = await service.list();
+    response.json({ data: records });
+  }
+});

tooling/api-module-template/template.routes.ts

@@ -0,0 +1,13 @@
+import { Router } from "express";
+import { createTemplateController } from "./template.controller";
+import { createTemplateService } from "./template.service";
+
+export const createTemplateRouter = () => {
+  const router = Router();
+  const service = createTemplateService();
+  const controller = createTemplateController(service);
+
+  router.get("/", controller.list);
+
+  return router;
+};

tooling/api-module-template/template.service.ts

@@ -0,0 +1,7 @@
+import type { TemplateRecord, TemplateService } from "./template.types";
+
+export const createTemplateService = (): TemplateService => ({
+  async list(): Promise<TemplateRecord[]> {
+    return [];
+  }
+});

tooling/api-module-template/template.types.ts

@@ -0,0 +1,8 @@
+export interface TemplateRecord {
+  id: string;
+  name: string;
+}
+
+export interface TemplateService {
+  list(): Promise<TemplateRecord[]>;
+}