Urbafix - Documentation Technique¶
v2.0 - Stateless-Ready
⬇️ Télécharger cette page en Markdown
Bienvenue¶
Urbafix est une plateforme de signalement d'incidents urbains permettant aux citoyens de reporter des problèmes dans leur quartier (nids-de-poule, éclairage défaillant, déchets sauvages, etc.) directement à leur municipalité.
Version actuelle
2.1.0 - Production (10 janvier 2026)
Nouveautés v2.1: - ✅ Authentification collectivité (EPCI) - Accès multi-villes - ✅ Dashboard avec carte multi-communes - ✅ Services intercommunaux - ✅ Géocodage automatique des communes - ✅ Gestion des emails invalides (bounces SMTP) - Dashboard superadmin
v2.0: Refactorisation architecturale majeure pour le scaling horizontal
Vue d'ensemble du Système¶
Composants Principaux¶
Stack Technique¶
| Composant | Technologie | Version |
|---|---|---|
| Backend | PHP | 8.2 |
| Web Server | Nginx | 1.24 |
| Base de données | MariaDB | 10.11 |
| Cache/Sessions | Redis | 7 Alpine |
| Application Mobile | Android Kotlin | SDK 34 |
| Cartes | OpenStreetMap | - |
| Containerisation | Docker | 24+ |
Fonctionnalités Principales¶
Pour les Citoyens (App Android)¶
- Signalement géolocalisé : Création d'incidents avec position GPS automatique
- Photos et vidéos : Upload de médias (max 5s pour vidéos)
- Floutage automatique : Anonymisation des visages (RGPD)
- Suivi en temps réel : Notifications de statut
- Mode hors-ligne : Synchronisation différée
- Regroupement intelligent : Détection automatique des doublons
Pour les Municipalités (Backoffice Web)¶
- Dashboard de gestion : Vue d'ensemble des incidents
- Authentification collectivité (EPCI) : Accès multi-villes pour intercommunalités
- Carte multi-communes : Visualisation géographique de toutes les communes membres
- Système de permissions : Filtrage par service municipal
- Services intercommunaux : Gestion EPCI cross-communes
- Traitement par lots : Actions groupées
- Exports de données : CSV, Excel, PDF
- Notifications automatiques : Emails aux services concernés
- Statistiques : Graphiques et métriques
Architecture v2.0¶
Principes Directeurs¶
Stateless-Ready
Architecture refactorisée pour supporter le scaling horizontal avec activation progressive via variables d'environnement.
Caractéristiques :
- Sessions abstraites : Fichiers PHP ou Redis (multi-instances)
- Stockage abstrait : Filesystem local ou S3
- Cache optionnel : Null cache ou Redis
- Queue asynchrone : Sync (immédiat) ou Redis (workers)
- Multi-tenant strict : Isolation complète par
mairie_id - ANSSI-compliant : TLS 1.3, permissions 0755/0644, face blurring RGPD
Couches Applicatives¶
Guides Rapides¶
Installation (Développement)¶
# Cloner le projet
git clone https://github.com/urbafix/urbafix.git
cd urbafix
# Configuration
cp .env.example .env
nano .env # Modifier DB_PASSWORD et autres variables
# Lancer les conteneurs
docker-compose up -d
# Accéder à l'application
http://localhost:8080 # Interface publique
http://localhost:8080/backend # Backoffice admin
Déploiement Production¶
# Configuration production
cp .env.example .env.production
# Modifier TOUS les mots de passe
# APP_ENV=production, APP_DEBUG=false
# Activer Redis
docker-compose --profile redis up -d
# Activer S3 (optionnel)
STORAGE_DRIVER=s3 dans .env
# Reverse proxy HTTPS (voir DEPLOYMENT.md)
Sécurité¶
Conformité ANSSI¶
- ✅ TLS 1.3 obligatoire
- ✅ Permissions fichiers strictes (0755/0644)
- ✅ Sessions sécurisées (HttpOnly, Secure, SameSite=Strict)
- ✅ Prepared statements SQL (anti-injection)
- ✅ Password hashing bcrypt
- ✅ Face blurring RGPD automatique
Multi-Tenant¶
Isolation Critique
Chaque mairie est isolée. Aucune donnée ne doit fuiter entre municipalités.
Mécanismes :
- Filtrage SQL strict par
mairie_id - Validation API par
code_postal→mairie_id - Permissions service-based
- Cache avec préfixe
mairie_id
Roadmap¶
v2.1 (Janvier 2026) ✅¶
- Authentification collectivité (EPCI)
- Dashboard multi-communes
- Services intercommunaux
- Géocodage automatique des communes
v2.2 (Q1 2026) 🚧¶
- Routage automatique par compétences
- Référentiel des compétences métier
- Gestion des organismes (commune, EPCI, syndicat, délégataire)
- Matrice de délégation des compétences
- Attribution automatique des incidents
- Transmission aux prestataires
- Notifications multi-acteurs
Q2 2026¶
- Workers Redis queue (Supervisord)
- Tests automatisés PHPUnit
- Prometheus metrics endpoint
- Migration S3 progressive
Q3 2026¶
- Kubernetes Helm charts
- Distributed tracing (Jaeger)
- Read replicas MariaDB
- Application iOS
Documentation¶
Par Thème¶
| Section | Description |
|---|---|
| Architecture | Architecture globale, modèle de données, flux |
| Infrastructure | Configuration, Docker, déploiement |
| Backend | API REST, services métier, jobs |
| Base de données | Schéma complet, modèle relationnel |
| Backoffice | Interface admin, permissions |
| Android | Architecture MVVM, fonctionnalités |
| Sécurité | Multi-tenant, RGPD, ANSSI |
| Roadmap | Changelogs détaillés |
Support et Contact¶
Ressources¶
- Documentation : Cette documentation MkDocs
- Code source :
/srv/urbafix/ - Fichiers de configuration :
.env,docker-compose.yml
Fichiers Clés¶
CLAUDE.md: Instructions pour l'assistant IAREADME.md: Guide utilisateur complet.env.example: Template de configuration
Statistiques¶
Version 2.0 :
- 42 fichiers créés (interfaces, services, jobs, migrations)
- 12 fichiers modifiés (endpoints sécurisés, config centralisée)
- ~3500 lignes de code ajoutées
- ~2500 lignes de documentation technique
- 100% backward compatible - Fonctionne comme avant par défaut
Navigation
Utilisez le menu latéral pour explorer chaque section. Chaque page propose un lien de téléchargement du fichier Markdown source.