# 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