Software architecture

Architecture is the set of structural decisions that constrain everything built afterward. Choosing how to decompose a system, where to hold state, and how components communicate determines not just initial behavior but long-term maintainability and the cognitive load placed on every contributor.

Module design sits at the core of most architectural debates. The Single Responsibility Principle is widely misapplied as “do one thing” when it actually calls for cohesive grouping under a single accountable concern single-responsibility-the-distorted-principle. Deep modules — small interfaces hiding large implementations — reduce the surface area that both humans and LLMs must understand to work with a system safely ai-likes-deep-modules. In Angular specifically, components bloated with dozens of inputs are a structural smell; the Composite Components pattern moves concerns into directives and sub-components so each piece stays encapsulated a-better-way-to-build-angular-components. Frontend codebases face an analogous tension: organizing by horizontal technical layers (components/hooks/utils) creates coupling across domains, while vertical domain-first colocation improves cohesion and discoverability the-vertical-codebase.

State management is where architectural choices become most consequential under failure. Temporal and its peers represent a class of durable execution platforms that persist workflow state at every step so distributed applications recover automatically temporal. A useful taxonomy breaks durable execution into three forms — stateless functions, sessions, and actors — mapped along a behavior-state continuum, with Temporal, Restate, DBOS, and Resonate implementing each differently the-three-durable-function-forms. Depot’s CI orchestrator applies this idea concretely: AWS Lambda durable functions run a stateful, checkpointed scheduler without a long-lived process building-ci-with-lambda-durable-functions. The 12-factor-agents project argues that AI applications should unify execution state and business state into a single context-window-derived thread, making the whole workflow serializable, debuggable, and forkable from any point humanlayer12-factor-agents.

Agent and multi-agent system design has surfaced a new set of architectural decisions. A data engineering agent evolved through rigid state machine, orchestrator, and single general-purpose agent forms before the team concluded that environmental constraints — tool design, ID keys, context visibility — outperform prompt engineering for reliability dont-prompt-your-agent-for-reliability. Anthropic’s Managed Agents service separates the agent harness, session log, and sandbox into stable interfaces so implementations can be swapped as models improve scaling-managed-agents. A GAN-inspired multi-agent harness — planner, generator, evaluator — overcomes context anxiety and self-evaluation bias during long autonomous coding sessions harness-design-for-long-running-application-development. Reliable agents generally need deterministic control flow encoded in software rather than elaborate prompt chains agents-need-control-flow-not-more-prompts.

Architectural documentation and enforcement matter as much as the decisions themselves. MarkdownLM centralizes architectural rules into a living knowledge base that AI agents query at commit time, blocking non-compliant code at the Git layer before it merges markdownlm. Architectural diagrams fail predictably through unlabeled resources, overloaded master diagrams, and oversimplified behavioral flows — each a symptom of trying to represent too many concerns in one view 7-more-common-mistakes-in-architecture-diagrams. The founders’ playbook notes that without specs and architectural constraints written somewhere an AI can read, each new session re-derives foundational decisions from scratch, causing drift that compounds rather than clears the-founders-playbook-building-an-ai-native-startup.

At infrastructure scale, the wrong abstractions impose costs that accumulate invisibly. Today’s cloud platforms — VMs tied to fixed resources, slow remote block storage, expensive networking — are structurally misaligned with how modern workloads actually run building-a-cloud. Linear’s near-instant performance comes from a coherent set of architectural choices: local-first IndexedDB sync, optimistic updates, aggressive code splitting, and service worker precaching — each decision reinforcing the others hows-linear-so-fast. The through-line across scales is the same: coherent structural decisions compound into systems that are fast, recoverable, and understandable; incoherent ones compound into systems that are none of those things.