30 Architectural Principles from a Senior Architect

Srinath, a senior software architect, Apache Axis2 co‑founder, and member of the Apache Software Foundation, shares thirty architectural principles he has distilled from years of experience in distributed systems.

Basic Principles

Principle 1: KISS (Keep it simple, stupid) – solve problems with the simplest solution possible.

Principle 2: YAGNI (You Aren’t Gonna Need It) – only implement features when they are truly needed.

Principle 3: Crawl, walk, run – first get a working version, then iteratively improve and optimize.

Principle 4: Automate testing – the only way to ensure stable, high‑quality products.

Principle 5: Consider ROI – invest effort only when it pays off.

Principle 6: Know your users – balance effort with user needs, avoiding over‑engineering.

Principle 7: Design and test features in isolation to avoid coupling and bottlenecks.

Principle 8: Avoid unnecessary flashiness; keep designs straightforward.

Feature Selection

Principle 9: Embrace MVP – build a minimal viable product, release early, and iterate based on feedback.

Principle 10: Implement as few features as possible; remove or defer doubtful ones.

Principle 11: Defer work until it is actually requested, unless it impacts core processes.

Principle 12: Say no to customers when necessary and propose better solutions; guide users rather than follow trends.

Server Design and Concurrency

Principle 13: Understand the full stack – hardware, OS, language – and minimize I/O calls.

Principle 14: Apply Amdahl’s law; use synchronization only when required and keep lock‑holding time minimal.

Principle 15: In non‑blocking, event‑driven architectures, never block threads with I/O.

Distributed Systems

Principle 16: Stateless systems are scalable and easier to manage.

Principle 17: Strive for exactly‑once delivery, but accept at‑least‑once with idempotent operations.

Principle 18: Make operations idempotent to simplify recovery.

Principle 19: Know the CAP theorem; use compensating transactions instead of distributed RDBMS transactions when possible.

Principle 20: Distributed consistency does not scale; keep node count modest (ideally ≤ 8).

Principle 21: Latency and failures are inevitable in distributed environments.

User Experience

Principle 22: Understand user personas and their technical background; tailor UI accordingly.

Principle 23: The best product needs no manual.

Principle 24: When faced with a binary choice, provide a sensible default rather than exposing every option to users.

Principle 25: Always set reasonable default values for configurations.

Principle 26: Provide example values for configurations to avoid confusion.

Principle 27: Configuration values must be understandable and directly editable by users.

Principle 28: Reject unknown configuration values with explicit errors.

Difficult Issues

Principle 29: New languages rarely simplify problems; avoid switching languages without strong justification.

Principle 30: Complex drag‑and‑drop UIs are costly; only attempt them with sufficient resources.

Conclusion

Architects should act as gardeners—pruning, guiding, and facilitating discussion rather than dictating designs. A widely accepted principle list provides a common anchor for debates and helps junior architects learn the trade.