# sarowar-alam/3-tier-with-docker architecture

> Architecture diagram of the GitHub repository sarowar-alam/3-tier-with-docker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sarowar-alam/3-tier-with-docker
- Repository: https://github.com/sarowar-alam/3-tier-with-docker

## Overview

1. This repository is a training-oriented wrapper around one real application: a 3-tier BMI Health Tracker. The app itself lives at the repo root, while the `01-fundamentals-containerizing` and `02-compose-migration` folders contain progressively more advanced Docker packaging, orchestration, and observability material for the same stack.

2. The runtime architecture is a classic three-tier flow: browser/client UI → REST API → PostgreSQL. In production, the frontend is served from an Nginx container on port 80, the backend runs as a Node.js/Express service on port 3000, and the database is PostgreSQL on port 5432.

3. The frontend is a React application built with Vite. `App.jsx` wires the page together, `MeasurementForm.jsx` handles user input, `TrendChart.jsx` renders historical trends, and `api.js` is the boundary where the UI talks to the backend. In production the frontend is compiled to static assets and served by Nginx; in development it uses Vite hot reload.

4. The backend is the application and business-logic boundary. `server.js` boots the service, `routes.js` defines the HTTP API surface, `calculations.js` contains BMI/BMR/daily-calorie logic, and `db.js` encapsulates persistence access. The backend also includes container-friendly startup behavior so it can tolerate the database not being ready immediately.

5. Persistence is centered on a measurements history model. The migrations under `backend/migrations` create the measurements table and later add a measurement date field, which supports the app’s historical tracking and 30-day trend views. The database setup script under `database/` supports local bootstrapping outside the container path.

6. `01-fundamentals-containerizing` is the “single-container-image” layer of the course. It contains production and development Dockerfiles for both backend and frontend, `.dockerignore` files, an Nginx config for serving the frontend, and build scripts for packaging both images. This folder is about image construction, layering, and runtime split between dev and prod.

7. `02-compose-migration` is the orchestration layer. It defines a production Compose stack, a development Compose stack, and a separate monitoring stack. This is where service discovery, network wiring, volume-backed persistence, environment-variable injection, and startup dependencies/health checks become part of the architecture.

8. The observability subsystem is isolated from the application stack but connected to it. Prometheus collects metrics, Loki stores logs, Promtail ships logs from containers, and Grafana provides dashboards and datasource provisioning. The included BMI dashboard JSON indicates the monitoring layer is intended to visualize this specific app, not just generic container health.

9. CI/CD is represented by `.github/workflows/docker-build-push.yml`. Its role is to build and publish container images, making the Docker artifacts first-class deployable units rather than just local classroom examples. The README calls out DockerHub and AWS ECR as likely registry targets.

10. The repository also includes a small runtime/process-management boundary in `backend/ecosystem.config.js`, which suggests a production process manager configuration for the Node service. That sits between the application code and the container runtime, helping define how the backend is launched and supervised.

11. The `setup`, `cleanup`, and `scripts` folders in both class directories are operational scaffolding. They don’t change the application architecture, but they do encode how the stack is started, stopped, reset, and demonstrated across Windows PowerShell and Unix shells.

12. Net result: the core application is a stateful web system with a clear split between presentation, API/business logic, and relational persistence, while the surrounding repository layers add container image buildability, multi-container orchestration, observability, and delivery automation.

