Project Structure

The monorepo is the backbone of this architecture. By co-locating all services in a single repository while enforcing strict module boundaries, we get the best of both worlds: the discoverability and refactoring power of a monolith, and the deployment and ownership isolation of microservices.

This guide explains how the repository is organized, why each boundary exists, and — most importantly — what should never cross those boundaries.

High-Level Structure

The repository is divided into two top-level directories: apps/ for deployable services, and libs/ for shared infrastructure.

.
├── apps/                           # Deployable services (Bounded Contexts)
│   ├── auth/                       # Authentication service
│   ├── iam/                        # Identity & Access Management
│   ├── data-owner-bc/              # Example: Data Owner Bounded Context
│   ├── data-consumer-bc/           # Example: Data Consumer Bounded Context
│   ├── admin-bc/                   # System administration Bounded Context
│   ├── master-data/                # Reference / master data service
│   ├── storage/                    # Object storage service (MinIO)
│   └── docs-gateway/               # Aggregated API documentation gateway
│
└── libs/                           # Shared libraries (infrastructure only)
    ├── common/                     # Guards, decorators, utilities
    ├── config/                     # Environment configuration module
    └── database/                   # Database connection module

The core rule: apps/ holds business logic. libs/ holds infrastructure. If you find domain-specific code in libs/, it belongs in an app.

Standard Service Structure

Every service — from auth to the smallest bounded context — follows this identical layout:

apps/auth/
├── docs/                           # Service-specific documentation
│   └── auth.md
├── jest.config.js                  # Jest configuration
├── src/
│   ├── auth.controller.ts          # HTTP & TCP controllers
│   ├── auth.module.ts              # NestJS module definition
│   ├── auth.service.ts             # Business logic
│   ├── dto/
│   │   └── login.dto.ts
│   └── main.ts                     # Bootstrap entry point
├── test/
│   ├── e2e/
│   │   └── auth.e2e-spec.ts
│   ├── jest-e2e.json
│   ├── mocks/
│   │   └── mock-auth.ts
│   └── unit/
│       └── auth.controller.spec.ts
└── tsconfig.app.json

This standardization means any engineer can navigate any service without a map.

Bounded Context Structure

Bounded contexts with multiple domain modules (most production services) extend the standard layout with a modules/ directory:

apps/data-owner-bc/
├── docs/
│   ├── overview.md
│   └── checklist.md
├── src/
│   ├── data-owner-bc.module.ts     # Root module
│   ├── main.ts
│   ├── modules/                    # Domain modules
│   │   ├── resource/               # "Resource" domain (e.g. Patient, Order)
│   │   │   ├── controllers/
│   │   │   │   └── resources.controller.ts
│   │   │   ├── services/
│   │   │   │   └── resources.service.ts
│   │   │   ├── dto/
│   │   │   │   ├── create-resource.dto.ts
│   │   │   │   └── update-resource.dto.ts
│   │   │   ├── entities/
│   │   │   │   └── resource.entity.ts
│   │   │   ├── enum/
│   │   │   ├── interface/
│   │   │   └── resource.module.ts
│   │   │
│   │   └── sub-resource/           # Related domain module
│   │       ├── controllers/
│   │       ├── services/
│   │       ├── dto/
│   │       ├── entities/
│   │       └── sub-resource.module.ts
│   │
│   └── typeorm-cli.ts
│
└── test/
    ├── e2e/
    ├── jest-e2e.json
    ├── mocks/
    └── unit/

Shared Library Structure

libs/ contains only cross-cutting technical infrastructure — never domain logic:

libs/
├── common/
│   └── src/
│       ├── common.module.ts
│       ├── decorators/
│       │   ├── current-user.decorator.ts
│       │   ├── public.decorator.ts
│       │   └── resource-type.decorator.ts
│       ├── dto/
│       │   └── query-params.dto.ts         # Generic pagination/filter DTO
│       ├── enum/
│       │   ├── app-microservice.enum.ts    # Service identifiers & message commands
│       │   └── app-databases.enum.ts       # Database connection identifiers
│       ├── guards/
│       │   ├── auth.guard.ts
│       │   └── permissions.guard.ts
│       ├── interfaces/
│       ├── middlewares/
│       ├── modules/
│       │   ├── redis/
│       │   └── logs/
│       ├── pipes/
│       ├── services/
│       │   └── microservice-client.service.ts
│       └── utils/
│           ├── bootstrap.util.ts
│           ├── http-exception/
│           └── http-success/
│
├── config/
│   └── src/
│       ├── config.module.ts                # Env validation with Joi
│       └── config.service.ts
│
└── database/
    └── src/
        ├── database.module.ts              # Primary/replica replication setup
        ├── database.service.ts
        └── migrations/

