Initial scaffold: FastAPI micro-services API (forge + founder)
This commit is contained in:
+44
-99
@@ -1,109 +1,54 @@
|
||||
# ARCHITECTURE.md — Micro-API
|
||||
# Architecture — MicroAPI
|
||||
|
||||
## Overview
|
||||
## Stack
|
||||
|
||||
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.
|
||||
| Couche | Technologie | Justification |
|
||||
|---|---|---|
|
||||
| Framework | FastAPI | Performant, async, documentation auto (Swagger) |
|
||||
| Serveur | Uvicorn | ASGI, production-ready |
|
||||
| Runtime | Python 3.11+ | Écosystème riche, gratuit |
|
||||
| Base de données | SQLite (phase 1) | Zéro ops, migration vers PostgreSQL si besoin |
|
||||
| Conteneurisation | Docker | Isolation, déploiement reproductible |
|
||||
| Reverse proxy | Caddy (existant) | Routing, HTTPS |
|
||||
| Paiements | Lemon Squeezy | MoR, 0€/mois, gère TVA |
|
||||
| Emails | Resend (gratuit 3K/mois) | Transactionnel |
|
||||
| Monitoring | Uptime Kuma (existant) | Health checks |
|
||||
|
||||
## 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
|
||||
## Structure des dossiers
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ VPS (82.165.176.5) │
|
||||
│ │
|
||||
│ ┌─────────┐ ┌──────────────────────┐ │
|
||||
│ │ Traefik │──▶│ micro-api:8000 │ │
|
||||
│ │ :443 │ │ (Docker container) │ │
|
||||
│ └─────────┘ │ FastAPI + Uvicorn │ │
|
||||
│ │ SQLite /data/ │ │
|
||||
│ └──────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ Future services (API v2, ...) │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────┘
|
||||
micro-api/
|
||||
├── main.py # Application FastAPI
|
||||
├── requirements.txt # Dépendances Python
|
||||
├── Dockerfile # Image Docker
|
||||
├── docker-compose.yml # Stack de déploiement
|
||||
├── README.md # Documentation utilisateur
|
||||
├── ARCHITECTURE.md # Ce document
|
||||
├── tests/ # Tests unitaires & intégration
|
||||
│ └── test_health.py
|
||||
├── app/ # Code applicatif (à venir)
|
||||
│ ├── routers/ # Endpoints API
|
||||
│ ├── services/ # Logique métier (transcription, etc.)
|
||||
│ ├── models/ # Modèles de données
|
||||
│ └── utils/ # Utilitaires
|
||||
└── data/ # Données persistantes (volumes)
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
## Principes
|
||||
|
||||
```
|
||||
Client ──HTTPS──▶ Traefik ──HTTP──▶ micro-api:8000
|
||||
│
|
||||
▼
|
||||
SQLite (file)
|
||||
/data/app.db
|
||||
```
|
||||
1. **Stateless** — Chaque requête est indépendante, pas de session serveur
|
||||
2. **Async-first** — Tous les endpoints sont async par défaut
|
||||
3. **API-first** — Documentation Swagger automatique sur `/docs`
|
||||
4. **12-factor** — Configuration par variables d'environnement
|
||||
5. **Zéro coût opérationnel** — Whisper local, pas d'API externe payante
|
||||
|
||||
## Database Strategy
|
||||
## Roadmap technique
|
||||
|
||||
### 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
|
||||
1. ✅ Scaffold (health check, structure)
|
||||
2. ⬜ Endpoint /api/transcribe (Whisper local, upload fichier)
|
||||
3. ⬜ Endpoint /api/summarize (Résumé de texte)
|
||||
4. ⬜ Endpoint /api/convert (Markdown→PDF, JSON→CSV)
|
||||
5. ⬜ Authentification API keys
|
||||
6. ⬜ Rate limiting + quotas
|
||||
7. ⬜ Intégration Lemon Squeezy (paiements)
|
||||
8. ⬜ Dashboard utilisateur
|
||||
|
||||
Reference in New Issue
Block a user