software-architecture

name	software-architecture
description	Trigger: how to structure a project, architecture choice, hexagonal, clean arch, DDD, vertical slice, feature folders, cómo estructuro, qué arquitectura. Recommends pattern + directory tree for your stack.
author	Gonzalo Astudillo
version	1.1.0
date	"2026-05-08T00:00:00.000Z"
user-invocable	true

Software Architecture

The Core Idea

Good architecture makes the business logic the center of gravity. Infrastructure (databases, HTTP, queues, email) is a detail — it can be swapped without touching the domain. The patterns in this skill all orbit that principle.

Hexagonal is always the starting point. Not something you graduate to after suffering with MVC. The overhead is minimal and it pays off from the first week. Everything else in this skill adds on top of hexagonal.

Mode: Conceptual vs Design

If the user is asking what something is ("¿qué es hexagonal?", "explain vertical slice") — answer directly and conversationally. No structure needed.

If the user is designing a system ("¿qué arquitectura uso?", "cómo estructuro esto?") — go through the phases below and produce a concrete recommendation.

Phase 1 — Diagnose the Context

Understand the system before recommending. If the context isn't in the conversation, ask:

1. What are you building? (REST API, worker, CLI, SaaS, microservice, monolith)
2. How many distinct domains? (orders, payments, users, inventory — or is it one main thing?)
3. What external integrations exist or are expected? (DB, queues, APIs, email, payments, etc.)
4. Team size? (1-2 devs vs 5+ changes whether extra patterns are worth the overhead)

Skip questions you already know the answers to from context.

Phase 2 — Choose the Pattern

Hexagonal is the base. Everything else is additive.

Scenario	Add to Hexagonal
System with 2+ distinct domains	+ Vertical Slice
Many side effects per action (email, stock, analytics...)	+ EDA in-process
Multiple independent teams or services	+ EDA with message broker
Large app with many service dependencies	+ DI Container

When the user asks "monolith vs microservices" — always recommend a well-structured monolith (hexagonal + vertical slice if multi-domain) first. Only suggest microservices when there are genuinely independent teams with independent deployment needs.

Phase 3 — Load the Relevant Reference

Read only what you need, and focus on extracting information specific to the user's context:

• Hexagonal → references/hexagonal.md
  • Extract: directory structure for their language/framework + port names using their domain vocabulary
• Hexagonal (Frontend SPA — React/Vue/Angular) → references/hexagonal-frontend.md
  • Extract: directory structure for their framework + use case and hook names using their domain vocabulary
• Vertical Slice → references/vertical-slice.md
  • Extract: how to group their specific domains into slices, communication between slices
• EDA → references/event-driven.md
  • Extract: in-process vs broker decision for their scenario + event names from their domain
• DI Container → references/dependency-injection.md
  • Extract: the specific framework they're using (FastAPI, NestJS, pure Python, etc.)
• Pattern comparison or anti-patterns → references/patterns-comparison.md

Phase 4 — Give the Recommendation

Respond conversationally. No formal document headers. Cover these points naturally:

• What and why — the pattern combination and the specific reason it fits their case (2-3 sentences, using their domain language)
• Trade-offs — what this approach costs them concretely
• Directory structure — a concrete tree for their language and framework, using their actual domain names
• Key ports — the main domain interfaces, named after the domain not the technology
• Where to start — the first concrete thing to build

Keep it tight. If they want to go deeper on a pattern, you can expand or point to the reference.

Output Contract

Phase 4 returns exactly 5 elements (conversational, no doc headers):

1. Pattern + reason — which combination and why it fits this specific case (use their domain language)
2. Trade-offs — what this costs concretely (complexity, overhead, learning curve)
3. Directory tree — concrete structure for their language/framework using their actual domain names
4. Key ports — 3–5 main domain interfaces named after the domain, not the technology
5. First step — the single first thing to build

Gotchas

• Never recommend microservices first — always monolith (hexagonal + vertical slice) unless teams are genuinely independent
• Directory trees that use generic names (services/, repositories/) don't help — use the user's actual domain vocabulary
• Jumping to DI container before the structure is stable creates over-engineering — DI goes last

Refactoring an Existing Codebase

When restructuring a working system, the priority is to never break production:

1. Find the worst coupling (usually: business logic inside controllers, ORM models with domain rules)
2. Extract domain logic into plain objects first — no framework, no DB
3. Define ports around the things that bleed into the domain
4. Replace concrete calls with port calls one adapter at a time
5. Wire DI last — only after the structure is stable

Incremental migration, never a big-bang rewrite.