# docker/getting-started architecture

> Architecture diagram of the GitHub repository docker/getting-started, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/docker/getting-started
- Repository: https://github.com/docker/getting-started

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is **a Docker “Getting Started” tutorial site** plus a **small sample web application** used throughout the tutorial.

You effectively have two “products” in one repository:
##### Documentation site (MkDocs) served for the tutorial content
- `docs/**`, `mkdocs.yml`, `requirements.txt`
2) **Demo application** (Node.js web app) used to teach containers, volumes, networking, compose, etc.
- `app/src/**`, `app/package.json`, `Dockerfile`, `docker-compose.yml`

- How the **tutorial site** is built/served (MkDocs container, local dev loop)
- How the **demo app** runs (Node web server + persistence backends)
- How Docker concepts connect them (images, containers, ports, volumes, networks, compose)

##### Documentation (MkDocs)
- `docs/**` → markdown content + assets
- `mkdocs.yml` → MkDocs site config (nav/theme/plugins)
- `requirements.txt` → Python deps for mkdocs build/serve
- `docker-compose.yml` (per README) → starts “mkdocs application” for local dev (likely bind-mounts docs)

##### Demo app (Node.js)
- `app/src/index.js` → main server entrypoint
- `app/src/routes/*.js` → route handlers:
- `addItem.js`, `deleteItem.js`, `getItems.js`, `updateItem.js`
- `app/src/persistence/*` → persistence layer:
- `index.js` abstraction/factory
- `sqlite.js` implementation
- `mysql.js` implementation
- `app/src/static/**` → frontend assets (index.html, JS, CSS, font-awesome, etc.)
- `app/spec/**` → tests for routes and persistence (indicates clear boundaries)

- serves **static frontend** and exposes **HTTP endpoints** for CRUD
- calls a **persistence interface** which can be backed by **SQLite** or **MySQL**

##### Container/build/deploy glue
- `Dockerfile` → image build for something in this repo (often the tutorial image + includes app/docs)
- `build.sh` → build helper
- `.github/workflows/build.yml` → CI build pipeline
- `.dockerignore` → build context hygiene

**Actors**
- Learner’s Browser
- Docker Desktop (local runtime)
- GitHub Actions (CI)

**Systems**
- Tutorial Site (MkDocs)
- Demo App (Node)
- Optional DB service (MySQL) and/or local DB file (SQLite)

- **mkdocs service/container** (dev server)
- **demo app container** (Node)
- **mysql container** (optional, depending on tutorial step)
- **Docker network** between services (compose default network)
- **Ports** exposed to host (e.g., `host:80 -> container:80` for tutorial image per README; demo app likely another port depending on implementation)
- **Volumes**
- bind mount for `docs/` into mkdocs container (dev)
- named volume for MySQL data (if present)
- bind mount or named volume for SQLite DB file (if tutorial uses volumes to persist)

- `index.js` (HTTP server + static hosting)
- `routes/` (CRUD endpoints)
- `persistence/index.js` (interface / selector)
- `persistence/sqlite.js` and `persistence/mysql.js` (implementations)
- Static frontend (`static/index.html`, `static/js/app.js`) calling backend endpoints

This is where you show *clean separations* that tests (`app/spec/**`) already imply.

##### Frontend JS (`static/js/app.js`) calls API endpoints
- `GET /items` → `routes/getItems.js`
- `POST /items` → `routes/addItem.js`
- `PUT /items/:id` → `routes/updateItem.js`
- `DELETE /items/:id` → `routes/deleteItem.js`
##### Persistence calls either
- SQLite (file-based; persisted via volume/bind mount), or
- MySQL (network call to DB container; data persisted via MySQL volume)

##### Build flow (CI/local)
- Source → Docker build (Dockerfile + .dockerignore) → image
- GitHub Actions runs `.github/workflows/build.yml` to validate/build/publish (if configured)

##### Architectural patterns to call out (because the tree proves them)
- **Layering / separation of concerns** in demo app:
- Routes layer (`routes/`) is separate from persistence layer (`persistence/`)
- Persistence has a **strategy/provider** approach (`index.js` chooses mysql vs sqlite)
- **Static SPA-ish frontend + API** (static assets served, JS calls CRUD endpoints)
- **Container-first tutorial design**
- Compose for local dev and multi-container examples
- Volumes/bind mounts for persistence and fast iteration

