LANMap/STRUCTURE.md

# Structure du Projet IPWatch

## Vue d'ensemble

```
ipwatch/
├── backend/                      # Backend FastAPI
│   ├── app/
│   │   ├── core/                # Configuration et database
│   │   │   ├── config.py        # Gestionnaire config YAML
│   │   │   └── database.py      # Setup SQLAlchemy
│   │   ├── models/              # Modèles SQLAlchemy
│   │   │   └── ip.py            # Tables IP et IPHistory
│   │   ├── routers/             # Endpoints API REST
│   │   │   ├── ips.py           # CRUD IPs + historique
│   │   │   ├── scan.py          # Contrôle scans
│   │   │   └── websocket.py     # Endpoint WebSocket
│   │   ├── services/            # Services métier
│   │   │   ├── network.py       # Scanner réseau (ping, ARP, ports)
│   │   │   ├── scheduler.py     # APScheduler pour tâches périodiques
│   │   │   └── websocket.py     # Gestionnaire WebSocket
│   │   └── main.py              # Application FastAPI principale
│   └── requirements.txt         # Dépendances Python
│
├── frontend/                    # Frontend Vue 3
│   ├── src/
│   │   ├── assets/
│   │   │   └── main.css         # Styles Monokai + animations
│   │   ├── components/
│   │   │   ├── AppHeader.vue    # Header avec stats et contrôles
│   │   │   ├── IPCell.vue       # Cellule IP dans la grille
│   │   │   ├── IPDetails.vue    # Détails IP (colonne gauche)
│   │   │   ├── IPGrid.vue       # Grille d'IP (colonne centrale)
│   │   │   └── NewDetections.vue # Nouvelles IP (colonne droite)
│   │   ├── stores/
│   │   │   └── ipStore.js       # Store Pinia + WebSocket client
│   │   ├── App.vue              # Layout 3 colonnes
│   │   └── main.js              # Point d'entrée
│   ├── package.json             # Dépendances Node
│   ├── vite.config.js           # Configuration Vite
│   ├── tailwind.config.js       # Configuration Tailwind (Monokai)
│   └── index.html               # HTML principal
│
├── tests/                       # Tests backend
│   ├── test_network.py          # Tests modules réseau
│   ├── test_models.py           # Tests modèles SQLAlchemy
│   ├── test_api.py              # Tests endpoints API
│   └── test_scheduler.py        # Tests APScheduler
│
├── config.yaml                  # Configuration principale
├── docker-compose.yml           # Orchestration Docker
├── Dockerfile                   # Image multi-stage
├── Makefile                     # Commandes utiles
├── start.sh                     # Script démarrage rapide
├── pytest.ini                   # Configuration pytest
├── .gitignore                   # Exclusions Git
├── .dockerignore                # Exclusions Docker
├── README.md                    # Documentation
├── CLAUDE.md                    # Guide pour Claude Code
└── STRUCTURE.md                 # Ce fichier
```

## Flux de données

### 1. Scan réseau (backend)

```
APScheduler (scheduler.py)
    ↓ déclenche périodiquement
NetworkScanner (network.py)
    ↓ effectue scan complet
    ├─→ Ping parallélisé
    ├─→ ARP lookup + MAC vendor
    └─→ Port scan
    ↓ résultats
SQLAlchemy (models/ip.py)
    ↓ enregistre dans
SQLite (data/db.sqlite)
    ↓ notifie via
WebSocket Manager (services/websocket.py)
    ↓ broadcast vers
Clients WebSocket (frontend)
```

### 2. Interface utilisateur (frontend)

```
App.vue (layout 3 colonnes)
    ├─→ IPDetails.vue (gauche)
    ├─→ IPGrid.vue (centre)
    │      └─→ IPCell.vue (x254)
    └─→ NewDetections.vue (droite)
    ↓ tous utilisent
Pinia Store (ipStore.js)
    ↓ communique avec
    ├─→ API REST (/api/ips/*)
    └─→ WebSocket (/ws)
```

