founder
110 lines
4.1 KiB
Markdown
110 lines
4.1 KiB
Markdown
# 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
|