Skip to main content

The Capstone Deployment Topology

What This Concept Is​

Topology is the picture a stranger can draw of your system after reading one README paragraph. It is the logical layout -- which components exist, how they connect, where state lives -- before any cloud-specific resource name enters the conversation.

For a capstone it almost always reduces to one of three shapes:

  • Three-tier: frontend -> API -> database. One web service, one app service, one data store. Possibly a load balancer in front and a CDN for static assets.
  • Serverless: frontend (CDN or static host) -> API Gateway or HTTP function -> managed data store. No long-running compute you own.
  • Container-based: one or more container workloads (API, worker, maybe a scheduled job) behind an ingress, with managed data.

Topology is not cloud-specific until the next step (modules, services, IAM boundaries). Fixing the logical shape first keeps you from mistaking "service X on cloud Y" for architecture.

Why It Matters Here (In the Capstone)​

The topology determines what you must put in Terraform, what must go in the pipeline, and how many things can fail at 3 a.m. For a solo-operated capstone, every extra box in the diagram is another thing you might have to restart while explaining why during a defense. Every arrow is a timeout to configure and a smoke test to extend.

Topology is also how your reviewer forms a first impression. A single Mermaid diagram with three boxes, each labeled with its managed service, is immediately legible. A diagram with 11 boxes and a bus in the middle invites the question "who operates all of this on a solo capstone budget?" and you will spend the defense defending the diagram rather than the product.

Concrete Example(s)​

Three shapes for the same "task-tracker" capstone:

Three-tier on Cloud Run

Serverless on AWS

Container-based on Fly.io

A Terraform sketch for the three-tier shape, showing that "topology" maps 1:1 to module boundaries:

module "network"  { source = "./modules/network" }
module "database" { source = "./modules/db"      ; network_id = module.network.id }
module "api"      { source = "./modules/api"     ; db_url = module.database.url }
module "frontend" { source = "./modules/frontend" }

Each one is a full, legitimate capstone topology. None includes Kubernetes on purpose -- not because k8s is wrong, but because the capstone rarely rewards the cost of running one.

Common Confusion / Misconceptions​

  • "A proper architecture has seven services and a message bus." For a capstone defended by one person, every extra service is a liability. An event bus that carries one message type is a weakness to defend, not a strength to showcase. If you want to demonstrate event-driven thinking, add one async job with a queue and justify it in an ADR.
  • "Topology equals cloud services." No -- topology is logical. The same three-tier shape maps to Cloud Run+Cloud SQL, to ECS+RDS, or to App Service+Azure SQL. Fix the logical shape first; pick managed services to fill each box second.
  • "Add a worker now, you'll need it later." Usually false. Add the worker the first time a real request type legitimately cannot complete inside a normal HTTP request window. Before that, it is cargo-culted complexity.
  • "I need multi-region for resilience." Multi-region is a capstone trap: real multi-region requires data replication strategy, DNS failover, and per-region cost. Single-region with honest backups is a better story than broken multi-region.

How To Use It (In Your Capstone)​

  1. Draw the topology on paper (or in Mermaid) in under 10 minutes. If you cannot, it is too complex; collapse a service.
  2. Label every arrow with the protocol (HTTPS, gRPC, SQL, queue) and every box with the managed service name on your chosen cloud.
  3. Circle every box you personally own (patches, scaling, failure response). That count is your operational surface.
  4. Name the single point of failure a rollback cannot fix (almost always: the database).
  5. For each async job or worker, write one sentence: "this exists because a synchronous request cannot ___."
  6. Commit the diagram as library/raw/architecture.mmd and render a PNG next to it.
  7. Re-draw whenever a service is added or removed -- the diagram is a contract with your future self and your reviewer.

Adding One Async Job -- The Legitimate Fourth Box​

If the product genuinely needs an async job (image thumbnailing, email send-on-signup, nightly report), add one box with one queue and justify it in library/raw/decisions/002-topology.md. Signs the box is legitimate:

  • the work cannot complete inside a normal HTTP request window (>30s) without blocking the user
  • retries are expected and must not duplicate user-visible side effects
  • the work can be delayed minutes without user impact

Signs the box is theater: "we might want to decouple later," "microservices are best practice," "I'd like to demonstrate event-driven architecture." Theater boxes invent their own failure modes.

How Topology Shapes Everything Downstream​

The topology you pick directly determines:

  • IaC surface: a three-tier topology needs network + db + compute in Terraform; serverless often needs just functions + managed store + IAM; container-based sits in between.
  • Pipeline steps: each long-running service is at least one extra deploy step and at least one extra smoke-test target.
  • Secrets surface: each service reads its own set; fewer services means fewer secret boundaries to maintain.
  • Rollback blast radius: when one service is behind a load balancer and the other is a scheduled job, rolling back the API does not automatically roll back the job.

Decide the topology before you scaffold Terraform, not while you scaffold it.

See also (integrative)​

Check Yourself​

  1. How many long-running services does the topology require you to monitor?
  2. Where is state (data) persisted and who owns backups?
  3. What is the single point of failure that a rollback cannot fix?
  4. If you added one extra service tomorrow, name every downstream concept that would also change (IaC, pipeline, secrets, smoke test, runbook).
  5. Which arrow in the diagram would fail most expensively, and what is the retry story?
  6. What protocol does each arrow carry, and how did you decide?

Mini Drill or Application (Capstone-scoped)​

  1. Three-shape draft. Draw all three topology shapes for your capstone in 20 minutes, each in Mermaid. Pick one.
  2. Ownership ring. Circle every box you personally own. If the count is above 4, justify each circled box in library/raw/decisions/002-topology.md or collapse.
  3. ADR note. In library/raw/decisions/002-topology.md write: chosen shape, three things it lets you not build, one thing it makes harder that you accept, and the Mermaid source embedded.

Source Backbone​

Capstone deployment applies cloud, delivery, and operations material. These books are the source backbone for the delivery decisions.