Polish repository layout

.dockerignore

@@ -2,6 +2,7 @@
 .venv/
 __pycache__/
 .pytest_cache/
+.ruff_cache/
 *.py[cod]
 .DS_Store
 .env

.github/workflows/test.yml

@@ -20,8 +20,8 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -r requirements.txt
-          python -m pip install -r requirements-dev.txt
+          python -m pip install -r requirements/base.txt
+          python -m pip install -r requirements/dev.txt
 
       - name: Lint
         run: python -m ruff check .

.gitignore

@@ -1,6 +1,7 @@
 .venv/
 __pycache__/
 .pytest_cache/
+.ruff_cache/
 *.py[cod]
 .env
 .DS_Store

Makefile

@@ -1,8 +1,16 @@
-.PHONY: test train bench replay compose compose-prod smoke docker-build
+.PHONY: lint compile test check train bench replay compose compose-prod smoke docker-build
+
+lint:
+	python -m ruff check .
+
+compile:
+	python -m compileall -q gateway worker training bench scripts tests
 
 test:
 	python -m pytest -q
 
+check: lint compile test
+
 train:
 	python training/train_text_model.py
 
@@ -13,10 +21,10 @@ replay:
 	python bench/replay_traffic.py --seconds-per-stage 8 --rps 18
 
 compose:
-	docker compose up --build
+	docker compose -f deploy/compose/docker-compose.yml up --build
 
 compose-prod:
-	docker compose -f docker-compose.prod.yml up --build
+	docker compose -f deploy/compose/docker-compose.prod.yml up --build
 
 smoke:
 	python scripts/smoke_check.py

README.md

@@ -9,7 +9,7 @@ The first version runs a FastAPI gateway in front of a few model workers. The ga
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate
-pip install -r requirements.txt
+pip install -r requirements/base.txt
 
 uvicorn worker.app.main:app --port 8011
 WORKER_URLS=http://localhost:8011 uvicorn gateway.app.main:app --port 8000
@@ -45,7 +45,7 @@ python bench/replay_traffic.py --seconds-per-stage 8 --rps 18
 ## Docker
 
 ```bash
-docker compose up --build
+make compose
 ```
 
 That starts Redis, one gateway, and two workers.
@@ -54,7 +54,7 @@ For a production-style local run:
 
 ```bash
 cp .env.example .env
-docker compose -f docker-compose.prod.yml up --build
+make compose-prod
 python scripts/smoke_check.py
 ```
 
@@ -69,6 +69,20 @@ keeps workers private and disables public worker failure controls.
 
 Deployment and validation steps are in `docs/hosted-demo.md`.
 
+## Repository layout
+
+```text
+gateway/          FastAPI gateway, routing, cache, metrics, dashboard
+worker/           model worker service and exported model artifact
+training/         MPS training and evaluation scripts
+bench/            benchmark and replay scripts with saved results
+scripts/          smoke checks and small operational helpers
+tests/            unit tests for gateway, worker, model, and settings
+docs/             architecture, deployment, report, and model card
+deploy/compose/   local Docker Compose files
+requirements/     runtime, development, and training dependency sets
+```
+
 ## Benchmarks
 
 The scenario runner starts local gateway and worker processes, sends load, then writes JSON and markdown results.
@@ -98,7 +112,7 @@ The worker can load a small trained text model artifact from `worker/app/artifac
 On Apple Silicon, the training script uses PyTorch MPS. It refuses to run on CPU by default so a slow accidental CPU run fails fast.
 
 ```bash
-pip install -r requirements-train.txt
+pip install -r requirements/train.txt
 python training/train_text_model.py
 ```
 

docker-compose.prod.yml → deploy/compose/docker-compose.prod.yml

@@ -6,23 +6,23 @@ services:
 
   worker-a:
     build:
-      context: .
+      context: ../..
       dockerfile: worker/Dockerfile
     restart: unless-stopped
     environment:
       WORKER_ID: worker-a
 
   worker-b:
     build:
-      context: .
+      context: ../..
       dockerfile: worker/Dockerfile
     restart: unless-stopped
     environment:
       WORKER_ID: worker-b
 
   gateway:
     build:
-      context: .
+      context: ../..
       dockerfile: gateway/Dockerfile
     restart: unless-stopped
     environment:

docker-compose.yml → deploy/compose/docker-compose.yml

@@ -6,7 +6,7 @@ services:
 
   worker-a:
     build:
-      context: .
+      context: ../..
       dockerfile: worker/Dockerfile
     environment:
       WORKER_ID: worker-a
@@ -15,7 +15,7 @@ services:
 
   worker-b:
     build:
-      context: .
+      context: ../..
       dockerfile: worker/Dockerfile
     environment:
       WORKER_ID: worker-b
@@ -25,7 +25,7 @@ services:
 
   gateway:
     build:
-      context: .
+      context: ../..
       dockerfile: gateway/Dockerfile
     environment:
       WORKER_URLS: http://worker-a:9000,http://worker-b:9000

docs/demo.md

@@ -5,7 +5,7 @@ This is the local demo flow I use to show the system moving.
 Terminal 1:
 
 ```bash
-docker compose up --build
+make compose
 ```
 
 Open:

docs/deployment.md

@@ -6,7 +6,7 @@ ModelMesh is still easiest to demo locally because the failure controls and traf
 
 ```bash
 cp .env.example .env
-docker compose -f docker-compose.prod.yml up --build
+make compose-prod
 python scripts/smoke_check.py
 ```
 

gateway/Dockerfile

@@ -4,7 +4,7 @@ ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONUNBUFFERED=1
 
 WORKDIR /app
-COPY requirements.txt .
+COPY requirements/base.txt ./requirements.txt
 RUN pip install --no-cache-dir -r requirements.txt
 
 COPY gateway ./gateway

worker/Dockerfile

@@ -4,7 +4,7 @@ ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONUNBUFFERED=1
 
 WORKDIR /app
-COPY requirements.txt .
+COPY requirements/base.txt ./requirements.txt
 RUN pip install --no-cache-dir -r requirements.txt
 
 COPY worker ./worker