be.CLEAR — Documentation de conception

Les IA peuvent maintenant construire leur propre application avec be.CLEAR.

Présentation

be.CLEAR est une application qui permet à toute organisation (ORG) de déterminer et de piloter ses interactions avec son environnement (ENV).

Ces interactions sont formalisées sous forme d'engagements (ENG) — chaque ENG représente une relation concrète entre une ou plusieurs ORG et un ou plusieurs ENV, planifiée dans le temps et décomposée en étapes séquentielles appelées évènements (EVENT).

be.CLEAR offre ainsi une vision complète du cycle de vie des interactions : de la définition des acteurs (ORG) et de leurs contextes (ENV) jusqu'au suivi opérationnel des engagements (ENG) et de leurs jalons (EVENT), avec un tableau de bord de progression de type Gantt.

Le stockage des données est organisé selon les principes de la programmation orientée objet : chaque entité du système (ORG, ENV, ENG, EVENT…) est une instance d'une classe (CLA). Les classes peuvent être organisées en hiérarchies — une sous-classe hérite automatiquement de toutes les propriétés (PROP) de ses classes parentes — et peut en définir de nouvelles. Ce schéma dynamique permet d'adapter finement la structure des données à chaque contexte sans modifier le modèle de base.

Construction et pilotage assistés par IA (MCP)

be.CLEAR expose nativement un serveur MCP (Model Context Protocol) qui permet à un assistant IA — Claude, ChatGPT ou tout autre client compatible MCP — de construire et piloter le système d'information de bout en bout en langage naturel.

À travers ce canal, l'IA dispose d'un accès complet et structuré au domaine :

Modélisation : création des classes (CLA), des propriétés (PROP) et des types (TORG, TENV, TENG, TEVENT) — l'assistant peut bâtir l'ossature du SI à partir d'une simple description métier.
Peuplement : création des organisations, environnements, engagements et évènements, avec leurs valeurs et leur cloisonnement domaine (DSEM).
Pilotage opérationnel : marquage des évènements accomplis, suivi des échéances (list_events_due, get_overdue_events), mise à jour des valeurs.
Exploration : recherche full-text (search) et interrogation sémantique du SI par RAG (rag_query) sur les données structurées.
Lecture détaillée : accès direct aux ORG, ENV et ENG avec leurs engagements et évènements rattachés.

Concrètement, un utilisateur peut décrire son activité en quelques phrases — "Je suis cabinet de conseil, je gère des missions clients avec des jalons mensuels…" — et obtenir un SI initialisé, peuplé et navigable, prêt à être enrichi via l'interface graphique ou la poursuite du dialogue avec l'IA.

Cette capacité fait de be.CLEAR un système d'information vivant, qui peut être construit, alimenté et interrogé indifféremment depuis l'application web, l'API REST ou un agent conversationnel.

Scénario type : l'IA analyse un use case sur le web et construit une application

Exemple : une IA reçoit un lien vers un cas d'usage public de type "suivi d'interventions terrain" et doit fabriquer une application métier dans be.CLEAR.

L'IA lit la source web (article, cahier des charges, documentation métier) et extrait le vocabulaire opérationnel.
Elle propose un mapping vers le modèle be.CLEAR :
- ORG = acteurs impliqués,
- ENV = contextes/lieux d'intervention,
- ENG = processus ou dossiers à piloter,
- EVENT = jalons et actions planifiées/réalisées.
Elle construit la structure de données via MCP :
- create_dsem pour le périmètre,
- create_cla et create_prop pour le schéma,
- create_torg, create_tenv, create_teng, create_tevent pour les types.
Elle instancie les premières données réelles avec create_org, create_env, create_eng, create_event.
Elle affine les objets avec update_value et valide les workflows avec les outils de lecture (list_*, get_*, search, rag_query).

Résultat : en partant d'un cas d'usage externe, l'IA peut créer un socle applicatif directement exploitable par les utilisateurs métiers — dans le respect des règles métier, des contrôles d'accès (ADMIN/EDITEUR/LECTEUR), de la journalisation et des recalculs automatiques du backend.

Limitations du modèle ORG-ENV-ENG-EVENT

Le modèle couvre très bien les interactions planifiées dans le temps, mais il a des limites à connaître.