The Data Owner / Data Consumer Pattern

This is the most critical architectural decision in the codebase. Understanding it is non-negotiable.

Why Can’t the Consumer Access the Owner’s Database?

Imagine data-consumer-bc needs resource data owned by data-owner-bc. The naive solution is to give it direct database access. The correct solution is to force it through an API call. Here’s why:

Single Source of Truth: data-owner-bc is the sole authority over its domain data. If consumers could modify the same tables, data integrity becomes impossible to guarantee.
Encapsulation: A bounded context’s database is its internal implementation detail — like a private method in a class. Allowing direct access is the distributed systems equivalent of breaking encapsulation.
Separation of Concerns: The consumer BC’s job is its own domain logic. The owner’s job is maintaining its data. Mixing these responsibilities creates tight coupling that makes both services harder to change independently.

How It Works in Practice

sequenceDiagram
    participant Consumer as data-consumer-bc
    participant Client as Microservice Client
    participant Owner as data-owner-bc Controller
    participant Service as data-owner-bc Service
    participant DB as Database

    Consumer->>Client: Need resource data
    Client->>Owner: TCP Message (cmd: GetResourceById)
    Owner->>Service: findById(resourceId)
    Service->>DB: SELECT * FROM resources
    DB-->>Service: Resource row
    Service-->>Owner: Resource entity
    Owner-->>Client: Resource response
    Client-->>Consumer: Typed resource data

The Owner: Exposing Data via MessagePattern

@ResourceType('resources')
@ApiTags('Resources')
@Controller('resources')
export class ResourcesController extends BaseControllerOperations<
    Resource,
    CreateResourceDTO,
    UpdateResourceDTO,
    ResourcesService
> {
    constructor(private readonly resourcesService: ResourcesService) {
        super(resourcesService);
    }

    // HTTP endpoints — inherited from BaseControllerOperations

    // TCP message handler — exposes data to other services
    @MessagePattern({ cmd: AppMicroservice.DataOwnerBc.cmd.GetResourceById })
    async handleGetResourceById(@Payload() resourceId: string): Promise<Resource> {
        return this.resourcesService.findById(resourceId);
    }
}

The Consumer: Requesting Data via TCP Client

@Module({
    imports: [
        CommonModule, // Provides the pre-registered microservice client
        DatabaseModule.registerAsync(AppDatabases.APP_CORE),
        TypeOrmModule.forFeature([Appointment], AppDatabases.APP_CORE),
    ],
    controllers: [AppointmentController],
    providers: [AppointmentService],
})
export class AppointmentModule {}

@Injectable()
export class AppointmentService extends BaseServiceOperations<
    Appointment,
    CreateAppointmentDTO,
    UpdateAppointmentDTO
> {
    constructor(
        logger: LogsService,
        private readonly configService: ConfigService,
        @InjectRepository(Appointment, AppDatabases.APP_CORE)
        private readonly appointmentRepository: Repository<Appointment>,
        @Inject(AppMicroservice.DataOwnerBc.name)
        private readonly ownerBcClient: ClientProxy,
        private readonly microserviceClient: MicroserviceClientService,
    ) {
        super(appointmentRepository, {
            logging: {
                logger,
                serviceName: configService.get('CONSUMER_BC_SERVICE_NAME'),
                serviceVersion: configService.get('CONSUMER_BC_SERVICE_VERSION'),
            },
        });
    }

    async createAppointmentForResource(
        resourceId: string,
        dto: CreateAppointmentDTO,
    ): Promise<Appointment> {
        // Fetch resource data from the owner BC via TCP
        const resource = await this.microserviceClient.sendWithContext<IResourceData>(
            this.logger,
            this.ownerBcClient,
            { cmd: AppMicroservice.DataOwnerBc.cmd.GetResourceById },
            { id: resourceId },
            null,
        );

        if (!resource) {
            throw new NotFoundException('Resource not found');
        }

        const appointment = this.appointmentRepository.create({
            ...dto,
            resource_id: resource.id,
            resource_reference: resource.reference_number,
        });

        return this.appointmentRepository.save(appointment);
    }
}

