Skip to content
Skills Library
Programming · Planning

code-architectures

/code-architectures

Use when choosing or structuring how a system is built: hexagonal layering, CQRS, event sourcing, event-driven design, sagas, microservices vs monolith, strangler-fig migration, service timeouts and contracts, CAP and eventual consistency. Not for aggregates or bounded contexts (domain-driven-design), one retry, breaker or outbox (design-patterns), or whether to abstract (engineering-principles).

Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
12
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when choosing or structuring how a system is built: hexagonal layering, CQRS, event sourcing, event-driven design, sagas, microservices vs monolith, strangler-fig migration, service timeouts and contracts, CAP and eventual consistency. Not for aggregates or bounded contexts (domain-driven-design), one retry, breaker or outbox (design-patterns), or whether to abstract (engineering-principles).

Original author description

Use when choosing or structuring how a system is built: hexagonal layering, CQRS, event sourcing, event-driven design, sagas, microservices vs monolith, strangler-fig migration, service timeouts and contracts, CAP and eventual consistency. Not for aggregates or bounded contexts (domain-driven-design), one retry, breaker or outbox (design-patterns), or whether to abstract (engineering-principles).

How it works

  1. Default to the simplest shape that works
  2. What to load
  3. Related skills
  4. Red flags
  5. Completion criteria
Original SKILL.md headings · 63 lines, 798 words
SKILL.md preview
---
name: code-architectures
description: >-
  Use when choosing or structuring how a system is built: hexagonal layering, CQRS, event sourcing, event-driven design, sagas, microservices vs monolith, strangler-fig migration, service timeouts and contracts, CAP and eventual consistency. Not for aggregates or bounded contexts (domain-driven-design), one retry, breaker or outbox (design-patterns), or whether to abstract (engineering-principles).
metadata:
  last_updated: "2026-11-11"
---

# Code Architectures

How a system is divided into parts, how those parts talk, and what each choice costs. This skill covers application architecture (layers, ports and adapters, CQRS), event-driven architecture (event sourcing, events and commands, delivery guarantees, sagas), and distributed architecture (monolith or microservices, boundaries, service communication, consistency). Examples are in TypeScript and Python and continue the Orders and Fulfillment domain from `domain-driven-design`.

## Default to the simplest shape that works

A single deployable with clean internal layers handles most systems. Each step below costs real operational and cognitive weight, so take it only when you can name the problem it solves.

| Signal | Lean toward |
| --- | --- |
| Domain logic tangled with framework, database or HTTP code | Layers with ports and adapters |
| Reads and writes need different shapes or scale | CQRS, starting with plain read-only queries |
| You need a full audit trail, or to rebuild state from history | Event sourcing, for the aggregates that need it |
| Parts must react to each other without importing each other | Domain events, then a broker only if they cross processes |
| Several teams must deploy on their own schedules | Separate services, along bounded-context lines |
| "Microservices are modern" | Stay with a modular monolith |
| Atomic writes needed across services | Keep that data in one service; otherwise a saga |

If the answer is a plain layered monolith, say so and stop. Adopting CQRS, event sourcing or services to look rigorous is the failure `references/anti-patterns.md` catalogs.

## What to load

Open only the file the task needs. [catalog.md](references/catalog.md) lists every architecture, what it is, and where it is covered.

| You are... | Read |
| --- | --- |
| Choosing an architecture, or refreshing what one is | [catalog.md](references/catalog.md) |
| Layering a codebase, placing ports and adapters, wiring a composition root, migrating a legacy service, testing each boundary | [application-architecture.md](references/application/application-architecture.md) |
| Splitting reads from writes, command and query handlers, read models and projections | [cqrs.md](references/application/cqrs.md) |
| Storing events as the source of truth, rebuilding state from a stream, snapshots, upcasting | [event-sourcing.md](references/event-driven/event-sourcing.md) |
| Publishing and reacting to events: events vs commands, choreography vs orchestration, at-least-once delivery, idempotent consumers, ordering, dead letters, schema evolution | [event-driven-architecture.md](references/event-driven/event-driven-architecture.md) |
| A business transaction across services: compensations, the pivot step, orchestration vs choreography, isolation countermeasures | [sagas.md](references/event-driven/sagas.md) |
| Deciding between a modular monolith and microservices, what justifies a split, how to spot a distributed monolith | [monolith-vs-microservices.md](references/distributed/monolith-vs-microservices.md) |
| Drawing service boundaries, database per service, gateway or BFF, strangler-fig migration | [microservices.md](references/distributed/microservices.md) |
| Sync vs async calls, timeouts and retries, contracts, versioning, chatty services | [service-communication.md](references/distributed/service-communication.md) |
| Consistency models, CAP and PACELC, why not distributed transactions, read-your-writes | [distributed-data.md](references/distributed/distributed-data.md) |
| Recognizing and fixing CQRS and event-sourcing cargo-culting, premature service splits, read concerns in the write model, events that are really commands, sagas without a pivot or compensations, chatty services, shared databases | [anti-patterns.md](references/anti-patterns.md) |

