Ce document détaille l'architecture technique, les choix de conception et la structure du projet OwL (Système de surveillance environnementale connecté).

Le système repose sur une architecture IoT classique : Capteurs -> Hub -> Cloud -> Interface Utilisateur.

graph TD
    User((Utilisateur))
    
    subgraph "Frontend (Vercel)"
        NextJS[Application Next.js]
    end
    
    subgraph "Backend (Vercel)"
        API[API Express.js]
    end
    
    subgraph "Services Tiers"
        Clerk[Clerk Auth]
        Supabase[(PostgreSQL DB)]
        Doppler[Doppler Secrets]
    end
    
    subgraph "Hardware (Domicile)"
        Hub[Boîtier Central ESP32]
        Sensors[Capteurs Fenêtres/CO2]
    end

    %% Flux
    User -- HTTPS --> NextJS
    NextJS -- HTTPS (Bearer Token) --> API
    API -- SQL (TypeORM) --> Supabase
    Hub -- HTTPS --> API
    Sensors -- RF/Fil --> Hub
    
    %% Auth
    NextJS -- Auth Check --> Clerk
    API -- Verify Token --> Clerk
    Clerk -- Webhook (Sync User) --> API

Note : Le schéma met en évidence une table centrale Sensors typée par SensorTypes, et une table volumineuse SensorReadings pour l'historique.

Le projet est organisé en une architecture Monorepo hébergée sur Vercel.

• Technologie : Next.js 15 (App Router), React, Tailwind CSS.
• Rôle : Interface utilisateur, Dashboard de visualisation.
• Architecture :
  • Server Components : Utilisés par défaut pour la récupération de données sécurisée et le SEO (ex: DashboardPage).
  • Client Components : Utilisés pour l'interactivité (ex: WindowSensorCard, graphiques Recharts).
  • Service Layer : Un apiClient centralisé gère les appels API et l'injection du token Clerk.

• Technologie : Node.js, Express, TypeScript.
• ORM : TypeORM.
• Hébergement : Déployé comme une Serverless Function sur Vercel.
• Structure : Architecture en couches (MVC) :
  • routes/ : Définition des endpoints.
  • controllers/ : Logique métier et validation.
  • entities/ : Modèles de données (TypeORM).
  • middlewares/ : Gestion de l'authentification (Clerk) et des erreurs.

La base de données est hébergée sur Supabase (PostgreSQL). Elle a été conçue pour la scalabilité des données IoT.

• Stratégie de Tables :
  • Users : Miroir local des utilisateurs Clerk pour maintenir l'intégrité référentielle.
  • Hubs & Sensors : Inventaire du matériel.
  • SensorReadings : Table historique contenant toutes les mesures. Elle est optimisée avec des index sur timestamp et sensor_id pour des requêtes rapides sur des millions de lignes.
• Intégrité des Données : Utilisation de contraintes CHECK pour garantir qu'une lecture est soit booléenne (ouverture), soit numérique (température), jamais les deux.
• Sécurité : L'API se connecte via un utilisateur dédié (express) avec des droits limités, et non en root.

L'API est de type RESTful. Elle est sécurisée et documentée.

• Documentation : Générée automatiquement via Swagger (OpenAPI).

  • URL (Dev uniquement) : /api-docs
  

• Authentification :

  • Tous les endpoints privés nécessitent un header Authorization: Bearer <token>.
  • Le token est validé via le SDK Clerk côté serveur.

• Endpoints Clés :

  • GET /api/sensors : État actuel de tous les capteurs.
  • GET /api/sensors/windows/stats : Statistiques d'agrégation (calculées par la DB) pour les graphiques.
  • POST /api/webhooks/clerk : Synchronisation des utilisateurs.

Nous n'interrogeons pas Clerk à chaque requête. Lorsqu'un utilisateur s'inscrit, Clerk notifie notre API via un Webhook. Notre API crée alors l'utilisateur dans notre base PostgreSQL. Cela garantit une indépendance totale de notre DB et des performances maximales pour les jointures SQL.

Pour le graphique "Habitudes d'ouverture", nous ne chargeons pas des milliers de points de données vers le frontend. Nous utilisons le QueryBuilder de TypeORM pour effectuer une agrégation SQL (GROUP BY, COUNT) directement en base de données. Le frontend reçoit un JSON léger de 24 points (les heures), ce qui est extrêmement performant.

Pour faciliter le développement avec des données de test statiques, l'API et le Frontend intègrent un mode "Simulation". Si l'API détecte que nous sommes en DEV, elle peut simuler le moment présent basé sur la dernière donnée enregistrée, permettant de tester les alertes "Fenêtre ouverte depuis > 1h" sans attendre réellement une heure.

La sécurité et la gestion des environnements sont gérées par Doppler.

• Secrets : Aucune clé API ou mot de passe n'est stocké dans le code (.env git-ignoré).
• Injection : Doppler injecte les variables d'environnement (DATABASE_URL, CLERK_SECRET_KEY) au moment du build (Vercel) ou du run (Local).
• Fichiers de config clés :
  • doppler.yaml : Configuration du projet Doppler.
  • vercel.json : Configuration du routage pour le déploiement monorepo.
  • tsconfig.json : Configuration TypeScript stricte.

• Lien vers le repo GitHub : github.com/BlacF0X/owl