how-to-sdlc

Short, illustrated explanations of how things work.

How Software Gets Made

An interactive guide to the software development lifecycle — planning, version control, review, continuous integration, testing, security, release, observability and the feedback loop that closes it — and to where AI coding agents actually fit in all of that. It is built around Delivery Park, a low-poly isometric simulation in the spirit of the 90s theme-park builders, which runs as the page's live background.

Source: docs/ · Live site: https://everyways.github.io/how-to-sdlc/ (once GitHub Pages is enabled, see below)

Companion to how-to-internet, which picks the story up at the moment your change is live.

What the simulation shows

The pipeline is drawn as a circuit. Work leaves the backlog plaza, runs through the planning office, the developer workshop, the repository vault, the review gatehouse, the build factory, the test lab and the security checkpoint, rehearses in staging, crosses the river into the production city, reaches the users, and comes back as telemetry.

The AI agent depot sits inside the ring with cables running out to the workshop, the repository, the review gate and the observability tower — because an agent is not a stage of the lifecycle, it is a worker plugged into most of them. The track still runs through review and CI before anything reaches the city.

Scenario	What it demonstrates
Ship a change (happy path)	The full loop, from a complaint to telemetry
An agent takes the ticket	An agent iterating against CI, and the human who approves
A test catches a bug	Fast feedback, and what a defect costs at each stage
Something breaks in production	Alerting, rollback-first, and a blameless postmortem
Big batch vs. small batches	Why batch size is the lever behind almost everything

The map is the background, and it is yours

The canvas is pinned behind the article rather than boxed inside it, and it stays interactive while you read:

• The article can be hidden. A Hide the article toggle sits in the top-right corner at all times: press it and the whole text container fades away, leaving the park with the entire viewport. Press it again — or esc — and the words come back at the scroll position you left them. The toggle never hides itself, so it cannot become a mode you get stuck in.
• It follows the article. Scrolling to a section highlights the station it is about and switches the simulation to the matching scenario. Uncheck Follow the article to drive it yourself.
• Drag the margins to pan, without interrupting reading — the text panels are the only pointer-catching things on the page.
• Click a building for what that station does and a link to the section about it.
• Keyboard: ← → rotate, + − zoom, space pause, esc bring the article back.

How it is built

Three static files, no build step, no dependencies, no external requests:

docs/
├── index.html   the article, the controls and the station inspector
├── styles.css   the two-layer page: a full-viewport map with panels floating over it
└── sim.js       the isometric renderer, world model and scene director

The simulation is plain JavaScript on a 2D canvas. There is no WebGL and no 3D library: buildings are axis-aligned boxes projected isometrically and drawn back-to-front with a painter's algorithm, which is how the games it borrows from did it too.

Key pieces in sim.js:

• Projection — rotXY rotates world tiles into one of four camera orientations, project flattens them to screen space, depthOf gives the sort key.
• World — NODES (stations) and LINKS (the track and the agent's spokes, as polylines) describe the map; routes are lists of node ids resolved by routePoints.
• Terrain — tile kinds and scenery are computed once into KIND_GRID, then cached into an offscreen canvas that is only redrawn when the camera moves. Since the map fills the viewport, this is what keeps the frame cost flat.
• Work items — spawn puts a cube on a route with a speed, an optional delay and an onArrive callback used to chain the next hop.
• Director — SCENARIOS holds the scripted steps; each step writes the narration, spawns work items, and completes when they have all landed.

To add a step, add an entry to a scenario's steps array. To add a station, add a node, a link in LINKS, and a draw function in BUILDERS.

Running locally

Any static server works:

cd docs
python3 -m http.server 8000    # then open http://localhost:8000

Publishing

The site lives in docs/ so it can be published either way:

• Simplest: Settings → Pages → Source: Deploy from a branch, branch main, folder /docs.
• Or via Actions: the included .github/workflows/pages.yml deploys docs/ on every push to main — choose Source: GitHub Actions.

Accuracy

The explanations are deliberately simplified. Real pipelines have more stages, more approvals and considerably more meetings; the four delivery measures are quoted without their caveats; and the section on agents describes a practice that is still moving. Every section is accurate in outline; none is complete. The links at the bottom of the page go to the rigorous versions.