Partie IV : Structure & Organisation du projet

Guide complet pour developpeurs - Architecture, modules et organisation de l'API MyTelevision v2.0

---

Table des matieres

1. Modules principaux
2. Relations entre modules
3. Conformite a MASTER_SPEC.md
4. Diagrammes
5. Deliverables
6. Acceptance Criteria
7. Synthese et Checklist finale

---

1. Modules principaux

L'API MyTelevision est organisee en 22 modules fonctionnels repartis en 4 categories principales.

1.1 Modules d'authentification et utilisateurs

Auth Module

Caracteristique	Description
Role fonctionnel	Gestion de l'authentification utilisateur (inscription, connexion, refresh tokens, sessions multi-devices, deconnexion)
Service associe	AuthService
Fichiers cles	src/presentation/modules/auth.module.ts, src/application/services/auth/auth.service.ts

Endpoints principaux (Client) :

Methode	Endpoint	Description
POST	/api/v2/auth/register	Inscription nouvel utilisateur
POST	/api/v2/auth/login	Connexion avec email/password
POST	/api/v2/auth/refresh	Renouvellement access token
POST	/api/v2/auth/logout	Deconnexion (revocation session)
GET	/api/v2/auth/me	Profil utilisateur connecte
GET	/api/v2/auth/sessions	Liste des sessions actives
DELETE	/api/v2/auth/sessions/{id}	Revoquer une session
POST	/api/v2/auth/forgot-password	Demande de reinitialisation mot de passe
POST	/api/v2/auth/reset-password	Reinitialisation mot de passe

Tips dev :

• Utiliser le header X-Device-Id pour identifier l'appareil client
• Le refresh token est valide 7 jours, l'access token 1 heure
• Implementer un intercepteur HTTP pour auto-refresh cote client

---

Users Module

Caracteristique	Description
Role fonctionnel	Gestion des profils utilisateurs, devices, preferences
Service associe	UsersService
Fichiers cles	src/presentation/modules/users.module.ts, src/application/services/users/users.service.ts

Endpoints principaux :

Methode	Endpoint	Description	Acces
GET	/api/v2/users/profile	Profil utilisateur	Client
PUT	/api/v2/users/profile	Mise a jour profil	Client
GET	/api/v2/admin/users	Liste des utilisateurs	Admin
GET	/api/v2/admin/users/{id}	Detail utilisateur	Admin
PUT	/api/v2/admin/users/{id}/role	Changer role	Admin
PUT	/api/v2/admin/users/{id}/status	Changer statut	Admin
DELETE	/api/v2/admin/users/{id}	Supprimer (soft delete)	Admin

---

RBAC Module (Role-Based Access Control)

Caracteristique	Description
Role fonctionnel	Gestion granulaire des roles et permissions, assignation des roles aux utilisateurs
Service associe	RbacService

Hierarchie des roles par defaut :

SUPER_ADMIN > ADMIN > MODERATOR > USER
     |          |          |         |
     |          |          |         +-- Lecture contenu, favoris, historique
     |          |          +-- + Moderation contenu (CRUD partiel)
     |          +-- + Gestion utilisateurs, settings
     +-- + Tous les droits, RBAC, logs systeme

---

1.2 Modules de contenu

Movies Module

Caracteristique	Description
Role fonctionnel	Catalogue des films avec auto-fill TMDb/IMDb, fichiers video multi-qualite, casting
Services associes	MoviesService, TmdbService

Workflow TMDb Auto-fill :

---

Series Module

Caracteristique	Description
Role fonctionnel	Catalogue des series TV avec saisons et episodes, auto-fill TMDb

Endpoints principaux :

Methode	Endpoint	Description	Acces
GET	/api/v2/series	Liste des series	Public
GET	/api/v2/series/{id}	Detail serie	Public
GET	/api/v2/series/{id}/seasons	Saisons d'une serie	Public
GET	/api/v2/series/{id}/seasons/{seasonNum}/episodes	Episodes d'une saison	Public
POST	/api/v2/admin/series	Creer une serie	Admin
POST	/api/v2/admin/series/{id}/seasons	Ajouter une saison	Admin
POST	/api/v2/admin/series/{seriesId}/seasons/{seasonId}/episodes	Ajouter un episode	Admin

---

Autres modules de contenu

