# 🏗️ Architecture PointCloud Viewer - Diagramme Mermaid

## Vue d'ensemble de l'architecture

```mermaid
flowchart TB
    subgraph "Infrastructure Docker"
        subgraph "Frontend Service:8091"
            FE[FastAPI Frontend]
            FE -- HTMX --> UI[Interface UI]
            UI -- AlpineJS --> FE
        end
        
        subgraph "Backend Service:8000"
            BE[FastAPI Backend]
            BE -- API --> FE
        end
        
        subgraph "External Services"
            POT[Potree Viewer:8090]
            PDAL[PDAL Tool]
            ENT[Entwine Tool]
        end
    end
    
    subgraph "Data Storage"
        UPLOADS[./backend/data/uploads/]
        EPT_DIR[./backend/data/ept/]
        CONFIG[./frontend/config/]
    end
    
    subgraph "Templates & Static"
        TEMPLATES[./frontend/templates/]
        COMPONENTS[./frontend/components/]
        STATIC[./backend/static/potree/]
    end
```

## Flux principal d'upload et conversion

```mermaid
sequenceDiagram
    participant User as Utilisateur
    participant FE as Frontend (8091)
    participant BE as Backend (8000)
    participant ENT as Entwine
    participant FS as Système de Fichiers

    User->>FE: 1. Télécharge fichier LAS/LAZ/PLY
    FE->>FE: 2. Vérifie format supporté
    FE->>BE: 3. POST /upload avec fichier
    BE->>BE: 4. Génère UUID (pc_id)
    BE->>FS: 5. Écrit fichier dans uploads/
    BE->>ENT: 6. LANCE entwine build
    ENT->>FS: 7. Convertit vers format EPT
    ENT->>FS: 8. Crée dossier ept/{pc_id}/
    ENT-->>BE: 9. Retourne résultat
    BE->>BE: 10. Sauvegarde manifest.json
    BE-->>FE: 11. Retourne JSON avec pc_id
    FE->>FE: 12. Affiche résultat HTMX
    FE->>POT: 13. Génère page viewer
    FE-->>User: 14. Affiche visualisation Potree
```

## Flux de visualisation

```mermaid
flowchart LR
    subgraph Frontend
        A[Page /viewer/list] --> B[HTMX Fetch /viewer/list]
        B --> C[cloud_list.html]
    end
    
    subgraph Backend
        D[API /viewer/list] --> E[Lecture EPT_DIR]
        E --> F[manifest.json]
        F --> G[Statistiques]
    end
    
    C -->|Affichage| H[Tableau Nuages]
    
    H -->|Click| I[Page /viewer/{pc_id}]
    I -->|HTMX| J[viewer.html partial]
    J -->|Embed| K[Potree Viewer]
    
    K -->|Chargement| L[/ept_data/{pc_id}/ept.json]
    L --> M[Visualisation 3D]
```

## Flux de crop (réduction du nuage)

```mermaid
sequenceDiagram
    participant User as Utilisateur
    participant FE as Frontend
    participant BE as Backend
    participant PDAL as PDAL
    participant FS as Système Fichiers

    User->>FE: 1. Sélectionne nuage + box 3D
    FE->>BE: 2. POST /admin/crop/{pc_id} avec box
    BE->>PDAL: 3. LANCE pdal filter
    PDAL->>FS: 4. Lit fichier source LAS
    PDAL->>FS: 5. Applique box de filtrage
    PDAL->>FS: 6. Écrit fichier LAS cropped
    PDAL-->>BE: 7. Retourne fichier cropped
    BE->>FS: 8. Lance entwine sur fichier cropped
    ENT->>FS: 9. Convertit vers EPT
    BE->>FS: 10. Sauvegarde nouveau nuage
    BE-->>FE: 11. Retourne nouveau pc_id
    FE->>FE: 12. Affiche nouveau nuage
```

## Architecture des routes

