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.
This commit is contained in:
R3D347HR4Y
parent
447567a411
commit
bd50a4a54c
196
CLAUDE.md
Normal file
196
CLAUDE.md
Normal file
@ -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
|
||||||
11
gmail-interface-clone.code-workspace
Normal file
11
gmail-interface-clone.code-workspace
Normal file
@ -0,0 +1,11 @@
|
|||||||
|
{
|
||||||
|
"folders": [
|
||||||
|
{
|
||||||
|
"path": "."
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "../ulti-backend"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"settings": {}
|
||||||
|
}
|
||||||
Loading…
Reference in New Issue
Block a user