Add minimal FastAPI service with health and version endpoints

Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com>

README.md

@@ -1,2 +1,57 @@
-# blackroad-os-api
+# BlackRoad OS API
-Create a minimal Operator service skeleton:  - app/: FastAPI or plain Python entrypoint with a /health endpoint - workers/: placeholder module for background jobs and agent orchestration - infra/: Dockerfile, requirements.txt, and a sample railway.toml with no secrets Use simple placeholder code only. Do not add complex business logic.
+
+A minimal FastAPI service for BlackRoad OS with health and version endpoints.
+
+## Project Structure
+
+```
+.
+├── app/              # FastAPI application
+│   ├── __init__.py   # Package initialization with version
+│   └── main.py       # Main application with /health and /version endpoints
+├── schemas/          # Pydantic models for requests/responses
+│   ├── __init__.py
+│   └── responses.py  # Response models
+└── infra/            # Infrastructure and deployment files
+    ├── Dockerfile    # Docker container configuration
+    ├── requirements.txt  # Python dependencies
+    └── railway.toml  # Railway.app deployment configuration
+```
+
+## Getting Started
+
+### Local Development
+
+1. Install dependencies:
+```bash
+pip install -r infra/requirements.txt
+```
+
+2. Run the server:
+```bash
+uvicorn app.main:app --reload
+```
+
+3. Access the API:
+- Health check: http://localhost:8000/health
+- Version: http://localhost:8000/version
+- API docs: http://localhost:8000/docs
+
+### Docker
+
+Build and run with Docker:
+```bash
+docker build -f infra/Dockerfile -t blackroad-os-api .
+docker run -p 8000:8000 blackroad-os-api
+```
+
+### Deploy to Railway
+
+This project includes a `railway.toml` configuration file for easy deployment to Railway.app.
+
+## API Endpoints
+
+- `GET /health` - Health check endpoint returning `{"status": "ok"}`
+- `GET /version` - Version endpoint returning `{"version": "0.1.0"}`
+- `GET /docs` - Interactive API documentation (Swagger UI)
+- `GET /redoc` - Alternative API documentation (ReDoc)

app/__init__.py

@@ -0,0 +1,3 @@
+"""BlackRoad OS API - Minimal API service."""
+
+__version__ = "0.1.0"

app/main.py

@@ -0,0 +1,23 @@
+"""FastAPI main application with health and version endpoints."""
+
+from fastapi import FastAPI
+
+from app import __version__
+
+app = FastAPI(
+    title="BlackRoad OS API",
+    description="Minimal API service for BlackRoad OS",
+    version=__version__,
+)
+
+
+@app.get("/health")
+async def health():
+    """Health check endpoint."""
+    return {"status": "ok"}
+
+
+@app.get("/version")
+async def version():
+    """Version endpoint."""
+    return {"version": __version__}

infra/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Copy requirements and install dependencies
+COPY infra/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY app/ ./app/
+COPY schemas/ ./schemas/
+
+# Expose port
+EXPOSE 8000
+
+# Run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

infra/railway.toml

@@ -0,0 +1,13 @@
+# Sample Railway.toml configuration
+# This is a sample configuration for deploying on Railway.app
+# For more details, visit: https://docs.railway.app/reference/config-as-code
+
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "infra/Dockerfile"
+
+[deploy]
+startCommand = "uvicorn app.main:app --host 0.0.0.0 --port $PORT"
+healthcheckPath = "/health"
+healthcheckTimeout = 100
+restartPolicyType = "ON_FAILURE"

infra/requirements.txt

@@ -0,0 +1,3 @@
+fastapi==0.115.5
+uvicorn[standard]==0.32.1
+pydantic==2.10.3

schemas/__init__.py

@@ -0,0 +1 @@
+"""Placeholder Pydantic models for BlackRoad OS API."""

schemas/responses.py

@@ -0,0 +1,15 @@
+"""Placeholder Pydantic models for API requests and responses."""
+
+from pydantic import BaseModel
+
+
+class HealthResponse(BaseModel):
+    """Health check response model."""
+
+    status: str
+
+
+class VersionResponse(BaseModel):
+    """Version response model."""
+
+    version: str