The same e-commerce application, running two ways: as a monolith (one Flask process, one shared database) and as three independently deployable microservices (user, product, order — each owning its own database). Click Migrate and watch a real strangler-fig cutover happen live — not an animation. Compare real before/after performance numbers. Read the architectural reasoning behind it all.
Teams inherit monoliths that "just work" until they don't: every deploy risks the whole app, one noisy feature (say, checkout under Black Friday load) forces scaling the entire system, and a schema change in one domain can silently break another. The textbook answer is "migrate to microservices" — but most explanations are diagrams, not code you can run.
| Monolith pain point | Microservices answer |
|---|---|
| One bug can take down the whole app | Fault isolation — a failing service doesn't crash the others |
| Scaling means scaling everything | Independent scaling per service |
| One team's schema change can break another's code | Each service owns its own database |
| Slow, risky "big bang" deploys | Small, independent deploys per service |
| Hard to reason about a large shared codebase | Smaller, focused codebases per bounded context |
This project makes that transition tangible: the same registration/login, product catalog,
and cart/checkout flow, provably working identically on both sides (see tests/smoke/test_post_run.py),
with a real (not simulated) migration process you can trigger and watch.
Browser → BFF (proxy) → ┌─────────────────────────────┐
│ monolith (Flask, :6000) │
│ ├── auth blueprint │
│ ├── catalog blueprint │
│ └── orders blueprint │
│ one shared database │ ← "Shared Persistence"
└─────────────────────────────┘
┌──────────────────────┐
┌────►│ user-service :5001 │──► user_db
│ └──────────────────────┘
Browser → BFF ──────┤ ┌──────────────────────┐
(proxy, :8000) ├────►│ product-service :5002│──► product_db
│ └──────────────────────┘
│ ┌──────────────────────┐
└────►│ order-service :5003 │──► order_db
└──────────┬───────────┘
│ HTTP (Anti-Corruption Layer)
▼
user-service :5001 (validates api_key)
Note the key architectural difference the migration introduces: in the monolith, order logic
queries the User table directly in the same database session. In the microservices version,
order-service has no access to the user database at all — it validates the caller by making
a real HTTP call to user-service (microservices/order-service/application/order_api/api/UserClient.py).
That's the Anti-Corruption Layer pattern in actual code, not just a diagram.
monolith/— the BEFORE state, modernized to Flask 3.1 / SQLAlchemy 2.0 / Python 3.12microservices/{user,product,order}-service/— the AFTER state, same business logic, three independent Flask services, each with its own databasebff/— a FastAPI backend-for-frontend that proxies the React app to either backend, drives the live migration, serves Learn content, and runs the benchmarkfrontend/— React + TypeScript + Vite, Contoso theme, with Home / Shop / Migrate / Learn / Metrics pages- Zero Docker Desktop, zero local containers — local dev is 100% plain Python/Node processes.
Containers exist only on Azure, built via
az acr build(cloud-side, no local Docker daemon) - Azure-hosted by default, local dev optional —
make provisiondeploys only the monolith; the microservices' Container Apps get created for real, live, when you trigger the migration from the browser (see "Deploying to Azure" below). Prefer to stay entirely local and free?make setup && make run-alldoes that too, with the same code.
Clicking Start Migration in local mode:
- Actually starts the
user-service,product-service, andorder-servicePython processes (they aren't running until you do this — the "before" state genuinely only has the monolith up) - Polls their real
/healthendpoints before advancing - Actually stops the monolith process in the final "Decommission" step
- Streams progress to the UI in real time (SSE), one step per Strangler Fig phase (domain assessment → proxy layer → extraction → ACL → traffic redirection → decommission)
In azure mode, it's the same idea but with real cloud infrastructure: make provision deploys
only the monolith (plus the BFF and the foundation — ACR, Container Apps Environment, MySQL,
Static Web App). The user-service, product-service, and order-service Container Apps do not
exist yet. Clicking Start Migration makes the BFF itself — using its own scoped Azure managed
identity — call the azure-mgmt-appcontainers SDK to create each one for real, one at a time,
waiting for each to answer its real /health endpoint before moving to the next step. The final
"Decommission" step scales the monolith Container App to zero replicas. Nothing about this is
pre-provisioned or simulated: run az containerapp list --resource-group <rg> -o table in another
terminal during the migration and watch user-service, then product-service, then
order-service appear one by one as the timeline advances.
Verified for real during development in local mode: clicked through the full migration in a browser, confirmed via direct port checks that the monolith was truly stopped and all three microservices were truly running afterward, then ran the full register→login→create product→add to cart→checkout flow against the post-migration microservices stack.
scripts/benchmark.py hits the monolith and product-service directly (ports 6000 and 5002),
bypassing the BFF entirely, so the comparison stays apples-to-apples: both sides are Flask +
identical route/serialization code — the only variable is "one process/one DB" vs. "three
processes/three DBs," not an extra proxy hop or a different framework. Results are saved to
results/benchmark_*.json and rendered as p95 latency and throughput comparison charts.
FastAPI is only used for the BFF — the orchestration/proxy layer in front of both stacks, not part of either side being measured. Both the monolith and all three microservices are Flask.
| Layer | Technology |
|---|---|
| Monolith & microservices | Flask 3.1, Flask-SQLAlchemy 3.1, Flask-Migrate 4.0, Flask-Login 0.6, SQLAlchemy 2.0 |
| Validation | Pydantic 2.10 everywhere — FastAPI-native in the BFF, a shared validate_form() helper in every Flask app |
| BFF | FastAPI 0.115, Uvicorn, httpx, SSE (sse-starlette), azure-mgmt-appcontainers |
| Frontend | React 18, TypeScript 5, Vite 5, recharts, react-router-dom |
| Local database | SQLite (one file per service, auto-created in dev) |
| Azure database | Azure Database for MySQL Flexible Server (Burstable B1ms, 4 logical DBs) |
| Infra-as-code | Bicep (infra/bicep/) + a thin Python orchestrator (infra/provision.py) |
| Containers | Built exclusively via az acr build — no local Docker daemon anywhere in this project |
| Testing | pytest (38 unit tests across 6 suites) + smoke tests (pre-setup/post-setup/post-run/post-teardown) |
- Python 3.12 (required — the original repo pinned Flask 1.1.1/Werkzeug 1.0.1 from 2020, which breaks on Python 3.10+; this project modernizes every pin)
- Node.js 18+ and npm (for the React frontend)
- Azure CLI (
az) — only needed if you usemake provision/make teardown - No Docker, no Docker Desktop, no other accounts or API keys required
| Local (free, no Azure) | Azure (the flagship demo) | |
|---|---|---|
| Command | make setup then make run-all |
az login, then make provision BUDGET_EMAIL=you@example.com — make setup is not required for this path |
| What it needs | Python 3.12 + Node.js only | Azure CLI logged in to a subscription — that's it |
| Why | make setup creates the 5 local Python venvs + frontend npm deps that make run / make run-all / make test run against |
infra/provision.py has zero third-party dependencies (stdlib only) and builds every container image remotely via az acr build — it never touches the local venvs, so skipping make setup is fine if you're going straight to Azure |
| Cost | $0 | ~$0.21 for an 8-hour session, ~$19.51/mo if left running — see the cost table below. Run make teardown when done. |
Doing both (local first, then Azure) is completely fine too — the two paths don't conflict — but
neither is a prerequisite for the other. If you only care about the Azure demo, you can skip
straight to git clone → az login → make provision below without ever running make setup.
git clone <your-fork-url> flask-monolith-to-microservices # or any folder name you like
cd flask-monolith-to-microservices
cp .env.example .env # optional — sensible defaults work out of the box
make setup # creates 5 Python 3.12 venvs + installs frontend npm deps
make run-all # starts monolith + all 3 microservices + bff + frontend togetherOpen http://127.0.0.1:5173.
Use
make run-all(not plainmake run) if you plan to run the benchmark: the benchmark needs the monolith and product-service reachable at the same time, andmake runalone only starts the monolith (the guided Migrate flow starts the microservices but also stops the monolith in its last step, so the two are never both up together on that path).make run-allstarts everything at once with nothing auto-stopped, so both the walkthrough below and a real fresh Migrate demo both work from the same starting point.
Go in this order the first time:
- Shop (Monolith tab) — click "Add sample products", register an account, add items to the cart, and check out. This proves the "before" state fully works end-to-end.
- Metrics — click "Run Benchmark" — hits the monolith and product-service directly and
renders real p95 latency/throughput comparison charts. Results are saved to
results/, so the Metrics page keeps showing them even after later steps stop the monolith. - Migrate — click "Start Migration" — since the microservices are already running (from
make run-all), the extraction steps just confirm they're healthy; the final "Decommission" step still genuinely stops the monolith process. Not an animation — you cancurl http://127.0.0.1:5001/healthin another terminal to watch it stay alive, orcurl http://127.0.0.1:6000/healthafterward to see the monolith actually go down. - Shop (Microservices tab) — repeat step 1 against the new backend. You'll need to register again (separate database — your monolith account doesn't carry over, which is the point).
- Learn — a quieter read: the Strangler Fig pattern, anti-patterns to avoid, and glossary, sourced from the study guides that shaped this build.
Other useful commands:
make run # starts only monolith + bff + frontend — microservices stay down until you
# trigger a migration from the Migrate page (the purest "before" starting point)
make test # 38 unit tests across 6 suites
make smoke # pre-setup/post-setup/post-run/post-teardown smoke tests
make benchmark # same benchmark the Metrics page runs, from the CLI (needs monolith + product-service up)
make clean # removes local SQLite files, __pycache__, and benchmark resultsLocal dev self-heals from leftover processes: if a previous run is still holding a port, make run
(or make run-all) detects it (by checking that process's own command line and working directory against this
project), stops it cleanly, and proceeds — verified for real, including the case where a leftover
process's command line is a generic python run.py with no repo path in it at all (this project
launches every service with cwd=<service_dir>, so cwd is checked in addition to the command line).
| Variable | Purpose | Default |
|---|---|---|
RUN_MODE |
local (SQLite, plain processes) or azure (MySQL, Container Apps) |
local |
SECRET_KEY |
Flask session secret | dev placeholder — set a real value for any shared use |
MONOLITH_PORT / USER_SERVICE_PORT / PRODUCT_SERVICE_PORT / ORDER_SERVICE_PORT / BFF_PORT / FRONTEND_PORT |
Local service ports | 6000 / 5001 / 5002 / 5003 / 8000 / 5173 |
AZURE_MYSQL_HOST / AZURE_MYSQL_ADMIN_USER / AZURE_MYSQL_ADMIN_PASSWORD |
Populated automatically by infra/provision.py — never set manually |
— |
AZURE_LOCATION / AZURE_RESOURCE_GROUP / AZURE_BUDGET_CEILING_USD |
Azure provisioning defaults — AZURE_LOCATION is never hardcoded in code, infra/provision.py reads it from .env first (falling back to az config get defaults.location, then eastus) |
eastus / rg-flask-monolith-microservices / 25 |
No third-party API keys are required anywhere in this project.
This is the intended way to experience the migration story: only the monolith goes live at
first, and the microservices get created for real, in front of you, when you trigger the
migration from the browser. Nothing runs side-by-side in the cloud the way make run-all does
locally — the cloud story is strictly sequential (deploy monolith → migrate live → compare
before/after), which is what makes watching the migration actually happen feel real.
You do not need to run
make setupfirst.infra/provision.pyhas zero third-party dependencies and never touches the local Python venvs — the only prerequisite is being logged into the Azure CLI (az login). Clone the repo and go straight to the command below.
git clone <your-fork-url> flask-monolith-to-microservices
cd flask-monolith-to-microservices
az login
az account set --subscription "<subscription-id-or-name>" # if you have more than one
make provision BUDGET_EMAIL=you@example.comThis deploys the foundation (ACR, Container Apps Environment, MySQL Flexible Server, Static Web
App, Log Analytics, budget alert) plus exactly two Container Apps: monolith and bff. The
bff Container App gets a system-assigned managed identity with Contributor scoped to just this
one resource group — that's what lets it create the microservices' Container Apps itself later,
without you running any command for that step.
The demo sequence:
- Open the Static Web App URL printed at the end of
make provision. Shop works fully against the monolith — register, add to cart, checkout — running on real Azure MySQL. - Go to Metrics, run a benchmark now. This is your durable "before" number.
- Go to Migrate, click Start Migration. Watch
user-service, thenproduct-service, thenorder-serviceContainer Apps get created live (confirm in another terminal withaz containerapp list --resource-group <rg> -o tableif you want to see it from both sides), then the monolith scale to zero. - Shop automatically switches to serving from the microservices — no toggle to click.
- Run the benchmark again on Metrics for your "after" number.
make teardownwhen you're done recording.
make teardown
make verify # polls until every resource is confirmed deletedprovision.py resolves collision-safe resource names (auto-incrementing on any naming collision
— tested for real against a live throwaway Azure Container Registry during development, including
discovering and fixing an ACR-specific naming-rule edge case), deploys the trimmed
infra/bicep/main.bicep with the exact approved SKUs, builds every service image via az acr build up front (no local Docker) so the live migration only has to create Container Apps from
already-pushed images — fast and demo-safe instead of a slow image build happening on camera —
and creates a Cost Management budget alert before any billable resource exists.
| Resource | SKU | Free tier? | 8-hr test session | 30 days if left running |
|---|---|---|---|---|
| Azure Container Registry | Basic | No — cheapest tier | $0.06 | $5.01 |
| Container Apps (monolith + bff upfront; microservices created live by the migration), scale-to-zero | Consumption | Yes, effectively (large monthly free grant) | ~$0 | ~$0 |
| Azure Database for MySQL Flexible Server | Burstable B1ms | No — cheapest tier | $0.15 | $14.50 |
| Static Web Apps (frontend) | Free | Yes | $0 | $0 |
| Contributor role assignment (bff's identity, scoped to this resource group) | n/a | Free (control-plane only) | $0 | $0 |
| Total | ~$0.21 | ~$19.51 |
No resource exceeds the $50/30-day threshold. ACR and MySQL Flexible Server are the only two
resources here with no free tier anywhere in Azure — everything else is already Free/scale-to-zero.
MySQL Flexible Server is the one resource that bills whether idle or not — run make teardown
when you're done testing.
Everything above also runs entirely locally with no Azure involved at all — see the section below.
monolith/ BEFORE — single Flask app, one shared schema
microservices/{user,product,order}-service/ AFTER — 3 independent Flask apps
bff/ FastAPI: shop proxy, live migration engine, benchmark, Learn content
frontend/ React + TypeScript + Vite, Contoso theme
infra/ Bicep templates, provision.py, teardown.py, verify_teardown.py
scripts/ setup.py, run_local.py (+ port self-heal), benchmark.py
tests/ smoke/ (HTTP-based) + unit/ (name_resolver, migration_engine, procutil)
monolith/tests/, microservices/*/tests/, bff/tests/ per-service unit tests
make test # unit tests — no services need to be running
make smoke # smoke tests — pre-setup checks always run; post-setup/post-run/post-teardown
# checks skip gracefully if their prerequisite (make setup / make run / an Azure
# deployment) hasn't happened yet, rather than failing| Challenge | Solution |
|---|---|
| Original repo pinned Flask 1.1.1 (2020, breaks on Python 3.10+) | Modernized to Flask 3.1 / SQLAlchemy 2.0 / Python 3.12 throughout |
| No Docker Desktop allowed | Containers exist only on Azure, built via az acr build; local dev is plain processes |
| Benchmark fairness (Flask vs. FastAPI would be an unfair comparison) | Benchmark hits the monolith and a microservice directly, bypassing the FastAPI BFF |
| ACR names are alphanumeric-only (no hyphens) | Discovered via a real collision test — the resolver uses a hyphen-free increment scheme for ACR specifically |
| Flask's dev reloader spawns a child process sharing the parent's port | Port-collision cleanup snapshots every PID's identity before killing any, so a cascade-killed child isn't mistaken for a foreign process |
psutil.net_connections() requires root on macOS |
Switched to per-process Process.net_connections(), which doesn't — caught for real when the "Decommission" migration step hung forever |
Leftover processes have a generic python run.py command line with no repo path in it |
Ownership check also verifies the process's working directory, not just its command line — caught for real against the actual invocation pattern this project uses |
monolith/config.py originally wrote its SQLite file to the repo root instead of monolith/instance/ |
Path-joining bug fixed; verified the file lands in the right place |
make teardown # deletes every Azure resource
make verify # confirms deletion completed (polls — resource group deletion is asynchronous)make teardown is a no-op if nothing was ever provisioned (checks for infra/.state.json first).























