software-architecture

Software Architecture

Core Principles

Clean Architecture & DDD

• Domain-driven design with ubiquitous language
• Separate domain entities from infrastructure
• Keep business logic independent of frameworks

SOLID

• Single Responsibility — one reason to change per module
• Open/Closed — extend, don't modify
• Liskov Substitution — subtypes must be substitutable
• Interface Segregation — specific interfaces over general
• Dependency Inversion — depend on abstractions

Code Quality Rules

• Early returns over nested conditions (max 3 levels)
• Functions under 50 lines
• Files under 200 lines — split if longer
• Library-first — search for existing solutions first
• Rule of Three — abstract only when pattern proven 3+ times

Anti-Patterns

• ❌ NIH syndrome — use libraries for auth/state/validation
• ❌ Premature optimization — measure first
• ❌ YAGNI — don't build for imaginary requirements
• ❌ God objects — no files with 50+ unrelated functions
• ❌ Generic names: utils, helpers, common

ADR Template

# ADR-[N]: [Decision Title]
## Status: Proposed | Accepted | Deprecated
## Context: [What problem are we solving?]
## Decision: [What we chose and why]
## Consequences: [Trade-offs and impacts]

Diagrams (Mermaid)

The dashboard renders Mermaid blocks inline. Pick the right shape for the question:

• Component / context — flowchart (LR or TB):

  flowchart LR
      Client --> API[(API Gateway)]
      API --> AuthSvc
      API --> OrderSvc
      OrderSvc --> DB[(Postgres)]
  

• Interaction over time — sequenceDiagram:

  sequenceDiagram
      participant U as User
      participant A as API
      participant D as DB
      U->>A: POST /orders
      A->>D: INSERT
      D-->>A: id
      A-->>U: 201 Created
  

• Data shape / aggregate boundaries — classDiagram or erDiagram.

Embed at most one diagram per ADR — pick the view that makes the decision unambiguous. Skip if a paragraph already does the job.