backend-module-standards

---
name: backend-module-standards
description: Enforce this repository's TypeScript backend module architecture standards. Use whenever creating, modifying, refactoring, or reviewing backend code under `server/`, including routes, services, modules, repositories, shared backend code, and backend tests. Do not apply these rules to frontend code or non-backend scaffolding.
---

# Backend Module Standards

Apply these rules after the repository's basic scaffolding is in place. Limit them to backend code under `server/`. Preserve the requested task scope: make touched and newly generated backend code compliant without performing an unrelated repository-wide migration.

## Inspect before editing

1. Identify the owning feature module and its existing barrel, services, routes, and tests.
2. Search for existing shared types, interfaces, and utilities before adding any definition.
3. Search for every consumer before changing a module's public exports.

## Organize backend modules

- Place each feature in `server/modules/<feature>/`.
- Use TypeScript for every file inside `server/modules/`. Do not add JavaScript backend module files.
- When touched JavaScript utilities belong to the work, migrate them to TypeScript. Place a one-use utility in its sole component; place a utility used in at least two locations in `server/shared/utils.ts`.
- Give every feature module an `index.ts` barrel that exposes only its required public API.
- Import another feature module only through that module's `index.ts`. Never deep-import another module's routes, services, repositories, adapters, or internal files.
- Treat `server/shared/` as the shared module. Keep shared definitions in `server/shared/types.ts`, `server/shared/interfaces.ts`, and `server/shared/utils.ts`, and expose only required cross-module members through its barrel.
- Do not create module-local `types.ts`, `interfaces.ts`, or `utils.ts` files.
- Keep module-private implementation details unexported.

## Place types, interfaces, and utilities

- Use `type` by default. Use `interface` only for a contract that a class is intended to implement.
- Use `export type` for type exports and `import type` for type-only imports.
- Define a type, interface, or utility directly in its component file when it is used in only that location.
- Move a type or interface used in two or more locations to `server/shared/types.ts` or `server/shared/interfaces.ts` as appropriate.
- Move a utility used in two or more locations to `server/shared/utils.ts`.
- Do not duplicate an existing shared definition to avoid importing it.
- Give every shared type, interface, and utility a detailed doc comment explaining its behavior, valid usage, and important constraints.
- Keep related shared definitions adjacent. Introduce each group with `//----------------- DESCRIPTION OF GROUP ------------` and separate unrelated groups with `// ---------------------------`.

## Design exports deliberately

- Export a function or variable at its declaration, such as `export function loadSession()`. Do not collect ordinary exports at the end of an implementation file.
- The preceding rule does not apply to `index.ts` barrel exports.
- For every exported component, add a brief comment at its definition naming the consuming module or modules and explaining why they use it. Update the comment when consumers change.
- Do not export speculative helpers, implementation details, or symbols that have no cross-file consumer.
- Use clear, specific names for functions and variables. Add a concise comment anywhere intent, ordering, invariants, or edge cases could be confusing.

## Keep routes thin

- Parse and validate transport input in the route, convert it to the service's expected typed input, call one or more services, and translate the result to the response.
- Keep business logic, persistence, filesystem work, subprocess execution, and orchestration out of routes.
- Allow a service to call other services. Access another module's services through that module's public barrel contract.

## Test within the module

- Put feature tests in `server/modules/<feature>/tests/`.
- Add or update unit tests for changed service behavior and route parsing.

## Verify the result

Before finishing:

1. Confirm all cross-module imports use `index.ts` barrels and all public exports are necessary and documented.
2. Confirm shared definitions follow the one-use versus multiple-use placement rule and grouping-comment format.
3. Confirm routes only parse, call services, and format responses.
4. Run the narrow relevant tests, then `npm run build`, `npm run typecheck`, and `npm run lint` when the task scope and environment permit.

• SKILL.md 5 KB
• agents/openai.yaml 1 KB