Aller au contenu principal

Source de verite -- MyTV v2 API

Version : 1.0.0 Statut : CONTRACTUEL -- Toute modification requiert validation formelle Langue officielle : Francais

Ce document constitue la source de verite absolue du projet MyTV v2 API.

Regles d'application​

priorite: MAXIMALE
application: OBLIGATOIRE
exceptions: AUCUNE
RegleDescription
SuprematieEn cas de conflit, ce document prevaut sur tout autre
ExhaustiviteTout ce qui n'est pas explicitement autorise est interdit
TracabiliteToute decision doit referencer ce document
ImmuabiliteModifications uniquement via PR approuvee par Tech Lead

Section 1 -- Identite du projet​

Informations generales​

projet:
  nom: 'MyTV v2 API'
  type: 'API REST / Backend Streaming Media'
  version_majeure: 2

stack_technique:
  runtime: 'Node.js >= 20 LTS'
  framework: 'NestJS'
  orm: 'Prisma'
  base_de_donnees: 'PostgreSQL 15+'
  cache: 'Redis 7+'
  conteneurisation: 'Docker'
  iac: 'Terraform'
  orchestration_future: 'Kubernetes'

environnements:
  - name: 'local'
    purpose: 'Developpement individuel'
    infrastructure: 'Docker Compose'
  - name: 'dev'
    purpose: 'Integration continue'
    infrastructure: 'Docker Compose / VM'
  - name: 'staging'
    purpose: 'Pre-production / UAT'
    infrastructure: 'Infrastructure cloud simulee'
  - name: 'production'
    purpose: 'Production live'
    infrastructure: 'Cloud manage + Kubernetes-ready'

Vision architecturale​

PHASE ACTUELLE          PHASE INTERMEDIAIRE      PHASE CIBLE
==============          ===================      ==========

 Docker Compose   --->   Terraform IaC Ready  --->  K8s Ready

Livrables:              Livrables:               Livrables:
- Dockerfiles           - Modules TF             - Manifests
- docker-compose        - State mgmt            - Helm Charts
- Multi-env             - Env separation         - GitOps

Section 2 -- Agents obligatoires​

Registre des agents​

Chaque agent est obligatoire et doit etre explicitement orchestre.

IDAgentResponsabiliteOutputs obligatoires
AG-01Docker & Runtime ArchitectDockerfiles, Compose, optimisation imagesDockerfiles, docker-compose.yml, docs/docker-guide.md
AG-02Terraform / IaC ArchitectInfrastructure as Code, modules, stateiac/, docs/iac-architecture.md
AG-03Cloud-Native & K8s StrategistKubernetes readiness, Helm, manifestsk8s/, helm/, docs/k8s-readiness.md
AG-04Documentation & Knowledge ArchitectDocs techniques, diagrammes, READMEdocs/, README.md, ARCHITECTURE.md
AG-05DevSecOps & Observability EngineerSecurite, monitoring, CI/CD.github/, monitoring/, SECURITY.md
AG-06DX (Developer Experience) GuardianOnboarding, debugging, troubleshootingguides/, ONBOARDING.md, FAQ.md
AG-07API Documentation SpecialistSwagger, Postman, API Referenceopenapi.yaml, postman/, API_REFERENCE.md

Contrat des agents​

Chaque agent DOIT :

obligations:
  - Produire des outputs tracables et verifiables
  - Documenter chaque decision technique
  - Justifier chaque choix avec des arguments factuels
  - Respecter les contraintes de ce document
  - Signaler tout conflit ou impossibilite

interdictions:
  - Creer de la logique "black-box"
  - Supposer ou deviner
  - Contourner les validation gates
  - Modifier ce document sans autorisation

Section 3 -- Phases d'execution​

Matrice des phases​

IDPhaseAgentsGate de validation
P-00Reconnaissance & AuditAG-04, AG-07AUDIT_REPORT.md cree
P-01Docker FoundationAG-01, AG-05Containers OK + Docs
P-02Artefacts APIAG-07, AG-04Swagger ↔ Postman OK
P-03IaC PreparationAG-02, AG-03TF structure validee
P-04Documentation TechAG-04, AG-06100% endpoints docs
P-05Environnements & ConfigAG-01, AG-05Tous envs fonctionnels
P-06Debugging & OpsAG-05, AG-06Playbooks complets
P-07Maintenance & EvolutionTOUSCLAUDE.md mis a jour

Regles de progression​

regles_absolues:
  - Une phase ne peut commencer que si la precedente est validee
  - Chaque phase produit un checkpoint documente
  - Aucun skip de phase autorise
  - Rollback possible uniquement sur decision Tech Lead