```mermaid
mindmap
  root((Architecture))
    Frontend
      /upload
        GET / - Redirection
        GET /upload - Page upload
        POST /upload - Upload fichier
        GET /health-check - Vérification
      /viewer
        GET /viewer/list - Liste nuages
        GET /viewer/{pc_id} - Visualisation
      /admin
        GET /admin/backend-config
        POST /admin/backend-config
        GET /admin/list
        GET /admin/debug/{pc_id}
        DELETE /admin/delete/{pc_id}
        POST /admin/crop/{pc_id}
    Backend
      /upload
        POST /upload - Conversion entwine
      /viewer
        GET /viewer/list - Liste EPT
        GET /viewer/{pc_id} - Page viewer
        GET /viewer-embed/{pc_id} - Embed
      /admin
        GET /debug/{pc_id} - Debug info
        DELETE /delete/{pc_id} - Suppression
        POST /admin/crop/{pc_id} - Crop PDAL
      /health - Health check
      / - Page HTML
      /ept_data - Serveur statique
      /static - Assets
```

## Structure des dossiers EPT

```mermaid
graph TD
    EPT[EPT Directory]
    EPT --> MANIFEST[manifest.json]
    EPT --> EPT_JSON[ept.json]
    EPT --> EPT_BUILD[ept-build.json]
    EPT --> EPT_DATA[ept-data/]
    EPT_DATA --> TUILES[.las.tileset]
    EPT_DATA --> META[meta.json]
    EPT --> EPT_HIERARCHY[ept-hierarchy/]
    EPT_HIERARCHY --> NOEUDS[.node]
    EPT --> EPT_SOURCES[ept-sources/]
    EPT_SOURCES --> SOURCES[.las]
```

## Diagramme complet des interactions

```mermaid
flowchart TB
    subgraph "Utilisateur"
        U[Utilisateur]
    end
    
    subgraph "Frontend Service [8091]"
        direction TB
        FE[FastAPI<br/>Jinja2 + HTMX + AlpineJS]
        UI[Interface<br/>DaisyUI + Tailwind]
        API_CLIENT[api_client.py<br/>httpx Async]
        CONFIG[config.py<br/>BACKEND_URL + POTREE_URL]
        
        U -->|Navigate| UI
        UI -->|HTMX| FE
        FE -->|Templates| UI
        FE -->|Routes| API_CLIENT
        API_CLIENT -->|HTTP| BE
        FE -->|Config| CONFIG
    end
    
    subgraph "Backend Service [8000]"
        direction TB
        BE[FastAPI<br/>PDAL + Entwine]
        ROUTES[Routes<br/>upload.py<br/>viewer.py<br/>admin.py]
        SERVICES[Services<br/>converter.py<br/>manifest.py<br/>html_generator.py]
        UTILS[Utils<br/>disk.py]
        STATIC[Static Files<br/>Potree Viewer]
        
        BE -->|Include| ROUTES
        ROUTES -->|Call| SERVICES
        SERVICES -->|Read| UTILS
        BE -->|Serve| STATIC
        BE -->|Mount| EPT_DIR[/ept_data/]
    end
    
    subgraph "Outils Externes"
        ENT[Entwine<br/>build EPT]
        PDAL[PDAL<br/>filter/crop LAS]
    end
    
    subgraph "Stockage"
        UPLOADS[uploads/<br/>fichiers LAS/LAZ]
        EPT[ept/<br/>nuages convertis]
        CONFIG_FILE[config/<br/>backend.json]
    end
    
    subgraph "External"
        POT[Potree Viewer<br/>WebGL 3D]
    end
    
    %% Flux Upload
    UI -->|1. Choix fichier| U
    U -->|2. POST /upload| API_CLIENT
    API_CLIENT -->|3. POST /upload| BE
    BE -->|4. Enregistrer| UPLOADS
    BE -->|5. Lancer| ENT
    ENT -->|6. Convertir| EPT
    BE -->|7. Sauvegarder| SERVICES
    SERVICES -->|8. manifest.json| EPT
    
    %% Flux Liste
    UI -->|9. /viewer/list| API_CLIENT
    API_CLIENT -->|10. GET /viewer/list| BE
    BE -->|11. Lire| EPT
    BE -->|12. Retourne| API_CLIENT
    API_CLIENT -->|13. Affiche| UI
    
    %% Flux Visualisation
    UI -->|14. /viewer/{pc_id}| FE
    FE -->|15. Embed| POT
    POT -->|16. Charger| EPT_DIR
    EPT_DIR -->|17. ept.json| POT
    POT -->|18. Visualiser| U
    
    %% Flux Crop
    UI -->|19. /admin/crop| API_CLIENT
    API_CLIENT -->|20. POST /admin/crop| BE
    BE -->|21. Lancer| PDAL
    PDAL -->|22. Filtre| UPLOADS
    BE -->|23. Convertir| ENT
    ENT -->|24. Nouveau EPT| EPT
    BE -->|25. Retourne| API_CLIENT
    API_CLIENT -->|26. Affiche| UI
    
    %% Styles
    classDef user fill:#e1f5ff,stroke:#1890ff,stroke-width:2px
    classDef frontend fill:#fff7e6,stroke:#fa8c16,stroke-width:2px
    classDef backend fill:#f6ffed,stroke:#52c41a,stroke-width:2px
    classDef tools fill:#f0f5ff,stroke:#2f54eb,stroke-width:2px
    classDef storage fill:#fff0f6,stroke:#eb2f96,stroke-width:2px
    classDef external fill:#f9f0ff,stroke:#722ed1,stroke-width:2px
    
    class U user
    class FE,UI,API_CLIENT,CONFIG frontend
    class BE,ROUTES,SERVICES,UTILS,STATIC backend
    class ENT,PDAL tools
    class UPLOADS,EPT,CONFIG_FILE storage
    class POT external
```

