Backend architecture core

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.