Software-Architecture Lesson 1: Software Architecture Lesson 1: One Login Screen, Three Different An

Introduction

Every developer hits the same wall eventually. You build something small, it works great, and then real users show up. Suddenly the thing that felt "done" starts breaking in ways that have nothing to do with a missing semicolon or a bad variable name. Requests slow down. One new feature quietly breaks another. Adding a simple field to a database table turns into a multi-hour ordeal.

At that point, the problem usually isn't the code. It's the architecture — or the lack of one.

This matters a lot for interviews too. Coding interviews test whether you can solve a problem correctly. System design interviews test something completely different: can you reason about how a real system holds together under real conditions — growth, failure, and constraints you don't fully control. Companies ask these questions because production systems don't fail from bad algorithms nearly as often as they fail from bad structural decisions made early and never revisited.

This lesson is the foundation for everything that follows in the series. Before touching Kafka, Kubernetes, or microservices, you need a clear mental model of what architecture even is — because without that model, every technology you learn later just becomes a buzzword you can name but not actually reason about.

Problem Overview

Let's define the four terms people mix up constantly: requirements, architecture, design, and implementation.

• Requirements describe what you need the system to do.
• Architecture describes how the major pieces of the system fit together.
• Design describes the structure within a component — classes, interfaces, patterns.
• Implementation is the actual code you write to make it real.

These are four different altitudes of thinking about the same problem, and most developers only ever practice the bottom one: implementation. That's fine for small projects. It stops being fine the moment a system has more than one moving part.

Example

Take a login screen — something almost every application needs.

• Implementation level: "How do I write the function that checks a password?"
• Design level: "Should this be a service class? A repository? Should I inject the password hasher as a dependency?"
• Architecture level: "Where does authentication actually live? Does every service check credentials itself, or does one dedicated service own identity? How do other services trust that a user is who they say they are? Where do we store tokens? What happens to every other service if the authentication service goes down?"

Same feature. Three completely different sets of questions, and three different people (sometimes the same person, wearing different hats) answering them. This is why "just add a login screen" can mean an afternoon of work or three weeks of infrastructure planning, depending entirely on the scale of the system it's going into.

Intuition

Here's the mental model that makes this click: think about building a house.

Nobody starts a house by laying bricks and figuring out the plumbing as they go. Before a single brick is placed, someone decides where the rooms go, where the doors are, and how water and electricity will actually run through the walls. That decision layer — the one that happens before implementation — is architecture.

An experienced engineer doesn't discover the right architecture by memorizing technology names. They discover it by asking questions in a specific order:

1. What are we building? — requirements
2. What are the major components? — architecture
3. How do they communicate? — APIs, events, queues, databases
4. What happens when something goes wrong? — reliability, security, scaling, recovery

Keep those four questions in your head for every system you design going forward. This series will keep coming back to them.

It also helps to split requirements into two categories:

• Functional requirements — what the system does. A user places an order. A restaurant accepts it. A customer tracks the delivery.
• Non-functional requirements — how well the system needs to do it. Support 100,000 users. Respond within 200ms. Stay up if a server dies. Keep customer data secure.

Functional requirements tell you what to build. Non-functional requirements are what actually drive architecture decisions — because a system built for 100 users and a system built for 10 million users can have identical functional requirements and completely different architectures.

Brute Force Solution

If "brute force" has an architecture equivalent, it's this: build everything as one big application, skip the questions above, and add whatever technology sounds impressive.

Idea: Throw in microservices, message queues, and multiple databases from day one because "that's what big companies use."

Algorithm: Guess at scale requirements you don't have yet. Over-provision for problems that don't exist. Add complexity preemptively.

Advantages: None, really — this isn't a legitimate strategy, it's a trap that looks like foresight.

Disadvantages: Massive operational overhead for a system with no traffic to justify it. Slower development. More failure points. Harder onboarding. You end up debugging distributed systems problems for a product that could have run on a single server.

Time and space complexity: Technically irrelevant here — the cost isn't computational, it's organizational: wasted engineering hours and unnecessary infrastructure spend.

This is the mistake the lesson explicitly warns against: complexity should only get introduced once the actual problem demands it, not because you know the vocabulary.

Optimal Solution