##### Two top-level concerns
- “Docs site (MkDocs)” and “Demo app (Node)”
##### Persistence is configurable
- Both SQLite and MySQL paths (even if mutually exclusive at runtime)
##### Docker concepts
- images vs containers
- volumes/bind mounts
- compose network
##### CI lane (because build.yml exists)
- GitHub Actions → docker build → (optional) publish

- **Browser**
- → HTTP → **Tutorial container/site** (`docker/getting-started` image per README) OR **MkDocs dev container** (for contributors)
- → HTTP → **Demo app container** (Node)
- **Demo app container**
- serves static UI + API
- talks to **MySQL container** (optional) over compose network
- and/or writes to **SQLite db file** mounted as volume
- **Volumes**
- `docs/` bind-mounted into mkdocs container (dev)
- MySQL data named volume
- SQLite data volume/bind mount

##### Then open `app/src/index.js` to confirm
- which port the Node server listens on
- route mount paths and static directory
- how persistence backend is chosen (env vars, config, defaults)
##### Validate persistence wiring by reading
- `app/src/persistence/index.js` (selection logic)
- `sqlite.js` / `mysql.js` (connection details)
##### Cross-check with tests in `app/spec/` to ensure you didn’t miss a route or behavior.

- Every storage element: **type + persistence mechanism** (named volume vs bind mount)
- Every boundary: **Host machine**, **Docker Desktop**, **Compose network**
- Every code boundary in the app: **routes**, **persistence interface**, **sqlite/mysql implementations**, **static UI**

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% L1 - System Context (C4)
%% =========================
subgraph "System Context (C4 L1)"
direction TB

Browser["Learner Browser"]:::actor

subgraph "Local Machine"
direction TB
DockerDesktop["Docker Desktop (Local Runtime)"]:::platform
end

subgraph "CI"
direction TB
GHA["GitHub Actions (CI)"]:::ci
end

MkDocsSite["Tutorial Site (MkDocs)"]:::svc
DemoApp["Demo App (Node.js)"]:::svc
MySQLSvc["MySQL (Optional)"]:::db
SQLiteFile[("SQLite DB File (Optional)")]:::db

Browser -->|"HTTP"| MkDocsSite
Browser -->|"HTTP"| DemoApp

DemoApp -->|"SQL/TCP 3306 (optional)"| MySQLSvc
DemoApp -->|"File I/O (optional)"| SQLiteFile

GHA -.->|"docker_build"| MkDocsSite
GHA -.->|"docker_build"| DemoApp
end

DockerDesktop --- MkDocsSite
DockerDesktop --- DemoApp
DockerDesktop --- MySQLSvc
DockerDesktop --- SQLiteFile

%% =========================
%% L2 - Containers / Compose
%% =========================
subgraph "Containers & Compose Runtime (C4 L2)"
direction TB

Host["Host OS"]:::platform

subgraph "Docker Desktop"
direction TB

subgraph "Compose Network (default)"
direction TB

MkDocsC["mkdocs service (Python/MkDocs)"]:::container
NodeC["demo-app service (Node.js)"]:::container
MySQLC["mysql service (Optional)"]:::container

NodeC -->|"SQL/TCP 3306"| MySQLC
end

DocsSrc[["docs/ (Markdown + assets)"]]:::artifact
MkDocsCfg[["mkdocs.yml config"]]:::artifact
PyDeps[["requirements.txt"]]:::artifact

StaticAssets[["Static UI (HTML/CSS/JS)"]]:::artifact

SQLiteVol[("Volume/Bind Mount: SQLite data")]:::volume
MySQLVol[("Named Volume: MySQL data")]:::volume

DocsSrc -->|"bind_mount (dev)"| MkDocsC
MkDocsCfg -->|"config"| MkDocsC
PyDeps -->|"deps"| MkDocsC

NodeC -->|"serves"| StaticAssets
NodeC -->|"reads/writes"| SQLiteVol
MySQLC -->|"persists"| MySQLVol
end

Host -->|"HTTP :80 (docs) → container"| MkDocsC
Host -->|"HTTP :3000 (app) → container"| NodeC
end

%% =========================
%% L3 - Demo App Components
%% =========================
subgraph "Demo App Internals (C4 L3 - app/src)"
direction TB

NodeEntry["index.js (HTTP server + static hosting)"]:::component

