Task 001: dockerized monorepo foundation

docs/public-health-interfaces.md

@@ -0,0 +1,120 @@
+# Public Health Interfaces
+
+Task 001 pre-requirement contract. These interfaces are the public test surface
+for the dockerized foundation implementation. Tests must exercise only the
+Docker Compose stack and HTTP endpoints, not service internals.
+
+## Local Stack
+
+The local stack starts from the repository root:
+
+```sh
+docker compose up --build
+```
+
+The implementation must expose these local ports:
+
+| Service | URL |
+| --- | --- |
+| Frontend | `http://localhost:3000` |
+| Backend | `http://localhost:8000` |
+| Runner | `http://localhost:8010` |
+
+## Health Endpoints
+
+### Backend Process Health
+
+```http
+GET http://localhost:8000/health
+```
+
+Expected response:
+
+```json
+{
+  "service": "backend",
+  "status": "ok"
+}
+```
+
+This endpoint proves that the FastAPI process is serving HTTP.
+
+### Backend Connectivity Smoke
+
+```http
+GET http://localhost:8000/health/dependencies
+```
+
+Expected response:
+
+```json
+{
+  "service": "backend",
+  "status": "ok",
+  "dependencies": {
+    "postgres": "ok",
+    "redis": "ok",
+    "object_storage": "ok"
+  }
+}
+```
+
+This endpoint is the public smoke surface for backend connectivity to Postgres,
+Redis, and S3-compatible object storage. Implementations may add fields, but
+must preserve these keys and `ok` statuses when dependencies are reachable.
+
+### Runner Health
+
+```http
+GET http://localhost:8010/health
+```
+
+Expected response:
+
+```json
+{
+  "service": "runner",
+  "status": "ok"
+}
+```
+
+### Frontend Health
+
+```http
+GET http://localhost:3000/health
+```
+
+Expected response:
+
+```json
+{
+  "service": "frontend",
+  "status": "ok"
+}
+```
+
+## Architecture Boundaries
+
+The frontend application must follow Feature-Sliced Design with these top-level
+layers:
+
+```text
+app/
+processes/
+pages/
+widgets/
+features/
+entities/
+shared/
+```
+
+The backend and runner services must use these top-level architecture layers:
+
+```text
+domain/
+application/
+infrastructure/
+presentation/
+shared/
+```
+