Module	Role	Endpoints cles
Live TV	Chaines TV en direct, categories	GET /livetv/channels, GET /livetv/categories
Radio	Stations radio avec streaming audio	GET /radio/channels, GET /radio/featured
Podcasts	Collections et episodes de podcasts	GET /podcasts, GET /podcasts/{id}/episodes
Live Events	Evenements en direct (sports, concerts)	GET /live-events, GET /live-events/live-now
News	Actualites et articles de presse	GET /news, GET /news/recent

---

1.3 Modules transversaux

Module	Role	Endpoints cles
Streaming	Securite du streaming : tokens, URLs signees, DRM	POST /streaming/generate-token
Catalog	Gestion centralisee des genres et categories	GET /catalog/genres
Favorites	Favoris utilisateur (films, series, chaines, etc.)	POST /favorites, GET /favorites
Watch History	Suivi de progression de visionnage	POST /watch-history, GET /watch-history/continue-watching

1.4 Modules de support et configuration

Module	Role	Endpoints cles
Settings	Configuration globale de l'application	GET /settings, PUT /admin/settings/{key}
Support	Systeme de tickets de support	POST /support/tickets, GET /support/tickets
Notifications	Notifications push (Firebase FCM), broadcast	GET /notifications, POST /admin/notifications/send
Countries	Pays (ISO codes, drapeaux)	GET /countries
Languages	Langues disponibles	GET /languages
Sliders	Carrousels promotionnels	GET /sliders
Banners	Bannieres publicitaires	GET /banners

---

2. Relations entre modules

2.1 Dependances inter-modules

2.2 Flux de donnees typiques

Creation d'un film avec auto-fill TMDb :

Generation d'un token de streaming :

---

3. Conformite a MASTER_SPEC.md

3.1 Checklist de conformite

Entites et ressources

Ressource	Statut	Notes
Live TV	Conforme	Channels avec categories, streaming multi-URLs
Live Events	Conforme	Categories, dates debut/fin, location
Movies	Conforme	TMDb auto-fill, cast/directors, multi-qualite
TV Series	Conforme	Seasons/Episodes, TMDb auto-fill
Podcasts	Conforme	Podcasters, Collections, Episodes
Radio	Conforme	Channels multi-categories, streaming
News	Conforme	Articles, categories, media attachments
Users	Conforme	Roles, subscriptions, devices, sessions
Settings	Conforme	Groupes: general, firebase, admob, tmdb, storage, etc.
Support System	Conforme	Tickets, messages, priorites

Authentification et securite

Exigence	Statut	Notes
JWT + Refresh Tokens	Conforme	Access 1h, Refresh 7j, rotation
Firebase Auth Compatible	Conforme	firebaseUid sur User
RBAC	Conforme	Roles, Permissions, UserRoleAssignment
Streaming Tokens	Conforme	IP binding, expiry, usage limit
DRM (AES-128)	Conforme	DrmKey model, rotation support
Rate Limiting	Conforme	@nestjs/throttler (3 tiers)

3.2 Recommandations d'amelioration

1. Domain Layer : Creer des entites de domaine pures pour decoupler de Prisma
2. Firebase Migration : Documenter le processus de migration des utilisateurs Firebase existants
3. DRM avance : Planifier l'integration Widevine/PlayReady pour les contenus premium
4. Observability : Ajouter OpenTelemetry pour le tracing distribue

---

4. Diagrammes

4.1 Architecture API globale

4.2 Clean Architecture - Couches

---

5. Deliverables

#	Livrable	Description	Statut
1	Architecture document	Ce guide (Parties I a IV)	Complet
2	Prisma Schema	50+ modeles, relations, indexes, enums	Complet
3	Migrations Prisma	Historique des migrations versionnees	Complet
4	Seeds	Donnees initiales (genres, settings, admin)	Complet
5	TMDb Auto-fill Service	Import automatique films/series	Complet
6	Cloudflare R2 Integration	Upload/serve media via S3-compatible	Complet
7	Hybrid Authentication	JWT + Firebase UID + Sessions	Complet
8	RBAC Module	Roles, Permissions, Assignments	Complet
9	Admin/Client API Split	/api/v2/... vs /api/v2/admin/...	Complet
10	Streaming Security	Tokens, IP binding, DRM AES-128	Complet
11	Content Modules	Movies, Series, LiveTV, Radio, Podcasts, News, Events	Complet
12	Swagger/OpenAPI	Documentation 100% coverage	Complet
13	Docker + docker-compose	Stack complete (API, PG, Redis)	Complet
14	Unit Tests	Pattern etabli, Jest	En cours
15	E2E Tests	SuperTest + Jest	En cours

