feat: backend FastAPI Smart App City — auth JWT, IoT, GIS, notifications, reporting
This commit is contained in:
Eric FELIXINE
183
smart-app-city/backend/ARCHITECTURE.md
Normal file
183
smart-app-city/backend/ARCHITECTURE.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# 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
|
||||
```python
|
||||
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
|
||||
```python
|
||||
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
|
||||
```python
|
||||
class Reading(BaseModel):
|
||||
id: UUID
|
||||
sensor_id: UUID
|
||||
value: float
|
||||
unit: str
|
||||
timestamp: datetime
|
||||
quality: float # 0-1 data quality score
|
||||
```
|
||||
|
||||
### Alert
|
||||
```python
|
||||
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
|
||||
Reference in New Issue
Block a user