SomtechSolutionMAxime/somcraft

SomCraft — Documentation de référence

SomCraft est un Document Management System (DMS) Markdown-first développé par Somtech Solutions. Ce skill documente son architecture, ses concepts, ses APIs, et les patterns d'exploitation.

Pour la doc spécifique à une instance client déployée, voir le skill somcraft-{client} dans le projet courant (s'il existe).

Vue d'ensemble

Ce que fait SomCraft :

• Éditeur Markdown block-based (BlockNote)
• Gestion de fichiers multi-formats (Markdown, PDF, images, docs)
• Storage et versioning via Supabase
• AI-assisted authoring (Claude : chat, transforms, Studio de génération)
• MCP server pour agents externes
• Export PDF/DOCX
• Multi-tenant via workspaces

Stack technique :

• Frontend : Next.js 15 (App Router), React, TypeScript, Tailwind CSS v4
• Éditeur : BlockNote (wrapper React sur ProseMirror)
• Backend : Supabase (PostgreSQL, Auth, RLS, Storage)
• AI : Anthropic SDK (Claude Sonnet/Opus)
• Export : markdown-it → Puppeteer (PDF), docx library (DOCX)
• Déploiement : Docker sur Fly.io

Structure monorepo :

somcraft/
├── apps/
│   └── web/          # Next.js app principale
│       ├── app/      # Routes App Router
│       ├── lib/      # AI client, export, MCP server
│       └── middleware.ts
├── packages/
│   ├── core/         # Types, Supabase client, constants
│   ├── editor/       # Composant MarkdownEditor + AI Chat + Studio
│   ├── files/        # FileManager + hooks + store Zustand
│   ├── db/           # CLI migrations
│   └── sync/         # Sync engine filesystem ↔ Supabase
└── supabase/
    └── migrations/   # Schema PostgreSQL

Concepts clés

Pour le détail, voir references/concepts.md.

• Workspace — Unité d'isolation multi-tenant. Chaque workspace a son propre storage bucket et ses membres.
• Document — Fichier ou dossier dans un workspace. Stocké en DB (métadonnées) + Supabase Storage (contenu).
• Version — Snapshot historique d'un document (table sc_document_versions).
• Studio — Panneau de génération de documents via pipelines AI multi-étapes (résumé exécutif, présentation, rapport, compte-rendu, proposition d'amélioration).
• MCP Server — Endpoint HTTP qui expose 25 tools pour agents externes (workspaces, lecture/écriture/édition de documents, liens & backlinks, commentaires, génération via Studio, etc.).

Data Model

Pour le détail, voir references/architecture.md.

Tables principales :

• sc_workspaces — id, name, slug, storage_bucket, api_key, created_by
• sc_documents — id, workspace_id, parent_id, type (file|folder), filename, path, storage_key, status, tags, metadata
• sc_document_versions — id, document_id, version_number, storage_key, checksum, created_at
• sc_workspace_members — workspace_id, user_id, role (viewer|editor|admin)
• sc_recent_activity — activity log (viewed|edited|uploaded)

RLS : Toutes les tables sc_* ont des policies basées sur auth.uid() et la membership dans sc_workspace_members.

API REST

Pour le détail, voir references/api-reference.md.

Endpoints principaux (tous sous /api/sc/) :

• GET/POST /api/sc/workspaces — Liste/créer workspaces
• GET/POST /api/sc/documents?workspace_id=X — Liste/créer documents
• GET/PUT /api/sc/documents/{id} — Lire/modifier un document
• GET /api/sc/documents/{id}/content — Contenu Markdown brut
• GET /api/sc/documents/{id}/export?format=pdf — Export PDF/DOCX
• POST /api/sc/ai/chat — Chat avec le document comme contexte
• POST /api/sc/ai/transform — Transformation ponctuelle (résumé, traduction, etc.)
• POST /api/sc/studio/generate — Pipeline Studio (SSE streaming)

Format de réponse : { "data": ... } ou { "data": ..., "next_cursor": ... } pour les listes.

Auth : Bearer token (Supabase JWT) dans le header Authorization, ou cookies Supabase pour les sessions navigateur.

MCP Tools

Pour le détail, voir references/api-reference.md.

Endpoint : POST /api/mcp/mcp avec Authorization: Bearer {api_key} et Accept: application/json, text/event-stream.

25 tools disponibles (SomCraft ≥ v0.21, source : apps/web/lib/mcp-server.ts). Il n'existe pas de move_document.

Documents

• list_workspaces, create_workspace
• list_documents, read_document, write_document, update_document, update_block
• search_documents, autocomplete_documents
• create_folder
• export_document — PDF/DOCX, retourne URL signée
• generate_document — pipeline Studio
• run_custom_command — exécute une commande AI custom

Liens & graphe

• read_backlinks, resolve_links, rewrite_links, preview_link_rename, audit_broken_links

Commentaires / collaboration

• create_comment_thread, read_comment_thread, list_comment_threads, reply_to_thread, set_thread_resolved, find_open_threads

Administration de clé

• regenerate_workspace_api_key

Sécurité

Pour le détail, voir references/security.md.

• RLS par workspace_id sur toutes les tables sc_*
• API keys MCP — 4 types (apps/web/lib/mcp-auth.ts) : clé workspace legacy sk_… (stockée dans sc_workspaces.api_key, format canonique sk_ + 32 [a-z0-9]), clé agent sk_agent_… (registre sc_agents / sc_agent_api_keys, recommandée pour les agents IA), clé utilisateur sk_user_… (sc_user_api_keys), clé admin sk_admin_… (cross-workspace, réservée à l'opérateur)
• Storage policies : chaque bucket est privé, accessible uniquement aux membres du workspace correspondant
• Service role key : uniquement utilisée côté serveur (Edge Functions, export PDF)
• Anon key : pour les clients (sessions auth)

Troubleshooting

Pour le détail, voir references/troubleshooting.md.

Problèmes communs :

• Workspace vide → Vérifier RLS (SELECT * FROM pg_policies WHERE tablename LIKE 'sc_%') et que le user est bien membre
• Studio génère des fichiers vides → Vérifier ANTHROPIC_API_KEY, vérifier les logs du pipeline
• MCP server retourne 401 → Vérifier que l'API key est bien dans sc_workspaces.api_key et qu'elle est passée en Bearer
• Export PDF échoue → Vérifier que Puppeteer est disponible (pas de libs système manquantes sur Fly.io)
• Sync MCP → Vérifier que le MCP server est correctement configuré dans .mcp.json

Opérations courantes

• Créer un nouveau workspace : INSERT dans sc_workspaces + créer bucket storage + INSERT membre admin
• Régénérer une API key : tool MCP regenerate_workspace_api_key, ou UPDATE sc_workspaces SET api_key = 'sk_...' WHERE id = ... (format sk_ + 32 [a-z0-9])
• Voir les documents d'un workspace : SELECT * FROM sc_documents WHERE workspace_id = ? ORDER BY created_at DESC
• Restaurer un document de la corbeille : UPDATE sc_documents SET status = 'active' WHERE id = ? AND status = 'trashed'

Pour des opérations spécifiques à un client déployé, utiliser le skill somcraft-{client} du projet courant.