Software Architecture

This skill covers structure above the class level. For code-level quality, use the clean-code skill. For judging whether a design is good at any level (economics of change, minimalism, cohesion and coupling, non-functional requirements), use the software-design skill. Read and update the living diagram with the architecture-diagram skill.

How to approach

1. Clarify the drivers first. Establish the following, and ask about any that are unknown and would change the answer:
   • functional scope
   • quality attributes: scalability, availability, latency, consistency, security, maintainability, and cost
   • constraints: team size and skills, deadlines, and existing systems
2. Propose the simplest architecture that meets the drivers. For significant decisions, present two or three options with their trade-offs.
3. Record significant decisions as ADRs.
4. Define how success is verified, using metrics and fitness functions such as ArchUnit rules, latency SLOs, and deploy frequency.

Core principles

• Dependency rule: source dependencies point inward toward domain policy. The domain has no framework imports.
• Separation of concerns: high cohesion within modules, low coupling between them.
• Explicit boundaries and contracts: each module hides its internals behind a published interface.
• Decompose by volatility: isolate what is likely to change. Don't abstract everything.
• Trade-offs: every choice gives something up. Name what you give up.
• Reversibility: prefer decisions that are cheap to undo, and delay irreversible ones until the last responsible moment.
• Conway's law: align boundaries with team ownership.

Structural styles

• Layered (controller, service, repository): fine for CRUD. Watch for leaking layers and anemic domains.
• Hexagonal / clean architecture: a domain core, ports (interfaces) defined by the core, and adapters for web, persistence, and messaging.
• Package by feature over package by layer.
• Modular monolith: the default for new products and small teams. Enforce module boundaries with tooling.
• Microservices: use only when independent deployability, independent scaling, or team autonomy justifies the operational cost.

Domain-driven design

• Bounded contexts each have their own ubiquitous language.
• Map how contexts relate: upstream and downstream, anti-corruption layer, shared kernel.
• An aggregate is a consistency boundary. Keep aggregates small and reference other aggregates by ID.
• Use domain events for reactions across aggregates and contexts.

Microservices checklist

• Boundaries:
  • Draw boundaries along bounded contexts and business capabilities, not technical layers.
  • Splitting by database table or noun is a smell.
• Data:
  • Each service owns its database.
  • No shared tables and no cross-service joins.
• Communication:
  • Use synchronous calls (REST or gRPC) for queries that need an immediate answer.
  • Use asynchronous events for propagating changes and decoupling services.
  • Avoid long chains of synchronous calls.
• Consistency:
  • Eventual consistency is the default.
  • Use sagas for multi-service workflows, choosing choreography or orchestration deliberately.
  • Use a transactional outbox for reliable event publishing.
  • Make consumers idempotent.
• Resilience:
  • Set a timeout on every remote call.
  • Retry with backoff and jitter, and only for idempotent operations.
  • Use circuit breakers, bulkheads, and fallbacks.
• APIs:
  • Version APIs and make changes backward-compatible by default.
  • Use consumer-driven contract tests.
• Observability:
  • Structured logs with correlation and trace IDs.
  • RED and USE metrics.
  • Distributed tracing.
  • Health and readiness probes.
• Security:
  • Authenticate at the edge and authorize in each service.
  • Give services their own identity for service-to-service calls (mTLS or JWT).
  • Keep secrets in a secrets manager.
• Delivery:
  • Each service has an independent pipeline.
  • Configuration is externalized.
  • Deploys have zero downtime.
• Smells:
  • Distributed monolith: services must deploy together.
  • Chatty services.
  • Shared libraries that carry domain models.
  • Shared database.
  • Nanoservices.

Cross-cutting concerns

Handle each consistently across the system, through a platform library, gateway, or sidecar:

• caching
• configuration
• logging
• auth
• rate limiting
• feature flags

Architecture decision record template

Store ADRs in docs/adr/NNNN-title.md:

• Title
• Status: proposed, accepted, or superseded
• Context: forces and constraints
• Decision
• Alternatives considered
• Consequences: positive and negative

Output formats

• For a design, give these in order:
  1. the drivers
  2. the options and their trade-offs
  3. a recommendation
  4. a C4 context or container diagram in Mermaid
  5. risks and open questions
  6. ADRs for the key decisions
• For a review, order findings by impact: data integrity and correctness, then reliability, then scalability, then maintainability. For each finding, give:
  • the principle it violates
  • the consequence
  • the recommended change
  • the cost of making the change

Spring Boot notes

• Enforce module boundaries with Spring Modulith or ArchUnit.
• Use Spring Cloud Gateway at the edge.
• Use Resilience4j for timeouts, retries, and circuit breakers.
• Use Micrometer with OpenTelemetry for metrics and tracing.
• Use Spring Cloud Stream or Spring Kafka for events, with an outbox table for reliable publishing.