Backend Module Standards

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.