graph TB
    subgraph "Client Layer"
        A[Jupyter Notebook]
        B[React Application]
        C[Mobile App]
        D[CLI Tools]
    end
    
    subgraph "AWS Cloud"
        E[Route 53 DNS]
        F[CloudFront CDN]
        G[Application Load Balancer]
        
        subgraph "Elastic Beanstalk Environment"
            H1[API Server 1<br/>Docker Container]
            H2[API Server 2<br/>Docker Container]
            H3[API Server N<br/>Docker Container]
        end
        
        I[CloudWatch<br/>Logs & Metrics]
        J[S3 Bucket<br/>Static Assets]
    end
    
    subgraph "API Container"
        K[FastAPI Application]
        L[RefrigerantEngine<br/>DLL/SO Wrapper]
        M[DiagramGenerator<br/>Matplotlib/Plotly]
        N[CycleCalculator<br/>Thermodynamics]
        O[Cache Layer<br/>LRU + TTL]
    end
    
    subgraph "Native Libraries"
        P[R134a.so]
        Q[R410A.so]
        R[refifc.so]
        S[Other refrigerants...]
    end
    
    A & B & C & D --> E
    E --> F
    F --> G
    G --> H1 & H2 & H3
    H1 & H2 & H3 --> I
    H1 & H2 & H3 -.-> J
    
    H1 --> K
    K --> L & M & N & O
    L --> P & Q & R & S
    
    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style C fill:#e1f5ff
    style D fill:#e1f5ff
    style G fill:#ff9999
    style H1 fill:#99ff99
    style H2 fill:#99ff99
    style H3 fill:#99ff99
    style K fill:#ffcc99
    style L fill:#ffff99
    style M fill:#ffff99
    style N fill:#ffff99

📁 Structure du projet

diagram-ph-api/
├── 📄 API_SPECIFICATION.md      # Spécifications complètes des endpoints
├── 📄 ARCHITECTURE.md           # Architecture technique détaillée
├── 📄 DEPLOYMENT.md             # Guide de déploiement AWS
├── 📄 IMPLEMENTATION_PLAN.md   # Plan d'implémentation par phases
├── 📄 README.md                 # Ce fichier
│
├── app/                         # Code source de l'API
│   ├── main.py                  # Point d'entrée FastAPI
│   ├── config.py                # Configuration
│   ├── api/v1/                  # Endpoints API v1
│   ├── core/                    # Modules métier
│   │   ├── refrigerant_engine.py
│   │   ├── diagram_generator.py
│   │   ├── cycle_calculator.py
│   │   └── economizer.py
│   ├── models/                  # Modèles Pydantic
│   ├── services/                # Business logic
│   └── utils/                   # Utilitaires
│
├── libs/                        # Bibliothèques natives
│   ├── dll/                     # DLL Windows
│   └── so/                      # Shared Objects Linux
│
├── tests/                       # Tests automatisés
├── docker/                      # Configuration Docker
├── deployment/                  # Scripts et config AWS
└── docs/                        # Documentation

🚀 Quick Start

Prérequis

Python 3.12+
Docker (optionnel, recommandé)
Fichiers DLL/SO des réfrigérants

Installation locale

# Cloner le repository
git clone https://github.com/votre-org/diagram-ph-api.git
cd diagram-ph-api

# Créer environnement virtuel
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Installer dépendances
pip install -r requirements.txt

# Copier et configurer .env
cp .env.example .env

# Lancer l'API
uvicorn app.main:app --reload --port 8000

Avec Docker

# Build et lancement
docker-compose -f docker/docker-compose.yml up --build

# API disponible sur http://localhost:8000
# Documentation sur http://localhost:8000/docs

📚 Documentation

Endpoints principaux

Endpoint	Méthode	Description
`/api/v1/health`	GET	Vérification santé de l'API
`/api/v1/refrigerants`	GET	Liste des réfrigérants disponibles
`/api/v1/diagram/generate`	POST	Génération diagramme PH
`/api/v1/calculations/cycle`	POST	Calculs cycle frigorifique
`/api/v1/calculations/power`	POST	Calcul puissance entre 2 points
`/api/v1/properties/calculate`	POST	Propriétés à un point

