System Architecture

This skill guides creation of system architectures that match actual requirements, not imagined future needs. Design real structures with clear boundaries, explicit trade-offs, and appropriate complexity.

The user provides architecture requirements: a system to design, a scaling challenge, or structural decisions to make. They may include context about team size, expected load, or existing constraints.

Before designing, understand the actual constraints:

• Scale: What's the real load? 100 users? 10,000? 10 million? Design for 10x current, not 1000x.
• Team: How many developers? Microservices for a 3-person team is organizational overhead, not architecture.
• Lifespan: Prototype? MVP? Long-term product? Temporary systems need temporary solutions.
• Change vectors: What actually varies? Abstract only where you have evidence of variation.

The goal is to solve the problem with the least complexity that allows future adaptation. Every abstraction, every boundary, every pattern has a cost. Pay only for what you need.

Then design systems that are:

• Appropriate to actual scale and team size
• Easy to understand and modify
• Explicit about trade-offs and constraints
• Deletable—components can be removed without archaeology

Draw Boundaries at Real Differences

Separate concerns that change for different reasons and at different rates.

src/ users/ # User management domain models.py services.py api.py billing/ # Billing domain models.py services.py api.py shared/ # Truly shared utilities auth.py

src/ interfaces/ IUserRepository.py # One implementation exists repositories/ UserRepositoryImpl.py # Wraps SQLAlchemy, which is already a repository services/ UserService.py # Just calls the repository

Make Dependencies Explicit and Directional

Core logic depends on nothing. Infrastructure depends on core.

domain/ # Pure business logic, no imports from outer layers order.py # Order entity with business rules

application/ # Use cases, orchestrates domain place_order.py # Imports from domain/, not infrastructure/

infrastructure/ # External concerns postgres.py # Implements persistence, imports from application/ stripe.py # Implements payments

Follow the Data

Architecture should make data flow obvious. Where does it enter? How does it transform? Where does it exit?

Each step is a clear function/module:

api/routes.py # Request enters validators.py # Validation transformers.py # Business logic transformation repositories.py # Storage serializers.py # Response shaping

Design for Failure

Network fails. Databases timeout. Services crash. Build this into the structure.

    payment = self.payments.charge(order.total)
    if payment.failed:
        self.inventory.release(inventory.reservation_id)  # Compensate
        return Result.failure("Payment failed", retry=True)

    return Result.success(order)

Design for Operations

You will debug this at 3am. Can you trace a request? Can you replay a failure?

@trace def handle_request(request): log.info("Processing", request_id=request.id, user=request.user_id) try: result = process(request) log.info("Completed", request_id=request.id, result=result.status) return result except Exception as e: log.error("Failed", request_id=request.id, error=str(e), context=request.to_dict()) # Full context for replay raise

Avoid premature distribution:

• Microservices before you've earned them → Start with a well-structured monolith
• Event sourcing for CRUD apps → Use simple state storage
• Message queues between functions in the same process → Just call the function
• Distributed transactions → Redesign to avoid them or accept eventual consistency

Avoid abstraction theater:

• Repository wrapping an ORM → The ORM is already a repository
• Interfaces with one implementation "for testing" → Mock at boundaries, not everywhere
• AbstractFactoryFactoryBean → Just instantiate the thing
• DI containers for simple object graphs → Constructor injection is enough

Avoid cargo cult patterns:

• "Clean architecture" with 7 layers for a TODO app → Match layers to actual complexity
• DDD tactical patterns without strategic design → Aggregates need bounded contexts
• Hexagonal ports when you have one adapter → Just call the database
• CQRS when reads and writes are identical → Add complexity when reads/writes diverge

Avoid future-proofing:

• "We might need to swap databases" → You won't; if you do, you'll rewrite anyway
• "This could become multi-tenant" → Build it when you have the second tenant
• "Microservices will help us scale the team" → They help at 50+ engineers, not 4

Your architecture is right-sized when:

1. You can draw it: The dependency graph fits on a whiteboard. If it doesn't, simplify.
2. You can explain it: A new team member understands data flow in under 30 minutes.
3. You can change it: Adding a feature touches 1-3 modules, not 10.
4. You can delete it: Removing a component doesn't require archaeology to find hidden dependencies.
5. You can debug it: Tracing a request from entry to exit takes minutes, not hours.
6. It matches your team: Number of deployable units ≤ number of teams.

Add complexity when you have:

• Measured evidence: Profiling shows the bottleneck, not intuition
• Proven need: The simpler solution has failed or is failing
• Operational capacity: The team can deploy, monitor, and debug the added complexity
• Clear benefit: The gain exceeds the cognitive and operational cost

A checklist before adding architectural complexity:

[ ] Have I tried the simple solution?
[ ] Do I have evidence it's insufficient?
[ ] Can my team operate this?
[ ] Will this still make sense in 6 months?
[ ] Can I explain why this complexity is necessary?

If any answer is "no", keep it simple.

Architecture is discovered, not designed upfront. For complex systems:

1. Start with the obvious structure: Group by domain, not by technical layer
2. Let hotspots emerge: Monitor which modules change together—they might belong together
3. Extract when painful: Only split a module when its current form causes measurable problems
4. Document decisions: Record why boundaries exist so future you knows what's load-bearing

Every senior engineer has a graveyard of over-engineered systems they regret. Learn from their pain. Build boring systems that work.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.