validation_gate:
  format: 'GATE_P{XX}_VALIDATED.md'
  contenu_obligatoire:
    - Date de validation
    - Agent(s) responsable(s)
    - Outputs produits
    - Tests passes
    - Blockers resolus

Section 4 -- Docker Foundation​

Contraintes Dockerfiles​

dockerfile_requirements:
  mandatory:
    - Multi-stage builds (build -> runtime)
    - Base image officielle avec tag explicite (pas de :latest)
    - User non-root (UID >= 1000)
    - HEALTHCHECK instruction
    - Labels OCI standard
    - .dockerignore exhaustif

  security:
    - Aucun secret en dur
    - Aucun package superflu
    - Scan de vulnerabilites obligatoire (Trivy/Snyk)

  optimization:
    - Layers ordonnees par frequence de changement
    - Cache npm/yarn optimise
    - Image finale < 500MB (cible < 200MB)

Services Docker Compose​

services_obligatoires:
  api:
    build: ./
    profiles: [dev, staging, prod]
    healthcheck: required
    depends_on: [db, redis]

  db:
    image: postgres:15-alpine
    profiles: [dev, staging, prod]
    volumes: [db-data:/var/lib/postgresql/data]

  redis:
    image: redis:7-alpine
    profiles: [dev, staging, prod]

  prometheus:
    image: prom/prometheus:latest
    profiles: [staging, prod]

  grafana:
    image: grafana/grafana:latest
    profiles: [staging, prod]

Profiles Docker​

ProfileServicesUsage
devapi, db, redisDeveloppement local
stagingapi, db, redis, prometheus, grafanaTests pre-prod
prodTous + configs securiseesProduction simulee

Section 5 -- Infrastructure as Code (Terraform)​

Architecture IaC​

iac/
+-- modules/
|   +-- network/
|   +-- compute/
|   +-- database/
|   +-- storage/
|   +-- observability/
|   +-- security/
+-- environments/
|   +-- dev/
|   +-- staging/
|   +-- prod/
+-- shared/
|   +-- providers.tf
|   +-- versions.tf
+-- README.md

Contraintes Terraform​

terraform_requirements:
  version: '>= 1.5'

  state_management:
    backend: 'remote (S3/GCS/Azure Blob)'
    locking: 'DynamoDB/GCS/Azure'
    encryption: 'obligatoire'

  conventions:
    naming: 'snake_case'
    modules: 'versionnes'
    variables: 'typees et documentees'
    outputs: 'exhaustifs'

  security:
    secrets: 'Vault / Cloud KMS'
    drift_detection: 'active'
    plan_review: 'obligatoire avant apply'

Kubernetes Readiness (sans deploiement)​

k8s_preparation:
  manifests_requis:
    - Deployment (avec probes)
    - Service (ClusterIP + NodePort)
    - Ingress (avec TLS)
    - ConfigMap
    - Secret (sealed/external)
    - HorizontalPodAutoscaler
    - PodDisruptionBudget

  helm_chart:
    structure:
      - Chart.yaml
      - values.yaml
      - values-dev.yaml
      - values-staging.yaml
      - values-prod.yaml
      - templates/

  documentation:
    - Migration path Docker -> K8s
    - Rollout strategy
    - Disaster recovery

Section 6 -- Documentation​

Structure obligatoire​

docs/
+-- README.md                     # Index principal
+-- ARCHITECTURE.md               # Vue d'ensemble technique
+-- API_REFERENCE.md              # Reference rapide endpoints
+-- AUTHENTICATION.md             # Flows auth detailles
+-- ERRORS.md                     # Catalogue des erreurs
+-- SECURITY.md                   # Politique de securite
|
+-- infrastructure/
|   +-- docker-guide.md
|   +-- iac-architecture.md
|   +-- k8s-readiness.md
|   +-- environments.md
|
+-- guides/
|   +-- ONBOARDING.md
|   +-- MOBILE_DEV.md
|   +-- WEB_DEV.md
|   +-- TESTING.md
|   +-- DEVOPS.md
|
+-- diagrams/
|   +-- architecture.mermaid
|   +-- auth-flow.mermaid
|   +-- data-model.mermaid
|   +-- infrastructure.mermaid
|
+-- playbooks/
|   +-- incident-response.md
|   +-- rollback-strategy.md
|   +-- disaster-recovery.md
|   +-- scaling-guide.md
|
+-- troubleshooting/
    +-- COMMON_ERRORS.md
    +-- DEBUGGING.md
    +-- FAQ.md

Fichiers racine obligatoires​