Main entry points: [`backend/src`](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/backend/src) (Backend), [`02-compose-migration`](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/02-compose-migration) (Compose stacks), [`frontend/src/App.jsx`](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/frontend/src/App.jsx) (App shell), [`02-compose-migration/monitoring`](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/02-compose-migration/monitoring) (Monitoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core App"]
  node_frontend["Frontend<br/>React/Vite UI"]
  node_frontend_app["App shell<br/>React composition<br/>[App.jsx]"]
  node_measurement_form["Input form<br/>UI component"]
  node_trend_chart["Trend chart<br/>UI component<br/>[TrendChart.jsx]"]
  node_frontend_api["API client<br/>HTTP boundary<br/>[api.js]"]
  node_backend["Backend<br/>Node/Express API"]
  node_server["Server boot<br/>startup entry<br/>[server.js]"]
  node_routes["Routes<br/>[routes.js]"]
  node_calculations["Calculations<br/>domain logic<br/>[calculations.js]"]
  node_db_access["DB access<br/>persistence adapter<br/>[db.js]"]
  node_migrations["Migrations<br/>schema evolution"]
  node_postgres[("PostgreSQL<br/>relational store")]
  node_process_manager["Process manager<br/>Node runtime config"]
end

subgraph group_packaging["Containerization"]
  node_docker_packaging["Docker images<br/>build packaging"]
  node_frontend_nginx["Nginx serve<br/>frontend runtime<br/>[nginx.conf]"]
end

subgraph group_orchestration["Compose Orchestration"]
  node_compose_stack["Compose stacks<br/>multi-container runtime"]
end

subgraph group_observability["Observability"]
  node_monitoring_stack["Monitoring<br/>observability stack"]
  node_grafana_dashboard["BMI dashboard<br/>dashboard config"]
end

subgraph group_delivery["Delivery"]
  node_ci_workflow["Build pipeline<br/>CI/CD workflow"]
end

node_frontend -->|"contains"| node_frontend_app
node_frontend_app -->|"uses"| node_measurement_form
node_frontend_app -->|"uses"| node_trend_chart
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_routes
node_backend -->|"boots"| node_server
node_server -->|"mounts"| node_routes
node_routes -->|"uses"| node_calculations
node_routes -->|"persists"| node_db_access
node_db_access -->|"reads/writes"| node_postgres
node_migrations -->|"migrates"| node_postgres
node_frontend -->|"served by"| node_frontend_nginx
node_docker_packaging -->|"packages"| node_frontend
node_docker_packaging -->|"packages"| node_backend
node_compose_stack -->|"runs"| node_backend
node_compose_stack -->|"runs"| node_frontend
node_compose_stack -->|"runs"| node_postgres
node_compose_stack -.->|"includes"| node_monitoring_stack
node_monitoring_stack -->|"provisions"| node_grafana_dashboard
node_monitoring_stack -->|"observes"| node_backend
node_monitoring_stack -->|"observes"| node_postgres
node_ci_workflow -->|"builds"| node_docker_packaging
node_process_manager -.->|"supervises"| node_backend

click node_frontend "https://github.com/sarowar-alam/3-tier-with-docker/tree/main/frontend"
click node_frontend_app "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/frontend/src/App.jsx"
click node_measurement_form "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/frontend/src/components/MeasurementForm.jsx"
click node_trend_chart "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/frontend/src/components/TrendChart.jsx"
click node_frontend_api "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/frontend/src/api.js"
click node_backend "https://github.com/sarowar-alam/3-tier-with-docker/tree/main/backend/src"
click node_server "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/src/server.js"
click node_routes "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/src/routes.js"
click node_calculations "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/src/calculations.js"
click node_db_access "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/src/db.js"
click node_migrations "https://github.com/sarowar-alam/3-tier-with-docker/tree/main/backend/migrations"
click node_postgres "https://github.com/sarowar-alam/3-tier-with-docker/tree/main/database"
click node_docker_packaging "https://github.com/sarowar-alam/3-tier-with-docker/tree/main/01-fundamentals-containerizing"
click node_frontend_nginx "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/01-fundamentals-containerizing/frontend/nginx.conf"
click node_compose_stack "https://github.com/sarowar-alam/3-tier-with-docker/tree/main/02-compose-migration"
click node_monitoring_stack "https://github.com/sarowar-alam/3-tier-with-docker/tree/main/02-compose-migration/monitoring"
click node_grafana_dashboard "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/02-compose-migration/monitoring/grafana/dashboards/bmi-app-dashboard.json"
click node_ci_workflow "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/.github/workflows/docker-build-push.yml"
click node_process_manager "https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/ecosystem.config.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_frontend_app,node_measurement_form,node_trend_chart,node_frontend_api,node_backend,node_server,node_routes,node_calculations,node_db_access,node_migrations,node_postgres,node_process_manager toneBlue
class node_docker_packaging,node_frontend_nginx toneAmber
class node_compose_stack toneMint
class node_monitoring_stack,node_grafana_dashboard toneRose
class node_ci_workflow toneIndigo
```

## Components

### Core App

Browser UI, API, and PostgreSQL data layer

- [Frontend](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/frontend): React/Vite UI · Client-facing app served statically in production and via Vite in development · `frontend`
- [App shell](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/frontend/src/App.jsx): React composition · Wires the main page and UI flow together · `frontend/src/App.jsx`
- [Input form](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/frontend/src/components/MeasurementForm.jsx): UI component · Collects BMI measurement data from the user · `frontend/src/components/MeasurementForm.jsx`
- [Trend chart](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/frontend/src/components/TrendChart.jsx): UI component · Renders historical measurements and trend views · `frontend/src/components/TrendChart.jsx`
- [API client](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/frontend/src/api.js): HTTP boundary · Frontend boundary for talking to the backend service · `frontend/src/api.js`
- [Backend](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/backend/src): Node/Express API · Business-logic and HTTP boundary for the application · `backend/src`
- [Server boot](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/src/server.js): startup entry · Starts the API service and handles runtime startup concerns · `backend/src/server.js`
- [Routes](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/src/routes.js): HTTP routes · Defines the REST API surface · `backend/src/routes.js`
- [Calculations](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/src/calculations.js): domain logic · BMI, BMR, and calorie-related computations · `backend/src/calculations.js`
- [DB access](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/src/db.js): persistence adapter · Encapsulates database reads and writes from the backend · `backend/src/db.js`
- [Migrations](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/backend/migrations): schema evolution · Creates and evolves the measurements table and date field · `backend/migrations`
- [PostgreSQL](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/database): relational store · Stores measurement history for historical and trend views · `database`
- [Process manager](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/backend/ecosystem.config.js): Node runtime config · Defines supervised backend launch behavior for production · `backend/ecosystem.config.js`

### Containerization

Image build and runtime packaging for the app

- [Docker images](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/01-fundamentals-containerizing): build packaging · Builds production and development images for frontend and backend · `01-fundamentals-containerizing`
- [Nginx serve](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/01-fundamentals-containerizing/frontend/nginx.conf): frontend runtime · Serves compiled frontend assets in production · `01-fundamentals-containerizing/frontend/nginx.conf`

### Compose Orchestration

Multi-container dev/prod stacks and operational scripts

- [Compose stacks](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/02-compose-migration): multi-container runtime · Defines dev, prod, and monitoring orchestration layouts · `02-compose-migration`

### Observability

Metrics, logs, and dashboards for the stack

- [Monitoring](https://github.com/sarowar-alam/3-tier-with-docker/tree/main/02-compose-migration/monitoring): observability stack · Prometheus, Loki, Promtail, and Grafana for the app · `02-compose-migration/monitoring`
- [BMI dashboard](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/02-compose-migration/monitoring/grafana/dashboards/bmi-app-dashboard.json): dashboard config · Grafana dashboard tailored to this application · `02-compose-migration/monitoring/grafana/dashboards/bmi-app-dashboard.json`

### Delivery

CI workflow for building and publishing images

- [Build pipeline](https://github.com/sarowar-alam/3-tier-with-docker/blob/main/.github/workflows/docker-build-push.yml): CI/CD workflow · Builds and publishes container images · `.github/workflows/docker-build-push.yml`

## Connections

- Frontend → App shell: contains · React app composition lives here
- App shell → Input form: uses · Page includes measurement input form
- App shell → Trend chart: uses · Page includes trend visualization
- App shell → API client: calls · UI sends data and fetches history through API boundary
- API client → Routes: requests · HTTP client talks to backend endpoints
- Backend → Server boot: boots · Service entrypoint starts the application
- Server boot → Routes: mounts · Server exposes the HTTP routes
- Routes → Calculations: uses · Routes apply BMI domain logic
- Routes → DB access: persists · Routes store and retrieve measurement data
- DB access → PostgreSQL: reads/writes · Database adapter talks to PostgreSQL
- Migrations → PostgreSQL: migrates · Schema changes are applied to the database
- Frontend → Nginx serve: served by · Production frontend is delivered by Nginx
- Docker images → Frontend: packages · Builds frontend image variants
- Docker images → Backend: packages · Builds backend image variants
- Compose stacks → Backend: runs · Compose starts backend service container
- Compose stacks → Frontend: runs · Compose starts frontend service container
- Compose stacks → PostgreSQL: runs · Compose wires database service and persistence
- Compose stacks → Monitoring: includes · Monitoring stack is deployed alongside application stacks
- Monitoring → BMI dashboard: provisions · Grafana is seeded with an app-specific dashboard
- Monitoring → Backend: observes · Metrics and logs are collected from the app services
- Monitoring → PostgreSQL: observes · Infrastructure monitoring includes the data layer
- Build pipeline → Docker images: builds · CI produces deployable container artifacts
- Process manager → Backend: supervises · Production launch configuration for the Node service