Architecture Codexia

⚠️ Document partiellement remplacé. Depuis le 2026-06-05, la vision d'ensemble, la taxonomie de nommage et l'architecture cible (multi-domaines, cœur tlr-symfony + bundles tlr-* + app telaria) vivent dans le doc fondateur architecture-univers-telaria.md, qui fait autorité. Ce document reste utile pour le détail technique de l'app codexia (stack, infra serveur, sécurité), mais ses sections « Modèle de données », « Flux applicatifs » et l'arborescence src/ décrivent une plateforme documentaire prospective non codée (entités Document/Resource/Expertise fictives) — à lire comme une cible historique, pas comme l'état réel. Pour le réel, voir auth-compte.md.

Ce document décrit l'architecture technique du projet Codexia, de l'infrastructure serveur jusqu'à la logique applicative.

Table des matières

• Vue d'ensemble
• Évolution du projet
• Architecture infrastructure
• Architecture applicative
• Modèle de données
• Flux applicatifs
• Bundles et modularité
• Sécurité
• Performance et scalabilité

Vue d'ensemble

Codexia est une plateforme de gestion documentaire permettant de composer des documentations à partir de ressources réutilisables (tips, howtos, descriptions fonctionnelles).

Métaphore du projet

"Assembler une documentation à partir d'ingrédients (ressources)"

Cette métaphore guide toute l'architecture :

• Ingrédients = Ressources documentaires (snippets, exemples, définitions)
• Documentation = Documents assemblés (guides, tutoriels, spécifications)
• Domaines d'expertise = Thématiques (Backend, Frontend, SecOps, etc.)

Stack technique

┌─────────────────────────────────────────────────────┐
│                   UTILISATEUR                       │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│              COUCHE PRÉSENTATION                    │
│  - Twig 3 (Templates)                               │
│  - Bootstrap 5 (CSS Framework)                      │
│  - Stimulus (JavaScript)                            │
│  - AssetMapper (Assets)                             │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│              COUCHE APPLICATIVE                     │
│  - Symfony 7.2 (Framework)                          │
│  - PHP 8.5 (Langage)                                │
│  - Controllers, Services, Events                    │
│  - Voters (Autorisations)                           │
│  - Messenger (Async)                                │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│              COUCHE PERSISTANCE                     │
│  - Doctrine ORM 3                                   │
│  - MySQL 8.4.7                                      │
│  - Repositories                                     │
│  - Migrations                                       │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│              INFRASTRUCTURE                         │
│  - Ubuntu Server 26.04 LTS                          │
│  - Apache 2.4 + PHP-FPM                             │
│  - MySQL 8.4                                        │
│  - Postfix + DKIM (emails)                          │
│  - Let's Encrypt (SSL/TLS)                          │
└─────────────────────────────────────────────────────┘

Évolution du projet

Phase 1 : OneTLD (tutoriel Grafikart)

Origine : Tutoriel Symfony 7 par Grafikart (thème recettes de cuisine)

• Application de gestion de recettes de cuisine (terminologie du tutoriel)
• CRUD basique (Recipes, Categories, Users)
• Authentification, API REST, i18n
• Base technique solide pour apprentissage

Phase 2 : Codexia (Plateforme documentaire)

Évolution : Conservation de la métaphore, changement de domaine

• Documentation structurée autour de documents/guides
• Ressources réutilisables pour assembler les documents
• Domaines d'expertise pour classifier les contenus

Nouvelles fonctionnalités :

• Gestion de ressources documentaires
• Assemblage de documents à partir de ressources
• Export multi-formats (HTML, EPUB, PDF)
• Recherche full-text et sémantique
• Versionnement de la documentation
• CMS éditorial (telaria-cms) pour pages légales et pages de contexte
• Backoffice global (telaria-admin) pour l'administration du site

État d'implémentation (actuel vs cible)

Important : ce document décrit l'architecture cible. Une partie n'est pas encore codée — les sections ci-dessous (modèle de données, flux, structure) la décrivent comme objectif.

