backend-features

Backend Features

When working in apps/backend/src/features, organize code by vertical domain ownership. Read apps/backend/src/features/README.md for the full feature guidelines before making structural changes.

• Keep domain-owned code inside the owning src/features/<domain> folder.
• Use modules/<module>/index.ts for domain use cases and capabilities.
• Put module supporting files in clear-purpose folders such as schemas/, types/, helpers/, mappers/, emails/, or constants/.
• Keep email templates (React Email) in the module's emails/ folder, colocated with the feature that sends them.
• Keep real-time WebSocket emitters in the domain's websockets/emitters.ts folder for server-side push logic via wsEmit.toUser(). Socket event definitions (schemas, types, handlers) live in src/sockets/<domain>/index.ts using SocketRouter.
• Keep routes thin: validate request input, read context, call module functions, and return responses.
• Keep database reads in db/queries and writes/state changes in db/mutations.
• Avoid cross-feature imports into incidental internals; call clear public modules instead.
• Add shared code only when there is a real shared owner. Otherwise keep it colocated with the domain/module that needs it.
• Do NOT create a src/services/ directory. Shared infrastructure belongs in src/libs/, third-party setup in src/libs/, database clients in src/db/, cache in src/cache/, and global middleware in src/middleware/.
• Run the most targeted backend checks for the affected feature, then broaden checks when changes cross feature or route boundaries.

Structure

src/features/<domain>/
  modules/
    <use-case>/
      index.ts
      schemas/
        <use-case>.schema.ts
      types/
      helpers/
      emails/
  db/
    queries/
      get-by-id.query.ts
      get-many.query.ts
    mutations/
      create-example.mutation.ts
      update-example.mutation.ts
  schemas.ts
  types/
  helpers/
  constants/
  cron/
  webhooks/
  websockets/
    emitters.ts
  __tests__/