FichierContenuResponsable
README.mdEntry point, quick start, liensAG-04
CLAUDE.mdInstructions IA, invariants projetAG-04, AG-06
MASTER_SPEC.mdSpecifications fonctionnelles/techniquesAG-04
GITFLOW.mdBranching, releases, hotfixesAG-05
CHANGELOG.mdHistorique des versionsAG-04
CONTRIBUTING.mdGuidelines contributionAG-06
SECURITY.mdPolitique de securiteAG-05

Diagrammes requis​

diagrammes_obligatoires:
  architecture:
    - Vue d'ensemble systeme (C4 Level 1)
    - Architecture conteneurs (C4 Level 2)
    - Architecture composants (C4 Level 3)

  flux:
    - Sequence authentification
    - Sequence paiement (si applicable)
    - Sequence streaming media

  infrastructure:
    - Topologie reseau
    - Flow de deploiement
    - Pipeline CI/CD

  donnees:
    - Modele entite-relation
    - Flow de donnees

Section 7 -- API & Artefacts​

Swagger/OpenAPI​

openapi_requirements:
  version: '3.1.0'

  per_endpoint:
    mandatory:
      - summary (max 80 chars)
      - description (contexte metier)
      - tags (module + sous-categorie)
      - operationId (unique)
      - parameters (path, query, header)
      - requestBody (si applicable)
      - responses (tous codes)
      - security (si protege)

    responses_obligatoires:
      200: 'Succes avec schema + example'
      201: 'Creation avec Location header'
      400: 'Bad Request avec ErrorDTO'
      401: 'Non authentifie'
      403: 'Non autorise'
      404: 'Not Found avec NotFoundDTO'
      422: 'Validation echouee avec details'
      429: 'Rate limit avec Retry-After'
      500: 'Erreur serveur'

Postman Collection​

postman_requirements:
  version: '2.1'

  structure:
    organisation: 'Par module/ressource'
    naming: '[ENV] MyTV v2 - {Module} - {Action}'

  per_request:
    - Nom descriptif
    - Description detaillee
    - URL avec variables
    - Headers standards
    - Body avec exemples (success + error)
    - Tests automatises (status, schema, timing)
    - Pre-request scripts si necessaire

  environments:
    local:
      variables: [baseUrl, token, userId, debug]
    staging:
      variables: [baseUrl, token, apiKey]
    production:
      variables: [baseUrl, token, apiKey, rateLimitBypass]

Section 8 -- Securite & Secrets​

Gestion des secrets​

politique_secrets:
  local:
    stockage: '.env.local (gitignored)'
    rotation: 'N/A'

  staging:
    stockage: 'Vault / Cloud Secret Manager'
    rotation: '90 jours'
    audit: 'active'

  production:
    stockage: 'Vault + Cloud KMS'
    rotation: '30-90 jours selon criticite'
    audit: 'obligatoire'
    backup: 'chiffre'

  ci_cd:
    stockage: 'GitHub Secrets / GitLab CI Variables'
    regles:
      - Jamais de secrets dans les logs
      - Tokens ephemeres preferes
      - Least privilege principle

Section 9 -- Debugging & Troubleshooting​

Commandes de reference​

# LOCAL DEVELOPMENT
npm run dev                      # Demarrage dev
npm run dev:debug                # Avec debugger attache
docker-compose logs -f api       # Logs conteneur API

# DATABASE
npx prisma studio                # GUI exploration DB
npx prisma migrate dev           # Appliquer migrations
npx prisma migrate reset         # Reset complet (destructif)
npx prisma db seed               # Charger seed data
npx prisma generate              # Regenerer client

# CACHE
redis-cli PING                   # Test connexion
redis-cli KEYS "mytv:*"          # Lister cles projet
redis-cli FLUSHDB                # Vider cache (destructif)

# DOCKER
docker-compose --profile dev up -d      # Demarrer env dev
docker-compose --profile staging up -d  # Demarrer env staging
docker-compose down -v                  # Arreter + supprimer volumes

# TESTS
npm run test                     # Tests unitaires
npm run test:watch               # Mode watch
npm run test:coverage            # Avec couverture
npm run test:e2e                 # Tests E2E

# TERRAFORM (design phase)
terraform init                   # Initialiser
terraform validate               # Valider syntaxe
terraform plan                   # Preview changes

Catalogue des erreurs​

