---
name: backend-architecture-core
description: "Shared reference for the backend-architecture cluster: the dependency-inversion boundary (domain → ports → adapters), the layering contract, REST/transport conventions, and the runtime/framework matrix. USE WHEN drawing a module boundary, designing an API, wiring an integration, or planning a deploy — the interlocking rules every backend spoke shares."
cluster: backend-architecture
version: 1.0.0
---

# Backend Architecture Core

Shared model for the `backend-architecture` cluster. The architecture, API, integration, and
deploy spokes all depend on these interlocking concepts — keep them consistent here so no spoke
contradicts another.

## 1. The decision this cluster turns on: dependencies point inward

Every spoke is an application of one rule — **the domain depends on abstractions, never on
infrastructure**. Business logic is pure; frameworks, drivers, and HTTP clients live at the edges
behind ports. This is the ports-and-adapters (hexagonal) boundary, and it is what makes a backend
testable, framework-swappable, and resistant to rot.

```
            (driving / inbound)                       (driven / outbound)
HTTP · CLI · queue · cron ──> [Port] ──> Domain + Use cases ──> [Port] ──> DB · API · bus · cache
        adapters                          (no framework imports)            adapters
```

- **Domain / use case** — pure business rules and orchestration; imports nothing from the framework, ORM, or transport. → `hexagonal-architecture`
- **Port** — an interface the core owns and depends on (e.g. `UserRepository`, `PaymentGateway`).
- **Adapter** — a concrete implementation at the edge (Express handler, NestJS controller, Prisma repo, an outbound API connector). Adapters depend on the core; the core never depends on them.

**Rule:** if removing a library would force you to rewrite a use case, the dependency is pointing
the wrong way — put a port between them.

## 2. The layering contract

| Layer | Owns | Depends on | Spoke |
|---|---|---|---|
| Transport | HTTP/MCP/CLI shape, (de)serialization, status codes | Application | `api-design`, `mcp-server-patterns`, `nestjs-patterns` |
| Application | use-case orchestration, transactions, validation | Domain (via ports) | `hexagonal-architecture`, `backend-patterns` |
| Domain | entities, business invariants | nothing external | `hexagonal-architecture` |
| Adapter (driven) | DB access, outbound calls, caching, jobs | Domain ports | `backend-patterns`, `api-connector-builder` |

Validate at the transport boundary; never trust an inbound request. Keep controllers thin —
they translate transport ⇄ use case, nothing more.

This cluster owns the app-layer view of data — the repository adapter, transactions via ports, the
API over it. A pure DB query, indexing, migration, or engine-tuning ask belongs to `databases-data`.

## 3. API & transport conventions

- **REST**: nouns + plurals for resources, correct status codes, cursor/offset pagination,
  consistent error envelope, explicit versioning, rate limiting on public surfaces. → `api-design`
- **Outbound integrations**: match the host repo's connector layout, config schema, auth model,
  error handling, and registration wiring — one pattern, not two. → `api-connector-builder`
- **MCP**: tools/resources/prompts with Zod-validated inputs; choose stdio vs Streamable HTTP by
  deployment. → `mcp-server-patterns`
- Treat a new public contract or persisted schema as a breaking-change candidate; record the call
  with `architecture-decision-records`.

## 4. Runtime / framework matrix

| Surface | Default | Spoke |
|---|---|---|
| Node service / API routes | Node + TypeScript (Express / Next.js routes) | `backend-patterns` |
| Structured TS backend | NestJS (modules, providers, guards, interceptors) | `nestjs-patterns` |
| Multi-language domain core | TS / Java / Kotlin / Go behind ports | `hexagonal-architecture` |
| AI tool server | MCP TypeScript SDK | `mcp-server-patterns` |
| Release | Docker + CI/CD (blue-green / canary / rolling), health checks, rollback | `deployment-patterns` |

SDK and framework APIs evolve — verify current method names against official docs/Context7 rather
than trusting memory.

## 5. Shared guardrails

- **Dependencies point inward**: domain imports no framework, driver, or HTTP client; edges go behind ports.
- Validate all inputs at the transport boundary; controllers stay thin.
- Match the existing repo pattern; don't introduce a second architecture for one more feature.
- State every contract change (public endpoint, persisted schema, outbound integration) explicitly.
- Capture non-obvious architectural trade-offs as ADRs so the "why" outlives the PR.
- Confirm health checks, rollback path, and env config **before** a production deploy.