Documentation Technique - Projet Crystal
Cette documentation technique détaille l'architecture, les flux de données et les cas d'utilisation du système Crystal, plateforme de recensement et de mise en relation des entrepreneurs en Côte d'Ivoire.
Le projet Crystal s'inscrit dans une démarche nationale visant à digitaliser l'écosystème entrepreneurial ivoirien et faciliter les interactions entre entrepreneurs et partenaires financiers.
Présentation du projet
Le projet Crystal est une initiative portée par Mafa Holding et PDE.CI pour:
- Identifier et répertorier l'ensemble des entrepreneurs du territoire
- Structurer et formaliser le secteur entrepreneurial
- Faciliter l'accès aux services administratifs pour les entrepreneurs
- Connecter les entrepreneurs avec des opportunités de financement
Le projet s'articule autour de plusieurs composants interconnectés, formant un écosystème complet de gestion des données entrepreneuriales.
Objectifs du projet
L'objectif principal est de créer un hub connectant entrepreneurs et partenaires financiers, avec les sous-objectifs suivants:
- Permettre aux entrepreneurs ayant donné leur consentement d'être visibles pour les institutions financières
- Faciliter l'accès au financement pour les entrepreneurs
- Offrir aux partenaires financiers un accès à un vivier d'entrepreneurs qualifiés
- Créer un système de qualification et de complétion des dossiers entrepreneurs
Les systèmes existants
L'écosystème actuel repose sur trois systèmes distincts:
Système de recensement MAPHA
Application permettant aux agents de collecter les informations des entrepreneurs directement sur le terrain. Cette application est gérée par MAPHA et la Côte d'Ivoire.
Application Inspector (NEIBA)
Application mobile utilisée par les inspecteurs pour vérifier les données collectées, notamment l'activation des cartes entrepreneurs, la capture GPS, et la mise à jour d'informations.
Plateforme PDE.CI
Interface web permettant aux entrepreneurs de consulter leurs informations, télécharger leur attestation d'entrepreneur, et donner leur consentement au partage de données.
Architecture Générale
Le système Crystal est conçu selon une architecture multi-couches:
1. Couche d'interface utilisateur
- Applications web pour administrateurs et partenaires financiers
- Application mobile Inspector V2 pour les agents terrain
- Interfaces API pour l'intégration avec PDE.CI
2. Couche métier
- Services de gestion des entrepreneurs
- Services de qualification et d'évaluation
- Services de gestion des partenaires
- Services de gestion des activités terrain
3. Couche de données
- Base de données PostgreSQL pour stockage structuré
- Système de fichiers pour documents
4. Couche d'intégration
- API RESTful pour communication avec PDE.CI
- Connecteurs pour intégration avec services partenaires
- Webhooks pour notifications asynchrones
5. Architecture du code source
L'analyse du code source révèle une organisation structurée en modules fonctionnels :
- Controllers - Points d'entrée API organisés par domaine :
- admin/ - Gestion des administrateurs et configurations
- security/ - Authentification et autorisation
- enterprise/ - Gestion des partenaires financiers
- external/ - Intégration avec systèmes externes (PDE)
- Core - Noyau fonctionnel avec :
- business/ - Logique métier
- services/ - Services applicatifs
- database/ - Accès aux données (models, repositories, etc.)
- models/ - Modèles partagés
- requests/ - DTOs pour les requêtes
- exceptions/ - Gestion d'erreurs
- configs/ - Configuration applicative
- filestorage/ - Gestion du stockage de fichiers
- Utilities - Fonctions utilitaires partagées
Modèle de Données
Le schéma de base de données est structuré autour des entités principales suivantes:
Utilisateurs et Comptes
Gestion des utilisateurs du système avec différents rôles et privilèges.
Tables principales: account, person, administrator, field_agent
Relations clés: account -> person -> (administrator|field_agent)
Entrepreneurs et PDE
Données des entrepreneurs importées depuis PDE.CI après consentement.
Tables principales: pde_entrepreneur, pde_entrepreneur_enterprise_relation
Relations clés: pde_entrepreneur -> activity_sector, sector
Entreprises Partenaires
Entreprises offrant des services financiers aux entrepreneurs.
Tables principales: enterprise, enterprise_service, account_enterprise_access
Relations clés: enterprise -> enterprise_service, account_enterprise_access
Activités Terrain
Suivi des activités des agents terrain et des interactions avec les entrepreneurs.
Tables principales: field_visit, entrepreneur_activity, activity_document
Relations clés: field_agent -> field_visit -> entrepreneur_form_response
Géographie et Localisation
Données géographiques pour l'organisation territoriale.
Tables principales: sub_prefecture, commune, neighborhood, sector
Hiérarchie: sub_prefecture -> commune -> neighborhood -> sector
Structure de Données Détaillée
Le schéma utilise plusieurs types de données spécialisés pour garantir l'intégrité:
- Énumérations: process_status, activity_status, enterprise_type, etc.
- Contraintes d'intégrité: Vérifications des emails, numéros de téléphone, etc.
- Fonctions utilitaires: Validation, formatage et transformations de données
Composants du Système
1. Back-Office Administrateur
Interface de gestion centralisée pour les administrateurs système, permettant:
- L'onboarding des partenaires financiers
- La gestion des utilisateurs et permissions
- Le monitoring de l'activité système
- La configuration des paramètres globaux
2. Back-Office Partenaire
Tableau de bord personnalisable (marque blanche) pour chaque partenaire financier:
- Visualisation des entrepreneurs disponibles
- Gestion des agents terrain
- Suivi des activités de qualification
- Gestion des services financiers proposés
3. Application Mobile Inspector V2
Application terrain utilisée par les agents des partenaires financiers:
- Localisation géographique des entrepreneurs
- Collecte d'informations complémentaires
- Qualification des entrepreneurs
- Capture de documents et pièces justificatives
4. Interfaces API
Ensemble d'API sécurisées pour l'intégration système:
- API de réception des données PDE (consentement)
- API d'exposition des entrepreneurs aux partenaires
- API mobile pour synchronisation terrain
- API de notifications et d'événements
5. Système de notifications
Mécanismes de communication pour informer les utilisateurs des événements importants:
- Notifications par email via Quarkus Mailer
- Templates d'emails personnalisables pour les différents événements
- Notifications en temps réel dans les interfaces utilisateur
- Rappels et alertes pour les actions en attente
- Communication bidirectionnelle avec les entrepreneurs (via PDE)
Flux de Recensement
Ce flux représente le processus initial de collecte des données des entrepreneurs:
- Les agents Mafa se déplacent sur le terrain avec l'application de recensement
- Ils collectent les informations des entrepreneurs (identité, activité, localisation)
- Les données sont envoyées au système central Mafa
- Des inspecteurs vérifient les données avec l'application Inspector
- Les données validées sont enregistrées définitivement
- L'entrepreneur reçoit une carte cristal avec son identifiant
Ce flux existe déjà et est géré par MAPHA et la Côte d'Ivoire. Le système Crystal intervient dans les étapes suivantes du parcours.
Flux de Consentement
Ce flux décrit comment les entrepreneurs donnent leur consentement au partage de leurs données:
- L'entrepreneur se connecte à la plateforme PDE.CI avec son identifiant
- Il accède à ses informations et peut télécharger son attestation
- Il est invité à accepter les CGU pour partager ses données
- S'il accepte, PDE.CI appelle l'API Crystal pour transmettre ses données
- Les données sont stockées dans la table pde_entrepreneur
- L'entrepreneur devient visible pour les partenaires financiers
Flux de Qualification
Ce flux détaille comment les entrepreneurs sont qualifiés par les partenaires:
- Le partenaire identifie un entrepreneur potentiellement intéressant dans son tableau de bord
- Un agent terrain est assigné pour le rencontrer
- L'agent utilise l'application Inspector V2 pour localiser l'entrepreneur
- Il collecte des informations complémentaires via des formulaires spécifiques
- Il évalue l'intérêt et le potentiel de l'entrepreneur
- Les données collectées sont synchronisées avec le système central
- Une relation est établie entre l'entrepreneur et l'entreprise (pde_entrepreneur_enterprise_relation)
Flux de Services Financiers
Ce flux illustre comment les services sont proposés aux entrepreneurs:
- Une fois qualifié, l'entrepreneur peut se voir proposer des services adaptés
- L'agent collecte les documents nécessaires pour le service
- Les documents sont vérifiés et validés dans le back-office
- Le dossier est traité selon les procédures du partenaire financier
- Le statut de la demande est mis à jour dans le système
- L'entrepreneur peut être recontacté pour finaliser la prestation
Cas d'utilisation: Entrepreneurs
UC-E1: Consentement au partage de données
Acteur principal: Entrepreneur recensé
Description: L'entrepreneur se connecte à PDE.CI et donne son consentement pour partager ses données avec les partenaires financiers.
Préconditions: Entrepreneur déjà recensé et possédant une carte cristal.
Flux principal:
1. L'entrepreneur se connecte à PDE.CI
2. Il accède à la section CGU
3. Il accepte le partage de ses données
4. Ses informations sont transmises au système Crystal
UC-E2: Qualification par un agent partenaire
Acteur principal: Entrepreneur ayant donné son consentement
Description: L'entrepreneur est contacté et qualifié par un agent d'un partenaire financier.
Préconditions: Consentement donné et entrepreneur visible dans le système Crystal.
Flux principal:
1. L'entrepreneur est contacté par un agent
2. Il répond aux questions de qualification
3. Il fournit des informations complémentaires
4. Il exprime son intérêt pour certains services
Cas d'utilisation: Partenaires Financiers
UC-P1: Onboarding d'un nouveau partenaire
Acteur principal: Administrateur système
Description: Enregistrement d'un nouveau partenaire financier dans le système.
Flux principal:
1. L'administrateur crée l'entreprise partenaire
2. Il configure l'accès au back-office
3. Il définit les paramètres de marque blanche
4. Il assigne un administrateur pour le partenaire
UC-P2: Gestion des services financiers
Acteur principal: Staff partenaire
Description: Configuration des services proposés aux entrepreneurs.
Préconditions: Partenaire déjà enregistré et configuré.
Flux principal:
1. Le staff définit les services financiers
2. Il configure les critères d'éligibilité
3. Il crée les formulaires de qualification
4. Il définit les documents requis
UC-P3: Recherche et filtrage d'entrepreneurs
Acteur principal: Staff partenaire
Description: Recherche d'entrepreneurs correspondant à des critères spécifiques.
Flux principal:
1. Le staff accède au back-office
2. Il utilise les filtres (localisation, secteur, taille)
3. Il visualise la liste des entrepreneurs correspondants
4. Il peut exporter les résultats ou assigner des agents
Cas d'utilisation: Administrateurs Système
UC-A1: Gestion des partenaires
Acteur principal: Super Admin
Description: Gestion du cycle de vie des partenaires dans le système.
Flux principal:
1. L'admin peut créer/modifier/désactiver des partenaires
2. Il définit les niveaux d'accès
3. Il supervise l'activité des partenaires
4. Il gère les problèmes d'accès
UC-A2: Monitoring système
Acteur principal: Administrateur système
Description: Surveillance et maintenance du système.
Flux principal:
1. L'admin consulte les tableaux de bord d'activité
2. Il vérifie les logs d'API et d'erreurs
3. Il surveille les performances
4. Il intervient en cas d'anomalie
Cas d'utilisation: Agents Terrain
UC-AG1: Qualification d'entrepreneurs
Acteur principal: Agent terrain
Description: Visite et qualification d'entrepreneurs sur le terrain.
Préconditions: Agent authentifié sur l'application Inspector V2.
Flux principal:
1. L'agent identifie les entrepreneurs à visiter
2. Il les localise sur la carte
3. Il rencontre l'entrepreneur et remplit le formulaire
4. Il évalue l'intérêt et la qualification
5. Il collecte des documents si nécessaire
UC-AG2: Collecte de documents
Acteur principal: Agent terrain
Description: Collecte et soumission de documents justificatifs.
Préconditions: Entrepreneur qualifié et intéressé par un service.
Flux principal:
1. L'agent explique les documents requis
2. Il capture les documents via l'application
3. Il associe les documents au dossier
4. Il synchronise les données avec le système central