Implémenté aujourd'hui (squelette transverse) :

• Authentification, 2FA e-mail, contact, profil, dashboard admin, i18n fr/en, token API → voir auth-compte.md.
• Entités réelles : User et ResetPasswordRequest. Le démo « recettes » (OneTLD/Grafikart) a été retiré.
• Bundles maison réels : codexia/ui-bundle et telaria/rag-bundle (cœur RAG, v0.1.x).

Cible, non encore codée :

• Plateforme documentaire : entités Document/Resource/Expertise, assemblage, export EPUB/PDF.
• CMS éditorial (telaria-cms.md), recherche (telaria-search.md), doc web /docs (docs-web.md), IA (ia-vitrine.md).
• La majorité des bundles listés ci-dessous sont prospectifs (hors codexia/ui-bundle et telaria/rag-bundle).

Architecture infrastructure

Serveur physique (VPS OVH KVM)

Le projet est hébergé sur une instance VPS (KVM) chez OVHcloud, offrant les caractéristiques suivantes :

• Processeur (vCPU) : 6 vCPU Intel Haswell (haute performance pour compilation/génération)
• Mémoire (RAM) : 12 Go (permettant la mise en cache agressive OPcache/MySQL)
• Stockage (SSD) : 96 Go SSD (IOPS élevés pour les opérations d'assemblage documentaire)
• Réseau : 250 Mbps (IP publique fixe, IPv4 + IPv6)
• Localisation : France (Gravelines/Strasbourg)

Description logicielle (OS & Services)

L'OS est une distribution Linux optimisée pour la stabilité et la performance.

• Système d'exploitation : Ubuntu Server 26.04 LTS
• Serveur Web : Apache 2.4 (MPM Event) + PHP-FPM
• Base de données : MySQL 8.4.7 (LTS)
• Serveur de messagerie : Postfix (SMTP transactionnel)
• Gestionnaire de certificats : Certbot (Let's Encrypt)

Paquets et applications par thème

🌍 Infrastructure & Web

• apache2 : Serveur HTTP haute performance
• php8.5-fpm : Processeur PHP avec pool dédié
• mysql-server-8.4 : Moteur de base de données relationnelle
• postfix : Agent de transfert de mail (MTA)
• brotli : Compression HTTP haute performance (guide perf-http.md)

🛡️ Sécurité & Certificats

• ufw : Uncomplicated Firewall pour le filtrage des ports (22, 80, 443)
• fail2ban : Protection contre les attaques par force brute (SSH, Apache)
• certbot + python3-certbot-apache : Automatisation des certificats SSL/TLS
• opendkim : Signature des emails pour la délivrabilité (guide email.md)

🛠️ Développement & Automatisation

• composer : Gestionnaire de dépendances PHP
• git : Contrôle de version (GitFlow)
• symfony-cli : Outils de développement et serveur de test local
• pandoc : Conversion multi-formats pour les exports (EPUB, PDF, etc.)
• telaria-bash : Outils CLI maison pour l'automatisation (guide bash.md)

Écosystème Symfony & Bundles

L'application Codexia repose sur une architecture modulaire utilisant des bundles spécialisés pour séparer les responsabilités.

Statut : seuls les bundles réellement implémentés sont listés ici. Les pistes de modularisation future vivent dans pilotage/roadmap.md.

Bundles implémentés

Architecture applicative

Structure Symfony

⚠️ Arborescence cible : les modules documentaires (Document, Resource, Expertise, assemblage, export) ne sont pas encore codés. Le code réel se limite au squelette transverse (auth, contact, profil, admin, i18n). Voir § « État d'implémentation ».

codexia-app/
├── bin/
│   └── console                 # CLI Symfony
├── config/
│   ├── packages/               # Configuration bundles
│   ├── routes/                 # Configuration routes
│   ├── services.yaml           # Services
│   └── security.yaml           # Firewall, voters
├── migrations/                 # Migrations Doctrine
├── public/
│   ├── index.php               # Front controller
│   ├── uploads/                # Images uploadées
│   └── downloads/              # EPUB/PDF générés
├── media/                       # Médias CMS (privé, hors webroot)
├── src/
│   ├── Controller/
│   │   ├── Admin/              # Backoffice (CRUD)
│   │   ├── API/                # API REST
│   │   ├── HomeController.php
│   │   ├── DocumentController.php
│   │   ├── CmsPublicController.php
│   │   └── SecurityController.php
│   ├── Entity/
│   │   ├── Document.php
│   │   ├── CmsContent.php
│   │   ├── CmsTag.php
│   │   ├── CmsImage.php
│   │   ├── Resource.php
│   │   ├── Expertise.php
│   │   └── User.php
│   ├── Repository/
│   │   ├── DocumentRepository.php
│   │   ├── CmsContentRepository.php
│   │   ├── CmsTagRepository.php
│   │   ├── CmsImageRepository.php
│   │   ├── ResourceRepository.php
│   │   ├── ExpertiseRepository.php
│   │   └── UserRepository.php
│   ├── Form/
│   │   ├── DocumentType.php
│   │   ├── CmsContentType.php
│   │   ├── ResourceType.php
│   │   └── ExpertiseType.php
│   ├── Service/
│   │   ├── DocumentAssembler.php
│   │   ├── ExportService.php (EPUB, PDF)
│   │   ├── FileUploader.php
│   │   ├── SearchService.php (telaria-search)
│   │   └── CmsRenderer.php
│   ├── Security/
│   │   └── Voter/
│   │       ├── DocumentVoter.php
│   │       └── ResourceVoter.php
│   ├── EventSubscriber/
│   │   ├── LocaleSubscriber.php (i18n)
│   │   └── SecuritySubscriber.php
│   └── Command/
│       ├── UserGenerateTokenCommand.php
│       └── ExportDocsCommand.php
├── templates/
│   ├── base.html.twig
│   ├── home/
│   ├── document/
│   ├── admin/
│   └── security/
├── translations/
│   ├── messages.fr.yaml
│   └── messages.en.yaml
├── var/
│   ├── cache/
│   ├── log/
│   └── email/                  # Emails dev
└── vendor/                     # Dépendances Composer

Couches architecturales

┌─────────────────────────────────────────────────────┐
│  CONTROLLER LAYER                                   │
│  - Gestion requêtes HTTP                            │
│  - Validation formulaires                           │
│  - Délégation aux services                          │
│  - Rendu templates                                  │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  SERVICE LAYER                                      │
│  - Logique métier                                   │
│  - DocumentAssembler (composition docs)             │
│  - ExportService (génération EPUB/PDF)              │
  │  - SearchService (telaria-search)                   │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  REPOSITORY LAYER                                   │
│  - Accès données (Doctrine)                         │
│  - Requêtes DQL personnalisées                      │
│  - Pagination                                       │
│  - Filtres et tri                                   │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  ENTITY LAYER                                       │
│  - Document, Resource, Expertise, User              │
│  - Validation (Constraints)                         │
│  - Relations (OneToMany, ManyToMany)                │
└─────────────────────────────────────────────────────┘

Modèle de données

⚠️ Modèle cible. À ce jour, seules les entités User et ResetPasswordRequest existent — voir auth-compte.md. Les entités Document/Resource/Expertise ci-dessous relèvent de la plateforme documentaire non encore codée.

Diagramme ER

┌──────────────────┐         ┌──────────────────┐
│      User        │         │    Expertise     │
├──────────────────┤         ├──────────────────┤
│ id (PK)          │         │ id (PK)          │
│ email            │         │ name             │
│ password         │         │ slug             │
│ roles (JSON)     │         │ description      │
│ api_token        │         │ created_at       │
│ created_at       │         │ updated_at       │
└──────────────────┘         └──────────────────┘
         │                            │
         │ 1                          │ 1
         │                            │
         │ N                          │ N
         │                            │
         │                   ┌────────┴────────┐
         │                   │                 │
         ▼                   ▼                 ▼
┌──────────────────────────────────────────────────────┐
│                    Document                          │
├──────────────────────────────────────────────────────┤
│ id (PK)                                              │
│ title                                                │
│ slug                                                 │
│ description                                          │
│ content (Markdown)                                   │
│ format (markdown|html|rst)                           │
│ language (fr|en)                                     │
│ accessibility_level (A|AA|AAA)                       │
│ user_id (FK → User)                                  │
│ expertise_id (FK → Expertise)                        │
│ created_at                                           │
│ updated_at                                           │
└──────────────────────────────────────────────────────┘
         │
         │ N
         │
         │ (ManyToMany)
         │
         │ N
         ▼
┌──────────────────────────────────────────────────────┐
│                    Resource                          │
├──────────────────────────────────────────────────────┤
│ id (PK)                                              │
│ title                                                │
│ slug                                                 │
│ type (snippet|example|definition|howto)              │
│ content (Markdown)                                   │
│ tags (JSON)                                          │
│ user_id (FK → User)                                  │
│ created_at                                           │
│ updated_at                                           │
└──────────────────────────────────────────────────────┘

Relations

• User → Document : Un utilisateur peut créer plusieurs documents (1:N)
• Expertise → Document : Un domaine d'expertise contient plusieurs documents (1:N)
• Document ↔ Resource : Un document peut utiliser plusieurs ressources, une ressource peut être dans plusieurs documents (N:N)

Flux applicatifs

⚠️ Flux cibles de la plateforme documentaire (non encore codée). Pour l'authentification réelle, voir auth-compte.md.

1. Création d'un document

┌─────────────┐
│  User       │
│  (logged)   │
└──────┬──────┘
       │
       ▼
┌──────────────────────────────────────┐
│  GET /admin/documents/new            │
│  - Affiche formulaire vide           │
│  - Liste des expertises disponibles  │
│  - Liste des ressources (sélection)  │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  POST /admin/documents/new           │
│  1. Validation formulaire            │
│  2. DocumentVoter (CREATE)           │
│  3. Persister Document               │
│  4. Lier Resources (ManyToMany)      │
│  5. Redirect /admin/documents/{id}   │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  Affichage document créé             │
│  - Preview HTML                      │
│  - Bouton "Exporter EPUB"            │
│  - Bouton "Modifier"                 │
└──────────────────────────────────────┘

2. Export EPUB

┌─────────────────────────────────────┐
│  GET /admin/documents/{id}/export   │
│  ?format=epub                       │
└──────┬──────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  ExportService::exportToEpub()       │
│  1. Récupérer Document + Resources   │
│  2. Assembler contenu Markdown       │
│  3. Convertir Pandoc → EPUB          │
│  4. Ajouter métadonnées accessibilité│
│  5. Valider EPUBCheck                │
│  6. Stocker dans public/downloads/   │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  Response (file download)            │
│  Content-Type: application/epub+zip  │
│  Content-Disposition: attachment     │
└──────────────────────────────────────┘

3. Recherche documentaire (telaria-search)

┌──────────────────────────────────────┐
│  GET /search?q=accessibilité         │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  SearchService::search()             │
│  1. Requête moteur (OpenSearch)      │
│  2. Filtres (expertise, language)    │
│  3. Tri par pertinence               │
│  4. Pagination (20 résultats/page)   │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  Affichage résultats                 │
│  - Cards avec excerpt                │
│  - Highlighting des termes           │
│  - Filtres latéraux                  │
│  - Pagination HATEOAS                │
└──────────────────────────────────────┘

4. API REST

┌──────────────────────────────────────┐
│  GET /api/v1/documents               │
│  Authorization: Bearer {token}       │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  1. Validation token (SHA-512 hash)  │
│  2. Vérifier rate limiting           │
│  3. DocumentRepository::findAll()    │
│  4. Serialization (JMS ou native)    │
│  5. Pagination + HATEOAS links       │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  Response JSON                       │
│  {                                   │
│    "status": "success",              │
│    "data": [...],                    │
│    "pagination": {...}               │
│  }                                   │
└──────────────────────────────────────┘

Bundles et modularité

Bundles externes

Codexia adopte une approche modulaire : les fonctionnalités réutilisables sont extraites en bundles Composer, consommés par l'application codexia.

codexia/ui-bundle
├── Thèmes Bootstrap custom
├── Composants Stimulus
└── AssetMapper presets

telaria/rag-bundle
├── Ingestion .md → chunks
├── Embeddings + index sqlite-vec
└── Service de retrieval

telaria/mcp-bundle
├── Transports stdio / Streamable HTTP
├── Registre d'outils (tools/list, tools/call)
└── Gouvernance multi-tenant

Architecture multi-bundles

codexia-app/
├── vendor/
│   ├── codexia/ui-bundle
│   ├── telaria/rag-bundle
│   └── telaria/mcp-bundle
└── src/
    └── [Code applicatif spécifique]

Sécurité

Authentification

┌──────────────────────────────────────┐
│  Login Form                          │
│  - email + password                  │
│  - CSRF token                        │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  Symfony Security                    │
│  1. CSRF validation                  │
│  2. User provider (Doctrine)         │
│  3. Password hasher (auto)           │
│  4. Session creation                 │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  Session active                      │
│  - Cookie sécurisé (httponly)        │
│  - Timeout configurable              │
│  - Remember me (optionnel)           │
└──────────────────────────────────────┘

Autorisation (Voters)

// DocumentVoter.php
class DocumentVoter extends Voter
{
    protected function supports(string $attribute, mixed $subject): bool
    {
        return in_array($attribute, ['VIEW', 'EDIT', 'DELETE'])
            && $subject instanceof Document;
    }

    protected function voteOnAttribute(
        string $attribute,
        mixed $subject,
        TokenInterface $token
    ): bool {
        $user = $token->getUser();

        if (!$user instanceof User) {
            return false;
        }

        /** @var Document $document */
        $document = $subject;

        return match($attribute) {
            'VIEW' => true, // Tous peuvent voir
            'EDIT', 'DELETE' => $document->getUser() === $user || in_array('ROLE_ADMIN', $user->getRoles()),
        };
    }
}

Rate Limiting

# config/packages/rate_limiter.yaml
framework:
    rate_limiter:
        api:
            policy: 'sliding_window'
            limit: 100
            interval: '1 hour'

        contact_form:
            policy: 'fixed_window'
            limit: 5
            interval: '15 minutes'

Performance et scalabilité

Optimisations actuelles

1. OPcache PHP : Bytecode mis en cache
2. Doctrine Query Cache : Requêtes DQL mises en cache
3. HTTP Cache : ETags + Cache-Control
4. Eager Loading : Éviter requêtes N+1 (jointures)
5. Assets : AssetMapper avec versioning

Scalabilité future

┌─────────────────────────────────────────────────────┐
│  Load Balancer (HAProxy/Nginx)                      │
└──────┬──────────────────────────────────────────────┘
       │
       ├─────────────┬─────────────┬─────────────┐
       ▼             ▼             ▼             ▼
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│ App Node 1│ │ App Node 2│ │ App Node 3│ │ App Node N│
└───────────┘ └───────────┘ └───────────┘ └───────────┘
       │             │             │             │
       └─────────────┴─────────────┴─────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  MySQL Master/Replica                               │
│  - Master : écriture                                │
│  - Replicas : lecture                               │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  Redis (Session + Cache)                            │
└─────────────────────────────────────────────────────┘

Liens et ressources

Documentation interne

• Philosophie du projet
• Principes d'ingénierie
• Domaines d'expertise
• Design system
• Recherche interne (telaria-search)
• Sécurité (SecOps)

Références externes

• Symfony Best Practices
• Doctrine Best Practices
• SOLID Principles

Implémentation

Historique des décisions