Il est centré sur une logique relationnelle ORG ↔ ENV via ENG : certains domaines très transactionnels peuvent nécessiter des objets additionnels.
EVENT représente un jalon atomique ; les workflows avec forte parallélisation ou dépendances complexes peuvent demander des conventions métier complémentaires.
Le modèle ne remplace pas un moteur BPMN natif : il structure et suit l'exécution, mais n'orchestre pas automatiquement des graphes de processus avancés.
La qualité du mapping initial reste critique : une mauvaise traduction du use case en CLA/PROP/types produit un modèle valide techniquement mais peu pertinent fonctionnellement.
Les documents non structurés et médias servent de contexte (RAG, pièces jointes), mais le pilotage métier principal repose sur les données structurées.
Les garde-fous d'autorisations (ADMIN/EDITEUR/LECTEUR) limitent volontairement l'autonomie de l'IA selon le token utilisé.

Structure du projet

be.CLEAR/
├── docker-compose.yml      # Orchestration des services
├── .env.example            # Variables d'environnement (modèle)
├── .gitignore
├── backend/                # FastAPI (Python)
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/               # React 19 + Vite + TypeScript
│   ├── Dockerfile
│   └── nginx.conf
└── design/                 # Documents de conception
    ├── domain/             # Modèle de domaine, glossaire, concepts clés
    ├── architecture/       # Architecture système, composants, flux
    ├── data/               # Modèle de données, entités, relations
    ├── functional/         # Spécifications fonctionnelles, user stories
    └── ux/                 # Parcours utilisateur, wireframes descriptifs

Déployer une nouvelle instance

be.CLEAR est conçu pour être multi-instance : plusieurs instances peuvent tourner en parallèle sur la même machine, chacune avec ses propres containers, volumes, réseau et ports.

Prérequis

Docker Engine ≥ 24
Plugin docker compose (v2)

Instance par défaut

# 1. Cloner le dépôt
git clone <repo> be.CLEAR && cd be.CLEAR

# 2. Configurer l'environnement
cp .env.example .env
# Éditer .env : POSTGRES_PASSWORD, SECRET_KEY, MEILISEARCH_MASTER_KEY, ...

# 3. Déployer
./deploy.sh

Instances multiples sur la même machine

Chaque instance utilise un fichier .env.<nom> avec des ports uniques :

# Instance 1
cp .env.example .env.be-clear-1
# Éditer .env.be-clear-1 : ports 3000/8000/7700/6379/5432 (valeurs par défaut)
./deploy.sh --instance=be-clear-1

# Instance 2
cp .env.example .env.be-clear-2
# Éditer .env.be-clear-2 : changer les ports — ex. 3001/8001/7701/6380/5433
#   FRONTEND_PORT=3001
#   BACKEND_PORT=8001
#   MEILI_PORT=7701
#   REDIS_PORT=6380
#   POSTGRES_PORT=5433
#   PUBLIC_BASE_URL=http://localhost:8001
#   VITE_API_URL=http://localhost:8001
./deploy.sh --instance=be-clear-2

Chaque instance est totalement isolée : containers, volumes et réseau sont préfixés automatiquement par le nom de l'instance.

C'est tout. Au premier démarrage, l'entrypoint du backend :

Attend que PostgreSQL soit prêt
Applique les migrations Alembic (alembic upgrade head)
Lance l'application — le seed crée automatiquement les données essentielles si elles sont absentes : rôles, types d'utilisateur, classe de base et un compte admin / admin

Idempotent : ./deploy.sh peut être relancé à tout moment sur une instance existante sans risque — les données existantes ne sont jamais écrasées.

Options du script

./deploy.sh --instance=NOM       # Cibler une instance spécifique
./deploy.sh --no-migrate         # Ne pas vérifier les migrations Alembic
./deploy.sh --no-search-setup    # Ne pas reconfigurer l'index Meilisearch
./deploy.sh --clean              # Repartir de zéro — supprime les volumes (demande confirmation)

Commandes utiles

# Remplacer <instance> par le nom choisi (ex. be-clear-1), ou "beclear" pour l'instance par défaut
docker compose -p <instance> logs -f
docker compose -p <instance> down
docker compose -p <instance> exec backend alembic upgrade head

État d'implémentation

Fonctionnalités implémentées