subgraph "Static Frontend (served by Node)"
direction TB
HTML["index.html"]:::frontend
AppJS["js/app.js (calls CRUD API)"]:::frontend
CSS["css/styles.css"]:::frontend
RB["js/react-bootstrap.js"]:::frontend
FA["css/font-awesome/ assets"]:::frontend
end

subgraph "Routes Layer (CRUD)"
direction TB
RGet["GET /items (getItems.js)"]:::route
RAdd["POST /items (addItem.js)"]:::route
RUpd["PUT /items/:id (updateItem.js)"]:::route
RDel["DELETE /items/:id (deleteItem.js)"]:::route
end

subgraph "Persistence Layer (Strategy/Provider)"
direction TB
PIndex["persistence/index.js (backend selector)"]:::persistence
PSQLite["persistence/sqlite.js"]:::persistence
PMySQL["persistence/mysql.js"]:::persistence
end

HTML -->|"loads"| AppJS
AppJS -->|"HTTP"| RGet
AppJS -->|"HTTP"| RAdd
AppJS -->|"HTTP"| RUpd
AppJS -->|"HTTP"| RDel

NodeEntry -->|"serves_static"| HTML
NodeEntry -->|"mounts_routes"| RGet
NodeEntry -->|"mounts_routes"| RAdd
NodeEntry -->|"mounts_routes"| RUpd
NodeEntry -->|"mounts_routes"| RDel

RGet -->|"calls"| PIndex
RAdd -->|"calls"| PIndex
RUpd -->|"calls"| PIndex
RDel -->|"calls"| PIndex

PIndex -->|"selects_sqlite"| PSQLite
PIndex -->|"selects_mysql"| PMySQL
end

%% =========================
%% Tests & Boundaries
%% =========================
subgraph "Tests (app/spec)"
direction TB
SpecRoot["Test Suite (spec/)"]:::test
SpecRoutes["Route Tests"]:::test
SpecPersist["Persistence Tests"]:::test
SpecSqlite["sqlite.spec.js"]:::test
SpecAdd["addItem.spec.js"]:::test
SpecDel["deleteItem.spec.js"]:::test
SpecGet["getItems.spec.js"]:::test
SpecUpd["updateItem.spec.js"]:::test

SpecRoot --> SpecRoutes
SpecRoot --> SpecPersist
SpecPersist --> SpecSqlite
SpecRoutes --> SpecAdd
SpecRoutes --> SpecDel
SpecRoutes --> SpecGet
SpecRoutes --> SpecUpd
end

SpecRoutes -.->|"validates"| RAdd
SpecRoutes -.->|"validates"| RDel
SpecRoutes -.->|"validates"| RGet
SpecRoutes -.->|"validates"| RUpd
SpecPersist -.->|"validates"| PIndex
SpecPersist -.->|"validates"| PSQLite
SpecPersist -.->|"validates"| PMySQL

%% =========================
%% Build & Image Pipeline
%% =========================
subgraph "Build & Image Pipeline"
direction TB

Source["Repository Source"]:::artifact
DockerfileNode["Dockerfile"]:::build
DockerignoreNode[".dockerignore"]:::build
BuildScript["build.sh"]:::build
Workflow[".github/workflows/build.yml"]:::build
Image["Docker Image(s)"]:::artifact

Source -.->|"uses"| DockerfileNode
Source -.->|"uses"| DockerignoreNode
BuildScript -.->|"docker_build"| Image
Workflow -.->|"docker_build"| Image
DockerfileNode -.->|"defines"| Image
DockerignoreNode -.->|"filters_context"| Image

Image -.->|"runs_as_containers"| MkDocsC
Image -.->|"runs_as_containers"| NodeC
Image -.->|"runs_as_containers"| MySQLC
end

%% =========================
%% Click Events (from mapping)
%% =========================
click DocsSrc "https://github.com/docker/getting-started/tree/master/docs/"
click MkDocsCfg "https://github.com/docker/getting-started/blob/master/mkdocs.yml"
click PyDeps "https://github.com/docker/getting-started/blob/master/requirements.txt"
click MkDocsC "https://github.com/docker/getting-started/blob/master/docker-compose.yml"