### 3. Workflow complet d'un scan

```
1. Scheduler déclenche scan
2. NetworkScanner génère liste IP (CIDR)
3. Ping parallélisé (50 simultanés)
4. ARP lookup pour MAC/vendor
5. Port scan (ports configurés)
6. Classification état (online/offline)
7. Mise à jour base de données
8. Détection nouvelles IP
9. Push WebSocket vers clients
10. Mise à jour UI temps réel
```

## Composants clés

### Backend

| Fichier | Responsabilité | Lignes |
|---------|---------------|--------|
| `services/network.py` | Scan réseau (ping, ARP, ports) | ~300 |
| `services/scheduler.py` | Tâches planifiées | ~100 |
| `services/websocket.py` | Gestionnaire WebSocket | ~150 |
| `routers/ips.py` | API CRUD IPs | ~200 |
| `routers/scan.py` | API contrôle scan | ~150 |
| `models/ip.py` | Modèles SQLAlchemy | ~100 |
| `core/config.py` | Gestion config YAML | ~150 |
| `main.py` | Application FastAPI | ~150 |

### Frontend

| Fichier | Responsabilité | Lignes |
|---------|---------------|--------|
| `stores/ipStore.js` | State management + WebSocket | ~250 |
| `components/IPGrid.vue` | Grille IP + filtres | ~100 |
| `components/IPDetails.vue` | Détails + édition IP | ~200 |
| `components/IPCell.vue` | Cellule IP individuelle | ~80 |
| `components/NewDetections.vue` | Liste nouvelles IP | ~120 |
| `assets/main.css` | Styles Monokai | ~150 |

## Points d'entrée

### Développement

**Backend** :
```bash
cd backend
python -m backend.app.main
# ou
make dev-backend
```

**Frontend** :
```bash
cd frontend
npm run dev
# ou
make dev-frontend
```

### Production (Docker)

```bash
docker-compose up -d
# ou
./start.sh
# ou
make up
```

## Configuration requise

### Backend
- Python 3.11+
- Privilèges réseau (ping, ARP)
- Accès au réseau local

### Frontend
- Node.js 20+
- npm

### Docker
- Docker 20+
- docker-compose 2+

## Ports utilisés

- **8080** : API backend + frontend buildé (production)
- **3000** : Frontend dev (développement)

## Volumes Docker

- `./config.yaml` → `/app/config.yaml` (ro)
- `./data/` → `/app/data/`
- `./logs/` → `/app/logs/`

## Base de données

**SQLite** : `data/db.sqlite`

Tables :
- `ip` : Table principale des IP (14 colonnes)
- `ip_history` : Historique des états (5 colonnes)

Index :
- `ip.last_status`
- `ip.known`
- `ip_history.timestamp`
- `ip_history.ip`

## Tests

Lancer les tests :
```bash
pytest
# ou
make test
```

Couverture :
```bash
pytest --cov=backend.app --cov-report=html
# ou
make test-coverage
```

## Commandes utiles

Voir toutes les commandes :
```bash
make help
```

Principales commandes :
- `make build` - Construire l'image
- `make up` - Démarrer
- `make down` - Arrêter
- `make logs` - Voir les logs
- `make test` - Tests
- `make clean` - Nettoyer
- `make db-backup` - Sauvegarder DB
- `make db-reset` - Réinitialiser DB

## Dépendances principales

### Backend (Python)
- fastapi 0.109.0
- uvicorn 0.27.0
- sqlalchemy 2.0.25
- pydantic 2.5.3
- apscheduler 3.10.4
- scapy 2.5.0
- pytest 7.4.4

### Frontend (JavaScript)
- vue 3.4.15
- pinia 2.1.7
- axios 1.6.5
- vite 5.0.11
- tailwindcss 3.4.1