CommonModule: Centralizing Microservice Client Registration

All TCP client registrations live in CommonModule, making them available globally via injection:

@Global()
@Module({
    imports: [
        ConfigModule,
        RedisModule,
        JwtModule,
        ClientsModule.registerAsync([
            {
                name: AppMicroservice.Auth.name,
                useFactory: (config: ConfigService) => ({
                    transport: Transport.TCP,
                    options: {
                        host: 'localhost',
                        port: config.get<number>('AUTH_MICROSERVICE_PORT', 5000),
                    },
                }),
                inject: [ConfigService],
            },
            {
                name: AppMicroservice.DataOwnerBc.name,
                useFactory: (config: ConfigService) => ({
                    transport: Transport.TCP,
                    options: {
                        host: 'localhost',
                        port: config.get<number>('OWNER_BC_MICROSERVICE_PORT', 4000),
                    },
                }),
                inject: [ConfigService],
            },
            // ... other services
        ]),
    ],
    providers: [AuthGuard, PermissionsGuard],
    exports: [AuthGuard, PermissionsGuard, ClientsModule, RedisModule, ConfigModule],
})
export class CommonModule {}

What Belongs in `libs/` vs. `apps/`

This question comes up constantly. The answer is always the same: ask whether it’s infrastructure or business logic.

✅ Belongs in `libs/`

These are technical cross-cutting concerns with no domain knowledge:

Category	Examples
Auth Guards	`AuthGuard`, `PermissionsGuard`
Decorators	`@Public()`, `@CurrentUser()`, `@ResourceType()`
Interceptors	`TransformInterceptor` (response formatting)
Exception Filters	`AllExceptionsFilter`
Infrastructure Modules	`DatabaseModule`, `ConfigModule`, `RedisModule`
Utility Functions	`bootstrapApplication()`, formatters
Generic DTOs	`QueryParamsDTO`, `FileUploadDTO`
System Enums	`AppMicroservice`, `AppDatabases`
Shared Services	`MicroserviceClientService`, `LogsService`

❌ Stays in `apps/`

These carry domain knowledge and must stay local to their bounded context:

Category	Why
Entities	Tied to a specific database and BC ownership — never share
Domain DTOs	Each BC defines its own API contract
Domain Enums	Represent business rules owned by a specific BC
Business Services	Domain logic belongs to the owning BC
Domain Interfaces	Shape of data specific to one BC’s needs

The Rule of Second Use

1. Always start local — create everything in the owning BC first.

2. Only promote to libs/ when:
   - It is purely technical infrastructure (no business logic)
   - It is actively used by 2+ services
   - It has zero domain coupling

3. For cross-service data — never share entities.
   Use a local interface typed to the data you need:

   // data-consumer-bc: local interface for data received from owner
   interface IResourceData {
       id: string;
       reference_number: string;
       first_name: string;
       last_name: string;
   }

   // Consumed via TCP call — never via a shared entity file
   const resource = await this.microserviceClient
       .sendWithContext<IResourceData>(...);

Required Directory Checklist

Every service that is added to apps/ must have:

apps/<service-name>/
├── docs/          # ✅ Required — service documentation
├── src/           # ✅ Required — source code
├── test/
│   ├── e2e/       # ✅ Required — end-to-end tests
│   └── unit/      # Optional but strongly encouraged
└── jest.config.js # ✅ Required — Jest configuration

And every domain module within a bounded context must have:

src/modules/<domain>/
├── controllers/   # ✅ Required
├── services/      # ✅ Required
├── dto/           # ✅ Required
├── entities/      # ✅ Required
├── enum/          # Optional
├── interface/     # Optional
└── <domain>.module.ts  # ✅ Required

Summary

The project structure enforces five guarantees:

Clear ownership: Every piece of data has exactly one authoritative service
Enforced boundaries: Cross-service access is always explicit — via TCP, never via shared repositories
Predictable layout: Any engineer can find any file without asking
Safe sharing: libs/ contains only code that is genuinely infrastructure
Independent deployability: Each bounded context can be scaled, deployed, or replaced without touching others