click DemoApp "https://github.com/docker/getting-started/blob/master/app/package.json"
click NodeEntry "https://github.com/docker/getting-started/blob/master/app/src/index.js"
click RAdd "https://github.com/docker/getting-started/blob/master/app/src/routes/addItem.js"
click RDel "https://github.com/docker/getting-started/blob/master/app/src/routes/deleteItem.js"
click RGet "https://github.com/docker/getting-started/blob/master/app/src/routes/getItems.js"
click RUpd "https://github.com/docker/getting-started/blob/master/app/src/routes/updateItem.js"
click RAdd "https://github.com/docker/getting-started/tree/master/app/src/routes/"
click RDel "https://github.com/docker/getting-started/tree/master/app/src/routes/"
click RGet "https://github.com/docker/getting-started/tree/master/app/src/routes/"
click RUpd "https://github.com/docker/getting-started/tree/master/app/src/routes/"

click PIndex "https://github.com/docker/getting-started/blob/master/app/src/persistence/index.js"
click PSQLite "https://github.com/docker/getting-started/blob/master/app/src/persistence/sqlite.js"
click PMySQL "https://github.com/docker/getting-started/blob/master/app/src/persistence/mysql.js"
click PIndex "https://github.com/docker/getting-started/tree/master/app/src/persistence/"

click HTML "https://github.com/docker/getting-started/blob/master/app/src/static/index.html"
click AppJS "https://github.com/docker/getting-started/blob/master/app/src/static/js/app.js"
click CSS "https://github.com/docker/getting-started/blob/master/app/src/static/css/styles.css"
click RB "https://github.com/docker/getting-started/blob/master/app/src/static/js/react-bootstrap.js"
click FA "https://github.com/docker/getting-started/tree/master/app/src/static/css/font-awesome/"
click StaticAssets "https://github.com/docker/getting-started/tree/master/app/src/static/"

click SpecRoot "https://github.com/docker/getting-started/tree/master/app/spec/"
click SpecRoutes "https://github.com/docker/getting-started/tree/master/app/spec/routes/"
click SpecPersist "https://github.com/docker/getting-started/tree/master/app/spec/persistence/"
click SpecSqlite "https://github.com/docker/getting-started/blob/master/app/spec/persistence/sqlite.spec.js"
click SpecAdd "https://github.com/docker/getting-started/blob/master/app/spec/routes/addItem.spec.js"
click SpecDel "https://github.com/docker/getting-started/blob/master/app/spec/routes/deleteItem.spec.js"
click SpecGet "https://github.com/docker/getting-started/blob/master/app/spec/routes/getItems.spec.js"
click SpecUpd "https://github.com/docker/getting-started/blob/master/app/spec/routes/updateItem.spec.js"

click DockerfileNode "https://github.com/docker/getting-started/tree/master/Dockerfile"
click DockerignoreNode "https://github.com/docker/getting-started/blob/master/.dockerignore"
click BuildScript "https://github.com/docker/getting-started/blob/master/build.sh"
click Workflow "https://github.com/docker/getting-started/blob/master/.github/workflows/build.yml"
click MkDocsC "https://github.com/docker/getting-started/blob/master/docker-compose.yml"

%% =========================
%% Styles
%% =========================
classDef actor fill:#FFF3CD,stroke:#B48B00,stroke-width:1px,color:#1f1f1f;
classDef platform fill:#E2E3E5,stroke:#6C757D,stroke-width:1px,color:#1f1f1f;
classDef svc fill:#D1E7DD,stroke:#1E7E34,stroke-width:1px,color:#0b2e13;
classDef container fill:#CFE2FF,stroke:#1D4ED8,stroke-width:1px,color:#0b1f44;
classDef db fill:#F8D7DA,stroke:#B02A37,stroke-width:1px,color:#3b0a0f;
classDef volume fill:#FCE7F3,stroke:#BE185D,stroke-width:1px,color:#3b0a1f;
classDef artifact fill:#E9D5FF,stroke:#6D28D9,stroke-width:1px,color:#2a0a44;
classDef component fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#0b1f44;
classDef route fill:#D9F99D,stroke:#3F6212,stroke-width:1px,color:#1a2e05;
classDef persistence fill:#FFE4B5,stroke:#B45309,stroke-width:1px,color:#3b1a05;
classDef frontend fill:#FFEDD5,stroke:#C2410C,stroke-width:1px,color:#3b1405;
classDef test fill:#E0F2FE,stroke:#0369A1,stroke-width:1px,color:#06283a;
classDef build fill:#F1F5F9,stroke:#475569,stroke-width:1px,color:#0f172a;
classDef ci fill:#DCFCE7,stroke:#166534,stroke-width:1px,color:#052e12;
```
