Elicia AI

1. Explication du projet

Elicia AI est une solution SaaS orientée immobilier qui automatise la relation commerciale avec les prospects grâce à un agent vocal IA (Retell). L’application permet de :

• centraliser les leads, les appels, les biens, les rendez-vous et les tâches ;
• lancer des appels sortants automatisés enrichis du catalogue de propriétés ;
• importer des données (CSV, scraping web) pour alimenter le CRM ;
• suivre l’activité via un tableau de bord analytique.

Le dépôt est structuré en monorepo avec deux applications Next.js indépendantes :

Le CRM constitue le cœur fonctionnel ; le site marketing acquiert et oriente les visiteurs vers la connexion à l’application (Sign In → CRM).

2. Objectif de la solution

Problème adressé

Les agences immobilières reçoivent de nombreux leads mais manquent souvent de temps pour les rappeler rapidement, les qualifier correctement et relier chaque conversation au bon bien. Les données sont dispersées (CRM, feuilles Excel, portails d’annonces) et le suivi des appels reste manuel.

Objectifs métier

1. Réactivité — Contacter chaque nouveau lead sans délai grâce à l’IA vocale.
2. Qualification — Structurer les informations collectées pendant l’appel (budget, critères, disponibilités).
3. Centralisation — Unifier leads, appels, biens et meetings dans une seule interface.
4. Productivité — Réduire le temps passé sur la prospection téléphonique répétitive.
5. Pilotage — Visualiser les KPIs (appels, leads actifs, rendez-vous, stock de biens).

Résultat attendu

Une agence peut traiter plus de prospects avec la même équipe, tout en conservant une traçabilité complète des échanges et un contexte immobilier injecté automatiquement dans les conversations IA.

3. À qui s’adresse cette solution ?

Utilisateurs principaux

Utilisateurs secondaires

• Prospects / leads — Interagissent via téléphone avec l’agent Retell (pas d’accès direct à l’app).
• Visiteurs du site marketing — Découvrent le produit, demandent une démo.
• Administrateurs techniques — Configuration webhooks Retell, variables d’environnement, déploiement Vercel.

Secteur et contexte

Solution pensée pour le marché immobilier (notamment flux d’annonces type portails régionaux, ex. scraping orienté Émirats / DrivenProperties via Firecrawl). Le positionnement marketing met l’accent sur l’automatisation 24/7, la qualification et la prise de rendez-vous.

4. Fonctionnalités

4.1 Application CRM (racine)

Tableau de bord (/dashboard, page d’accueil /)

• Cartes KPI : total d’appels, leads actifs, meetings planifiés, nombre de biens.
• Filtres par période (jour, semaine, mois, trimestre, année).
• Graphiques et indicateurs de tendance.
• Liens rapides vers les modules principaux.

Leads (/leads)

• CRUD complet (création, édition, suppression, consultation).
• Statuts de qualification (new, contacted, etc.) et sources (website, referral, …).
• Recherche, filtres et tableau paginé.
• Import CSV de leads.
• Lien avec les appels (identifiant lead transmis à Retell).

Appels (/calls)

• Historique des appels depuis Supabase (calls_unified).
• Détails : contact, direction, statut, durée, enregistrement, notes, issue.
• Création d’appel sortant via API Retell (POST /api/calls).
• Injection du contexte : catalogue de propriétés envoyé dans les métadonnées de l’appel pour que l’agent IA réponde avec connaissance du stock.
• Réception des événements Retell via webhook (/api/webhook) : call_ended, call_analyzed, synchronisation Supabase.

Biens immobiliers (/properties)

• Listing, ajout et édition de propriétés.
• Champs riches : référence, type, statut, prix, surface, chambres, parking, features, images.
• Import automatique par scraping (API /api/firecrawl + service Firecrawl) depuis une URL d’annonce.
• Galerie d’images pour la présentation des biens.

Meetings (/meetings)

• Gestion des rendez-vous liés aux leads.
• CRUD et import CSV.
• Synchronisation avec Supabase.

Tâches (/tasks)

• Module de suivi des tâches opérationnelles (complément au pipeline commercial).

Upload (/upload)

• Import massif de données (CSV) pour leads, appels ou meetings.
• Indicateur de progression (UploadProgress).

Démo (/demo)

• Configuration et test des webhooks Retell (WebhookSetup).
• Démonstration de recherche de propriétés pendant un appel (PropertySearchDemo).

