From ee149d1fb9d777b6d2f2e7af775c6cb535765816 Mon Sep 17 00:00:00 2001 From: 365 Date: Thu, 4 Jun 2026 21:17:16 +0200 Subject: [PATCH] Add Shell infra MVP priorities --- docs/architecture/scalability-principles.md | 12 ++++ .../ADR-0004-shell-infra-mvp-priorities.md | 69 +++++++++++++++++++ factory-control-center/database/schema.sql | 6 ++ 3 files changed, 87 insertions(+) create mode 100644 docs/decisions/ADR-0004-shell-infra-mvp-priorities.md diff --git a/docs/architecture/scalability-principles.md b/docs/architecture/scalability-principles.md index 06b5b62..840f70d 100644 --- a/docs/architecture/scalability-principles.md +++ b/docs/architecture/scalability-principles.md @@ -11,6 +11,8 @@ 5. **Circuit breaker** sur les dépendances externes (cf v2 lib/circuitBreaker.ts) 6. **Cache** uniquement après mesure (pas de cache prématuré) 7. **CDN** pour assets statiques (Vercel/Cloudflare auto) +8. **Indexes avant replicas** : optimiser les requetes et index critiques avant + d'ajouter de la replication Postgres. ## Patterns appliqués @@ -24,9 +26,19 @@ | Billing gate / auto-degrade | v2 Stripe webhook + site_config + cron auto-degrade | | Append-only logs | growth-data-layer consent_ledger + lead_delivery_log | +## Ordre d'adoption Shell + +| Niveau | Briques | +|--------|---------| +| MVP prod | HTTPS, cookies secure, indexes SQL, queue + worker, rate limit, logs, uptime, CORS explicite, smoke tests, rollback manuel | +| MVP multi-sites | factory-control-center, `ops/services/*.yml`, staging obligatoire, couts/incidents/deployments visibles | +| Ops avance | API Gateway, blue-green/canary, Prometheus + Grafana + Alertmanager, load balancer, Redis + BullMQ | +| Scale | Redis cache mesure, analytics hors DB principale, read replicas, WebSockets si temps reel reel | + ## Anti-patterns ❌ Optimiser avant de mesurer ❌ Cache invalidation distribuée prématurée ❌ Microservices avant que monolithe pose problème ❌ k8s pour 5 utilisateurs +❌ Read replicas avant indexation et analyse `EXPLAIN` diff --git a/docs/decisions/ADR-0004-shell-infra-mvp-priorities.md b/docs/decisions/ADR-0004-shell-infra-mvp-priorities.md new file mode 100644 index 0000000..0171344 --- /dev/null +++ b/docs/decisions/ADR-0004-shell-infra-mvp-priorities.md @@ -0,0 +1,69 @@ +# ADR-0004 - Shell infra MVP priorities + +## Status +Accepted - 2026-06-04 + +## Context +Shell doit rester capable de lancer plusieurs SaaS sans dette de securite ni +backend freestyle. La discussion du 2026-06-04 a compare plusieurs briques +infra : HTTPS, API gateway, Prometheus, replication Postgres, blue-green deploy, +WebSockets, CORS, SQL indexes, load balancer, Redis cache et message queue. + +Le risque principal est de confondre une stack PaaS serieuse avec une stack +distribuee trop lourde pour le MVP. Shell doit donc formaliser les priorites +sans transformer chaque brique en obligation immediate. + +## Decision +Shell adopte une progression en quatre niveaux. + +### MVP prod +- HTTPS obligatoire. +- Cookies securises, OAuth et Stripe uniquement derriere HTTPS. +- Index SQL sur les colonnes de lookup, ownership, status et chronologie. +- Queue + worker pour toute tache longue, avec le pattern Postgres `SKIP LOCKED` + par defaut. +- Rate limiting, logs structures, uptime checks, Sentry ou equivalent. +- CORS configure explicitement, sans le traiter comme une brique produit. +- Rollback manuel documente et smoke tests post-deploy. + +### MVP multi-sites +- `factory-control-center` devient la vue centrale des sites, incidents, couts, + decisions et deploiements. +- `ops/services/*.yml` sert de registre d'exploitation. +- Staging/preview obligatoire avant production. +- Monitoring minimum par site : health, uptime, erreurs, couts et incidents. + +### Ops avance +- API Gateway quand plusieurs APIs/services doivent partager auth, rate limits, + logs, versioning et API keys. +- Blue-green ou canary deploy quand le rollback manuel devient insuffisant. +- Prometheus + Grafana + Alertmanager si Shell opere une infra self-host ou + plusieurs services persistants. +- Load balancer quand plusieurs instances applicatives sont gerees directement + par Shell. +- Redis + BullMQ quand la queue Postgres approche ses limites ou que le volume + depasse environ 10k jobs/jour. + +### Scale +- Redis cache uniquement apres mesure. +- Analytics lourdes hors DB principale. +- Read replicas Postgres seulement apres charge lecture reelle et tuning SQL. +- WebSockets seulement pour un besoin temps reel concret : logs live, + monitoring live, chat ou notifications. + +## Consequences +- **Positives** : Shell garde un MVP fiable sans surinvestir en infra. +- **Negatives** : certaines briques avancees restent des contrats ou options + jusqu'a ce que le volume les justifie. +- **Risks** : si Shell self-host plusieurs sites tot, Prometheus, gateway et + load balancing peuvent devenir prioritaires plus vite. + +## Alternatives considered +- Tout integrer des le MVP - rejete, car cela augmente le cout et la surface + operationnelle avant validation de charge. +- Rester uniquement sur Vercel/Supabase sans doctrine gateway/monitoring - + rejete, car Shell vise une factory multi-sites et doit anticiper l'exploitation. + +## Review date +2026-09-04, ou plus tot si Shell opere plus de 3 sites actifs ou depasse +10k jobs/jour sur un produit. diff --git a/factory-control-center/database/schema.sql b/factory-control-center/database/schema.sql index fd05986..dbf9f8e 100644 --- a/factory-control-center/database/schema.sql +++ b/factory-control-center/database/schema.sql @@ -172,6 +172,12 @@ create table if not exists deployments ( metadata jsonb not null default '{}' ); +create index if not exists deployments_site_env_time_idx + on deployments(site_id, environment, deployed_at desc); + +create index if not exists deployments_status_idx + on deployments(status); + -- ---------------------------------------------------------------------------- -- 8. File de décisions à valider (humain) -- ----------------------------------------------------------------------------