# IliaCloud — Specifications Projet

> **IliaCloud** — *"Il y a Claude, il y a Cloud"*
> Agent IA mobile connecte a tes serveurs via SSH. Dashboard, actions, chat — tout depuis ton telephone.

---

## Vision

Une PWA mobile-first qui te donne un acces complet a tes serveurs distants :
- Un **dashboard** visuel (sante, Docker, logs)
- Des **actions rapides** configurables (boutons → commandes)
- Un **agent Claude** integre qui peut lire, diagnostiquer, et modifier tes fichiers

Pense Claude Code, mais sur mobile, avec une vraie UI et une connexion SSH persistante.

---

## Cas d'usage principaux

| Situation | Ce qu'on fait |
|-----------|---------------|
| Urgence serveur en deplacement | Ouvrir IliaCloud → dashboard → diagnostiquer → corriger |
| Container plante | Voir les logs → demander a Claude → fix automatique |
| Verifier l'etat general | Dashboard temps reel → CPU, RAM, disque, uptime |
| Deployer depuis le canape | Bouton "Redeployer X" → confirmation → execute |
| Probleme complexe | Chat Claude avec contexte serveur → analyse → fix fichier |

---

## Stack technique

### Frontend
- **PWA React 18 + Vite 5** — mobile-first, installable Android/iOS
- **Tailwind CSS 3** — theme dark (slate/indigo), theme clair/sombre
- **Chart.js** — graphiques metriques historiques
- **xterm.js** — terminal SSH dans le navigateur
- **CodeMirror 6** — editeur de code avec coloration syntaxique
- **Lucide React** — icones
- **Playwright** — tests E2E
- Interface : navigation par sections + bottom nav mobile
- Mode offline basique (PWA service worker)

### Backend
- **Node.js 20 + Express 4** — API REST + WebSocket
- **PostgreSQL 16** — 22 tables, plans en JSONB
- **ssh2** — connexion SSH persistante avec pool, reconnexion automatique
- **ws** — WebSocket (metriques temps reel, terminal SSH, docker logs streaming)
- **jsonwebtoken** — JWT access (15min) + refresh (7j) avec rotation
- **bcryptjs** — hash mots de passe (12 rounds)
- **web-push** — notifications push VAPID
- **Helmet + CSP** — headers securite HTTP
- **Vitest** — 554 tests unitaires (29 fichiers)
- Tourne dans un container Docker sur le VPS, expose via Traefik

### Agent IA
- [x] **API Anthropic** (Claude) avec tool use
- [x] **OpenAI** (GPT-4o, GPT-4o-mini)
- [x] **Google** (Gemini 2.5 Pro/Flash)
- [x] **DeepSeek** (R1, V3)
- [x] **Mistral** (Large, Small)
- [x] **xAI** (Grok)
- Tool principal : `bash_exec(command)` → SSH → stdout/stderr → reponse
- Acces fichiers : lecture + ecriture (avec confirmation)
- Tool use conditionne par le plan (desactive pour le plan free)

### Auth
- [x] Email + password avec JWT (cookies httpOnly + Secure + SameSite)
- [x] Refresh token rotation (ancien token supprime)
- [x] Account lockout (5 echecs = 15 min de blocage)
- [x] Multi-user natif des le depart (tout scope a un `user_id`)
- [x] Plans Free / Pro / Business — Stripe integre (checkout + portal + webhooks)
- [x] CSRF double submit cookie

---

## Fonctionnalites

### Section Serveur — Dashboard
- [x] CPU, RAM, disque, uptime, charge (load 1m/5m)
- [x] Graphiques temps reel via WebSocket (refresh 5s)
- [x] Historique metriques 1h/6h/24h/7j/30j avec Chart.js
- [x] Alerte visuelle si seuil critique depasse
- [x] Espace disque dans l'overview (barre progression, warning 85%, critical 95%)
- [x] Multi-serveurs : vue comparative de tous les serveurs

### Section Docker
- [x] Liste tous les containers avec leur etat (running / stopped / exited)
- [x] Fiche detail : infos (image, ports, volumes, date creation)
- [x] Logs stdout (et logs applicatifs si montes)
- [x] Actions : restart / stop / start / supprimer / prune
- [x] Stacks : Docker Swarm + Compose, redeployer, rollback, config, historique
- [x] Stats : CPU/RAM/Network par container en temps reel
- [x] Logs streaming : `tail -f` en direct via WebSocket
- [x] Confirmation obligatoire sur les actions destructives

