From bd50a4a54cdb27fa2ed0ba4ca37e4d7d5781f3a6 Mon Sep 17 00:00:00 2001 From: R3D347HR4Y Date: Fri, 22 May 2026 00:50:36 +0200 Subject: [PATCH] Add initial project documentation and workspace configuration - Created CLAUDE.md to outline the vision, architecture, and key features of the Ultimail project, including client and backend responsibilities. - Added a workspace configuration file for easier project management, linking the frontend and backend directories. --- CLAUDE.md | 196 +++++++++++++++++++++++++++ gmail-interface-clone.code-workspace | 11 ++ 2 files changed, 207 insertions(+) create mode 100644 CLAUDE.md create mode 100644 gmail-interface-clone.code-workspace diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..aeb0f25 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,196 @@ +# Ultimail + +Client mail unifié multi-comptes avec backend de synchronisation, frontend web (Next.js) et desktop (Tauri). + +--- + +## Vision & positionnement + +Alternative souveraine à Gmail et Google Suite. L'interface s'inspire fortement de Google pour que les utilisateurs ne soient pas dépaysés et conservent leurs habitudes tout en migrant progressivement leur infrastructure vers cette solution. + +### Objectifs clés + +- **Parité fonctionnelle** — supporter un maximum de fonctionnalités utiles des suites mail existantes (Gmail, Outlook) +- **Au-delà de Gmail** — fonctionnalités de pointe absentes ou limitées chez les géants : connectivité contrôlée avec agents IA, bots, webhooks avancés avec templates +- **Expérience uniforme cross-plateforme** — même UX sur desktop web, desktop app (Tauri) et mobile, avec les détails d'implémentation qui rendent cette uniformité possible +- **Migration progressive** — un utilisateur peut rattacher ses comptes existants et migrer à son rythme + +--- + +## Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ Clients (frontend) │ +│ ├─ Web — Next.js 16 / React 19 (ce repo) │ +│ └─ Desktop — Tauri (wrapper du même frontend) │ +├─────────────────────────────────────────────────────────┤ +│ Backend (futur) │ +│ ├─ Client IMAP/POP3 + SMTP (collecte & envoi) │ +│ ├─ Moteur de règles (tri, forward, réponses auto) │ +│ ├─ Scheduler (envoi programmé, actions différées) │ +│ ├─ API REST/WS pour sync clients │ +│ └─ API tokens fine-grained (agents IA, webhooks) │ +├─────────────────────────────────────────────────────────┤ +│ Database — PostgreSQL │ +│ ├─ Mails + métadonnées complètes + méta Ultimail │ +│ ├─ Identifiants connexion serveurs mail │ +│ ├─ Comptes Ultimail, préférences, libellés, dossiers │ +│ ├─ Règles de tri, webhooks, tokens API │ +│ └─ Auth comptes Ultimail │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## Modèle de domaine + +### Compte Ultimail vs Compte mail + +| Concept | Description | +|---------|-------------| +| **Compte Ultimail** | Compte utilisateur sur la plateforme. Possède préférences, libellés unifiés, règles, auth. | +| **Compte mail** | Connexion SMTP/IMAP ou POP3 vers un serveur/fournisseur. Un compte Ultimail en gère plusieurs. | +| **Identité d'envoi** | Adresse "From" utilisée pour envoyer. Peut différer du compte mail d'envoi (alias, catch-all). | +| **Identité de réception** | Adresse de destination. Peut différer du compte mail de réception (catch-all, routing). | + +### Relations clés + +- 1 compte Ultimail → N comptes mail (envoi et/ou réception) +- 1 compte mail → N identités d'envoi / réception (catch-all, alias) +- Adresse de réception ≠ nécessairement le compte mail de réception (liées mais distinctes) +- Adresse d'envoi ≠ nécessairement le compte mail d'envoi (envoi via un autre serveur) +- Libellés et dossiers unifiés cross-comptes au niveau du compte Ultimail + +--- + +## Backend — Responsabilités (futur) + +### Synchronisation & collecte +- Client IMAP/SMTP permanent (toujours en ligne, même clients offline) +- Collecte des mails de tous les comptes mail rattachés +- Sync bidirectionnelle avec les clients (web/Tauri) +- Configuration unique propagée à tous les clients + +### Règles de tri & automatisations +- Règles de tri à la réception (conditions → actions) +- Envoi programmé (schedule pour le lendemain, etc.) +- Réponses automatiques +- Forward automatique +- Webhooks à la réception selon règles + +### Intégrations IA & programmatiques +- Tri par LLM (fournisseurs OpenAI-compatibles) avec contexte/prompt personnalisé par règle +- Tokens API fine-grained : accès partiel pour agents IA (lire certains mails, envoyer, catégoriser) +- Comportements programmatiques personnalisés par l'utilisateur + +### Stockage (PostgreSQL) +- Mails complets + métadonnées originales + métadonnées Ultimail (libellés, dossiers, statuts) +- Identifiants de connexion aux serveurs mail (chiffrés) +- Réglages comptes Ultimail, préférences d'organisation +- Règles de tri, webhooks, tokens API, auth + +--- + +## Frontend — Responsabilités (actuel) + +### Web (Next.js 16 — ce repo) +- Interface mail complète (liste, lecture, composition, recherche, contacts) +- Navigation URL-driven (`/mail/{folder}`, `/mail/search`, `/contacts`) +- État persisté côté client (Zustand + localStorage) — sera remplacé par sync backend +- Mock data actuellement (`lib/email-data.ts`, `lib/contacts/mock-data.ts`) + +### Desktop (Tauri — futur) +- Même frontend wrappé dans Tauri +- Accès natif (notifications, raccourcis système, stockage local) + +--- + +## Réglages & règles + +Tous les réglages sont gérables depuis l'interface settings d'Ultimail : + +### Niveaux de configuration +- **Global** (compte Ultimail) — libellés unifiés, préférences d'affichage, densité, thème +- **Par identité mail** — signature, nom affiché, réponse par défaut, règles spécifiques + +### Types de règles +- Tri automatique (conditions sur expéditeur, sujet, contenu → libellé, dossier, archive) +- Forward automatique +- Réponse automatique +- Envoi programmé +- Webhook (POST vers URL externe à la réception) +- Tri IA (prompt + contexte personnalisé, fournisseur LLM configurable) +- Actions API (tokens fine-grained pour agents externes) + +### Webhooks — système de templates + +Les webhooks supportent un format de payload personnalisable via templates réutilisables. + +Principe : l'utilisateur définit un template (ex: "Slack", "Discord", "Custom") qui décrit le JSON à envoyer, avec des variables interpolées depuis le mail déclencheur. + +``` +Variables disponibles (exemples) : + $sender.name, $sender.email + $subject + $body.textContent, $body.htmlContent + $date, $timestamp + $recipients.to, $recipients.cc + $attachments.count, $attachments.names + $labels, $folder + $account.email (identité de réception) +``` + +Exemple — template Slack : +```json +{ + "text": "Nouveau mail de $sender.name", + "blocks": [ + { + "type": "section", + "text": { "type": "mrkdwn", "text": "*$subject*\nDe: $sender.email\n$body.textContent" } + } + ] +} +``` + +Cela permet de brancher n'importe quel service (Slack, Discord, n8n, Make, custom) sans code, juste en adaptant le template JSON et l'URL du webhook. + +--- + +## Stack technique (actuel) + +| Couche | Choix | +|--------|-------| +| Framework | Next.js 16 (App Router, standalone) | +| UI | React 19, TypeScript 5.7 | +| Styles | Tailwind CSS 4, shadcn/ui (Radix, style new-york) | +| État | Zustand 5 (persist JSON debounced) | +| Éditeur riche | TipTap 3 | +| Icônes | @iconify/react, lucide-react | +| Recherche client | fuse.js | +| Package manager | pnpm | +| Deploy | Docker multi-stage → Node 22 Alpine, CapRover | + +--- + +## Conventions + +### Navigation +- URL = source de vérité (dossier, onglet inbox, page, message ouvert) +- `useMailRoute` + `lib/mail-url.ts` pour parsing/building +- Recherche via query params sur `/mail/search` + +### Stores (Zustand) +- Persistés : mail-store, mail-settings-store, nav-store, account-store, scheduled-store +- Éphémères : mail-search-store, mail-ui-store +- Ne pas persister l'UI éphémère sauf besoin produit explicite + +### Composants (`components/gmail/`) +- Organisation par feature : `compose/`, `email-list/`, `email-view/`, `sidebar/`, `mail-search/`, `contacts/` +- Re-exports publics à la racine (`email-list.tsx` → `email-list/`) +- Hooks dédiés par domaine dans chaque feature + +### Docs internes +- `components/gmail/README.md` — arborescence composants +- `lib/stores/README.md` — architecture stores diff --git a/gmail-interface-clone.code-workspace b/gmail-interface-clone.code-workspace new file mode 100644 index 0000000..224f0a2 --- /dev/null +++ b/gmail-interface-clone.code-workspace @@ -0,0 +1,11 @@ +{ + "folders": [ + { + "path": "." + }, + { + "path": "../ulti-backend" + } + ], + "settings": {} +} \ No newline at end of file