muhammadcaeed/backend-structure

Backend Module Implementation Skill (Aegis)

Purpose

This skill defines the mandatory structure and rules for implementing any backend module in the Aegis system.

It must be applied whenever: • a new domain module is created
• an existing module is extended
• controllers, services, or repositories are added

This skill assumes a Docker first runtime and enforces patterns compatible with containerized execution.

---

Architectural Assumptions

All modules must comply with:

• NestJS framework
• Modular monolith architecture
• MongoDB persistence
• Strict multi tenancy via communityId
• Role based authorization via guards
• Docker based runtime execution

If any assumption is unclear, Claude must stop and ask.

---

Required Module Structure

Each backend domain module must contain:

• <domain>.module.ts
• <domain>.controller.ts
• <domain>.service.ts
• <domain>.repository.ts
• dto/
• types/ or enums/
• guards/ if domain specific authorization is required

Example structure:

payments
payments.module.ts
payments.controller.ts
payments.service.ts
payments.repository.ts
dto
enums
guards

No domain logic is allowed outside its module.

---

Controller Rules

Controllers must:

• expose HTTP endpoints only
• perform request validation via DTOs
• extract authentication context
• delegate all business logic to services

Controllers must not:

• contain business logic
• access the database directly
• perform authorization checks inline
• compute derived state
• rely on runtime environment assumptions

Controllers must remain thin and environment agnostic.

---

Service Rules

Services are the owners of business logic.

Services must:

• enforce domain invariants
• perform lifecycle transitions
• trigger side effects such as notifications
• assume authorization has already passed
• remain stateless between requests

Services must not:

• trust client provided identifiers
• bypass repository abstractions
• mutate verified or immutable state
• perform direct request parsing
• depend on local filesystem or host state

---

Repository Rules

Repositories are the only layer allowed to access MongoDB.

Repositories must:

• scope all queries by communityId
• provide explicit query methods
• return domain entities or null
• be safe to execute in containerized environments

Repositories must not:

• expose raw collections
• perform authorization checks
• return partial or ambiguous data
• assume database availability at process start

---

Multi Tenancy Enforcement

Every repository query must include:

• communityId
• additional scope constraints if applicable

Rules:

• communityId is resolved from authentication context
• communityId must never be accepted from client input

If communityId is missing at any layer, this is a bug.

---

Authorization Enforcement

Authorization must be enforced using:

• NestJS guards
• role based checks
• household scope validation

Rules:

• Controllers assume guards have already run
• Services assume authorization is valid
• Frontend is never trusted for authorization

Authorization logic must not depend on runtime environment.

---

Runtime and Docker Safety Rules

Generated code must:

• be stateless between requests
• not rely on local filesystem persistence
• not assume fixed ports or hostnames
• read all configuration from environment variables

Generated code must not:

• hardcode ports
• reference localhost directly
• assume writable disk paths
• depend on globally installed binaries

---

Error Handling Rules

Modules must:

• throw explicit domain errors
• fail fast on misconfiguration
• use meaningful HTTP status codes

Errors must not:

• leak sensitive information
• expose container internals
• hide startup failures

---

Naming Conventions

Use clear and explicit naming such as:

• createPayment
• submitPayment
• verifyPayment
• rejectPayment

Avoid ambiguous names such as:

• handlePayment
• processData
• doAction

---

Testing Expectations

Each module must include:

• <domain>.service.spec.ts for service unit tests • multi-tenancy isolation tests (mandatory) • state transition tests for any state machine • error path tests for validation and authorization

Test Infrastructure Usage

Tests must use the project test infrastructure:

import { createUser, createPayment } from '../../test/factories';
import { createMockRepository, mockProvider } from '../../test/helpers';
import { createTenantTestContext } from '../../test/helpers';

Required Test Categories

1. Happy path - Core use case works
2. Error cases - Invalid input, not found, forbidden
3. Multi-tenancy - Cannot access other community's data
4. State machine - All valid/invalid transitions (if applicable)

Test Structure

<domain>.service.spec.ts
├── describe('<Domain>Service')
│   ├── describe('<method>')
│   │   ├── it('should <happy path>')
│   │   └── it('should throw <error case>')
│   └── describe('Multi-tenancy isolation')
│       ├── it('should not return data from different community')
│       └── it('should use communityId from JWT')

Tests must not rely on host specific behavior.

---

Enforcement Clause

If an instruction conflicts with this skill or with CLAUDE.md:

Claude must stop and ask for clarification.

Claude must not generate code that violates these rules.