Project architecture

01Layers: each part has one job

Think of a restaurant. The waiter takes the order (HTTP layer), the chef decides how to cook it (business layer), the storeroom keeps ingredients (data layer). The waiter never cooks, and the chef never talks to customers. In code: controllers or route handlers parse the request and return a response; services or use cases apply business rules; repositories or ORM models read and write data. Dependencies point inward: the controller knows the service, the service knows the data layer, but the business logic does not know about HTTP. That makes the same logic reusable from an API, a CLI command, a queue job or a test.

• Presentation: controllers, request validation, response formatting.
• Application: services or use cases that orchestrate a task (PlaceOrder, RefundPayment).
• Domain: entities, value objects and rules (Money, OrderStatus transitions).
• Infrastructure: database, queues, payment gateways, email providers.

02Services, use cases and DTOs

A service groups related operations for one domain (OrderService). A use case, or action, is a single operation with a clear name (PlaceOrder). Both take plain input and return plain output. That input is a DTO, a Data Transfer Object: a small, typed object describing exactly the fields an operation accepts. DTOs stop raw request arrays from leaking into business logic and make the contract obvious. Validate at the edges: check shape and types where data enters (HTTP request, webhook, CSV import, message from a queue), then trust the DTO inside. Business rules such as 'a cancelled order cannot be paid' still live in the domain, because they are not about input shape.

1// Edge: validate and map to a DTO
2export const CreateOrderSchema = z.object({
3  branchId: z.string().uuid(),
4  items: z.array(z.object({ productId: z.string().uuid(), qty: z.number().int().min(1) })).min(1),
5});
6export type CreateOrderDto = z.infer<typeof CreateOrderSchema>;
7 
8// Use case: business logic only, no HTTP
9export class PlaceOrder {
10  constructor(private orders: OrderRepository, private pricing: PricingService) {}
11 
12  async execute(companyId: string, dto: CreateOrderDto) {
13    const quote = await this.pricing.quote(companyId, dto.items);
14    return this.orders.create({ companyId, branchId: dto.branchId, ...quote });
15  }
16}

03Folder structure: by domain, not by file type

Small apps can group by type: all controllers in one folder, all models in another. Past twenty or so features this becomes painful, because one change touches five distant folders. Grouping by domain, sometimes called feature folders or modules, keeps everything about orders together. Each module exposes a small public surface (a service, some types) and hides the rest. Shared, cross-cutting code (auth, logging, money helpers) goes into a shared or core folder. In Laravel you can keep the framework's folders and add domain subfolders inside Models and Services; in NestJS modules map to this naturally.

1src/
2  modules/
3    orders/
4      orders.controller.ts
5      orders.service.ts
6      dto/create-order.dto.ts
7      orders.module.ts
8    menu/
9    loyalty/
10  shared/
11    auth/  logging/  money/
12  config/
13    env.ts

04Separate APIs for web, mobile and admin

One backend often has three audiences. The public website, the mobile app and the admin panel need different response shapes, different auth (cookie session vs token vs staff login with 2FA), different rate limits, and different release cycles: a mobile app version can live on phones for a year, so its API must stay backward compatible. A good pattern is separate route groups or controllers per channel that call the same services. Customer features that are identical for web and mobile can be defined once and mounted under both prefixes. Admin endpoints live in their own group with stricter permissions and audit logging. Version the mobile API explicitly (v1, v2) so you can evolve it safely.

05Monorepos, config and environment

A monorepo keeps several apps and packages in one repository: api, web, admin, mobile, plus shared packages like types, an API client, UI components or ESLint config. pnpm workspaces link packages locally, and Turborepo (or Nx) runs tasks in dependency order with caching, so only what changed is rebuilt and tested. Configuration should follow the twelve-factor rule: code is the same everywhere, environment differs. Read environment variables once at startup, validate them with a schema and fail fast if something is missing. Never commit .env files; commit a .env.example with placeholder values instead.

1# pnpm-workspace.yaml
2packages:
3  - "apps/*"
4  - "packages/*"
5 
6# turbo.json
7{
8  "tasks": {
9    "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
10    "test": { "dependsOn": ["^build"] },
11    "lint": {}
12  }
13}

06Keeping architecture healthy over time

