Documentation technique

Architecture globale

Mon Agent IA est une application PHP 8.2+ / Apache dont seul le dossier public/ est exposé. La logique métier vit dans includes/, les données dans data/ (hors web).

Navigateur Chat · Espace Code · Admin

Mon Agent IA public/ · includes/ · data/

Open WebUI LLM local

Routeur API LLM via API cloud

MySQL 1 BDD / projet

Portainer API Stacks Docker

SonarQube Analyse qualité

Conteneurs preview maia-ws-{project_id} — Apache/PHP

Couche	Rôle
`public/`	Interface web, API JSON, proxy preview, symlinks workspace
`includes/`	Auth, projets, agent, Portainer, Sonar, versions, LLM
`data/`	Utilisateurs, projets, conversations, logs, settings, clés SSH
`docker/`	Images app et preview PHP
Conteneurs preview	Exécution isolée du code utilisateur (volume partagé avec le workspace)

Arborescence du dépôt

/var/www/html/
├── config.php                 # Config (secrets → variables d'env en prod)
├── public/                    # DocumentRoot Apache
│   ├── index.php, guide.php, technique.php
│   ├── chat.php, code.php, preview.php, terminal.php
│   ├── api/                   # Endpoints JSON (+ terminal-session.php)
│   └── ws/{id}/ → symlink     # Listing workspace
├── includes/
│   ├── ProjectStore.php       # CRUD projets, README, preview
│   ├── ProjectPreviewManager.php
│   ├── CodeAgent.php          # Agent (blocs <<<file>>>)
│   ├── Workspace.php          # Fichiers + versions
│   ├── LlmClientFactory.php   # Open WebUI / routeur API
│   └── …
├── data/
│   ├── projects-by-user/{user}/{id}/
│   │   ├── project.json
│   │   ├── workspace/
│   │   ├── conversations/
│   │   ├── .versions/         # Historique fichiers
│   │   └── .releases/         # Snapshots projet
│   ├── settings/              # llm.json, features.json, preprompts
│   └── logs/
└── docker/
    ├── app/
    └── preview-php/

LLM

Le chat et l'Espace Code partagent la même couche LLM, configurable en administration.

api/chat.phpChat général

api/code-chat.phpAgent code (SSE)

LlmClientFactory

Open WebUIou routeur API

Composant	Rôle
`data/settings/llm.json`	Fournisseur actif, clé et modèle du routeur API
`LlmSettings.php`	Lecture / écriture, surcharge par variables d'env
`OpenWebUIClient`	API `/v1/chat/completions` + streaming SSE
`OpenAiCompatibleChatClient`	Client OpenAI-compatible (routeur API)

Variables d'environnement LLM

