fix: Resolve model loading and deployment issues

This commit fixes several critical issues that prevented the service from deploying correctly and loading the TTS models.

- **Fix Model Loading:** Corrected the volume mount path in  to point to the correct  source directory. The  engine code was also updated to use absolute paths () inside the container, making the model loading mechanism robust.
- **Update Session Resume:** The  has been updated to reflect the final debugging steps and the successful resolution of all issues.

app/engines/piper.py

@@ -29,7 +29,7 @@ class PiperEngine(TTSEngineBase):
 
     def _load_config(self, model: str):
         """Load the model config JSON file to get speaker mappings."""
-        model_dir = f"./app/models/piper/{model}"
+        model_dir = f"/models/piper/{model}"
         config_file = os.path.join(model_dir, f"{model}.onnx.json")
         if os.path.isfile(config_file):
             with open(config_file, 'r') as f:
@@ -60,7 +60,7 @@ class PiperEngine(TTSEngineBase):
             raise RuntimeError("Piper executable not found. Please install it and ensure it's in your PATH.")
         if not model:
             raise ValueError("Model must be specified for Piper.")
-        model_dir = f"./app/models/piper/{model}"
+        model_dir = f"/models/piper/{model}"
         model_file = os.path.join(model_dir, f"{model}.onnx")
         if not os.path.isfile(model_file):
             raise FileNotFoundError(f"Piper model not found: {model_file}")
@@ -108,7 +108,7 @@ class PiperEngine(TTSEngineBase):
         return output_other_path
 
     def list_models(self):
-        models_dir = "./app/models/piper/"
+        models_dir = "/models/piper/"
         if not os.path.isdir(models_dir):
             return []
         return [name for name in os.listdir(models_dir)

docker-compose.yml

@@ -8,8 +8,8 @@ services:
     volumes:
       # Mount local app directory for hot-reloading in dev
       - ./app:/home/appuser/app
-      # Mount models directory to provide models to the container
+      # Mount models directory to a top-level directory in the container
-      - ./models:/home/appuser/app/models
+      - ./app/models:/models
       # Mount asset directory to persist generated audio files
       - ./asset:/home/appuser/app/asset
     command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

session_resumee.md

@@ -89,6 +89,30 @@ The project was a modular FastAPI-based TTS server with a `TTSEngineBase` interf
 
 ---
 
-**Next Steps (Troubleshooting the 404):**
+### Final Debugging & Resolution (Post-Refactoring)
 
-The `404 page not found` when accessing `http://localhost/health` via Traefik is the current blocker for full verification. I need to investigate the logs of the `audio-engine-hub_app` container (the FastAPI app) to determine if the application itself is starting correctly and serving the `/health` endpoint as expected. If the app is indeed serving, the issue lies with Traefik's routing configuration.
+After the major refactoring, the service was unable to start and was returning `404` errors. The final debugging session addressed these issues.
+
+1.  **FastAPI App Startup Fix:**
+    *   **Problem:** The Uvicorn server was failing with `Attribute "app" not found in module "app.main"`.
+    *   **Solution:** The `app` instance was only created inside the `if __name__ == "__main__"` block. Moved `app = create_app()` to the module's global scope in `app/main.py` so Uvicorn could find it.
+
+2.  **Traefik & Docker Compose Issues:**
+    *   **Problem:** The initial `docker-compose.yml` included a Traefik service for reverse proxying, which was causing multiple issues (invalid container names due to missing `.env` variables, Docker client API version errors). The user also clarified that they use an existing reverse proxy and did not want a new Traefik container deployed.
+    *   **Solution:** Removed the `traefik` service entirely from `docker-compose.yml`. The `app` service's port was exposed directly to the host.
+
+3.  **Model Loading Failure:**
+    *   **Problem:** The `piper` engine was not loading any models, returning an empty list and causing `/tts` requests to fail with a `422 Unprocessable Entity` error.
+    *   **Diagnosis:** The root cause was an incorrect volume mount. The `docker-compose.yml` was attempting to mount a non-existent, empty `./models` directory from the host. The actual models were located in `./app/models`.
+    *   **Solution:**
+        1.  Corrected the `docker-compose.yml` volume mount to point to the correct source directory: `- ./app/models:/models`.
+        2.  Updated the `app/engines/piper.py` code to use the absolute path `/models/piper/` to look for models inside the container, making the configuration more robust and independent of the working directory.
+
+4.  **Developer Experience (DX) Improvements:**
+    *   **Automatic Port Finding:** The `Makefile` was enhanced. The `make up` and `make run` commands now automatically find a free port starting from 8000, preventing port conflicts.
+    *   **Health Check Command:** A `make health-check` target was added. It runs a sanity check against the deployed container's `/health` endpoint to verify that the service is up and all engines are reporting an "ok" status.
+    *   **Documentation:**
+        *   The `README.md` was completely rewritten to provide a clear and up-to-date guide for getting started, usage, and available `make` commands.
+        *   A note was added to `docs/guide.md` to clarify that it describes an older, more advanced setup and to point readers to the new `README.md`.
+
+**Final Status:** The service is now fully deployable via `make up` and passes `make health-check`. All identified startup issues and bugs have been resolved.