# 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
```