Initial scaffold: FastAPI micro-service with Docker, SQLite, tests

2026-06-05 02:45:49 +02:00
commit 350143ceb4
16 changed files with 460 additions and 0 deletions
@@ -0,0 +1,109 @@
+# ARCHITECTURE.md — Micro-API
+
+## Overview
+
+Micro-API is the foundation service of the organization's micro-services platform. It provides a lightweight HTTP API designed to be deployed on a single VPS and scaled horizontally as needs grow.
+
+## Design Principles
+
+1. **Zero cost** — No paid services, no cloud dependencies. Runs on the existing VPS behind Traefik/Caddy.
+2. **Simplicity first** — SQLite for local dev and single-node deploys. Postgres optional when multi-service.
+3. **Containerized** — Every service ships as a Docker container, orchestrated via docker-compose.
+4. **Stateless API** — Health-checkable, horizontally scalable behind a reverse proxy.
+5. **Tested from day one** — pytest on every service before deploy.
+
+## System Architecture
+
+```
+┌──────────────────────────────────────────┐
+│              VPS (82.165.176.5)           │
+│                                           │
+│  ┌─────────┐   ┌──────────────────────┐  │
+│  │ Traefik │──▶│   micro-api:8000     │  │
+│  │  :443   │   │   (Docker container) │  │
+│  └─────────┘   │   FastAPI + Uvicorn  │  │
+│                │   SQLite /data/       │  │
+│                └──────────────────────┘  │
+│                                           │
+│  ┌──────────────────────────────────┐    │
+│  │  Future services (API v2, ...)   │    │
+│  └──────────────────────────────────┘    │
+└──────────────────────────────────────────┘
+```
+
+## Data Flow
+
+```
+Client ──HTTPS──▶ Traefik ──HTTP──▶ micro-api:8000
+                                        │
+                                        ▼
+                                   SQLite (file)
+                                  /data/app.db
+```
+
+## Database Strategy
+
+### Phase 1 — SQLite (current)
+- Single file: `data/app.db`
+- WAL mode enabled for concurrent reads
+- Docker volume-mounted for persistence
+- Backups via `sqlite3 .backup` or file copy during VPS backup window
+
+### Phase 2 — Postgres (optional)
+- Add `psycopg2` to requirements
+- Set `DATABASE_URL=postgresql://...`
+- Add a `postgres` service to `docker-compose.yml`
+- Run migrations via Alembic
+
+## Deployment Plan
+
+### Target
+- VPS: `82.165.176.5` (founder@82.165.176.5)
+- Path: `/opt/micro-api/`
+- Managed via: `docker compose`
+
+### Steps (not yet executed)
+1. Push repo to Gitea: `http://82.165.176.5`
+2. SSH to VPS, clone to `/opt/micro-api/`
+3. `cp .env.example .env` and adjust
+4. `docker compose up -d --build`
+5. Verify: `curl http://localhost:8000/api/health`
+6. Add Traefik route label to docker-compose
+
+### Reverse Proxy Integration
+
+Add these labels to `docker-compose.yml` when Traefik is running:
+
+```yaml
+labels:
+  - "traefik.enable=true"
+  - "traefik.http.routers.micro-api.rule=Host(`api.your-domain.com`)"
+  - "traefik.http.services.micro-api.loadbalancer.server.port=8000"
+```
+
+## Security
+
+- No secrets in code — everything via env vars
+- `.env` is gitignored, `.env.example` is the template
+- CORS is open (`*`) for now — restrict in production
+- Container runs as non-root in future iteration
+
+## Testing Strategy
+
+- **Unit tests**: pytest on all routes, models, and DB utilities
+- **Integration**: `TestClient` against the FastAPI app
+- **Smoke test**: `curl /api/health` after deploy
+- **CI**: GitHub Actions / Gitea Actions (future)
+
+## Future Services
+
+Each new micro-service follows the same scaffold:
+1. Copy this template
+2. Add service-specific routes/models
+3. Add to the main `docker-compose.yml`
+4. Register with Traefik
+
+## Maintainers
+
+- **Founder** — architecture decisions, deployment
+- **AutoClaw (forge agent)** — initial scaffold, CI/CD