## Fonctionnalités de l'application

### 1. Upload et Conversion
- Téléchargement de fichiers LAS, LAZ, PLY, XYZ, PTS
- Conversion automatique vers format EPT (Entwine Point Tile)
- Génération de manifeste pour chaque nuage
- Suivi du temps de conversion

### 2. Visualisation 3D
- Intégration Potree Viewer (WebGL)
- Chargement direct des tuiles EPT
- Configuration de la taille de point et forme
- Support des modes embed et standalone

### 3. Administration
- Liste de tous les nuages de points
- Informations détaillées (taille, nombre de fichiers, date)
- Debug panel pour inspection
- Suppression de nuages

### 4. Traitement PDAL
- Crop 3D des nuages de points
- Définition de box de sélection
- Conversion du résultat en EPT

### 5. Configuration Dynamique
- URL du backend configurable
- URL de Potree configurable
- Sauvegarde dans fichier JSON
- Variables d'environnement

### 6. Monitoring
- Endpoint /health pour vérification
- Indicateur de disponibilité Entwine
- Affichage de l'espace disque libre
- Version de PDAL

### 7. Relevant Files and Code:

- __backend/main.py__: Point d'entrée backend, mounting de /ept_data, /static, /potree
- __backend/routes/upload.py__: POST /upload - conversion entwine avec UUID
- __backend/routes/viewer.py__: GET /viewer/list, /viewer/{pc_id}, /viewer-embed/{pc_id}
- __backend/services/converter.py__: run_entwine() - commande entwine build
- __backend/services/manifest.py__: save_manifest(), read_manifest()
- __backend/services/html_generator.py__: generate_viewer_html() - template Potree
- __frontend/api_client.py__: check_health(), upload_file(), get_debug(), delete_pointcloud(), crop_pointcloud()
- __frontend/routes/upload.py__: POST /upload → api_client.upload_file()
- __frontend/routes/crop.py__: POST /admin/crop/{pc_id} → api_client.crop_pointcloud()
- __frontend/templates/index.html__: Interface principale avec HTMX tabs (Upload, Admin)
- __docker-compose.yml__: 2 services, volumes mount, environment variables