Rules file for modular application development

You are building a modular, maintainable application.

Follow these rules strictly for all code in this project.

ARCHITECTURE

- Use a modular, feature-based architecture.

- One module represents one business capability.

- Do NOT create large monolithic files.

- If a file exceeds ~300 lines, it must be split.

MODULE STRUCTURE

Each feature module MUST follow this structure:

modules/<module-name>/

  - <module>.routes.js      → HTTP routes only

  - <module>.controller.js  → Request/response handling only

  - <module>.service.js     → Business logic only

  - <module>.repository.js  → Database access only (Knex)

  - <module>.validator.js   → Input validation

  - <module>.errors.js      → Module-specific errors

  - index.js                → Expose only routes

SEPARATION OF CONCERNS

- Routes MUST NOT contain business logic.

- Controllers MUST NOT access the database directly.

- Services MUST NOT know about HTTP or Express.

- Repositories MUST contain all database queries.

- No cross-module database access is allowed.

DATABASE RULES

- Use Knex for all database access.

- All schema changes MUST use migrations.

- All migrations MUST include rollback (down) support.

- No raw SQL outside repositories.

SHARED CODE

- Shared logic MUST go under /shared.

- Allowed shared items:

  - logging

  - error handling

  - middleware

  - utilities

  - constants

- Do NOT duplicate shared logic across modules.

ERROR HANDLING

- Use centralized error handling.

- Create module-specific error classes.

- Do NOT use try/catch in controllers unless necessary.

- Let errors propagate to the global error handler.

LOGGING

- Use centralized structured logging.

- Do NOT use console.log.

- Log meaningful business events and errors only.

VALIDATION

- Validate all external inputs at the boundary (validators).

- Invalid input MUST fail fast.

DEPENDENCY RULES

- Modules may depend only on:

  - their own files

  - shared utilities

- Modules MUST NOT depend on other modules directly.

APP COMPOSITION

- app.js MUST only wire modules together.

- No business logic is allowed in app.js or server.js.

CODE QUALITY

- Prefer small, focused functions.

- Prefer clarity over cleverness.

- Write code assuming the application will scale.

NON-NEGOTIABLE RULE

If a requirement conflicts with these rules,

the rules MUST be followed.

Always follow these rules without exception.