docs: streamline README with natural technical overview

README.md

@@ -1,8 +1,90 @@
 ---
-title: HF Backend Host
+title: HF Backend
 emoji: ⚡
-colorFrom: indigo
-colorTo: blue
+colorFrom: purple
+colorTo: indigo
 sdk: docker
 app_port: 7860
 ---
+
+# HF Backend
+
+FastAPI host running on a Hugging Face Docker Space. It mounts backend routers from separate project repositories under specific URL prefixes.
+
+## How it works
+
+The host application does not define business logic. Each subproject lives in its own repository, exposes a router in `<package>/router.py`, and is installed as a Python package.
+
+The host imports each router dynamically from `registry.py` and mounts it under a prefix. If an individual router fails to import, the host logs the error, records the failure, and keeps running for the other services.
+
+```
+/project-1/* -> HEARTFLOW_OS backend router
+/project-2/* -> Semantic Comment Analyzer backend router
+/health      -> Host health status
+```
+
+## Adding a project
+
+Adding a new service takes two steps:
+
+1. Add the prefix and router path to `registry.py`:
+```python
+PROJECT_REGISTRY = {
+    "/project-1": "heartflow_backend.router:router",
+    "/project-2": "semantic_backend.router:router",
+    "/project-3": "new_project.router:router",
+}
+```
+
+2. Add the pinned Git tag to `requirements.txt`:
+```text
+git+https://github.com/<user>/<repo>.git@v1.0#subdirectory=backend
+```
+
+Pushing to `main` syncs the change to Hugging Face and rebuilds the Space container.
+
+## Configuration
+
+Set these in the Space settings under **Variables and secrets**:
+
+| Variable | Required | Default | Notes |
+| :--- | :--- | :--- | :--- |
+| `CORS_ALLOWED_ORIGINS` | No | None | Comma-separated allowed origins. Wildcards (`*`) are ignored. |
+| `DISABLE_PROJECTS` | No | None | Comma-separated prefixes to skip loading (e.g. `project-2`). |
+| `MAX_BODY_SIZE_BYTES` | No | 10485760 (10 MB) | Max request body size before returning 413. |
+| `REQUEST_TIMEOUT_SECONDS` | No | 60.0 | Request timeout before returning 504. |
+| `GITHUB_TOKEN` | Only for private repos | None | GitHub token passed as a build secret to clone private dependencies. |
+
+GitHub repository secrets (used by GitHub Actions):
+
+| Secret | Notes |
+| :--- | :--- |
+| `HF_BACKEND_SPACE` | Hugging Face write token used to push code and trigger Space restart. |
+| `HF_SPACE_URL` | Optional. Health URL for the keep-alive workflow. |
+
+## Endpoints
+
+### `GET /health`
+Returns the status of the host and each registered project.
+
+```json
+{
+  "status": "healthy",
+  "loaded": {
+    "/project-1": "heartflow_backend.router:router",
+    "/project-2": "semantic_backend.router:router"
+  },
+  "failed": {}
+}
+```
+
+If any service fails to load, `status` changes to `"degraded"` or `"unhealthy"` and the error is listed under `"failed"`.
+
+Interactive documentation (`/docs`, `/redoc`, `/openapi.json`) is disabled.
+
+## Release workflow
+
+1. Test changes in the project repository using its `dev.py`.
+2. Tag the release (`git tag v1.0`, `git push origin v1.0`).
+3. Update the tag in this repo's `requirements.txt`.
+4. Push to `main`. The GitHub Actions workflow pushes to Hugging Face and restarts the Space.