### Section Logs
- [x] Logs serveur systeme (`syslog`, `auth.log`, etc.)
- [x] Logs applicatifs configures par l'utilisateur
- [x] 3 types : fichier, Docker stdout, fichier dans container (docker-file)
- [x] Scrollable, filtrable, tail avec search
- [x] Scan automatique des logs a l'ajout du serveur

### Actions rapides
- [x] Boutons configurables par l'utilisateur
- [x] Chaque bouton = un nom + une commande bash + un flag `requires_confirm`
- [x] Ordonnables par l'utilisateur (`sort_order`)
- Exemples : "Redeployer CoolCare", "Vider le cache Redis", "Relancer Nginx"

### Agent Claude (Chat)
- [x] Accessible depuis n'importe quelle section via un bouton flottant
- [x] Contexte automatique : Claude sait sur quel serveur tu es
- [x] Peut executer des commandes bash sur le serveur
- [x] Peut lire et **modifier des fichiers** (avec confirmation explicite)
- [x] Confirmation obligatoire avant toute action sensible
- [x] Historique des sessions conserve en base
- [x] 6 providers IA (Anthropic, OpenAI, Google, DeepSeek, Mistral, xAI)
- [x] 15 modeles selectionnables
- [x] Compteur messages/jour avec barre de progression
- [x] Tool use conditionne par le plan

### Terminal SSH
- [x] xterm.js dans le navigateur
- [x] Bouton flottant, drawer redimensionnable
- [x] Connexion via WebSocket
- [x] Feature bloquee pour le plan free

### Editeur de fichiers
- [x] Navigateur d'arborescence
- [x] Edition avec CodeMirror (coloration syntaxique)
- [x] Lecture pour tous, ecriture bloquee en plan free

### Cron manager
- [x] CRUD crontab sur le serveur distant
- [x] Presets, activation/desactivation
- [x] Lecture pour tous, CRUD bloque en plan free

### Monitoring & Alertes
- [x] Uptime monitoring : ping HTTP toutes les 1-5min, uptime %, graphique latence
- [x] SSL monitoring : verification TLS directe toutes les heures, alerte avant expiration
- [x] Surveillance HTTP 5xx : scan des access logs toutes les 60s
- [x] Alertes avec recovery : CPU/RAM/Disque/Load — alerte puis recovery automatique
- [x] Push notifications : Web Push via VAPID, seuils configurables par metrique
- [x] 10 types de webhooks : server_alert/recovery, uptime_down/up, ssl_expiring/expired/recovery, backup_error/success, http_error
- [x] 4 plateformes : Discord (embeds), Slack (emojis), Telegram (Markdown), Custom (JSON)

### Backups
- [x] PostgreSQL + MySQL, manuel ou planifie (horaire/quotidien/hebdo)
- [x] Auto-scan des containers DB
- [x] Restauration en un clic avec confirmation
- [x] Retention par plan (3j / 30j / 90j), nettoyage automatique
- [x] Download et restore conditionnes par le plan
- [x] Webhook succes/echec a chaque backup

### Administration
- [x] Audit log : toutes les actions loguees (16 categories), filtres, recherche, export CSV
- [x] Import/Export config : chiffree AES-256-GCM avec PBKDF2 100k iterations
- [x] Status page publique : page sans login, personnalisable (titre, logo, couleurs)
- [x] Page pricing publique : comparaison Free/Pro/Business
- [x] Theme clair/sombre (toggle + preference systeme)
- [x] PWA installable (service worker, manifest, icones)
- [x] Onboarding guide pour les nouveaux utilisateurs

---

## Systeme de plans & Monetisation

### Plans

| | Free | Pro (12EUR/mois) | Business (35EUR/mois) |
|---|---|---|---|
| Serveurs | 1 | 5 | Illimite |
| Monitors uptime | 3 | 20 | Illimite |
| Intervalle uptime min | 5 min | 1 min | 30s |
| Certificats SSL | 3 | 20 | Illimite |
| Webhooks | 1 | 5 | Illimite |
| Regles d'alerte | 2 | 20 | Illimite |
| Actions rapides | 3 | 20 | Illimite |
| Chemins de logs | 3 | 20 | Illimite |
| Backups planifies | 1 | 10 | Illimite |
| Backups manuels/jour | 1 | Illimite | Illimite |
| Retention backups | 3j | 30j | 90j |
| Messages IA/jour | 20 | 200 | Illimite |
| Sessions chat | 3 | Illimite | Illimite |
| Status pages | 0 | 2 | Illimite |
| Retention metriques | 1j | 30j | 1 an |
| Retention audit | 1j | 30j | 1 an |
| Terminal SSH | - | Oui | Oui |
| Editeur fichiers (ecriture) | - | Oui | Oui |
| Docker stats/stacks/prune | - | Oui | Oui |
| Docker logs streaming | - | Oui | Oui |
| Cron CRUD | - | Oui | Oui |
| Backup download/restore | - | Oui | Oui |
| Chat tool use (bash) | - | Oui | Oui |
| Alertes HTTP/SSL | - | Oui | Oui |
| Export config/CSV audit | - | Oui | Oui |