Authentification (pages prévues)

• /login, /sign-up, /forgot-password — Parcours d’authentification (RBAC en cours d’implémentation selon la roadmap).

Paramètres (/settings)

• Configuration utilisateur et préférences applicatives.

4.2 Site marketing (/marketing)

• Page d’accueil : hero, carrousel de logos, onglets « How it works » (Automate / Qualify / Book), bénéfices chiffrés, cas d’usage, témoignages, FAQ.
• Demande de démo (/demo-request) : formulaire de contact commercial.
• Documentation produit (/docs) : contenu informatif.
• Redirection Sign In vers l’application CRM.

4.3 Fonctionnalités en cours ou à venir

Détail du suivi : voir docs/FONCTIONNALITES.md et docs/PRD.md.

5. Éléments techniques

5.1 Stack technologique

5.2 Architecture logicielle

┌─────────────────────────────────────────────────────────────┐
│                     Navigateur (client)                      │
│  Pages React (app/*) + composants UI + hooks métier           │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│              Next.js — Route Handlers (app/api/*)            │
│  /api/calls  /api/webhook  /api/firecrawl                    │
└───────┬─────────────────┬─────────────────┬───────────────┘
        │                 │                 │
        ▼                 ▼                 ▼
   Supabase          Retell API        Firecrawl API
   (leads, calls,    (appels vocaux)   (scraping annonces)
    properties,
    meetings)

Organisation du code CRM :

• app/ — Pages et routes API (App Router).
• app/components/ — Layout (DashboardLayout, Sidebar), cartes, graphiques, design system (ui/Button, Table, Modal, …).
• app/services/ — Accès données (Supabase, localStorage fallback, mappers, CSV, Firecrawl, contexte propriétés).
• app/config/ — Configuration Retell (webhook, agent).
• Hooks par module : useLeadStorage, useCallApi, useDashboardData, useMeetingStorage, usePropertyStorage.

Principe de sécurité : les clés sensibles (RETELL_API_KEY, SUPABASE_SERVICE_ROLE_KEY, FIRECRAWL_API_KEY) sont utilisées uniquement côté serveur (Route Handlers). Les webhooks Retell sont vérifiés par signature (Retell.verify) en production.

5.3 Modèle de données (Supabase)

Tables principales identifiées dans le code :

5.4 Intégrations externes

Retell AI

• Création d’appels téléphoniques sortants (createPhoneCall).
• Variables : RETELL_API_KEY, RETELL_AGENT_ID, RETELL_FROM_NUMBER.
• Webhook : POST /api/webhook pour persister fin d’appel et analyses.
• Métadonnées d’appel : lead_id, customer_name, properties_context (JSON du stock).

Firecrawl

• POST /api/firecrawl : scrape d’une URL d’annonce → parsing HTML → insertion propriété.
• Paramètres régionaux (ex. country: 'ae') pour les portails ciblés.

Supabase

• Client serveur dans les API routes avec SUPABASE_SERVICE_ROLE_KEY.
• Client partagé dans app/services/supabaseClient.ts pour les opérations applicatives.

5.5 Structure du dépôt

elicia-ai/
├── app/                    # CRM Next.js (pages + API)
├── marketing/              # Site vitrine Next.js
├── docs/                   # PRD, fonctionnalités, déploiement
├── public/                 # Assets (logos Elicia, images)
├── DOCUMENTATION-PROJET.md # Ce document
├── package.json            # Dépendances CRM
├── next.config.ts
├── .env.local              # Variables locales (non versionné)
└── README.md

5.6 Scripts et démarrage local

CRM (racine) :

npm install
npm run dev          # http://localhost:3000
npm run build
npm run start

Site marketing :

cd marketing
npm install
npm run dev          # http://localhost:3001 (si 3000 occupé)

6. Synthèse

Elicia AI est une réalisation full-stack moderne (Next.js 15, React 19, Supabase, IA vocale) qui répond à un besoin concret du secteur immobilier : automatiser et structurer la prospection téléphonique tout en gardant le contrôle sur les données métier. Le projet combine une application CRM riche, des intégrations IA et scraping, et une présence marketing dédiée — ensemble déployable de façon indépendante sur Vercel.

Pour aller plus loin : docs/PRD.md, docs/FONCTIONNALITES.md, README.md.