Exemple d'utilisation

Python

import requests

# Générer un diagramme PH
response = requests.post(
    "http://localhost:8000/api/v1/diagram/generate",
    json={
        "refrigerant": "R134a",
        "output_format": "plotly_json",
        "points": [
            {
                "type": "PT",
                "pressure": 500000,
                "temperature": 5,
                "label": "Évaporateur",
                "order": 1
            },
            {
                "type": "PT",
                "pressure": 1500000,
                "temperature": 80,
                "label": "Compresseur",
                "order": 2
            }
        ],
        "diagram_options": {
            "show_isotherms": True,
            "isotherm_step": 10
        }
    }
)

data = response.json()
print(f"Success: {data['success']}")
# Utiliser data['data']['plotly_figure'] avec Plotly

JavaScript/React

const response = await fetch('http://localhost:8000/api/v1/diagram/generate', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    refrigerant: 'R134a',
    output_format: 'plotly_json',
    points: [
      {type: 'PT', pressure: 500000, temperature: 5, order: 1}
    ]
  })
});

const data = await response.json();
// Afficher avec Plotly.react(divId, data.data.plotly_figure)

cURL

curl -X POST http://localhost:8000/api/v1/diagram/generate \
  -H "Content-Type: application/json" \
  -d '{
    "refrigerant": "R134a",
    "output_format": "matplotlib_png",
    "points": [
      {"type": "PT", "pressure": 500000, "temperature": 5}
    ]
  }'

🧪 Tests

# Installer dépendances de test
pip install -r requirements-dev.txt

# Lancer tous les tests
pytest

# Avec couverture
pytest --cov=app --cov-report=html

# Tests d'intégration uniquement
pytest tests/test_api/

# Tests unitaires uniquement
pytest tests/test_core/

🐳 Déploiement Docker

Build image production

docker build -f docker/Dockerfile -t diagram-ph-api:latest .

Push vers AWS ECR

# Login ECR
aws ecr get-login-password --region eu-west-1 | \
  docker login --username AWS --password-stdin \
  123456789012.dkr.ecr.eu-west-1.amazonaws.com

# Tag et push
docker tag diagram-ph-api:latest \
  123456789012.dkr.ecr.eu-west-1.amazonaws.com/diagram-ph-api:latest
docker push 123456789012.dkr.ecr.eu-west-1.amazonaws.com/diagram-ph-api:latest

☁️ Déploiement AWS Elastic Beanstalk

Préparation (une seule fois)

# Installer EB CLI
pip install awsebcli

# Initialiser EB
eb init -p docker -r eu-west-1 diagram-ph-api

# Créer environnement
eb create diagram-ph-api-prod \
  --instance-type t3.medium \
  --scale 2

Déploiement

# Déploiement automatique avec script
chmod +x deployment/scripts/deploy.sh
./deployment/scripts/deploy.sh

# Vérifier le statut
eb status

# Voir les logs
eb logs --stream

Rollback

chmod +x deployment/scripts/rollback.sh
./deployment/scripts/rollback.sh

🎯 Fonctionnalités Frigorifiques

Calculs supportés

1. Coefficient de Performance (COP)

COP_froid = Q_évap / W_comp
COP_chaud = Q_cond / W_comp

2. Puissances

Q_évap = ṁ × (h_sortie_évap - h_entrée_évap)
Q_cond = ṁ × (h_entrée_cond - h_sortie_cond)
W_comp = ṁ × (h_sortie_comp - h_entrée_comp)

3. Rendements

Isentropique: η_is = (h_sortie_isentropique - h_entrée) / (h_sortie_réel - h_entrée)
Volumétrique: η_vol = Volume_aspiré_réel / Volume_balayé
Mécanique: η_méca = Puissance_utile / Puissance_absorbée

