Software Architecture

Conway's Law says a system's structure ends up mirroring how the teams that built it communicate. Four teams building a compiler tend to produce a four-pass compiler, because each team's boundary becomes an interface in the software.

A functional requirement says WHAT the system does ("users can reset a password"). A quality attribute says HOW WELL it does it — fast, available, secure, maintainable. Quality attributes shape the architecture; functions can usually be implemented in many architectures.

A decision is architecturally significant when it is expensive to change later, affects many parts of the system or many teams, and drives qualities such as performance, security or availability. Routine choices are local and cheap to reverse.

An architectural style is a named, whole-system shape — how the big pieces are split and how they talk (layered, event-driven, microservices). A design pattern is a small, local solution inside one piece (e.g. Strategy, Observer). Style = macro, pattern = micro.

The north-star is the agreed target architecture: a picture of the desired future state and why it is better. Current-state is what actually runs today. The gap between them drives a roadmap of incremental steps.

An ADR is a short document recording one significant architecture decision and why it was made. Nygard's template has four sections: Context (the forces at play), Decision (what we chose), Status (proposed/accepted/superseded), and Consequences (what results, good and bad).

C4 is four zoom levels. Context: your system, its users, and neighbouring systems. Container: the separately runnable/deployable pieces (web app, API, database). Component: the major building blocks inside one container. Code: classes inside one component — usually skipped.

An ADR is a short document capturing one significant architecture decision: the context that forced the choice, the option chosen, and the consequences. ADRs are numbered, dated, kept in version control, and never rewritten — superseded ones stay for history.

Stakeholders are people who care about the system; concerns are what they care about (cost, security, uptime). A viewpoint is a reusable template for describing one such area; a view is the actual description produced by applying that template to your system.

Logical view: functionality and domain structure. Process view: runtime processes, threads, concurrency. Development view: code modules, packages, build units. Physical (deployment) view: mapping software onto machines and networks. Plus Scenarios: key use cases that tie the four together.

Ca counts things outside the component that depend on it (incoming arrows). Ce counts things it depends on (outgoing arrows). I = Ce/(Ca+Ce) runs 0 to 1: 0 = maximally stable (everyone depends on it, it depends on nobody), 1 = maximally unstable.

A quality attribute scenario is a concrete, testable sentence: some source sends a stimulus to the system in a given environment, and the system responds with a measurable result. "Scalable" has no measure, so nobody can agree whether a design meets it.

A fitness function is an automated, objective check that the system still meets a required architectural quality — response time, allowed dependencies, security rules. A unit test checks business behaviour; a fitness function guards a structural or quality property.

Technical debt is a shortcut in design or code that makes today faster but future changes slower. The principal is the work needed to fix the shortcut; the interest is the extra effort every change costs while it stays unfixed.

It means improving one desirable property usually costs another. Example: caching copies of data makes reads fast but copies can be stale; adding redundant servers raises availability but raises cost and operational complexity.

A boundary is a line separating parts of a system that change for different reasons. The interface is the small set of operations other parts may call; the implementation is the hidden internals (data structures, algorithms, storage) they must not touch.

REP: things released together should be usable together. CCP: put classes that change for the same reason in the same component. CRP: don't force users to depend on code they never use. Together they decide component contents.

DIP says high-level policy should not depend on low-level details; both should depend on an abstraction. You define an interface next to the policy, the policy calls it, and the detail implements it — so the arrow now points from the detail to the policy.

Coupling is how much one module depends on another; cohesion is how well the things inside one module belong together. Low coupling means changing one module rarely forces changes elsewhere; high cohesion means each module does one clear job.

Presentation handles input and output (UI, HTTP endpoints). Domain holds business rules and decisions. Infrastructure talks to databases, files, and other systems. Dependencies point one way — upper layers know about lower ones, never the reverse.