### Implementation technique
- [x] Table `plans` en PostgreSQL (JSONB) — modifiable sans redeployer
- [x] Cache memoire 5 min avec fallback sur defaults
- [x] Middlewares backend : `requireFeature`, `checkQuota`, `checkDailyQuota`, `checkPlanValue`
- [x] Verification plan dans WebSocket (terminal SSH, docker logs)
- [x] Services background filtres par plan (httpErrorWatcher, sslChecker)
- [x] Cleanup metriques + audit a minuit, retention par plan
- [x] Frontend : `PlanButton` (boutons desactives), `PlanQuotaInfo` (jauges X/Y), `PlanLimitModal` (modal upgrade global), `UpgradeBanner` (bannieres preventives)
- [x] Intercepteur API : erreurs 403/429 PLAN_* declenchent le modal
- [x] Stripe : checkout, portal client, webhooks signature verifiee

---

## Connexion SSH

- [x] Persistante en arriere-plan avec pool de connexions
- [x] Reconnexion automatique et transparente
- [x] La cle SSH privee vit **cote backend uniquement**, jamais exposee au browser
- [x] Cle chiffree en base de donnees (AES-256-GCM)

---

## Configuration utilisateur

### Compte
- [x] Email, mot de passe, plan
- [x] Mot de passe : min 8 chars, max 128, bcrypt 12 rounds

### Serveurs (multi-serveurs)
- [x] Nom affiche, IP/hostname, port SSH (defaut 22)
- [x] User SSH
- [x] Cle SSH associee + passphrase optionnelle
- [x] Test de connexion au moment de la sauvegarde

### Cles IA
- [x] Cle API Anthropic
- [x] Cle API OpenAI
- [x] Cle API Mistral
- [x] Cle API Google (Gemini)
- [x] Cle API DeepSeek
- [x] Cle API xAI (Grok)
- [x] Modele par defaut configurable par provider

### Logs configures
- [x] **Decouverte automatique a l'ajout du serveur** : scan des chemins + containers Docker
- [x] Possibilite d'ajouter des chemins manuellement
- [x] 3 types : `file` (chemin fichier), `docker` (stdout container), `docker-file` (fichier dans container)

### Actions rapides
- [x] Creer / editer / supprimer / reordonner ses boutons
- [x] Lie a un serveur specifique

---

## Onboarding (premier lancement)

1. [x] Creer son compte (email + password)
2. [x] Ajouter son premier serveur (wizard guide)
3. [x] Coller / uploader sa cle SSH → test de connexion immediat
4. [x] Scan automatique des logs → cocher ce qu'on veut surveiller
5. [x] Ajouter sa cle API IA
6. [x] Guide onboarding interactif dans l'interface
7. **Pret en < 5 minutes**

---

## Schema de base de donnees