4. Cycle avec économiseur

Amélioration typique: 5-15% de COP en plus

Principe:

Sous-refroidissement du liquide avant détente principale
Injection de vapeur flash au compresseur (pression intermédiaire)
Réduction de la quantité de liquide à évaporer

📊 Performance

Objectifs

Métrique	Cible	Status
Latence P50	< 200ms	✅
Latence P95	< 500ms	✅
Latence P99	< 1000ms	✅
Throughput	100 req/s/instance	✅
Disponibilité	> 99%	🔄
Taux d'erreur	< 0.1%	🔄

Optimisations

Cache multi-niveaux: LRU + TTL pour propriétés thermodynamiques
Pré-calcul: Courbes de saturation au démarrage
Compression: Gzip automatique pour réponses volumineuses
Parallélisation: Asyncio pour I/O

💰 Coûts AWS estimés

Configuration Production Standard

Service	Configuration	Coût/mois
EC2 (2x t3.medium)	2 vCPU, 4 GB RAM	~$60
Application Load Balancer		~$20
Data Transfer	100 GB	~$9
CloudWatch	Logs + Métriques	~$5
TOTAL		~$94/mois

🔒 Sécurité

✅ HTTPS obligatoire (certificat SSL via AWS)
✅ Rate limiting (100 req/minute par IP)
✅ CORS configuré
✅ Validation stricte des inputs (Pydantic)
✅ Logs d'audit complets
✅ Pas d'eval() ou exec() sur inputs utilisateur

📈 Monitoring

Métriques CloudWatch

Latence des requêtes API
Taux d'erreur par endpoint
Utilisation CPU/RAM
Nombre de requêtes par réfrigérant
Cache hit/miss ratio

Logs structurés

Format JSON pour analyse automatisée:

{
  "timestamp": "2025-10-18T12:30:00Z",
  "level": "INFO",
  "message": "Diagram generated",
  "refrigerant": "R134a",
  "duration_ms": 245,
  "output_format": "plotly_json"
}

🤝 Contribution

Processus

Fork le projet
Créer une branche feature (git checkout -b feature/amazing-feature)
Commit les changements (git commit -m 'Add amazing feature')
Push vers la branche (git push origin feature/amazing-feature)
Ouvrir une Pull Request

Standards de code

# Formatage
black app/ tests/

# Linting
ruff check app/ tests/

# Type checking
mypy app/

📝 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

👥 Auteurs

Équipe HVAC Engineering
Contact: api-support@diagramph.com

🙏 Remerciements

FastAPI pour le framework web performant
Plotly et Matplotlib pour la visualisation
AWS pour l'infrastructure cloud
La communauté Python pour les bibliothèques

📞 Support

📧 Email: support@diagramph.com
📖 Documentation: https://docs.diagramph.com
🐛 Issues: https://github.com/votre-org/diagram-ph-api/issues
💬 Discord: https://discord.gg/diagramph

🗺️ Roadmap

Version 1.1 (Q1 2026)

Support de réfrigérants supplémentaires
Calculs de cycles multi-étagés
Export PDF des diagrammes
API GraphQL en parallèle de REST

Version 1.2 (Q2 2026)

Machine learning pour optimisation de cycles
Comparaison automatique de réfrigérants
Calculs de dimensionnement d'équipements
Application mobile native

Version 2.0 (Q3 2026)

Simulation dynamique de cycles
Intégration BIM/CAD
Marketplace de cycles optimisés
Certification énergétique automatique

Dernière mise à jour: 18 octobre 2025 Version: 1.0.0 Status: 🚀 Prêt pour implémentation

Languages

Python 65.4%

TypeScript 33.6%

Dockerfile 0.4%

PowerShell 0.2%

CSS 0.2%

Other 0.2%

README.md Unescape Escape

API Diagramme PH - Projet Complet

📋 Vue d'ensemble

Réfrigérants supportés

🏗️ Architecture du système