Architecture decays one shortcut at a time. Protect it with rules that tools check: lint rules or dependency-cruiser that forbid one module importing another's internals, TypeScript strict mode, and tests at the service layer. Write short architecture notes (an ADR, Architecture Decision Record) when you make a big choice, so the next person knows why. Start as a modular monolith: one deployable app with clean module boundaries. Splitting into services later is easy if boundaries are clean and almost impossible if they are not. Refactor continuously in small steps rather than planning one big rewrite.

07Enforcing boundaries with tools, not good intentions

A diagram on a wiki does not stop a tired developer at 6 pm from importing another module's internal repository. A failing CI check does. In TypeScript, dependency-cruiser checks import rules across the whole project, and Nx has an enforce-module-boundaries lint rule for workspaces. In PHP, Deptrac defines layers and allowed dependencies, and Pest architecture tests express rules as tests, such as 'controllers may not use the DB facade'. A good first rule set is small: modules may import only another module's public entry file; domain code may not import HTTP or framework classes; shared code may not import from modules. Add the rules to CI in warning mode, fix existing violations, then switch to error. Every new rule should describe a real problem you have had, not a theoretical purity goal.

1// .dependency-cruiser.cjs
2module.exports = {
3  forbidden: [
4    {
5      name: 'no-cross-module-internals',
6      comment: 'Import other modules only through their index.ts',
7      severity: 'error',
8      from: { path: '^src/modules/([^/]+)/' },
9      to: {
10        path: '^src/modules/[^/]+/',
11        pathNot: ['^src/modules/$1/', '^src/modules/[^/]+/index[.]ts$'],
12      },
13    },
14    { name: 'shared-stays-generic', severity: 'error', from: { path: '^src/shared/' }, to: { path: '^src/modules/' } },
15  ],
16};

08Domain modelling: invariants, aggregates and state machines

An invariant is a rule that must always be true: an order total equals the sum of its lines, a refunded order cannot be paid. An aggregate is the cluster of objects that protects such rules together, like an order with its lines, and it is changed only through its own methods, never by editing a line row directly from elsewhere. Status fields are where most bugs hide, so model them as explicit state machines: a table of allowed transitions and one function that applies them. Then 'can a cancelled order be refunded?' has one answer in one place, and you can test every pair. Combine this with value objects for money (integer minor units plus currency) and quantities, and many classes of bugs, such as float rounding or negative stock, disappear by construction.

1type OrderStatus = 'draft' | 'placed' | 'paid' | 'fulfilled' | 'cancelled' | 'refunded';
2 
3const allowed: Record<OrderStatus, OrderStatus[]> = {
4  draft: ['placed', 'cancelled'],
5  placed: ['paid', 'cancelled'],
6  paid: ['fulfilled', 'refunded'],
7  fulfilled: ['refunded'],
8  cancelled: [],
9  refunded: [],
10};
11 
12export function transition(order: Order, to: OrderStatus): Order {
13  if (!allowed[order.status].includes(to)) {
14    throw new DomainError('Cannot move order from ' + order.status + ' to ' + to);
15  }
16  return { ...order, status: to, version: order.version + 1 };
17}

09How modules talk: direct calls, events and read models

Modules must cooperate without knowing each other's insides. Use a direct call to another module's public service when you need an answer now, for example checkout asking pricing for a quote. Use a domain event when something happened and others may react, for example OrderPaid triggering loyalty points, a receipt email and a stock movement; the order module does not need to know who listens. Inside one process, events can be dispatched after commit; once listeners live in another process, write them to an outbox in the same transaction. Avoid two modules writing the same table, because then neither owns the rules. Reports that need data from many modules are a special case: build a read model, a denormalised table updated from events or a nightly job, instead of one giant query that joins every module's tables.

• Command: 'do this' to one owner, may fail, needs an answer.
• Event: 'this happened', zero or more listeners, past tense name.
• Read model: a query-optimised copy, eventually consistent, rebuilt from the source of truth.

10Changing legacy systems: seams, strangler fig and anti-corruption layers

Big-bang rewrites usually fail: the old system keeps changing while the new one chases it. The strangler fig pattern replaces a system piece by piece. Put a routing layer in front, such as a reverse proxy or the router of the new app, move one endpoint or screen at a time, and send the rest to the old code until nothing remains. Before touching risky code, write characterization tests that record what it does today, even if that behaviour looks wrong, so refactoring changes structure and not results. When the new code must talk to the legacy model or an external ERP with strange names and rules, put an anti-corruption layer in between: a translator that maps their concepts into yours, so their mess does not leak into your domain. Feature flags let you switch traffic gradually and roll back instantly.