Skip to content
Elements of Scalable Web Applications
ContentsProjectCasesDemos

Demo showcase#

Work through one module at a time: change the inputs, inspect what responds, and connect the result to your own project. Repeat a scenario until you can explain the trade-off without relying on the interface.

Modules
26
Runtime
Browser
Mode
Self-guided
01

Scalable development

Implementation discovery lab
Ready

Implementation discovery lab

Find a direction worth building three times

The behavior is shared. Your interpretation, stack, architecture, and experiment are yours to choose.

0/4 anchors Begin with the character of your implementation.
Interpret the common brief

Keep the required behavior, but decide what kind of product your version feels like. There is no preferred interpretation.

Need a starting point? Borrow a lens, then change anything you dislike.
Keep the common workspace capability, but choose its meaning and vocabulary: a project, room, run, campaign, class, site, or something else.
Map the required lifecycle to something concrete. It could be a task, job, case, experiment, scene, agent assignment, or repair.
Choose one user and one moment to optimize. This gives the interface a point of view without adding more required features.
Choose the technical material

Pick tools that support a learning question or a practical constraint. Familiar and unusual stacks are equally valid.

Explore a stack family These are prompts, not recommended answers.
Name the primary runtime and web framework. Normally your group keeps this family across all three builds so the AI workflow is easier to compare.
Give the system a shape

Decide where the important boundaries sit. The goal is an explainable first hypothesis, not a final architecture.

Another group must be able to run the project. Name the supported local, container, cloud, edge, or other path early.
Choose what you want to learn

A useful experiment is a question, not an extra pile of features. Keep the common core small enough that you can examine the result.

Ask something the implementation can teach you: about the stack, architecture, local model, developer experience, performance, portability, or resource use.

Your current hypothesis

Implementation direction

This is a conversation starter, not a commitment. Revise it after trying the local model and inspecting the first evidence.