---

6. Acceptance Criteria

Checklist d'acceptance

API & Modules

• 100% des modules definis dans MASTER_SPEC.md sont implementes
• Swagger/OpenAPI 3 couvre 100% des endpoints
• Validation des DTOs avec class-validator
• Pagination standardisee (page, limit, meta)
• Codes d'erreur documentes (400, 401, 403, 404, 500)

Base de donnees

• Schema Prisma complet avec toutes les entites
• Relations definies (1:1, 1:N, N:M)
• Indexes optimises pour les requetes frequentes
• Soft delete sur les entites principales
• Seeds fonctionnels pour donnees initiales

Authentification & Securite

• JWT Access + Refresh tokens fonctionnels
• Rotation des refresh tokens implementee
• Sessions multi-devices supportees
• RBAC complet (Roles, Permissions, Assignments)
• Rate limiting configure (3 tiers)
• Streaming tokens avec IP binding

Infrastructure

• Docker + docker-compose fonctionnels
• PostgreSQL 16 configure
• Redis 7 pour cache et sessions
• Health checks configures
• Path aliases TypeScript configures

Tests (Objectifs)

• Coverage >= 80% (objectif)
• Pattern de tests etabli
• Tests E2E complets (en cours)

---

7. Synthese et Checklist finale

Synthese du guide

Partie	Contenu	Public cible
I	Consommation API, Swagger, Auth, Bonnes pratiques	Frontend / Mobile
II	Configuration locale, Docker, Variables DEV	Backend juniors
III	Configuration PROD, CI/CD, Securite, Rollback	DevOps / Seniors
IV	Architecture, Modules, Relations, Diagrammes	Tous niveaux

Checklist du nouveau developpeur

Premier jour

• Lire README.md et CLAUDE.md
• Installer les prerequis (Node 20, Docker, Git)
• Cloner le repo et configurer .env
• Lancer npm run docker:up
• Verifier http://localhost:3000/api/docs
• Tester un endpoint public (GET /api/v2/health)

Premiere semaine

• Lire Partie I (Consommation API)
• Lire Partie II & III (Configuration)
• Comprendre le schema Prisma (prisma/schema.prisma)
• Explorer Prisma Studio (npm run prisma:studio)
• Creer un compte test via /auth/register
• Tester les endpoints avec Postman/Insomnia

Avant de contribuer

• Lire GITFLOW.md en entier
• Comprendre les conventions de commit
• Lire Partie IV (Architecture)
• Identifier le module concerne
• Verifier les tests existants
• Creer une branche feature/backend/...

Avant de creer une PR

• Tests passent (npm run test)
• Lint OK (npm run lint)
• Build OK (npm run build)
• Swagger mis a jour
• Commit messages conventionnels
• PR vers develop (pas main)

Ressources essentielles

Ressource	URL / Chemin
Swagger UI	http://localhost:3000/api/docs
Prisma Studio	http://localhost:5555 (apres npm run prisma:studio)
MASTER_SPEC	./MASTER_SPEC.md
GITFLOW	./GITFLOW.md

Recommandations d'amelioration

Court terme (1-2 sprints)

1. Completer les tests pour atteindre 80% de coverage
2. Configurer GitHub Actions pour CI/CD automatise
3. Ajouter OpenTelemetry pour le tracing distribue
4. Documenter l'API avec Redoc en complement de Swagger

Moyen terme (1-2 mois)

1. Implementer GraphQL en complement de REST
2. Ajouter Webhooks pour les evenements (nouveau contenu, ticket, etc.)
3. SDK TypeScript auto-genere depuis OpenAPI
4. Pagination cursor-based pour les gros datasets

Long terme (roadmap)

1. Widevine/PlayReady DRM pour les contenus premium
2. Multi-tenancy si expansion vers d'autres marches
3. Event Sourcing pour l'audit trail complet
4. Microservices si la charge le justifie

---

Changelog

Version	Date	Modifications
1.0.0	2025-12-12	Version initiale Partie IV

---

Derniere mise a jour : 12 decembre 2025 Auteurs : Equipe MyTelevision + Claude Code AI

---

Ce guide est un document vivant. Proposez des ameliorations via GitHub Issues ou Pull Requests.