Module	Fonctionnalité	Backend	Frontend
Auth	Connexion JWT (login/logout)	✅	✅
Auth	API publique — clé API (Bearer token externe)	✅	✅ profil
Panel	Panel personnel (OBJ créés par l'utilisateur)	✅	✅
Admin	Gestion CLA + PROP (création, modification, suppression)	✅	✅
Admin	Gestion TORG, TENV, TENG, TEVENT	✅	✅
Admin	Gestion des utilisateurs (USER)	✅	✅
Admin	Configuration globale (Obsidian, Ollama, LLM distants)	✅	✅
Admin	Journal LOG (consultation, filtres)	✅	✅
Admin	Réindexation Meilisearch	✅	✅
ORG	CRUD complet + navigation TORG → ORG	✅	✅
ORG	Détail : description, propriétés, images, documents, ENG, EVENT, graphe, RPT, timeline	✅	✅
ORG	Fusion d'ORG, transfert ENG en masse, suppression avec garde-fou 409 + réassignation	✅	✅
ENV	CRUD complet + navigation TENV → ENV	✅	✅
ENV	Détail : description, propriétés, images, documents, ENG, EVENT, calendrier, RPT, timeline	✅	✅
ENV	Fusion d'ENV, transfert ENG en masse, suppression avec garde-fou 409 + réassignation	✅	✅
Auth	SSO OIDC (OpenID Connect) — bouton login, callback, provisionnement USER, config admin	✅	✅
ENG	CRUD complet + filtres (statut, TENG, ORG, ENV, recherche, `type_document`, plages temporelles `updated_after`/`date_debut_after`)	✅	✅
ENG	Détail : Gantt Mermaid, accomplissement, ORG/ENV liées, EVENTs, images, documents, timeline, engagements liés	✅	✅
ENG	Duplication d'engagement	✅	✅
ENG	Création automatique des EVENTs depuis la séquence du TENG (RF-T1)	✅	✅
ENG	Relations typées entre ENG (`depend_de` / `suite_de` / `lie_a`) — CRUD + section dans le détail	✅	✅
ENG	EVENT TRANSFERT auto à chaque transfert d'ENG entre ENV/ORG (traçabilité)	✅	✅
ENG	Assignation d'ORG en mode ajout (sans remplacer la liste existante)	✅	✅
Admin	Séquence TEVENT par TENG — ajouter, réordonner, supprimer des TEVENTs (template)	✅	✅
EVENT	CRUD complet + calendrier + vue liste	✅	✅
EVENT	Détail : dates prévues/effectives, propriétés, images, documents, timeline	✅	✅
IMG	Upload, suppression, désignation image principale	✅	✅
DOC	Upload, téléchargement, suppression	✅	✅
Recherche	Full-text Meilisearch (ORG, ENV, ENG, EVENT) avec highlight et filtres + paramètre `filters` Meilisearch passthrough	✅	✅
Graphe	Visualisation force-directed globale + par ORG/ENV	✅	✅
Terminal IA	RAG : embedding pgvector + génération LLM (Ollama, OpenAI, Anthropic, Euria/Infomaniak)	✅	✅
Terminal IA	Métadonnées du moteur RAG (`/api/rag/info`) — couverture vector store, LLM par défaut, latences	✅	✅ admin
Terminal IA	Chat persistant (localStorage), citations cliquables, suggestions de follow-ups, feedback 👍/👎, stats admin	✅	✅
Terminal IA	Résolveur d'entités nommées + reformulation des follow-ups + RRF (Reciprocal Rank Fusion)	✅	n/a
Terminal IA	Périmètre RAG élargi : nom, description, values + texte extrait des DOC (PDF text-natif, .docx, .md)	✅	n/a
Terminal IA	Chunking multi-vecteurs par OBJ — une description longue ne dilue plus le centre sémantique	✅	n/a
Terminal IA	Mode agentique — Euria explore via tool_calls (`search_objs`, `get_entity_detail`, `list_engs_for_org`, `get_eng_with_events`)	✅	✅ toggle
RPT	Rapport Markdown ORG et ENV — téléchargement ou export filesystem/Obsidian	✅	✅
Export	Export JSON et Markdown sur ORG / ENV / ENG (`?format=json\|markdown`)	✅	✅ dropdown
Panel	Section « Hygiène des engagements » — ENG sans event planifié + ENG à 100 % non clos (via `/api/dashboard`)	✅	✅
API	Validation stricte des query parameters — `400` sur paramètre inconnu	✅	n/a
Webhooks	Notifications HTTP signées HMAC-SHA256 sur événements métier — retry 3× backoff	✅	✅ admin
DSEM	Domaine sémantique — filtre strict opt-in `?dsem=` (API/MCP) + préférence USER (`dsem_actif`) + tag `cla.dsem_id` avec héritage à la création + admin CRUD, sélecteur Mon panel, badge sidebar. CLA non taguée ⇒ visible uniquement en mode « Tous » (v1, 2026-05-25)	✅	✅

Travaux restants

Priorité	Sujet	Description
✅ Fait	Auth externe OIDC	Login SSO via OpenID Connect (Keycloak, Google, GitHub, Authentik…) — découverte automatique, state HMAC, provisionnement USER, secret chiffré Fernet
✅ Fait	Graphe global	Vue globale ORG↔ENG↔ENV avec filtres par type, recherche de nœud et optimisation N+1 (selectinload)
✅ Fait	Tests automatisés	Suite pytest-asyncio (SQLite in-memory) : 232 tests — auth, CRUD ORG/ENV/ENG/EVENT/TORG/TENV/TENG/TEVENT, duplication ENG, RPT, règles métier RF-02/RF-03/RF-04/RF-08/RF-09/RF-11/RF-12/RF-13/RF-15, OIDC state HMAC, crypto, RAG intégration, LOG, STATS, search, media, config/LLM/token, seed BDD multi-instance, templates TENG/TEVENT
✅ Fait	Tests E2E Playwright	Tests navigateur sur les parcours critiques : auth (login/logout/protection), ENG (liste, création), recherche full-text — lancés avec `npm run e2e`
✅ Fait	CI/CD GitHub Actions	Pipeline sur chaque push/PR : lint + tests backend, lint + typecheck + build frontend, build images Docker
✅ Fait	Gestion USER — désactivation	Bouton désactiver/réactiver un utilisateur dans l'onglet Utilisateurs de l'administration
✅ Fait	Pagination côté serveur	Vérifiée : ORG, ENV, ENG, EVENT ont tous un `page`/`per_page` côté serveur
✅ Fait	Chiffrement clés LLM	Chiffrement Fernet (AES-128-CBC) au repos — clé dérivée du SECRET_KEY
✅ Fait	Serveur MCP (étapes 1-4)	Serveur Model Context Protocol exposant les données be.CLEAR à Claude Desktop et autres clients MCP — outils lecture/écriture avancés (modélisation DSEM/CLA/PROP/types + création ORG/ENV/ENG/EVENT), ressources `beclear://`, 10 prompts types, transport stdio et SSE Docker (`--profile mcp`)
📋 TODO	ChatGPT Actions (étape 5)	Exposer be.CLEAR à ChatGPT via OpenAPI Actions — prérequis : déploiement HTTPS public. Créer un spec OpenAPI réduit (`/api/openapi_gpt.json`) couvrant search, RAG, ORG, ENG, EVENT. Configurer l'authentification par clé API dans GPT Builder. Dépend de l'infrastructure d'hébergement public.

Documents produits

Document	Type	Statut
Glossaire du domaine	Domaine	✅ Rédigé
Modèle de domaine	Domaine	✅ Rédigé
Modèle de données	Données	✅ Rédigé
Spécifications fonctionnelles	Fonctionnel	✅ Rédigé
Domaine sémantique (DSEM)	Fonctionnel	✅ v1 implémentée
Architecture système	Architecture	✅ Rédigé
Terminal IA — Architecture RAG	Architecture	✅ Rédigé
Serveur MCP — Intégration Claude Desktop	Architecture	✅ Rédigé
Opérations en masse et extensions	Fonctionnel	✅ Rédigé
UX / GUI	UX	✅ Rédigé

Menu principal

L'interface est organisée autour d'un menu latéral permanent donnant accès à toutes les fonctionnalités :

Entrée de menu	Description
Mon panel	Tableau de bord personnel — liste les OBJ créés par l'utilisateur connecté, avec accès rapide aux dernières modifications
Organisations	Navigation dans l'arborescence des types d'ORG (TORG) et accès à la liste des ORG de chaque type — création, consultation, modification, suppression
Environnements	Navigation dans l'arborescence des types d'ENV (TENV) et accès à la liste des ENV de chaque type — création, consultation, modification, suppression
Engagements	Liste filtrée et triable de tous les ENG — filtres par statut (non démarré / en cours / terminé), par TENG, par ORG, par ENV — vue Gantt et accomplissement par engagement
Évènements	Liste et calendrier de tous les EVENT — vue mensuelle, semaine ou liste — filtres par ENG, par TEVENT, par statut d'accomplissement
Recherche	Recherche full-text Meilisearch sur tous les OBJ (nom, description, VALUE textuelles) avec mise en évidence des occurrences et filtres par type d'entité
Graphe	Visualisation force-directed des relations ORG ↔ ENG ↔ ENV — filtrable par type, zoomable, avec recherche de nœud
Terminal IA	Interface RAG — interrogation du système en langage naturel (ex. : "Quels engagements d'Acme Corp sont en retard ?") avec choix du modèle LLM
Administration	Gestion des CLA et PROP, des types (TORG, TENV, TENG, TEVENT), des utilisateurs (USER), de la configuration globale (Obsidian, LLM, OIDC), des webhooks (notifications HTTP signées), du moteur RAG (couverture/latences) et consultation du journal LOG

Fonctionnalités transverses

Navigation et accès aux données

Fonctionnalité	Description
Panel personnel	Accès rapide aux OBJ créés par le USER connecté
Navigation TORG → ORG	Parcours de l'arborescence des types d'ORG — sélectionner un TORG affiche un tableau de toutes les ORG de ce type avec leurs PROP/VALUE en colonnes triables ; cliquer une ligne bascule sur ses ENG
Navigation TENV → ENV	Parcours de l'arborescence des types d'ENV — même comportement que TORG → ORG
Recherche full-text	Recherche sur les champs textuels des OBJ (nom, description, VALUE de type TEXTE/MARKDOWN) — DOC exclus

API — Accès par des systèmes externes

be.CLEAR expose une API REST/JSON complète qui permet à tout système externe (script, application compagnon, automate, CRM, ERP…) d'interagir avec les données du système sans passer par l'interface web.

Authentification

Un utilisateur ADMIN génère une clé API depuis son profil (section Tokens). La clé est transmise en en-tête HTTP à chaque requête :

Authorization: Bearer <votre-clé-api>

La clé hérite des droits du USER auquel elle est rattachée (LECTEUR, EDITEUR ou ADMIN). Un token peut être révoqué à tout moment depuis l'interface.

La documentation interactive complète (Swagger UI) est disponible à l'adresse :

http://<hôte>:8000/docs

Endpoints disponibles

Groupe	Préfixe	Opérations principales
ORG	`/api/org`	Lister, créer, lire, modifier, supprimer une organisation
ENV	`/api/env`	Lister, créer, lire, modifier, supprimer un environnement
ENG	`/api/eng`	Lister (avec `type_document`, `updated_after`, `date_debut_after`), créer, lire, modifier, supprimer un engagement ; Gantt Mermaid ; bulk-move ENV ↔ ORG ; relations entre ENG ; assignation d'ORG en mode ajout
EVENT	`/api/event`	Lister, créer, lire, modifier, supprimer un évènement ; vue calendrier ; overdue ; upcoming
Types	`/api/torg`, `/api/tenv`, `/api/teng`, `/api/tevent`	Lister et consulter les types
Recherche	`/api/search`	Recherche full-text Meilisearch (ORG, ENV, ENG, EVENT) + paramètre `filters` passthrough
RAG / IA	`/api/rag`	Interroger le système en langage naturel (RAG + LLM) ; `info` pour les métadonnées du moteur
RPT	`/api/rpt`	Déclencher la génération d'un rapport Markdown ORG ou ENV
Export	`/api/export/{eng\|env\|org}/{id}?format=json\|markdown`	Export structuré d'une entité avec ses ENG/EVENT/propriétés
Médias	`/api/media`	Accéder aux images et documents attachés aux OBJ
Graphe	`/api/graph`	Récupérer le graphe global ou filtré par ORG/ENV
Dashboard	`/api/dashboard`	Vue agrégée — events overdue/upcoming, ENG sans event, ENG à 100 % non clos, stats
Webhooks	`/api/webhook`	(ADMIN) Gérer les abonnements aux événements métier (signés HMAC-SHA256)
Utilisateurs	`/api/user`	Lister et consulter les USER (ADMIN uniquement pour les modifications)
Auth	`/api/auth`	Connexion, profil, gestion des tokens API, flux OIDC

Exemple de scénario — intégration CRM → be.CLEAR

Contexte : Un CRM enregistre la signature d'un contrat avec un client. Il doit automatiquement créer dans be.CLEAR un ENG Déploiement liant l'organisation cliente et l'environnement Production, puis planifier les étapes d'onboarding.

Étape 1 — Récupérer les identifiants ORG et ENV du client

GET /api/org?q=Acme+Corp
Authorization: Bearer <clé-api>

{ "items": [{ "id": 42, "nom": "Acme Corp", ... }], "total": 1 }

Étape 2 — Récupérer l'identifiant de l'ENV cible

GET /api/env?q=Production
Authorization: Bearer <clé-api>

{ "items": [{ "id": 7, "nom": "Production", ... }], "total": 1 }

Étape 3 — Créer l'ENG

POST /api/eng
Authorization: Bearer <clé-api>
Content-Type: application/json

{
  "nom": "Déploiement Acme Corp — Contrat 2026-05",
  "teng_id": 3,
  "date_debut": "2026-06-01T08:00:00Z",
  "org_ids": [42],
  "env_ids": [7],
  "values": []
}

{ "id": 201, "nom": "Déploiement Acme Corp — Contrat 2026-05", ... }

Étape 4 — Ajouter les EVENTs d'onboarding

POST /api/event
Authorization: Bearer <clé-api>
Content-Type: application/json

{
  "nom": "Réunion de lancement",
  "tevent_id": 11,
  "eng_id": 201,
  "date_heure_prevue": "2026-06-01T09:00:00Z"
}

POST /api/event
Content-Type: application/json
Authorization: Bearer <clé-api>

{
  "nom": "Formation utilisateurs",
  "tevent_id": 12,
  "eng_id": 201,
  "date_heure_prevue": "2026-06-08T09:00:00Z"
}

À l'issue de ces quatre appels, l'ENG est visible dans be.CLEAR avec son diagramme Gantt, ses ORG et ENV liées, et ses EVENTs planifiés — sans aucune action manuelle dans l'interface.

Exemple de scénario — tableau de bord externe en lecture seule

Contexte : Un tableau de bord de direction (PowerBI, Grafana, application maison) doit afficher en temps réel l'état d'avancement de tous les engagements en cours et les alertes sur les EVENTs en retard, sans accès à l'interface be.CLEAR.

Récupérer les ENG en cours (accomplissement entre 1 % et 99 %)

GET /api/eng?status=en_cours&per_page=100
Authorization: Bearer <clé-api-lecteur>

{
  "items": [
    {
      "id": 201, "nom": "Déploiement Acme Corp", "accomplissement": 42.5,
      "nb_events": 6, "date_fin_prevue": "2026-07-15T00:00:00Z",
      "org_principale_nom": "Acme Corp", "env_principale_nom": "Production"
    },
    ...
  ],
  "total": 14
}

Récupérer les EVENTs en retard

GET /api/event/overdue
Authorization: Bearer <clé-api-lecteur>

[
  { "id": 88, "nom": "Recette technique", "eng_id": 201,
    "date_heure_prevue": "2026-05-20T09:00:00Z", "est_accompli": false }
]

Interroger le système en langage naturel (RAG)

POST /api/rag/query
Authorization: Bearer <clé-api-lecteur>
Content-Type: application/json

{ "question": "Quels engagements impliquant Acme Corp sont en retard ?" }

{
  "reponse": "Deux engagements impliquant Acme Corp ont des EVENTs en retard : ...",
  "sources": [{ "type": "eng", "id": 201, "nom": "Déploiement Acme Corp" }]
}

Le tableau de bord se rafraîchit en interrogeant ces trois endpoints à intervalle régulier — aucune synchronisation de base de données, aucun accès direct au backend.

MCP — Intégration Claude Desktop

be.CLEAR expose un serveur MCP (Model Context Protocol) qui permet à Claude Desktop d'accéder directement aux données et d'y effectuer des opérations en langage naturel.

Élément	Description
Transport	stdio (Claude Desktop local) ou SSE HTTP (Docker, accès réseau)
Outils lecture	`search`, `rag_query`, `get_org`, `list_orgs`, `get_eng`, `list_engs`, `get_env`, `list_events_due`, `get_overdue_events`
Outils écriture	`create_event`, `mark_event_done`, `update_value` (rôle EDITEUR requis)
Ressources	`beclear://orgs`, `beclear://envs`, `beclear://org/{id}`, `beclear://eng/{id}/gantt`
Prompts	10 gabarits prédéfinis : `briefing_org`, `avancement_eng`, `jalons_semaine`, `engs_en_retard`, `historique_interactions`, `onboarding_eng`, `rapport_activite_org`, `comparaison_orgs`, `suivi_env`, `diagnostic_obj`
Sécurité	Authentification par token API be.CLEAR — droits ROLE respectés — écritures tracées dans le LOG

Démarrage rapide

Créer un token API dans Administration → Tokens
Ajouter la configuration dans ~/Library/Application Support/Claude/claude_desktop_config.json :

{
  "mcpServers": {
    "beclear": {
      "command": "python3",
      "args": ["/chemin/vers/backend/mcp_server.py"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@localhost:5432/beclear",
        "SECRET_KEY": "<SECRET_KEY>",
        "BECLEAR_API_TOKEN": "<token>",
        "BECLEAR_API_URL": "http://localhost:8000"
      }
    }
  }
}

Redémarrer Claude Desktop — l'icône 🔌 confirme la connexion

Mode Docker (accès réseau) : docker compose --profile mcp up → SSE sur :8001

→ Documentation complète : design/architecture/mcp-serveur.md

Webhooks — notifications HTTP sortantes

be.CLEAR peut notifier en push des systèmes tiers à chaque événement métier (création/modification/suppression d'ENG, EVENT, ORG, ENV, fusion, etc.) — alternative au polling pour les intégrations temps réel (WUDD.ai, n8n, Make, automates internes).

Élément	Description
CRUD	`/api/webhook` — création, liste, mise à jour, suppression (ADMIN)
Événements	15 événements supportés (`eng.created/updated/deleted`, `event.created/updated/deleted/done`, `env.created/updated/deleted/merged`, `org.created/updated/deleted/merged`)
Signature	`X-BeClear-Signature: sha256=<hmac>` — HMAC-SHA256 du body avec un secret partagé (généré à la création, retourné une seule fois)
Headers	`X-BeClear-Event` (nom événement), `X-BeClear-Webhook-Id` (identifiant du webhook)
Retry	3 tentatives avec backoff exponentiel (0.5 s, 1 s, 2 s)
Diagnostic	`last_triggered_at`, `last_status`, `last_error` visibles dans l'admin

Démarrage rapide — Webhooks

Administration → Webhooks → + Nouveau webhook
Saisir l'URL réceptrice + sélectionner les événements (groupés par préfixe)
Copier le secret affiché (visible uniquement à la création — il est hashé en base)
Vérifier la signature côté récepteur :

import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(request.headers["X-BeClear-Signature"], expected)

→ Documentation complète : design/functional/operations-en-masse-et-extensions.md

Terminal IA

Élément	Description
Type	Interface RAG (Retrieval-Augmented Generation)
Usage	Requêtes en langage naturel sur les données du système
Périmètre RAG	Données structurées (ORG, ENV, ENG, EVENT, OBJ, VALUE, PROP) + texte extrait des DOC attachés (PDF text-natif, .docx, .md) — IMG et PDF scannés sans OCR exclus
LLM	Ollama (local) par défaut, ou LLM distant configuré, ou Euria/Infomaniak via toggle « Use Euria » par requête
Mémoire	Chat persistant côté navigateur (localStorage, 30 derniers messages) + mémoire conversationnelle (4 derniers messages envoyés au LLM)
Observabilité	Journal `rag_log` complet + feedback 👍/👎 par message + `GET /api/rag/stats` (ADMIN)

CONFIG — Configuration globale de l'application

Paramètre	Description
Vault Obsidian	Chemin vers le coffre pour l'export RPT
LLM distants	0..n fournisseurs configurables (Claude, OpenAI, etc.) — traitements complexes
LLM local	0..1 modèle local — traitements légers, économie de tokens

RPT — Rapport d'activité

Élément	Description
Portée	Générable pour chaque ORG ou ENV
Contenu	Activité de l'entité : ENGs et EVENTs associés avec leurs données et les images (IMG) de chaque élément
Format	Markdown
Déclenchement	À la demande uniquement (manuel)
Stockage externe	Filesystem local ou coffre Obsidian (vault) — connexion configurée au niveau de l'application

Contraintes architecturales

Contrainte	Description
Performance	La vitesse d'accès est primordiale. Des dénormalisations ciblées seront envisagées lors de la conception du modèle de données pour les chemins d'accès critiques, malgré la structure normalisée.
Déploiement	Docker — chaque service containerisé. Docker Compose pour l'orchestration locale. Compatible Kubernetes pour la montée en charge.
Portabilité	Stack 100% open source, auto-hébergeable, aucune dépendance à un cloud provider spécifique.

Concepts fondamentaux

Partie "Activité"

Concept	Description
ORG	Organisation utilisatrice — typée par 1 TORG à la fois (peut changer dans le temps) — possède 0..n USER
ENV	Environnement de l'ORG — typé par 1 TENV à la fois (peut changer dans le temps)
ENG	Engagement — interaction entre 1..n ORG et 1..n ENV — typé par 1 TENG — dates début/fin prévues et effectives — composé de 1..n EVENT séquentiels — état d'accomplissement et date de fin prévue calculés à partir des EVENTs — visualisable en diagramme Gantt Mermaid
EVENT	Unité atomique d'un ENG — typé par 1 TEVENT — appartient à exactement 1 ENG — possède une `date_heure` (détermine l'ordre) — durée prévue par défaut héritée du TEVENT — date suggérée automatiquement à la création
USER	Acteur du système — typé par 1 TUSER (nature) — possède 1 ROLE (permission) — relié à 1 OBJ — USER humain : rattaché à 1 ORG + 1 identifiant auth externe — USER non-humain : sans ORG
TUSER	Type d'USER — liste plate — nature : humain, système, cron, IA... — classificateur uniquement, pas de CLA associée
ROLE	Niveau de permission des USER humains : ADMIN, EDITEUR, LECTEUR — USER non-humains hors système de ROLE, agissent en ADMIN, tracés dans LOG
TORG	Type d'ORG — arborescence hiérarchique — tout nœud valide — appartient à 1 CLA
TENV	Type d'ENV — arborescence hiérarchique — tout nœud valide — appartient à 1 CLA
TENG	Type d'ENG — liste plate — appartient à 1 CLA
TEVENT	Type d'EVENT — liste plate — appartient à 1 CLA — porte la durée prévue par défaut (valeur + unité : secondes, minutes, heures, jours, mois...)

Partie "Objet"

Concept	Description
OBJ	Instance — chaque ORG, ENG, ENV, EVENT et USER est relié à exactement 1 OBJ — porte les VALUE pour toutes les PROP (propres + héritées) de sa CLA — peut avoir 0..n IMG et 0..n DOC
IMG	Image attachée à un OBJ — 0..n par OBJ — 1 désignée comme image principale
DOC	Document attaché à un OBJ — 0..n par OBJ — format Markdown (préférentiel) ou Microsoft Office
CLA	Classe — définit un schéma de PROP — peut hériter d'une super-classe — possède 0..n PROP propres (0 PROP = étiquette typologique pure) — possède un texte de comportement (Markdown) et un visuel (icône ou image)
PROP	Attribut d'une CLA — hérité par les sous-classes
VALUE	Valeur d'une PROP pour un OBJ — exactement 1 VALUE par PROP (propre ou héritée) par OBJ

Fondement : OOP classique — CLA = classe, OBJ = instance, PROP = attribut, VALUE = valeur d'attribut, avec héritage de PROP entre CLA (super-classe → sous-classe).

Principe de schéma dynamique : le TYPE d'une entité détermine sa CLA, donc l'ensemble des PROP disponibles, le comportement (Markdown) et le visuel (icône ou image). Les types (TORG, TENV, TENG, TEVENT, TUSER) n'ont pas de visuel propre — ils héritent de celui de leur CLA. L'OBJ porte les VALUE concrètes.

Métadonnées système

Champ	OBJ	Tous les autres éléments
`uid` (UUID universel)	oui	non
`nom` (chaîne)	oui	non
`description` (Markdown)	oui	non
`created_at`	oui	oui
`updated_at`	oui	oui
`created_by` (USER)	oui	oui
`updated_by` (USER)	oui	oui

LOG — Journal des opérations

Toutes les opérations (création, modification, suppression) sur tous les éléments du système sont enregistrées dans un journal LOG. Permet de retracer l'historique complet, y compris des éléments supprimés.

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
backend		backend
design		design
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
DESIGN.md		DESIGN.md
Makefile		Makefile
RAPPORT-veille-beclear-setup-2026-05-17.md		RAPPORT-veille-beclear-setup-2026-05-17.md
README.md		README.md
backup.sh		backup.sh
deploy.sh		deploy.sh
docker-compose.yml		docker-compose.yml
restore.sh		restore.sh
start.sh		start.sh
stop.sh		stop.sh

Latest commit

History

Folders and files

Repository files navigation