Decision anchors

    Questions to discuss

      02

      Scalable development

      Constraint feedback loop
      Ready

      Constraint learning loop

      Turn evidence into project memory

      Round 1 · constrain the change Task: add CSV export to the browser event list.
      1. 01Constrainstate what must remain true
      2. 02Generateproduce a bounded candidate
      3. 03Validatecompare evidence with intent
      4. 04Revisemake the learning explicit
      5. ↩ revision constrains the next round

      Browser fixture · /events

      Three events are visible

      ● ● ● Events
      Title Location
      Architecture clinic Room 204
      Build, measure, learn Main hall
      API "office hours" Online
      Change request

      “Make the Export CSV button download exactly these visible rows.”

      Candidate boundary

      Constraints sent to the generator

      Candidate + evidence

      No candidate generated

      Round 1
      Choose the constraints the candidate should receive.
      • —Browser testCan clicking Export create a download?
      • —Changed-files checkDid the patch stay inside export.ts and export.test.ts?
      • —CSV assertionAre commas and quotation marks escaped?

      Generation is not evidence. Generate a candidate, then run the checks.

      03

      Scalable development

      Deterministic boundary lab
      Ready

      Deterministic boundary lab

      Give the agent a map

      Goal: ship a safe change The agent can choose only events enabled by the statechart.
      01

      Agentic shell

      One goal can produce different valid routes through the model.

      Current state active.planning
      Available next events
      02

      Deterministic core XState v5 + ELK

      Hierarchy shares rules; parallel regions represent simultaneous facts.

      Change delivery statechart Planning leads to implementation and parallel verification. Failed tests or requested changes return to implementation. Successful verification enables release, while cancellation can leave the active hierarchy at any point. active compound state initial planning initial implementing verifying parallel state checks compound state running initial passed review compound state waiting initial reviewing approved ready released cancelled RELEASE: active.ready to released RELEASE CANCEL: active to cancelled CANCEL PLAN_APPROVED: active.planning to active.implementing PLAN_APPROVED PATCH_READY: active.implementing to active.verifying PATCH_READY TESTS_FAIL: active.verifying.checks.running to active.implementing TESTS_FAIL REQUEST_CHANGES: active.verifying.review.reviewing to active.implementing REQUEST_CHANGES both regions final: active.verifying to active.ready both regions final TESTS_PASS: active.verifying.checks.running to active.verifying.checks.passed TESTS_PASS REVIEW_START: active.verifying.review.waiting to active.verifying.review.reviewing REVIEW_START APPROVE: active.verifying.review.reviewing to active.verifying.review.approved APPROVE
      Active configuration active.planning
      Why this matters

      The parent state exposes one shared cancellation rule.

      Inspect or export the executable model

      Copy the XState machine and paste it into Stately Sketch to inspect or simulate the generated diagram.

      Open Stately Sketch ↗
      Observed events
      1. No events sent yet.
      04

      What is scalability?

      Scalability dimensions lab
      Ready

      Scalability dimensions lab

      Choose what must scale first

      Pick project pressures Scalability is not one axis. Different growth pressures stress different parts of the system.

      Event tracker scenario

      Establish project

      A small event-oriented app records check-ins, status changes, sensor readings, or workflow events. Choose the pressures that would matter if the project succeeded.

      Growth pressures

      Dimension radar

      Primary trade-off

      Strongest dimension
      -
      Stressed part
      -
      Watch for
      -

      Choose pressures to see which scalability dimension matters first.

      05

      Architecture

      Boundary trace
      Ready

      Architecture boundary trace

      Trace one event request

      Trace POST /events Architecture becomes concrete when a request crosses boundaries.

      User action

      Room A Check in 09:15
      You tap "Check in"

      The browser turns that tap into a `session.checked_in` event for Room A.

      Browser sends POST /events
      type: session.checked_in entity: room-a time: 09:15

      What happens around the request?

      Request path

      Trace analysis

      Inspect boundary

        Architecture pressure

        Request path
        -
        Highest risk
        -
        Rules to implement
        -

        A local function call becomes a distributed workflow once the browser, server, network, and storage can disagree.

        Trace brief

        Boundary brief

        06

        Architecture

        Cache decision lab
        Ready

        HTTP reuse control room

        Where does the next response come from?

        Fresh cache hit shared cache

        Every case begins after one successful response. Change its policy and age, then trace the next request without changing the URL.

        Choose the response profile
        Stored response policy Versioned asset
        stored fresh for 365 days timeline: 400 days
        01Browser cache
        02Shared cache
        03Origin
        Decision trace cache → response
          Response source
          Browser waits?
          Origin body bytes
          Representation used

          Architectural reading

          Reuse the fingerprinted response

          Policy rule immutable means the URL carries the version

          The trace models compliant HTTP cache behavior at a teaching scale. Real cache keys, platform overrides, authorization, request directives, and invalidation rules must be verified in the deployed path.

          07

          Architecture

          Web architecture lens
          Ready

          Two architectural decisions

          Compose a web request

          SSR × MPA delivery × interaction
          These labels answer different questions.

          SSR, ISR, and CSR describe where and when a view is produced. MPA, HDA, and SPA describe how the browser moves to later application states.

          01 Where and when is the view produced?
          02 How is the next state presented?
          /activity
          Work activity Today
          Rendered now
          • 09:15Design review
          • 10:30API implementation
          Ready to trace the interaction.
          Browser requests
          2
          Returned UI
          Complete HTML
          Update scope
          Whole document
          Local draft
          Reset
          Modeled response transfer after click
          ≈18 KB complete document

          Illustrative compressed responses. Headers and the common POST body are excluded; CSR assumes a 45 KB JavaScript bundle on a cold cache.

          6 requests · ≈54 KB responses · 3 document replacements

          What this combination means

          SSR + MPA

          Initial document
          After the POST
          Freshness pressure
          Client responsibility

          08

          Architecture

          Client activation lens
          Ready

          Browser activation cutaway

          What wakes up before the click?

          Hydration component tree

          The server returns the same useful event page in every case. Change only how browser behavior becomes available, then trace the first attempt to record an event.

          Choose the activation boundary
          /activity server HTML
          01 · header Work activity HTML
          02 · filters
          HTML
          03 · event feed
          1. 09:15 Design review
          2. 10:30 API implementation
          HTML
          04 · record form
          HTML
          05 · analytics
          HTML

          The document is visible. Inspect which behavior arrived with it.

          Network and execution trace Before interaction
            Initial application JS
            ≈54 KB
            Work before interaction
            Replay 5 regions
            JS at first action
            0 KB
            State crossing boundary
            Initial props snapshot

            Architectural reading

            Replay the application

            Pressure moved to initial client work

            Illustrative compressed JavaScript values for one teaching model. They show where work moves; they do not rank frameworks.

            09

            Architecture

            API contract lens
            Ready

            Contract topology lab

            Where does the client learn what it can do?

            Resource HTTP address + representation

            Hold the domain intent constant. Move between contracts to see which facts live in client code, which arrive from the server, and where change creates coordination.

            Choose the interaction style
            Fixed user intent Start work on item 42
            Required view state · title · workspace · next actions
            Wire contract HTTP exchange
            01 Client 02 Contract 03 Domain 04 Result
              Observed result Not sent yet

              Run the exchange to see what each boundary actually does.

              Knowledge ledger before the request

              C Client carries

                S Server publishes

                  Effect of requested field
                  Interaction shape
                  Discovery
                  Cache unit
                  Pressure lands on

                  Architectural reading

                  Coordinate around resources

                  Do not confuse HTTP-shaped with full REST

                  This is a structural comparison, not a ranking. Authentication, authorization, retries, observability, and versioning still apply in every mode.

                  10

                  Benchmarking

                  Tail latency simulator
                  Ready

                  Tail latency simulator

                  An average can hide slow requests

                  Choose a claim before measuring A deterministic teaching model of 60 POST /events requests. It does not contact a server.

                  01 / Define the run

                  Workload controls

                  Predict the result

                  02 / Read the distribution

                  Completion time per request

                  Typical Slow path

                  Make a prediction, then run the workload.

                  0 ms —
                  Average
                  —
                  p50
                  —
                  p95
                  —
                  Slowest
                  —

                  A benchmark should test an explicit claim. Which measurement do you expect to cross the objective?

                  11

                  Benchmarking

                  Browser performance workbench
                  Ready

                  Browser performance workbench

                  Repeat one interaction before trusting it

                  Ready for five local runs Measurements come from this browser and this device. No data leaves the page.

                  01 / Define the workload

                  Event-list interaction

                  Update strategy

                  Predict first: which strategy has the shorter total time, and which has the shorter uninterrupted slice?

                  02 / Inspect the runs

                  Time until the next painted frame

                  Local evidence

                  Run the same interaction five times to reveal its distribution.

                  Median total
                  —
                  Fastest
                  —
                  Slowest
                  —
                  Median longest slice
                  —

                  One run is an observation. Repeated runs show whether that observation was typical.

                  12

                  Benchmarking

                  Queue balance lab
                  Ready

                  Little’s Law · L = λW

                  Check whether the queue tells one story

                  Measurements agree

                  01 / Define the observation window

                  10 = 20 × 0.5 expected work in progress = arrival rate × time in system
                  Expected L
                  10.0
                  Observed L
                  10
                  Gap
                  0.0

                  The three averages are mutually consistent for a stable observation window.

                  13

                  Benchmarking

                  Model evaluation lab
                  Ready

                  Challenge eval lab

                  Compare two model attempts on the same task

                  Score the attempts The result is local to this task set, not a universal model ranking.

                  Start with one task from the work you actually do in Challenge. The eval is only meaningful if the task represents your real project work.

                  Input context

                  Both models receive the same context, task, and required output shape.

                  Rubric

                  Use the same rubric for both pasted outputs.

                    Paste and score attempts

                    Run the shared prompt with two models, paste each output, then score against the rubric. Use samples only when demonstrating the workflow.

                    Compare the local result

                    Add deterministic checks where possible, then report a narrow claim about this task set.

                    Local conclusion

                    Score both attempts to see what this tiny eval can and cannot claim.

                    Comparison

                    Model Quality Checks Latency Cost
                    14

                    Benchmarking

                    Observability signal picker
                    Ready

                    Observability signal picker

                    Choose evidence for one symptom

                    Pick a symptom Your goal is not to collect everything. Choose signals that answer your operational question.

                    Which signals would let you explain why summaries are behind?

                    Candidate signals

                    What the selected signals answer

                    15

                    Benchmarking

                    OpenTelemetry trace explorer
                    Ready

                    OpenTelemetry trace explorer

                    Follow one request, span by span

                    Slow storage path found A client-only trace simulation. No telemetry is collected, exported, or stored.
                    Applicationstarts + ends spans → OTel SDKbatches span records → Collectorreceives OTLP + routes → Backendstores + explores

                    The rows below are spans from one trace. Select a row to inspect the record the SDK could include in a batched OTLP export.

                    Trace

                    POST /events · 286 ms

                    4bf92f3577b34da6a3ce929d0e0e4736

                    Select any span row to inspect its telemetry record.

                    0 ms143 ms286 ms

                    Selected span

                    store event

                    Duration
                    184 ms
                    Status
                    Unset
                    Source
                    Manual

                    Attributes

                    Inspect conceptual span record

                    This keeps the important structure visible. Literal OTLP/JSON adds typed values and a more verbose envelope, and a real export may contain several spans.

                    This child span explains most of the end-to-end latency. The trace narrows the investigation; it does not prove the underlying cause.

                    16

                    Friction

                    Workflow loop
                    Ready

                    Workflow loop lab

                    Trace a human-agent change loop

                    Choose the workflow shape Friction appears in feedback, review packages, and correction loops.

                    Workflow shape

                    The human reads, edits, tests, and prepares the review package.

                    Loop map

                    Feedback evidence

                    Score what the workflow can prove before a human reviewer reads the diff.

                    Loop pressure

                    Likely correction loops
                    0
                    Human review load
                    0 min
                    Automation leverage
                    -

                    Strong feedback turns review comments into faster local signals.

                      Review package

                      Review package

                      17

                      Friction

                      Friction audit
                      Ready

                      Friction audit lab

                      Find the slow part of a small change

                      Score the change path Friction compounds when setup, tests, review, and context fail.

                      Change request

                      A new event type needs one required field in the UI, API, storage, and summary view.

                      Likely touch points

                        In this mode, you do the search, edit, test, and review work manually.

                        Estimate basis

                        The agent multipliers are bounded by published developer productivity studies: a constrained Copilot task was 55.8% faster, while a 2025 open-source field experiment found experienced developers 19% slower with AI tools on mature projects.

                        • Peng et al. 2023
                        • Becker et al. 2025
                        • Zhang et al. 2023

                        What slows this down?

                        Change process

                        Audit result

                        Estimated change cost
                        0 min
                        Likely rework loops
                        0
                        Agent rework risk
                        -
                        Largest source
                        -

                        Choose one feedback loop

                        Everyone starts from the same runnable project and known data.

                        Impact

                        Before
                        0 min
                        After
                        0 min
                        Time saved
                        0 min

                        Pick a feedback loop to see what repeated work it removes.

                        Friction audit artifact

                        Friction audit artifact

                        18

                        Reality

                        Changed assumptions map
                        Ready

                        Reality pressure map

                        Map changed assumptions to failures

                        Choose changed assumptions A pressure map connects new reality to the first binding limit and the recovery options prepared for it.

                        Establish baseline

                        Users One small group

                        People submit events while the app is online and calm.

                        Data Few event types

                        The dashboard can query the same database used for writes.

                        Operations Manual diagnosis

                        Logs and local testing are enough to explain most problems.

                        Changed assumptions

                        Pressure map

                        First signal

                        Assumptions changed
                        0
                        Primary pressure
                        -
                        Most stressed part
                        -

                        Pick at least one changed assumption to reveal the first likely failure.

                        Pressure brief

                        Challenge pressure brief

                        19

                        Agent fleets

                        Agent fleet delegation
                        Ready

                        Compare delegation lab

                        Plan a small agent fleet

                        Choose a task You remain responsible for integration and review.

                        Scenario

                        Fleet roles

                        Model assignment

                        Match model strength to role difficulty. Direct cost is only one part of the decision; review and rework can dominate the workflow.

                        Recommended workflow

                          Coordination
                          0
                          Integration risk
                          Low
                          Best pattern
                          Single agent
                          Model cost
                          0.00 EUR
                          Model latency
                          0 min
                          Review time
                          0 min
                          Rework risk
                          Low

                          Choose roles and models to compare direct model cost with review burden.

                          Run packet

                          Copyable prompt packet

                          20

                          Agent fleets

                          Sequential work bound
                          Ready

                          Amdahl’s Law · S(N) = 1 / ((1 − p) + p/N)

                          Find the work that more agents cannot remove

                          2.50× ideal speedup

                          01 / Describe the workflow

                          The ideal bound excludes coordination, conflicts, retries, and review queues.

                          One agent100%
                          4 agents
                          40%
                          SequentialParallel share after division
                          Ideal speedup
                          2.50×
                          Relative time
                          40.0%
                          Efficiency
                          62.5%
                          Infinite-agent ceiling
                          5.00×

                          Four agents divide the parallel work, but the sequential 20% remains.

                          21

                          Scaling

                          Scaling pressure planner
                          Ready

                          Compare scaling lab

                          Choose scaling moves for one pressure

                          Describe the pressure A scaling choice is only defensible when the pressure, cost, and signal are explicit.

                          Event tracker pressure

                          Pressure levels

                          Candidate moves

                          Selection rule

                          Choose the smallest set that addresses the named pressure. Every extra move must pay for itself with a benefit, signal, and failure story.

                            Resulting design

                              Write relief
                              0/10
                              Read relief
                              0/10
                              Freshness risk
                              Low
                              Operational complexity
                              Low
                              Resource cost
                              Low
                              Waterbed lens
                              Trace displaced complexity
                              Choose a scaling move

                              Select techniques to see the trade-off.

                              Trade-off table

                              Copyable scaling artifact

                              22

                              Scaling

                              Saturation boundary lab
                              Ready

                              Capacity envelope

                              Find the first binding limit

                              Inspecting pipeline Compare effective demand with every stage.

                              Disturbance

                              Declared stage capacity

                              Effective demand 147 ev/s offered load + retries
                              Boundary —
                              Headroom —
                              Hidden backlog —
                              Rejected explicitly —

                              Adjust demand or capacity to expose a boundary.

                              First useful signal
                              —
                              Prepared recovery
                              —
                              Next closest boundary
                              —
                              Boundary report

                              Copyable saturation analysis

                              This is a teaching model, not a capacity benchmark. It compares one effective demand rate with declared stage limits so the movement of a bottleneck is visible.

                              23

                              Scaling

                              Contention curve lab
                              Ready

                              Universal Scalability Law · C(N)

                              See when adding concurrency starts taking capacity away

                              Capacity is still rising

                              01 / Shape the scaling cost

                              1 workerConcurrency →32 workers
                              Selected capacity
                              5.57×
                              Peak at
                              22
                              Peak capacity
                              7.33×
                              Next worker
                              helps

                              At eight workers, added concurrency still increases modeled capacity.

                              24

                              Scaling

                              Orchestration control loop
                              Ready

                              Browser cluster lab · Webernetes

                              Watch the control loop close

                              Starting simulated cluster… Controllers are assembling a three-node teaching environment.
                              Simulation boundary This runs Kubernetes-compatible control logic in your browser. It does not run Docker images or measure production capacity.
                              Desired 3
                              Running 0
                              Release v1
                              Served 0
                              NodePort service · :31000 event-api
                              round robin
                              01node-1
                                02node-2
                                  03node-3
                                    Controller feed Newest event first
                                    Reconciling
                                      Debrief the mechanism and its limits

                                      Name the desired state, the observed state, and the controller action after each experiment. Then identify what remains outside this model.

                                      • Replicas add service instances; they do not remove database limits.
                                      • Replacement demonstrates recovery, not uninterrupted availability.
                                      • This simulator omits real images, resource limits, persistent volumes, and production networking.
                                      25

                                      Scaling

                                      Latency budget map
                                      Ready

                                      Latency budget lab

                                      Count distance and database waits

                                      Build the request path The numbers are approximate, but the accumulation pattern is real.

                                      Request topology

                                      Edge read replica

                                      Reads stay close to the application, but writes may still coordinate with a primary database.

                                      Physical floor

                                      User App DB
                                      User to app 500 km 5.0 ms RTT floor
                                      App to DB 1 km 0.0 ms RTT floor

                                      Map derived from BlankMap-World.svg by Canuckguy and contributors, public domain, via Wikimedia Commons.

                                      In fiber, light travels at roughly 200,000 km/s. That is about 200 km per millisecond one way, before routing, queues, TLS, server work, or database execution.

                                      User RTT floor
                                      0 ms
                                      App-DB RTT floor
                                      0 ms

                                      Database access pattern

                                      Typical production instance

                                      Ordinary compute and database performance: hardware matters, but round trips can still dominate.

                                      Compare access shapes

                                      Sequential DB wait
                                      0 ms
                                      If batched into 2 trips
                                      0 ms
                                      Round-trip penalty
                                      0 ms
                                      Network per DB trip
                                      0 ms
                                      Server execution
                                      0 ms

                                      Edge read replica

                                      Reads stay close to the application, but writes may still coordinate with a primary database.

                                      Edge placement helps read-heavy paths most. It does not remove consistency, replication, or write-routing trade-offs.

                                      Latency budget

                                        Totals

                                        Estimated response
                                        0 ms
                                        Physical network floor
                                        0 ms
                                        Avoidable DB wait
                                        0 ms
                                        100-request page cost
                                        0 s

                                        Interpretation

                                        Adjust distance and database access to see what dominates.

                                        26

                                        Recap

                                        Final reflection package
                                        Ready

                                        Final reflection package

                                        Build a reflection from course artifacts

                                        Pick project evidence A strong reflection names the artifact, the claim it supports, and the limitation it does not prove.

                                        Artifacts in your folder

                                        What to add before writing

                                          Draft package

                                          Elements of Scalable Web Applications by Juho Vepsäläinen.