smart-city-digital-twin-martinique/smart-app-city/backend/ARCHITECTURE.md

Smart App City — Backend Architecture Proposal

Overview

Backend Python FastAPI + JWT pour l'application mobile Smart City Martinique.

Architecture

api-gateway/          → Point d'entrée unique, rate limiting, CORS
auth-service/         → Inscription, login, JWT, gestion utilisateurs
iot-service/          → Données capteurs, alertes, historique
gis-service/          → Données géospatiales, couches, géocodage
notification-service/ → Notifications push, alertes
reporting-service/    → Rapports, statistiques, export PDF

Tech Stack

• Framework : FastAPI (async, OpenAPI auto, Pydantic)
• Auth : JWT (python-jose) + bcrypt (passlib)
• DB : PostgreSQL (existant) + SQLModel (ORM)
• Cache : Redis (existant)
• Messages : MQTT (Mosquitto existant) pour temps réel
• Notifications : Firebase Cloud Messaging (FCM)
• Maps : Tuiles vectorielles OpenStreetMap

API Endpoints (MVP)

Auth Service (/api/v1/auth)

Method	Endpoint	Description
POST	/register	Inscription utilisateur
POST	/login	Login → JWT tokens
POST	/refresh	Refresh access token
GET	/me	Profil utilisateur
PUT	/me	Modifier profil
POST	/logout	Invalider token

IoT Service (/api/v1/iot)

Method	Endpoint	Description
GET	/sensors	Liste des capteurs
GET	/sensors/{id}	Détail capteur
GET	/sensors/{id}/data	Données historiques
GET	/zones	Zones de la ville
GET	/zones/{id}/sensors	Capteurs par zone
GET	/alerts	Alertes actives
GET	/stats	Statistiques globales

GIS Service (/api/v1/gis)

Method	Endpoint	Description
GET	/layers	Couches disponibles
GET	/layers/{id}/features	Features d'une couche
GET	/search	Recherche d'adresse
GET	/reverse	Géocodage inversé

Reporting Service (/api/v1/reports)

Method	Endpoint	Description
GET	/daily	Rapport journalier
GET	/weekly	Rapport hebdomadaire
GET	/custom	Rapport personnalisé
GET	/export/pdf	Export PDF

Notification Service (/api/v1/notifications)

Method	Endpoint	Description
GET	/	Notifications utilisateur
PUT	/read/{id}	Marquer comme lu
POST	/register-device	Enregistrer token FCM
GET	/preferences	Préférences notifications

Data Models

User

class User(BaseModel):
    id: UUID
    email: str
    username: str
    hashed_password: str
    first_name: str
    last_name: str
    phone: Optional[str]
    role: UserRole  # admin, user, viewer
    avatar_url: Optional[str]
    created_at: datetime
    updated_at: datetime

Sensor

class Sensor(BaseModel):
    id: UUID
    name: str
    type: SensorType  # temperature, humidity, air_quality, traffic, noise
    status: SensorStatus  # active, inactive, maintenance, error
    location: GeoPoint  # [lng, lat]
    zone_id: Optional[UUID]
    last_reading: Optional[Reading]
    battery_level: Optional[int]
    created_at: datetime

Reading

class Reading(BaseModel):
    id: UUID
    sensor_id: UUID
    value: float
    unit: str
    timestamp: datetime
    quality: float  # 0-1 data quality score

Alert

class Alert(BaseModel):
    id: UUID
    sensor_id: UUID
    type: AlertType  # threshold_offline, anomaly
    severity: AlertSeverity  # low, medium, high, critical
    message: str
    value: Optional[float]
    threshold: Optional[float]
    status: AlertStatus  # active, acknowledged, resolved
    created_at: datetime
    resolved_at: Optional[datetime]

Services Structure (per service)

Each service follows this structure:

service-name/
├── Dockerfile
├── requirements.txt
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI app entry
│   ├── config.py        # Settings, env vars
│   ├── database.py      # DB connection, session
│   ├── models/          # SQLModel models
│   │   ├── __init__.py
│   │   └── models.py
│   ├── schemas/         # Pydantic schemas
│   │   ├── __init__.py
│   │   └── schemas.py
│   ├── routes/          # API routes
│   │   ├── __init__.py
│   │   └── routes.py
│   ├── services/        # Business logic
│   │   ├── __init__.py
│   │   └── service.py
│   └── auth/            # JWT verification
│       ├── __init__.py
│       └── jwt.py
└── tests/
    ├── __init__.py
    └── test_routes.py

Deployment Options

Option A: Single Container (simplifié)

Tous les services dans un seul container FastAPI avec des routers séparés.

• Plus simple à déployer
• Moins de ressources
• Idéal pour MVP

Option B: Multi-containers (microservices réel)

Chaque service dans son propre container.

• Plus scalable
• Plus complexe à gérer
• Nécessite Docker Compose

Recommandation MVP : Option A (single container avec routers), puis refactor en microservices si besoin.

Next Steps

1. Choisir Option A ou B
2. Créer le backend complet
3. Intégrer avec le frontend Expo existant
4. Déployer sur le serveur