docs: Update README and architecture documents with build instructions and detailed data models

README.md

@@ -38,13 +38,27 @@ For contributors: the `routes/`, `models/` and `services/` folders contain the p
 
 The repository ships with a multi-stage `Dockerfile` that produces a slim runtime image.
 
+### Build container
+
 ```powershell
 # Build the image locally
 docker build -t calminer:latest .
+```
 
-# Run the container (exposes FastAPI on http://localhost:8000)
-docker run --rm -p 8000:8000 calminer:latest
+### Push to registry
 
+```powershell
+# Tag and push the image to your registry
+docker login your-registry.com -u your-username -p your-password
+docker tag calminer:latest your-registry.com/your-namespace/calminer:latest
+docker push your-registry.com/your-namespace/calminer:latest
+```
+
+### Run container
+
+Expose FastAPI on <http://localhost:8000> with database configuration via granular environment variables:
+
+```powershell
 # Provide database configuration via granular environment variables
 docker run --rm -p 8000:8000 ^
   -e DATABASE_DRIVER="postgresql" ^
@@ -57,6 +71,8 @@ docker run --rm -p 8000:8000 ^
   calminer:latest
 ```
 
+### Orchestrated Deployment
+
 Use `docker compose` or an orchestrator of your choice to co-locate PostgreSQL/Redis alongside the app when needed. The image expects migrations to be applied before startup.
 
 ## CI/CD expectations