```
users                          plans (JSONB)
├── id (uuid, PK)              ├── name (PK: free/pro/business)
├── email                      ├── limits (JSONB — 35 cles)
├── password_hash              └── updated_at
├── plan (free/pro/business)
├── locked_until               subscriptions (Stripe)
└── created_at                 ├── user_id (FK → users)
                               ├── stripe_customer_id
ssh_keys                       ├── stripe_subscription_id
├── id (uuid, PK)              ├── plan, status
├── user_id (FK → users)       └── current_period_start/end
├── name
├── encrypted_private_key      uptime_monitors
├── passphrase_encrypted       ├── user_id, url, label
└── created_at                 ├── interval_s, enabled
                               └── created_at
servers
├── id (uuid, PK)              uptime_history
├── user_id (FK → users)       ├── monitor_id, status
├── ssh_key_id (FK)            ├── latency_ms
├── name, host, port, ssh_user └── created_at
└── created_at
                               ssl_certificates
api_keys                       ├── user_id, domain, port
├── user_id, provider          ├── issuer, subject, valid_from/to
├── encrypted_key              ├── alert_days, enabled
├── default_model              ├── last_check, last_status
└── created_at                 └── created_at

log_paths                      ssl_check_history
├── server_id, label           ├── certificate_id, status
├── path, type                 ├── days_remaining, error
└── created_at                 └── created_at

quick_actions                  webhooks
├── server_id, label           ├── user_id, label, url
├── command, requires_confirm  ├── platform, events[]
├── sort_order                 ├── enabled
└── created_at                 └── created_at

chat_sessions                  alert_rules
├── user_id, server_id         ├── server_id, user_id
├── title                      ├── metric, threshold
└── created_at                 ├── enabled
                               └── created_at
chat_messages
├── session_id                 alert_history
├── role (user/assistant)      ├── alert_rule_id, server_id
├── content                    ├── metric, value, threshold
└── created_at                 └── created_at

metrics_history                push_subscriptions
├── server_id                  ├── user_id, endpoint
├── cpu/mem/disk/load          ├── keys_p256dh, keys_auth
└── created_at                 └── created_at

backups                        backup_schedules
├── server_id, label           ├── server_id, user_id
├── db_type, db_name           ├── db_type, db_name
├── file_path, file_size       ├── frequency, retention
├── status, error              ├── enabled, last_run
└── created_at                 └── created_at

status_pages                   status_page_monitors
├── user_id, slug              ├── status_page_id
├── title, description         ├── monitor_id, label
├── logo_url, colors           ├── sort_order
├── enabled                    └── created_at
└── created_at

audit_logs                     refresh_tokens
├── user_id, action            ├── user_id
├── category, target           ├── token_hash
├── details (JSONB), ip        ├── expires_at
└── created_at                 └── created_at
```

### Relations (22 tables)
- `users` → `servers` (1 user, N serveurs)
- `users` → `ssh_keys` (1 user, N cles)
- `users` → `api_keys` (1 user, N cles IA, 1 par provider)
- `users` → `subscriptions` (1 user, 1 abonnement Stripe)
- `users` → `webhooks` (1 user, N webhooks)
- `users` → `uptime_monitors` (1 user, N monitors)
- `users` → `ssl_certificates` (1 user, N certificats)
- `users` → `alert_rules` (1 user, N regles)
- `users` → `status_pages` (1 user, N pages)
- `users` → `push_subscriptions` (1 user, N appareils)
- `users` → `audit_logs` (1 user, N logs)
- `users` → `refresh_tokens` (1 user, N tokens)
- `ssh_keys` → `servers` (1 cle, N serveurs)
- `servers` → `log_paths`, `quick_actions`, `backups`, `backup_schedules`, `metrics_history`
- `chat_sessions` → `chat_messages` (1 session, N messages)
- `uptime_monitors` → `uptime_history` (1 monitor, N pings)
- `ssl_certificates` → `ssl_check_history` (1 cert, N checks)
- `status_pages` → `status_page_monitors` (1 page, N services)
- `plans` : table standalone (free, pro, business)

---

## Securite

- [x] Cles SSH et cles API **chiffrees en base** (AES-256-GCM, IV 96-bit)
- [x] Cle de chiffrement dans les variables d'environnement, jamais en base
- [x] JWT avec expiration courte (15min) + refresh token rotation (7j)
- [x] Cookies httpOnly + Secure + SameSite
- [x] CSRF double submit cookie
- [x] Confirmation obligatoire avant toute action destructive
- [x] Account lockout : 5 echecs login en 15 min = bloque 15 min
- [x] Rate limiting : global (1000/15min), auth (50/15min), inscription (10/IP/jour), WebSocket (30/min/IP)
- [x] Protection SSRF : blocage IPs privees + metadata endpoints sur uptime et webhooks
- [x] Shell escape sur toutes les commandes SSH
- [x] Path validation anti-traversal + null bytes
- [x] Container name validation (alphanumerique uniquement)
- [x] Helmet + CSP (headers securite HTTP)
- [x] Audit log : toutes les actions mutantes, echecs auth traces, sensibles masques
- [x] Validation .env au demarrage (refuse de boot si secrets manquants/trop courts)
- [x] PBKDF2 100k iterations pour l'export de config
- [x] Anti timing-attack (dummy hash pour users inexistants)
- [x] Filtrage env vars sensibles dans le detail Docker
- [x] Stripe webhook signature verifiee
- [x] Plan enforcement cote serveur sur chaque route (35 limites)

---

## Infrastructure