The optimal approach is to let architecture evolve with real, observed constraints — not anticipated ones. Here's what that looks like in stages:

Stage 1 — A single server talking to a database. For a genuinely large number of applications, this is not a starting point to graduate from quickly — it's just enough, and it stays enough until you have evidence otherwise.

Stage 2 — Traffic grows. Add a load balancer and a second server, both still talking to the same single database. You've solved the "one server can't handle the load" problem without touching anything else.

Stage	Bottleneck	Fix Added
1	None yet	Single server + database
2	Server capacity	Load balancer + second server
3	Database reads	Cache layer

Stage 3 — The database becomes the slow part. A cache goes in front of it to absorb repeated reads. Notice what's still missing: no microservices, no message queue, no sharded databases. Each piece was added because a specific, observed bottleneck demanded it — not because it sounded advanced.

The trade-offs at each layer matter too:

• SQL vs. NoSQL: SQL gives strong relationships and real transactions; NoSQL gives flexibility and different scaling characteristics.
• Monolith vs. microservices: a monolith is simpler to build and reason about; microservices let pieces scale and deploy independently, at the cost of real operational complexity.
• Cache: speeds up responses, but introduces invalidation and consistency problems you didn't have before.

None of these are universally "right." They're right for the constraints you actually have.

Python Code

This lesson is conceptual, so instead of a coding solution, here's a lightweight way to encode the four architecture questions as a checklist you can run against any system you're about to design:

from dataclasses import dataclass, field


@dataclass
class ArchitectureChecklist:
    """A minimal framework for the four core architecture questions."""

    system_name: str
    functional_requirements: list[str] = field(default_factory=list)
    non_functional_requirements: list[str] = field(default_factory=list)
    components: list[str] = field(default_factory=list)
    communication: list[str] = field(default_factory=list)
    failure_modes: list[str] = field(default_factory=list)

    def summary(self) -> str:
        return (
            f"System: {self.system_name}\n"
            f"What we're building: {self.functional_requirements}\n"
            f"How well it must perform: {self.non_functional_requirements}\n"
            f"Major components: {self.components}\n"
            f"How they talk: {self.communication}\n"
            f"What happens on failure: {self.failure_modes}\n"
        )


def demo() -> None:
    checklist = ArchitectureChecklist(
        system_name="Food Delivery App",
        functional_requirements=["place order", "accept order", "track delivery"],
        non_functional_requirements=["100k users", "<200ms response", "stays up on server failure"],
        components=["order service", "database", "load balancer"],
        communication=["REST API", "database queries"],
        failure_modes=["failover to backup server", "retry queue"],
    )
    output = checklist.summary()
    assert "Food Delivery App" in output
    assert len(checklist.functional_requirements) == 3
    print(output)


if __name__ == "__main__":
    demo()

Code Walkthrough

• The ArchitectureChecklist dataclass exists purely to force you to answer the four questions explicitly instead of jumping straight to implementation.
• functional_requirements and non_functional_requirements are kept as separate lists because conflating "what it does" with "how well it must do it" is exactly the mistake that leads to premature complexity.
• components and communication map directly to "what are the major pieces" and "how do they talk to each other."
• failure_modes forces you to think about reliability before you've written a single line of business logic — the same way the lesson asks "what happens if the auth service goes down?"
• demo() runs a concrete example (the food delivery app from the lesson) and asserts the structure holds, so this isn't just a data container — it's a runnable sanity check.

Dry Run

Using the food delivery app from the lesson:

1. functional_requirements gets populated with the three core actions — placing, accepting, and tracking an order.
2. non_functional_requirements captures scale and reliability targets — 100k users, sub-200ms latency, uptime under server failure.
3. components lists the order service, database, and load balancer as the major building blocks.
4. communication records that the order service talks to the database via a REST API and queries.
5. failure_modes records the plan for when a server dies — failover and retry.
6. summary() prints all five categories together, giving you a single-page view of the system's architecture before any code gets written.

This is the exercise you should run mentally — or literally, with this script — before starting any new system.

Complexity Analysis

Time complexity: O(1) relative to the size of the checklist — populating and printing five short lists is constant-time bookkeeping, not an algorithmic concern.

Space complexity: O(n) where n is the total number of requirements, components, and failure modes you list — trivially small in practice.