Variable	Description
`LLM_PROVIDER`	`openwebui` ou routeur API
`OPENWEBUI_API_URL`	URL de l'instance Open WebUI
`OPENWEBUI_API_KEY`	Clé API Open WebUI
Routeur API	URL, clé et modèle — Admin → Paramètres ou `data/settings/llm.json` (surcharge possible via variables d'environnement, voir `config.example.php`)

Agent développeur

L'agent modifie les fichiers réels du workspace via des blocs <<<file path="…">>>. Il ne se connecte pas en SSH : l'utilisateur exécute les commandes shell si besoin.

Message utilisateur → api/code-chat.php (flux SSE).
CodeAgent + LlmClientFactory → réponse LLM.
Archivage versions fichier (si module actif) avant application.
Workspace::write() — écriture disque.
Validation PHP optionnelle (php -l + test HTTP, max 3 corrections).
Choix cliquables via bloc <<<choices>>>.

Fichier clé	Rôle
`CodeAgent.php`	Parse opérations, applique write/mkdir/delete
`Workspace.php`	CRUD fichiers, versions, upload
`AgentUndoStore.php`	Annulation dernière série de modifs agent
`ConversationStore.php`	Discussions code par projet

Docker & Portainer

Chaque projet Espace Code déclenche le déploiement d'une stack Docker via l' API REST Portainer. La stack s'appelle maia-ws-{project_id} sur le réseau llm_default (configurable).

Modèles de projet

Modèle	ID	Image	Port app
Site web (PHP)	`site-web`	`maia-preview-php:latest`	80

Cycle de vie

Création projet → provisioning MySQL + génération compose.
Appel Portainer → démarrage conteneur preview.
Volume hôte monté : workspace/ du projet.
Édition IDE / agent → fichiers visibles immédiatement dans le conteneur.
Suppression / archivage → destruction stack + DROP base.

Variable clé : PORTAINER_HOST_DATA_PATH
Racine de l'app sur le NUC (ex. /home/mike/docker_config/llm).
Le compose monte {HOST}/data/projects-by-user/{user}/{id}/workspace dans le conteneur.

Variables Portainer

Variable	Description
`PORTAINER_URL`	URL API Portainer
`PORTAINER_TOKEN`	Jeton d'accès API
`PORTAINER_ENDPOINT_ID`	ID de l'endpoint Docker
`PORTAINER_HOST_DATA_PATH`	Chemin hôte des données projet
`PORTAINER_NETWORK`	Réseau Docker (défaut `llm_default`)
`PORTAINER_SSH_CONNECT_HOST`	IP/DNS pour SSH vers conteneurs

Preview & SSH

Deux URLs distinctes par projet :

URL	Rôle
`/ws/{id}/`	Listing Apache du workspace (symlink)
`/preview/{id}/`	Proxy HTTP vers le conteneur PHP

Utilisateur

preview.php

maia-ws-{id}:80

SSH preview (mode DEV)

Port SSH hôte aléatoire publié par chaque conteneur.
Identifiants dans workspace/README.md (section auto-générée).
Usage : composer, pip, logs, tests CLI.
Terminal web : /terminal.php (xterm.js, module web_terminal) — auth root/mot de passe preview via sshpass, TERM=xterm-256color, poll séquentiel.
Pas de sous-domaine public pour le terminal (session Maia uniquement).

MySQL — provisioning

À la création d'un projet, ProjectDatabaseProvisioner crée automatiquement une base et un utilisateur dédiés via un compte MySQL admin configuré dans config.php.

Variable	Description
`CHATBOT_MYSQL_HOST`	Hôte MySQL admin
`CHATBOT_MYSQL_PORT`	Port (défaut 3306)
`CHATBOT_MYSQL_ADMIN_USER`	Compte avec droits CREATE DATABASE / USER
`CHATBOT_MYSQL_ADMIN_PASSWORD`	Mot de passe admin

Les identifiants projet sont injectés dans le README.md du workspace et exportés dans l'archive ZIP.

Versions projet & versions fichier

Versions fichier

Automatique — project/.versions/

Déclenché : Ctrl+S, autosave, modification agent
v1 créée à la création du fichier
Rattrapage à l'ouverture du modal si fichier legacy

Versions projet

Manuel — project/.releases/

Snapshot ZIP complet du workspace
Changelog IA des fonctionnalités
VERSIONS.md + CHANGELOG.md
Vue chronologique dans l'UI
Restauration : workspace, discussions, versions fichier et dump MySQL
Sauvegarde automatique avant chaque restauration

Discussions code : renommage au clic, recherche dans la discussion active (bouton loupe, surlignage côté client).

SonarQube

Analyse statique déclenchée depuis l'Espace Code. Le scan s'exécute via le conteneur sonar-scanner-cli et communique avec le serveur SonarQube configuré.

Rapports : .maia/rapport-analyse.md + .maia/rapport-analyse.json
Modale interactive avec saut à la ligne dans l'éditeur
Suppression projet → retrait côté SonarQube

Variable	Description
`SONARQUBE_ENABLED`	Activer le module
`SONARQUBE_URL`	URL serveur SonarQube
`SONARQUBE_TOKEN`	Jeton d'authentification
`SONARQUBE_SCANNER_IMAGE`	Image scanner (défaut `sonarsource/sonar-scanner-cli`)

Modules fonctionnels

Fichier data/settings/features.json — lu par AppFeatures.php, activable en admin.

Clé	Effet
`project_export`	Export ZIP projet (+ dump SQL MySQL)
`project_versions`	Snapshots projet + changelog IA
`file_versions`	Historique automatique par fichier
`code_sonar`	Analyse qualité SonarQube
`php_validation`	Vérification PHP post-agent
`agent_choices`	Boutons `<<<choices>>>`
`ws_access`	Protection mot de passe `/ws/`
`web_terminal`	Terminal SSH web (`/terminal.php`)

Modèle de projet : data/settings/project-models.json (Site web PHP).

API principales

Endpoint	Rôle
`api/chat.php`	Chat général (SSE)
`api/code-chat.php`	Agent code (SSE + application fichiers)
`api/files.php`	Arbre, lecture, écriture, versions fichier
`api/projects.php`	CRUD projets, export, versions projet, `restore_version`
`api/code-conversations.php`	Discussions code (list, create, rename…)
`api/upload.php`	Import fichiers workspace
`api/share-conversations.php`	Partage lecture seule
`api/terminal-session.php`	Session terminal web SSH (start/poll/send/resize/stop)

Configuration & déploiement

Prérequis

Composant	Version
PHP	8.2+ (extensions curl, json, mbstring, pdo_mysql, zip)
Apache	2.4 — `mod_rewrite`, DocumentRoot = `public/`
Open WebUI	Instance accessible (URL + clé API)
MySQL / MariaDB	Provisioning BDD par projet
Docker + Portainer	Preview conteneurisé par projet

Post-install

cd /var/www/html
sudo php scripts/fix-permissions.php
sudo apache2ctl configtest
sudo systemctl reload apache2
sh scripts/build-preview-images.sh      # sur le NUC
php scripts/repair-preview-setup.php

Documentation détaillée : README du dépôt, docs/SCHEMA-PROJET.md, docs/MIGRATION-NOUVELLE-INFRA.md, docs/CHOIX-MODELE-LLM.md.

Scripts CLI

Script	Rôle
`scripts/fix-permissions.php`	Droits www-data + symlinks `public/ws/`
`scripts/build-preview-images.sh`	Build image `maia-preview-php`
`scripts/repair-preview-setup.php`	Sync `data/.maia-docker/`
`scripts/diagnose-preview-portainer.php`	Test config Portainer + dry-run compose
`scripts/ensure-preview-ssh-keys.php`	Paire clés SSH plateforme

Sécurité

Session PHP 8 h par défaut — données isolées par utilisateur.
config.php et data/ hors DocumentRoot.
Preview et /ws/ : authentification requise.
SSH preview : mode DEV, mot de passe root éphémère par déploiement.
Secrets : privilégier les variables d'environnement en production.
Logs structurés JSON : data/logs/app-AAAA-MM-JJ.log.