## Related skills

- `domain-driven-design`: bounded contexts, aggregates, value objects and domain events. Read it first to find the boundaries these architectures divide along.
- `design-patterns`: the code-level patterns this skill leans on, including dependency injection, outbox, retry, circuit breaker and idempotency key.
- `solid-principles`: dependency inversion, the rule that makes ports and adapters work.
- `engineering-principles`: whether to abstract at all, and how much.

## Red flags

- "Let's use CQRS and event sourcing because it's the proper way." Justify each against the table above or skip it.
- "We'll split it into services now and sort out the boundaries later." Boundaries drawn wrong across a network are far costlier to move than inside a process.
- "The domain imports the ORM." The dependency rule is broken; see the application-architecture reference.
- "This handler updates three aggregates in one transaction." Use events and eventual consistency instead, and a saga when the aggregates live in different services (see sagas.md).

## Completion criteria

- The chosen architecture answers a problem you can state in one sentence.
- Dependencies point inward: domain and use cases import only their own types and ports.
- If you chose ports and adapters, every external dependency sits behind a port, wired in one composition root.
- Where CQRS or event sourcing was added, the cost was justified against the table at the top.
- Where events or sagas were added, consumers are idempotent, each compensable step has an idempotent compensation, and the pivot is named.
- Where a service was split out, the split answered a problem you can name, the service owns its data, and every remote call has a timeout and is safe to retry.
- Any code blocks you wrote parse and run.
Files in this package (12)
  • SKILL.md 6 KB
  • references/anti-patterns.md 4 KB
  • references/catalog.md 3 KB
  • references/application/application-architecture.md 13 KB
  • references/application/cqrs.md 9 KB
  • references/distributed/distributed-data.md 5 KB
  • references/distributed/microservices.md 5 KB
  • references/distributed/monolith-vs-microservices.md 4 KB
  • references/distributed/service-communication.md 6 KB
  • references/event-driven/event-driven-architecture.md 9 KB
  • references/event-driven/event-sourcing.md 11 KB
  • references/event-driven/sagas.md 14 KB

Versions

The database has no other skills named code-architectures.

Database snapshot: 13.11.2026 · package version d28f8e531e5d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100design-patterns
    Use when picking or implementing a named pattern: Strategy, Observer, Adapter, Decorator, Factory, Repository, Unit of Work, Dependency injection, Retry with backoff, Circuit Breaker, Idempotency key, Outbox, Result type. Not for whether to abstract at all (use…
  • 90system-design
    System design patterns for distributed systems: monolith vs microservices decision, modular monolith, event-driven, strangler fig, CQRS, cell-based architecture. Use when choosing architecture, scaling systems, decomposing services.
  • 90software-architect
    Use when the user is deciding, reviewing, or second-guessing a software architecture or tech-stack choice — monolith vs microservices vs serverless vs event-driven, backend language, database type, caching, CQRS/event sourcing, polyglot, or a migration like Strangler Fig.…
  • 100domain-driven-design
    Use when modeling a business domain or structuring a backend around business rules — designing aggregates, entities, value objects, domain events, repositories; separating reads from writes (CQRS); event sourcing; bounded contexts and ubiquitous language; or…
  • 100event-driven
    Event-driven architecture patterns and best practices. Covers Saga, Outbox, CQRS, Event Sourcing, and messaging patterns for distributed systems. USE WHEN: user mentions "event-driven", "Saga", "Outbox pattern", "CQRS", "Event Sourcing", "distributed transactions", "eventual…
  • 90event-sourcing-architect
    Designs event-sourced systems with CQRS, event stores, projections, and eventual consistency patterns. Use when architecting event-driven systems or when the user mentions event sourcing, CQRS, event store, or domain events.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.