Why this matters: the "complexity" that actually matters in architecture isn't Big-O — it's organizational and operational complexity, which this checklist exists to manage by making you enumerate trade-offs before committing to them.

Alternative Solutions

An alternative to a manual checklist is a formal Architecture Decision Record (ADR) — a short document per major decision capturing the context, the decision, and the consequences. ADRs are heavier-weight than the checklist above but create a searchable history of why a system looks the way it does, which becomes valuable once a team grows beyond one person. For a solo learner working through this series, the lightweight checklist is enough; ADRs become worth adopting once you're working with a team and decisions need to survive turnover.

Edge Cases

• Empty requirements: If you can't fill in functional requirements, you're not ready to think about architecture yet — go back to requirements gathering.
• Only non-functional requirements, no functional ones: A common trap. Knowing you need "high scale" without knowing what the system actually does leads to over-engineering in the wrong direction.
• Single-component systems: If there's only one component, you likely don't have an architecture problem yet — Stage 1 (single server, single database) is still the right answer, and that's fine.
• Undefined failure behavior: A system with no answer to "what happens when something breaks" isn't finished, regardless of how clean the happy path looks.
• Requirements that change mid-design: Non-functional requirements especially (scale targets, latency targets) tend to shift — treat architecture as something that gets revisited, not something decided once and frozen.

Common Mistakes

1. Confusing design with architecture. Deciding between a service class and a repository is a design question, not an architecture question — they operate at different altitudes.
2. Adding technology before the problem exists. Reaching for microservices, Kafka, or Kubernetes because they're familiar names, not because a measured bottleneck demands them.
3. Skipping non-functional requirements. Building only for "what it does" and ignoring scale, latency, and reliability targets until they cause an outage.
4. Treating architecture as a one-time decision. A good architecture at 100 users can be actively wrong at 10 million — revisiting the decision is part of the job, not a failure of the original decision.
5. Assuming there's a "correct" architecture. There's only the right trade-off for your actual constraints — SQL vs. NoSQL, monolith vs. microservices, cache vs. no cache all depend on context, not universal correctness.

Interview Questions

• "Walk me through how you'd design authentication for a system with three separate services."
• "What's the difference between a functional and a non-functional requirement, and why does that distinction matter for architecture?"
• "When would you choose a monolith over microservices, and why?"
• "How would this system's architecture change if traffic grew 100x overnight?"
• "What happens to your design if the database becomes unavailable?"

Similar Problems

• Design a URL Shortener — a classic system design problem that forces you to reason about component boundaries and data storage from scratch (and is this series' next challenge).
• Design a Rate Limiter — tests the "what happens when something goes wrong" question directly, since rate limiters exist purely to protect a system from overload.
• Design a Chat Application — introduces real-time communication and forces a decision between polling, websockets, and message queues.
• Design a Distributed Cache — extends the "cache in front of the database" stage from this lesson into a standalone system design problem.

Key Takeaways

• Architecture, design, implementation, and requirements are four distinct altitudes of thinking, not interchangeable terms.
• The four architecture questions — what are we building, what are the components, how do they communicate, what happens on failure — apply to every real system.
• Non-functional requirements, not functional ones, are usually what drive real architecture decisions.
• Every architecture decision is a trade-off; there is no universally correct answer, only the right fit for your current stage.
• Complexity should be added only when an actual, observed bottleneck demands it — not because you know the technology's name.

Watch the Video

This lesson is easier to absorb with the visual walkthrough of the login screen example and the three-stage system evolution. Watch the full video here: {LINK}

About the Series

This article is part of Fun with Learning Technology, a series built for developers who want to actually understand systems, not just memorize pattern names for interviews. Software Architecture is a multi-part course that starts here, with the fundamentals, and builds gradually into APIs, databases, caching, distributed systems, security, the cloud, and full real-world system design — the same way real systems actually grow.

Call To Action

If this helped clarify what architecture actually means, drop a like on the video on YouTube — it's the easiest way to support the series. Subscribe on YouTube so you don't miss Lesson 2, and consider subscribing to the Substack newsletter for deeper written breakdowns that go alongside each video. Got a question about your own system's architecture? Drop it in the comments — and if this was useful, share it with a developer who's about to hit that "it worked with 10 users" wall.

---