Application Architecture

Default to the simplest structure that works. Add architectural patterns only when complexity demands them -- not before.

Every decision tree below starts with a YAGNI gate. If the gate tells you to stop, stop. Patterns exist to manage complexity; applying them to simple systems creates the complexity they were designed to solve.

Read the relevant reference file when you need deeper trade-off analysis, criteria, and pseudocode examples.

Architectural Smell Table

When reviewing existing code, use this table to identify which decision point is relevant. A smell is not always a problem -- check the YAGNI gate before recommending changes.

1. Business Logic Structure

The question: Where does business logic live, and how is it organized?

YAGNI Gate

Simple CRUD service with <5 business rules and minimal conditional logic? -> Transaction Script (procedural functions, one per operation). Stop here. No domain model, no service layer. Add structure when the transaction scripts start duplicating logic or growing beyond what one developer can hold in their head.

Decision Criteria

Progression: Most applications start as Transaction Script. When scripts duplicate logic or conditionals multiply, extract a Domain Model. When multiple interfaces need the same operations, add a Service Layer. When infrastructure coupling becomes painful, consider Hexagonal Architecture.

Implementation: See software-design for composition and interface design. See python-design for Protocol-based port definitions.

-> Read references/business-logic-structure.md for detailed trade-offs and pseudocode.

2. Data Access Strategy

The question: How does the application read and write persistent data?

YAGNI Gate

Using an ORM with straightforward queries against <10 tables? -> Use the ORM directly. No Repository, no Gateway abstraction. The ORM is your data access layer. Add abstractions when you need to test domain logic without a database, or when query logic starts duplicating across the codebase.

Decision Criteria

Key distinction: Repository abstracts collections of domain objects. Gateway abstracts access to a specific resource. A Repository contains domain logic (query specifications, consistency rules); a Gateway is a thin wrapper over an external system.

Implementation: See python-design for Protocol-based repository interfaces. See api-design for Gateway API surface design.

-> Read references/data-access-strategy.md for detailed trade-offs and pseudocode.

3. Domain Modeling

The question: How should domain concepts be represented in code?

YAGNI Gate

All data is flat, with no invariants to enforce and no behavior beyond CRUD? -> Use plain data structures (structs, dicts, dataclasses). No Value Objects, no Aggregates. Domain modeling adds value when there are business rules that data structures alone can't enforce.

Decision Criteria

Aggregate boundaries: The most common mistake is making aggregates too large. An Aggregate is a transactional consistency boundary, not a containment hierarchy. Ask: "What data must be consistent within a single transaction?" That's your aggregate. Everything else references by ID, not by direct object reference.

Implementation: See python-design for frozen dataclass (Value Object), Protocol (entity interfaces), and Enum (Special Case) patterns.

-> Read references/domain-modeling.md for detailed trade-offs and pseudocode.

4. Cross-Boundary Communication

The question: How does data cross process, service, or team boundaries?

YAGNI Gate

Single-process monolith where all code is in the same deployment? -> Call functions directly. No DTOs, no facades, no anti-corruption layers. These patterns solve problems that arise from distribution, not from complexity.

Decision Criteria

DTO direction: DTOs serve the consumer, not the producer. Design them around what the caller needs, not what the database returns. A DTO that mirrors your ORM model is not a DTO -- it's a leak.

Implementation: See api-design for field naming, pagination, and error handling in DTOs. See software-design for Separated Interface patterns at boundaries.

-> Read references/cross-boundary-communication.md for detailed trade-offs and pseudocode.

5. State Changes and Side Effects

The question: How should the system handle writes, side effects, and derived actions?

YAGNI Gate

Simple request-response where each write hits one table and triggers no downstream effects? -> Let your ORM handle transactions directly. No events, no CQRS, no event sourcing. These patterns exist for systems where a single write triggers multiple independent reactions or where the read model diverges from the write model.

Decision Criteria

Escalation ladder: Direct ORM transactions -> Unit of Work (if ORM doesn't cover it) -> Domain Events (when side effects appear) -> CQRS (when read/write models diverge) -> Event Sourcing (when event log is source of truth). Each step adds significant complexity. Justify every escalation.

Implementation: See software-design for pure functions (keeping side effects at boundaries). See test-design for testing event-driven architectures.

-> Read references/state-changes-side-effects.md for detailed trade-offs and pseudocode.

6. Concurrency, Load & Infrastructure Realism

The question: How should the application handle threads, async I/O, load spikes, and infrastructure choices?

YAGNI Gate

Single-threaded, low-traffic service with no blocking I/O contention and no infrastructure complexity? -> Do nothing here. Concurrency primitives, async runtimes, and distributed infrastructure all carry real costs. Add them only when a measured problem demands them.

Decision Criteria

Substrate note: when a layer spawns endless workaround layers (framework churn, adapter chains), the defect is usually the layer beneath. Fix the source. This extends the Anti-Corruption Layer guidance in §4: an ACL is appropriate for external systems you don't control; for systems you do control, fix the source instead.

Events note: for sequential actions, write serial code or use a thread. For reactive patterns, decide exactly when in the execution cycle the handler fires before reaching for an event system. This reinforces the Domain Events caution in §5.

-> Read references/concurrency-and-load.md for thread/async trade-offs, mutex discipline, queueing theory, and infrastructure minimalism.

References