feat: add smart-app-city sub-project architecture

- Architecture globale (React Native + NestJS + FastAPI) - Beckn Protocol (OTN-DPI) integration docs - AI layer: RAG pipeline + AI Agents (LocalAI + Qdrant) - i18n: FR/EN/ES/DE support - Docker Compose for backend services - Project structure with frontend, backend, ai, beckn directories
2026-05-26 18:47:02 -04:00
parent f1e1b98519
commit 94f74f2dfc
20 changed files with 1013 additions and 0 deletions
--- a/smart-app-city/docs/ARCHITECTURE.md
+++ b/smart-app-city/docs/ARCHITECTURE.md
@@ -0,0 +1,326 @@
+# Smart App City — Architecture & Propositions
+
+> Sous-projet Smart City Digital Twin Martinique
+> Créé le : 2026-05-28
+
+## 1. Vision
+
+Application mobile multi-plateforme (Android/iOS) pour les citoyens de Martinique, couvrant :
+- **Transport** : Info trafic, bus, parking
+- **Environnement** : Qualité de l'air, météo, pollution sonore
+- **Services municipaux** : Démarches, alertes, événements
+- **Tourisme** : Points d'intérêt, itinéraires, réalité augmentée
+- **Citoyen** : Signalements, participations, notifications
+
+**Inspiration** : [SmartAppCity](https://smartappcity.com/en/) — plateforme smart city multi-services.
+
+## 2. Architecture Globale
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        MOBILE APP (React Native)                    │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
+│  │ Transport│ │ Environ. │ │ Services │ │ Tourisme │ │ Citoyen  │ │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
+│       └────────────┴────────────┴────────────┴────────────┘        │
+│                              │                                      │
+│                    ┌─────────┴─────────┐                           │
+│                    │   API Gateway     │                           │
+│                    │   (Kong / Traefik)│                           │
+│                    └─────────┬─────────┘                           │
+└──────────────────────────────┼──────────────────────────────────────┘
+                               │
+┌──────────────────────────────┼──────────────────────────────────────┐
+│                         BACKEND                                     │
+│                              │                                      │
+│  ┌───────────────────────────┴───────────────────────────────────┐  │
+│  │                    Beckn Protocol (OTN-DPI)                    │  │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │  │
+│  │  │   BAP    │ │   BPP    │ │ Beckn    │ │  ONDC    │        │  │
+│  │  │ (Buyer)  │ │ (Seller) │ │ Gateway  │ │ Adapter  │        │  │
+│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                              │                                      │
+│  ┌───────────────────────────┴───────────────────────────────────┐  │
+│  │                      AI / LLM Layer                           │  │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │  │
+│  │  │  RAG     │ │  Agents  │ │  LLM     │ │  NLP     │        │  │
+│  │  │ (Retriev)│ │(Actions) │ │(Generate)│ │(Intent)  │        │  │
+│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                              │                                      │
+│  ┌───────────────────────────┴───────────────────────────────────┐  │
+│  │                    Microservices Backend                       │  │
+│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐     │  │
+│  │  │Auth    │ │Notif.  │ │GIS     │ │IoT     │ │Analytics│    │  │
+│  │  │Service │ │Service │ │Service │ │Service │ │Service │     │  │
+│  │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘     │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                              │                                      │
+│  ┌───────────────────────────┴───────────────────────────────────┐  │
+│  │                      Data Layer                                │  │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │  │
+│  │  │PostgreSQL│ │ InfluxDB │ │  Redis   │ │  MinIO   │        │  │
+│  │  │  (Users) │ │  (IoT)   │ │ (Cache)  │ │  (Files) │        │  │
+│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## 3. Frontend — React Native
+
+### Stack Technique
+| Composant | Technologie | Justification |
+|-----------|-------------|---------------|
+| **Framework** | React Native + Expo | Cross-platform, hot reload, large communauté |
+| **State Management** | Zustand + React Query | Léger, performant, cache intelligent |
+| **Navigation** | React Navigation v6 | Standard React Native |
+| **UI Kit** | React Native Paper + Tamagui | Material Design + performance |
+| **Maps** | react-native-maps + MapBox | Cartographie interactive |
+| **i18n** | i18next + react-i18next | Multi-langue (FR, EN, ES, DE) |
+| **Notifications** | Firebase Cloud Messaging | Push notifications cross-platform |
+| **Offline** | WatermelonDB + SQLite | Mode hors-ligne essentiel |
+| **Auth** | OAuth2 + Keychain | Sécurité des credentials |
+
+### Écrans Principaux
+1. **Dashboard** — Vue d'ensemble temps réel (météo, trafic, alertes)
+2. **Carte interactive** — Points d'intérêt, capteurs, événements
+3. **Transport** — Itinéraires, horaires bus, disponibilité parking
+4. **Signalement** — Photo + géolocalisation + catégorisation
+5. **Services** — Démarches administratives, RDV, formulaires
+6. **Profil** — Paramètres, langue, notifications
+
+## 4. Backend — Microservices
+
+### Stack Technique
+| Composant | Technologie | Justification |
+|-----------|-------------|---------------|
+| **Runtime** | Node.js (NestJS) + Python (FastAPI) | NestJS pour l'API, FastAPI pour l'IA |
+| **API Gateway** | Kong ou Traefik | Routage, rate limiting, auth |
+| **Auth** | Keycloak (existant) | SSO, OAuth2, multi-tenant |
+| **Message Queue** | RabbitMQ (existant) | Async communication |
+| **Cache** | Redis (existant) | Sessions, rate limiting |
+| **Search** | Meilisearch | Recherche full-text rapide |
+| **Storage** | MinIO (S3-compatible) | Fichiers, images, documents |
+
+### Microservices
+1. **Auth Service** — Authentification, rôles, permissions (Keycloak)
+2. **User Service** — Profils, préférences, historique
+3. **Notification Service** — Push, SMS, email (multi-canal)
+4. **GIS Service** — Données géospatiales, itinéraires (PostGIS)
+5. **IoT Service** — Ingestion données capteurs (InfluxDB)
+6. **Reporting Service** — Signalements, suivi, analytics
+7. **Translation Service** — i18n côté serveur
+
+## 5. Beckn Protocol (OTN-DPI)
+
+### Intégration
+Le Beckn Protocol permet l'interopérabilité avec les services externes (transport, commerce, administration).
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  Mobile App │────▶│  Beckn BAP  │────▶│  Beckn GW   │
+│  (Buyer)    │◀────│  (Backend)  │◀────│  (OTN)      │
+└─────────────┘     └─────────────┘     └──────┬──────┘
+                                               │
+                                        ┌──────┴──────┐
+                                        │  Beckn BPP  │
+                                        │  (Sellers)  │
+                                        │  - Transport│
+                                        │  - Commerce │
+                                        │  - Admin    │
+                                        └─────────────┘
+```
+
+### Cas d'usage Beckn
+- **Transport** : Recherche/réservation de trajets (bus, covoiturage)
+- **Commerce local** : Découverte de commerces, commandes
+- **Services publics** : RDV mairie, demandes de documents
+- **Tourisme** : Réservation d'activités, guides
+
+## 6. AI / LLM Layer
+
+### Architecture AI
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        AI Layer                              │
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │                   LLM (LocalAI / Ollama)              │   │
+│  │  - Modèle : Llama 3.1 70B ou Mistral 7B             │   │
+│  │  - API : OpenAI-compatible                           │   │
+│  │  - Hébergement : LocalAI container (existant)        │   │
+│  └──────────────────────────────────────────────────────┘   │
+│                          │                                   │
+│  ┌───────────────────────┴───────────────────────────────┐   │
+│  │                    RAG Pipeline                        │   │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐             │   │
+│  │  │ Embedding│ │ Vector   │ │ Retriever│             │   │
+│  │  │ (E5)     │ │ (Qdrant) │ │ (Hybrid) │             │   │
+│  │  └──────────┘ └──────────┘ └──────────┘             │   │
+│  └───────────────────────────────────────────────────────┘   │
+│                          │                                   │
+│  ┌───────────────────────┴───────────────────────────────┐   │
+│  │                   AI Agents                            │   │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐             │   │
+│  │  │ Transport│ │ Tourisme │ │ Services │             │   │
+│  │  │ Agent    │ │ Agent    │ │ Agent    │             │   │
+│  │  └──────────┘ └──────────┘ └──────────┘             │   │
+│  └───────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Cas d'usage AI
+1. **Chatbot citoyen** — Réponses aux questions (RAG sur documents municipaux)
+2. **Recommandations** — Activités, restaurants, événements personnalisés
+3. **Prédictions** — Trafic, qualité de l'air, affluence
+4. **Analyse signalements** — Classification automatique, priorisation
+5. **Traduction temps réel** — Conversations multilingues
+
+## 7. Multi-Langue (i18n)
+
+### Langues supportées
+| Langue | Code | Priorité |
+|--------|------|----------|
+| Français | fr | 1 (principal) |
+| English | en | 2 |
+| Español | es | 3 |
+| Deutsch | de | 4 |
+
+### Architecture i18n
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    i18n Pipeline                             │
+│                                                              │
+│  Frontend (React Native)          Backend (NestJS)          │
+│  ┌─────────────────────┐         ┌─────────────────────┐   │
+│  │ i18next + ICU       │         │ nestjs-i18n         │   │
+│  │ Format.js           │         │ Accept-Language     │   │
+│  │ Pluralization       │         │ Content negotiation │   │
+│  └─────────────────────┘         └─────────────────────┘   │
+│                          │                                   │
+│  ┌───────────────────────┴───────────────────────────────┐   │
+│  │              Translation Management                    │   │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐             │   │
+│  │  │ Crowdin  │ │ LLM      │ │ Manual   │             │   │
+│  │  │ (Sync)   │ │ (Auto)   │ │ (Review) │             │   │
+│  │  └──────────┘ └──────────┘ └──────────┘             │   │
+│  └───────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 8. Infrastructure & Déploiement
+
+### Conteneurs Docker
+```yaml
+# docker-compose.smart-app.yml
+services:
+  # Frontend (dev server)
+  mobile-web:
+    build: ./frontend
+    ports: ["8081:8081"]
+    
+  # Backend API
+  api-gateway:
+    image: kong:3.5
+    ports: ["8000:8000"]
+    
+  auth-service:
+    build: ./backend/auth
+    depends_on: [keycloak]
+    
+  gis-service:
+    build: ./backend/gis
+    depends_on: [postgis]
+    
+  iot-service:
+    build: ./backend/iot
+    depends_on: [influxdb]
+    
+  notification-service:
+    build: ./backend/notification
+    depends_on: [rabbitmq]
+    
+  # AI Services
+  rag-service:
+    build: ./ai/rag
+    depends_on: [localai, qdrant]
+    
+  agent-service:
+    build: ./ai/agents
+    depends_on: [localai]
+    
+  # Data
+  qdrant:
+    image: qdrant/qdrant:latest
+    ports: ["6333:6333"]
+    
+  meilisearch:
+    image: getmeili/meilisearch:v1.7
+    ports: ["7700:7700"]
+```
+
+### CI/CD
+- **GitHub Actions** → Build → Test → Deploy
+- **EAS Build** (Expo) → Builds iOS/Android
+- **CodePush** → OTA updates
+
+## 9. Roadmap
+
+### Phase 1 — MVP (2-3 mois)
+- [ ] Setup React Native + Expo
+- [ ] Auth Keycloak + profil utilisateur
+- [ ] Dashboard temps réel (météo, qualité air)
+- [ ] Carte interactive (capteurs, POI)
+- [ ] i18n FR/EN
+- [ ] Notifications push
+
+### Phase 2 — Services (3-4 mois)
+- [ ] Signalements citoyens
+- [ ] Transport (info trafic, bus)
+- [ ] Beckn BAP/BPP integration
+- [ ] Chatbot RAG (documents municipaux)
+- [ ] i18n ES/DE
+
+### Phase 3 — AI & Avancé (4-6 mois)
+- [ ] AI Agents (transport, tourisme, services)
+- [ ] Recommandations personnalisées
+- [ ] Prédictions (trafic, environnement)
+- [ ] Réalité augmentée (tourisme)
+- [ ] Mode offline complet
+
+## 10. Répertoires
+
+```
+smart-app-city/
+├── docs/
+│   ├── ARCHITECTURE.md (ce fichier)
+│   ├── BECKN_INTEGRATION.md
+│   ├── AI_ARCHITECTURE.md
+│   └── I18N.md
+├── frontend/
+│   ├── src/
+│   │   ├── screens/
+│   │   ├── components/
+│   │   ├── services/
+│   │   ├── i18n/
+│   │   └── store/
+│   ├── app.json
+│   └── package.json
+├── backend/
+│   ├── api-gateway/
+│   ├── auth-service/
+│   ├── gis-service/
+│   ├── iot-service/
+│   ├── notification-service/
+│   └── reporting-service/
+├── ai/
+│   ├── rag-service/
+│   ├── agent-service/
+│   └── models/
+├── beckn/
+│   ├── bap/
+│   └── bpp-adapter/
+├── docker-compose.yml
+└── README.md
+```