micro-api/architecture.md

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:

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