CodeMessageCauseSolution
DB_CONN_FAILEDDatabase connection failedPool epuise, firewall, credentialsVerifier DATABASE_URL, pool size, firewall rules
DB_MIGRATION_FAILEDMigration failedSchema conflict, permissionsVerifier migration files, DB permissions
REDIS_TIMEOUTRedis connection timeoutNetwork latency, overloadVerifier REDIS_URL, augmenter timeout
REDIS_AUTH_FAILEDRedis authentication failedWrong passwordVerifier REDIS_PASSWORD
JWT_INVALIDInvalid tokenMalformed, tamperedVerifier format du token, regenerer
JWT_EXPIREDToken expiredTTL depasseRefresh token, verifier horloge serveur
RATE_LIMIT_429Too many requestsRate limit depasseImplementer backoff, verifier whitelist
S3_ACCESS_DENIEDS3 access deniedIAM mal configureVerifier IAM policies, bucket CORS
PRISMA_P2002Unique constraint violationDonnees dupliqueesUtiliser upsert, verifier donnees existantes
PRISMA_P2025Record not foundID invalideVerifier que l'ID existe, verifier soft delete

Section 10 -- Observabilite​

Stack obligatoire​

observability_stack:
  metrics:
    tool: 'Prometheus'
    retention: '15 jours (dev), 30 jours (prod)'

  visualization:
    tool: 'Grafana'
    dashboards:
      - API Overview
      - Database Performance
      - Redis Metrics
      - Error Rates

  logging:
    format: 'JSON structure'
    levels: [error, warn, info, debug]
    retention: '7 jours (dev), 90 jours (prod)'

  alerting:
    channels: [Slack, Email, PagerDuty]

Seuils d'alerte​

MetriqueWarningCriticalAction
CPU Usage> 70%> 90%Scale horizontal
Memory Usage> 75%> 90%Scale vertical
DB Connections> 80% pool> 95% poolAugmenter pool
Response Time (p95)> 500ms> 2sInvestiguer
Error Rate> 1%> 5%Incident response
Disk Usage> 70%> 85%Cleanup/Expand

Section 11 -- Criteres d'acceptation​

Checklist globale​

infrastructure:
  docker:
    - Tous Dockerfiles multi-stage
    - Containers non-root
    - Healthchecks configures
    - docker-compose fonctionnel (tous profiles)
    - Images scannees (0 critical vulns)

  terraform:
    - Structure modulaire validee
    - State management configure
    - Variables typees et documentees
    - Plan executable sans erreur

  kubernetes_readiness:
    - Manifests crees et valides
    - Helm chart fonctionnel
    - Documentation migration complete

documentation:
  api:
    - 100% endpoints dans Swagger
    - Swagger valide (0 erreurs)
    - Postman collection complete
    - Environnements Postman configures
    - Tests Postman passent

  technique:
    - README complet
    - Tous diagrammes crees
    - Guides par profil (dev/test/devops)
    - Troubleshooting exhaustif
    - CLAUDE.md a jour

coherence:
  - Swagger <-> Code: 100% sync
  - Postman <-> Swagger: meme structure
  - Docs <-> .env.example: variables listees
  - Diagrammes <-> Architecture reelle

dx_metrics:
  - Onboarding < 30 minutes
  - Premier appel API < 10 minutes
  - Toute erreur documentee avec solution

security:
  - Aucun secret dans le code
  - Scan vulnerabilites OK
  - Headers securite configures
  - Rate limiting actif

Section 12 -- Principes fondamentaux​

Regles inviolables​

  1. TRANSPARENCE RADICALE -- Si ca ne peut pas etre explique, c'est invalide
  2. ZERO BLACK BOX -- Aucune logique implicite ou "magique"
  3. DOCUMENTATION FIRST -- Code non documente = code inexistant
  4. SECURITE BY DEFAULT -- Secure by design, pas en afterthought
  5. TESTABILITE OBLIGATOIRE -- Tout code doit etre testable et teste
  6. REPRODUCTIBILITE -- Meme input = meme output, toujours
  7. AUDITABILITE -- Chaque decision tracable et justifiable

Processus de modification​

modification_source_of_truth:
  qui_peut_modifier: 'Tech Lead uniquement'
  processus: 1. Creer une PR dediee
    2. Justification ecrite obligatoire
    3. Review par 2 seniors minimum
    4. Validation impact analysis
    5. Communication a toutes les equipes
  delai_minimum: '48h entre proposition et merge'

Annexes​

Glossaire technique​

TermeDefinition
DXDeveloper Experience - qualite de l'experience developpeur
IaCInfrastructure as Code - infrastructure definie en code
GatePoint de validation obligatoire entre phases
DriftEcart entre etat reel et etat declare de l'infra
Sealed SecretSecret chiffre stockable dans Git

Contacts & Escalation​

RoleContactEscalation
Tech LeadA definirCTO
DevOps LeadA definirTech Lead
SecurityA definirTech Lead

Ce document est la LOI du projet MyTV v2 API. Toute violation est consideree comme un incident critique.