- [x] Container Docker dans le Swarm OVH (141.94.42.172)
- [x] Expose via Traefik avec HTTPS/Let's Encrypt
- [x] Base de donnees : PostgreSQL 16-alpine (container dedie, volume persistant)
- [x] Frontend : Nginx servant le build Vite (port 80)
- [x] Backend : Node.js Express (port 3000)
- [x] Separe de CoolCare et FailDaily
- [x] SonarQube : quality gate (0 bugs, 0 vulnerabilites)

### Services en arriere-plan

| Service | Intervalle | Role |
|---------|-----------|------|
| **metricsCollector** | 5 min | Collecte CPU/RAM/Disque/Load, verifie les seuils |
| **uptimeChecker** | 60s | Ping les URLs, detecte DOWN/UP, envoie les alertes |
| **sslChecker** | 1h | Verifie l'expiration des certificats TLS |
| **httpErrorWatcher** | 60s | Scanne les access logs pour les erreurs 5xx |
| **backupScheduler** | 15 min | Execute les backups planifies, nettoie les anciens |
| **cleanup** | Minuit | Purge metriques + audit par plan (free 1j, pro 30j, business 1 an) |

---

## Tests

| Type | Framework | Nombre | Couverture |
|------|-----------|--------|------------|
| **Unitaires backend** | Vitest | 554 tests (29 fichiers) | Parsers, crypto, auth, middleware, services, routes, plans |
| **Unitaires frontend** | Vitest + RTL | 109 tests (22 fichiers) | Pages, composants, API client, contextes |
| **E2E** | Playwright | 7 scenarios (3 fichiers) | Auth, navigation, status page publique |
| **Qualite** | SonarQube | Quality gate | 0 bugs, 0 vulnerabilites |

---

## MVP vs Plus tard

### MVP
- [x] Auth email/password + JWT
- [x] Ajout d'un serveur avec cle SSH
- [x] Connexion SSH persistante
- [x] Dashboard serveur (CPU, RAM, disque, uptime)
- [x] Liste Docker + detail + logs container
- [x] Section Logs configures
- [x] Actions rapides custom
- [x] Chat Claude avec acces bash + fichiers
- [x] Scan automatique des logs a l'onboarding
- [x] Confirmation sur actions sensibles

### Roadmap — Fait
- [x] Multi-serveurs dans l'UI (vue comparative)
- [x] Alertes push (seuils CPU/RAM/disque) + recovery automatique
- [x] Editeur de fichiers integre (CodeMirror)
- [x] Support OpenAI / Mistral / Google / DeepSeek / xAI (6 providers, 15 modeles)
- [x] Plan Free / Pro / Business + Stripe (checkout, portal, webhooks)
- [x] Alertes Discord / Slack / Telegram / Custom (10 types d'events)
- [x] Terminal SSH web (xterm.js)
- [x] Docker stacks (Swarm + Compose), stats, logs streaming
- [x] Uptime monitoring + scan Traefik
- [x] SSL / Certificats monitoring
- [x] Surveillance HTTP 5xx
- [x] Backups PostgreSQL/MySQL planifies + restauration
- [x] Cron manager CRUD
- [x] Status page publique personnalisable
- [x] Audit log (16 categories) + export CSV
- [x] Import/export config chiffre AES
- [x] Theme clair/sombre + PWA installable
- [x] Systeme de plans DB-driven (35 limites enforced)
- [x] Securite OWASP (lockout, SSRF, rate limiting, audit echecs)
- [x] 663 tests (Vitest + Playwright + SonarQube)

### Roadmap — A faire
- [ ] Partage d'acces multi-user (roles + permissions)
- [ ] CI/CD triggers (redeploiement depuis l'app)
- [ ] MFA optionnel (TOTP)
- [ ] Alertes email
- [ ] Mode offline enrichi (sync quand reconnecte)

---

## Notes de dev

- Tout est scope a `user_id` des le depart → multi-tenant natif
- Champ `plan` sur `users` + table `plans` JSONB → modifiable sans redeployer
- Champ `provider` sur `api_keys` → 6 providers supportes
- BYOK (Bring Your Own Key) : chaque user fournit sa propre cle API IA
- Plans stockes en DB avec cache 5 min, fallback sur defaults si DB inaccessible
- Cleanup automatique a minuit : metriques + audit purges selon le plan
- Le backend refuse de demarrer si les secrets sont manquants ou trop courts

---

*Document de reference — IliaCloud v1.0*
*Derniere mise a jour : avril 2026*