Software Architecture
Architecture is the set of significant decisions about how a software system is organized — the boundaries between components, the direction dependencies flow, and the patterns that govern how the system evolves. Get architecture right and the system stays maintainable; get it wrong and every feature becomes harder than the last. This hub covers the major architectural patterns (Clean, Hexagonal, Onion, Layered, Microservices, Event-Driven), decision frameworks for choosing between them, and how AI-generated code interacts with architectural boundaries.
Hub visual
Foundations
- What Is Software Architecture? — The anchor article. Architecture vs. design, the role of the architect, how architectural decisions get made, and why they matter more than most teams think.
Architectural Patterns
Each pattern represents a different set of tradeoffs. These articles cover what each pattern is, when it works, and when it doesn't.
- Clean Architecture — Robert C. Martin's dependency rule: dependencies point inward, business logic doesn't depend on frameworks. Entities, use cases, interface adapters, and frameworks & drivers.
- Hexagonal Architecture — Alistair Cockburn's Ports & Adapters. Application logic isolated from external concerns via clearly defined ports and swappable adapters. The pattern that makes testability natural.
- Onion Architecture — Jeffrey Palermo's concentric layers with the domain at the center. How it relates to Clean and Hexagonal, and when the domain-centric emphasis is the right choice.
- Layered Architecture — The traditional N-tier approach: presentation, business logic, data access. When it works, when it creates tight coupling, and the difference between strict and relaxed layering.
- Microservices Architecture — Independently deployable services organized around business capabilities. Service boundaries, inter-service communication, data ownership, and the operational complexity tax you're signing up for.
- Event-Driven Architecture — Events as first-class architectural citizens. Domain events, integration events, pub/sub, event streaming, and the relationship between event-driven architecture and event sourcing (they're different things).
Decision Making
- Monolith vs. Microservices — The debate that won't end. Why monoliths aren't bad, the modular monolith as a middle ground, practical decision frameworks, and why some companies went micro and came back.
- Architectural Tradeoffs and Decision Frameworks — How to evaluate architectural options systematically: constraint analysis, ATAM, Architecture Decision Records, and common mistakes in architecture decisions.
AI & Architecture
- How AI-Generated Code Impacts Architecture — AI agents don't inherently respect architectural boundaries. How to make architecture agent-friendly, why explicit constraints matter more with AI, and how context engineering prevents architectural drift.
Where This Hub Connects
- Software Design — Architecture defines the big decisions; design fills in the details. DDD, CQRS, event sourcing, and design patterns operate within the architectural boundaries established here.
- AI Code Governance & Quality — Architectural constraints are the rules that governance enforces. Clean boundaries make it possible to write validators that catch violations automatically.
- Context Engineering — Structural context (AST parsing, dependency graphs) is how agents understand your architecture. Context engineering delivers the architectural knowledge agents need to respect boundaries.
- Systems Design & Performance — Architecture and system design overlap: distributed systems fundamentals, consistency models, and caching strategies all connect to architectural decisions.
Suggested reading order
If you're reading this hub end to end, this sequence builds understanding progressively. Each article stands alone, but they are designed to compound.
10
Articles
~80 min
Total read
What Is Software Architecture?
FoundationArchitecture is the decisions you'll regret changing later. Clear boundaries prevent coupling; explicit dependencies enable independence; good structure lets teams work in parallel. It's not just technical—it's about people and how they coordinate.
Clean Architecture: The Dependency Rule and Concentric Layers
FoundationDependencies point inward: frameworks depend on business logic, not the reverse. Business rules know nothing of databases or web frameworks. Test logic without infrastructure. Swap databases without rewriting the domain. Concentric layers enforce this discipline.
Hexagonal Architecture: Ports and Adapters
FoundationDesign your application first, then plug in external systems via ports. Swap a database adapter without rewriting core logic. Test without infrastructure. The hexagon's just a convention; the real power is inverting dependencies so external systems adapt to you.
Onion Architecture: Concentric Layers Without Compromise
Core patternsConcentric layers with domain sacred at the core. Everything else—UI, persistence, external services—is infrastructure that adapts to the domain. Clearer layer guidance than Clean Architecture; explicit about what belongs where.
Layered Architecture: The Traditional N-Tier Pattern
Core patternsThree layers: presentation, business logic, data access. Simple, familiar, works great for straightforward CRUD. But horizontal layering can create coupling across the entire system, making changes expensive. Know when to use it and when to break the pattern.
Microservices Architecture: Breaking the Monolith
Core patternsMicroservices let teams and services scale independently; each owns data and deploys alone. But operational complexity is real. Worth it for large teams and complex domains. Poor boundaries create distributed monoliths with worse problems than monoliths.
Event-Driven Architecture: Decoupling with Events
Applied practiceInstead of Order Service calling Payment Service, it publishes OrderCreated and Payment Service listens. This decouples services, enables async processing, allows parallel reactions. But adds complexity: eventual consistency, event ordering, distributed failure modes.
Monolith vs. Microservices: The Real Tradeoff
Applied practiceMonoliths are simple and fast; microservices are complex but independent. Choose monolith for small teams and early stage. Evolve to services when team size or scaling pressure makes the operational complexity worth it. Many successful companies stay modular monolith.
Architectural Tradeoffs and Decision Frameworks
Applied practiceEvery architecture trades off simplicity, scaling, team autonomy, and complexity. The right choice depends on domain complexity, team size, scaling pressure, and consistency requirements. Use a decision framework to be explicit about constraints instead of copying what others do.
How AI-Generated Code Impacts Architecture
Applied practiceAgents solve problems fast; they don't respect boundaries. Without explicit architectural constraints, AI generates code that works locally but violates boundaries globally. Architecture matters more with AI, not less. Learn what agents break and how to protect against it.
Get Started with Bitloops.
Apply what you learn in these hubs to real AI-assisted delivery workflows with shared context, traceable reasoning, and architecture-aware engineering practices.
curl -sSL https://bitloops.com/install.sh | bash
Get Started
GitHub
DiscordRelated articles
What Is Software Design? The Decisions That Shape Your Code
Design is every deliberate choice you make about how code is structured, not what it does. Good design makes maintenance cheap, changes low-risk, and teams productive. Poor design costs you compounding velocity loss every single sprint.
Architectural Constraints for AI Agents: Enforcing Structural Patterns in Generated Code
Tell agents what your architecture actually is, not as docs they'll ignore, but as constraints they can't violate. Layer boundaries, no circular deps, module isolation—make the rules executable and agents follow them automatically.
Structural Context Using AST Parsing: How Agents See Code Structure
Grep and embeddings make educated guesses. AST parsing gives real answers. It tells agents exactly where functions are called, what imports what, where scopes begin and end. That precision is what separates safe refactoring from blind guessing.
From Experiment to Infrastructure: Building Internal Agent Platforms
Buying works for 1-3 simple agents. At 5+ agents with overlapping needs, you'll likely build. This covers the architecture: tool registry, context management, orchestration, governance. When to build it, what goes in it, how to avoid the pitfalls.
Distributed Systems Fundamentals
Building distributed systems means accepting that networks fail, servers crash, and data gets out of sync. The CAP theorem, consensus protocols, and the eight fallacies of distributed computing show you what's actually possible.
Testing Strategies for Large Systems
Test smart: many unit tests, fewer integration tests, fewer end-to-end tests. Use property-based testing and mutation testing to catch bugs that regular tests miss. The wrong test mix wastes effort without catching real problems.