From c566e294bcad5a95af4f3e0aee7dffac9345a24f Mon Sep 17 00:00:00 2001 From: Christian Date: Fri, 16 Oct 2026 17:16:32 +0200 Subject: [PATCH] docs: update README.md with DAG validator, catalog loader, and 100+ product scaling guide --- README.md | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index de566c5..eda0aa9 100644 --- a/README.md +++ b/README.md @@ -21,10 +21,16 @@ The game is packaged as a lightweight, turnkey **Docker Compose stack** powered 1. **Agriculture & Food:** Wheat, Milled Flour, Sugar Beet, Refined Sugar, Artisan Bread, Packaged Meals. 2. **Forestry & Materials:** Raw Timber, Milled Planks, Industrial Paper, Office Furniture. 3. **Mining & Metallurgy:** Iron Ore, Coking Coal, Structural Steel, Heavy Frameworks. - 4. **Chemicals & Polymers:** Crude Oil, Silica Quartz Sand, Industrial Polymers, Purified Silicon. + 4. **Chemicals & Polymers:** Crude Oil, Silica Quartz Sand, Industrial Polymers, Purified Silicon, Industrial Fertilizer. 5. **High-Tech & Electronics:** Silicon Microchips, PCB Motherboards, Consumer Smartphones. 6. **Heavy Industry & Vehicles:** Industrial Engines, Commercial Logistics Trucks. +* **Modular "Plug & Play" Product Architecture (Scale to 100+ Products):** + * Sector manifests are stored as self-contained ES-module catalog files under `frontend/js/data/sectors/*.js`. + * **Single Source of Truth:** The Python FastAPI backend dynamically parses and registers sector files on startup (`backend/catalog_loader.py`), keeping frontend and backend simulation logic 100% in sync without duplicated configurations. + * Creating a new sector or adding 10, 50, or 100+ new units requires simply dropping a new sector file or object into `frontend/js/data/sectors/` and adding matching photos. + * See [`PRODUCT_GENERATOR_GUIDE.md`](./PRODUCT_GENERATOR_GUIDE.md) for complete manifest schemas, AI generator prompts, and instructions for bulk-adding products and sectors. + * **Dedicated Facility Intelligence Dossier (Unit Detail View):** * Clicking any facility card opens a comprehensive, full-page analytics dossier tailored for data and numbers enthusiasts. * **Financial Telemetry:** Wholesale unit price, live revenue/s, projected revenue/hour, asset valuation, and stock inventory value. @@ -108,12 +114,18 @@ docker compose up -d --build The game is live in your browser at: 👉 **`http://localhost:8081`** (or the port defined in `.env`). -### 4. Running Backend Verification Tests -To run the automated Python backend engine simulation tests: +### 4. Running Verification & DAG Validation +To run the automated backend engine simulation tests: ```bash python backend/test_engine.py ``` +To run the automated supply chain integrity and DAG validator: +```bash +python backend/validate_dag.py +``` +*(Verifies cycle-free graphs, valid input/output dependencies, positive tier-margin economics, and file reference consistency across all modular sectors.)* + --- ## 📁 Project Directory Structure @@ -122,16 +134,19 @@ python backend/test_engine.py . ├── .env.example ├── docker-compose.yml -├── FACILITY_PHOTO_PROMPT_GUIDE.md # Photographic generation guide for all 24 units & goods +├── FACILITY_PHOTO_PROMPT_GUIDE.md # Photographic generation guide for units & goods +├── PRODUCT_GENERATOR_GUIDE.md # AI prompt & schema guide for scaling to 100+ products ├── backend/ │ ├── Dockerfile │ ├── requirements.txt │ ├── auth.py # JWT authentication & password hashing +│ ├── catalog_loader.py # Dynamic loader for modular frontend sector files │ ├── database.py # SQLite connection and migration setup │ ├── engine.py # Authoritative DAG simulation and offline calculations │ ├── main.py # FastAPI endpoints │ ├── models.py # Pydantic schemas -│ └── test_engine.py # Comprehensive backend regression test suite +│ ├── test_engine.py # Comprehensive backend regression test suite +│ └── validate_dag.py # Automated DAG integrity, cycle & margin validator ├── frontend/ │ ├── index.html # Full-width executive workspace layout │ ├── assets/ @@ -161,8 +176,8 @@ python backend/test_engine.py │ │ ├── state.js # State manager, schema handling & IPO reset │ │ └── sync.js # Backend synchronization & auth handling │ ├── data/ -│ │ ├── products.js # 24+ commodities across 6 sectors -│ │ ├── sectors/ # Modular sector & product definitions +│ │ ├── products.js # Central re-exporter of modular sectors +│ │ ├── sectors/ # Modular sector & product definitions (Agriculture, etc.) │ │ ├── contracts.js # B2B procurement tenders │ │ ├── boardroom.js # IPO perks and Venture Share logic │ │ └── achievements.js @@ -184,4 +199,5 @@ python backend/test_engine.py ## 🎨 Asset Generation & Custom Visuals -Refer to [`FACILITY_PHOTO_PROMPT_GUIDE.md`](./FACILITY_PHOTO_PROMPT_GUIDE.md) for master prompts and camera recipes to generate photorealistic assets for all 24 production facilities and commodities using modern image models (Midjourney, Stable Diffusion, Imagen). Dropping generated images into `frontend/assets/images/facilities/` and `frontend/assets/images/products/` seamlessly populates the facility dossiers without modifying any code. +* Refer to [`FACILITY_PHOTO_PROMPT_GUIDE.md`](./FACILITY_PHOTO_PROMPT_GUIDE.md) for master prompts and camera recipes to generate photorealistic assets for production facilities and commodities using modern image models (Midjourney, Stable Diffusion, Imagen). Dropping generated images into `frontend/assets/images/facilities/` and `frontend/assets/images/products/` seamlessly populates the facility dossiers without modifying any code. +* Refer to [`PRODUCT_GENERATOR_GUIDE.md`](./PRODUCT_GENERATOR_GUIDE.md) when generating new products, supply chain DAG tiers, or entire industry sectors.