# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

IPWatch is a network scanner web application that visualizes IP addresses, their states (online/offline), open ports, and historical data. The project consists of:

- **Backend**: FastAPI + SQLAlchemy + APScheduler for network scanning
- **Frontend**: Vue 3 + Vite + Tailwind with Monokai dark theme
- **Deployment**: Docker containerization with volumes for config and database

## Key Specification Files
Speek in french and comment in french
The project has detailed specifications that MUST be followed when implementing features:

- [prompt-claude-code.md](prompt-claude-code.md) - Overall project objectives and deliverables
- [architecture-technique.md](architecture-technique.md) - Technical architecture (backend modules, frontend structure, Docker setup)
- [modele-donnees.md](modele-donnees.md) - SQLite database schema (ip and ip_history tables with required indexes)
- [workflow-scan.md](workflow-scan.md) - 10-step scan pipeline from YAML config to WebSocket push
- [consigne-parametrage.md](consigne-parametrage.md) - Complete YAML configuration structure with all sections (app, network, ip_classes, scan, ports, locations, hosts, history, ui, colors, network_advanced, filters, database)
- [consigne-design_webui.md](consigne-design_webui.md) - UI layout (3-column design), interaction patterns, visual states
- [guidelines-css.md](guidelines-css.md) - Monokai color palette, IP cell styling rules (solid border for online, dashed for offline, animated halo for ping)
- [tests-backend.md](tests-backend.md) - Required unit and integration tests

## Architecture Principles

### Backend Structure
- FastAPI application with separate modules for network operations (ping, ARP, port scanning)
- SQLAlchemy models matching the schema in [modele-donnees.md](modele-donnees.md)
- APScheduler for periodic network scans
- WebSocket endpoint for real-time push notifications
- REST APIs for: IP management, scan operations, configuration, historical data

### Frontend Structure
- Vue 3 with Composition API
- Pinia for global state management
- WebSocket client for real-time updates
- 3-column layout: left (IP details), center (IP grid + legend), right (new detections)
- Monokai dark theme with specific color codes from [guidelines-css.md](guidelines-css.md)

### Data Flow
1. YAML configuration loads network CIDR and scan parameters
2. Scheduled scan generates IP list, performs ping (parallel), ARP lookup, port scanning
3. Results classified and stored in SQLite
4. New/changed IPs trigger WebSocket push to frontend
5. UI updates grid with appropriate visual states

## Database Schema

### ip table (PRIMARY)
- `ip` (PK): IP address
- `name`, `known` (bool), `location`, `host`: metadata
- `first_seen`, `last_seen`: timestamps
- `last_status`: current online/offline state
- `mac`, `vendor`, `hostname`: network info
- `open_ports`: JSON array

### ip_history table
- `id` (PK)
- `ip` (FK to ip.ip)
- `timestamp`, `status`, `open_ports` (JSON)
- **Required index**: timestamp for efficient historical queries

### Important Indexes
- Index on `ip.last_status` for filtering
- Index on `ip_history.timestamp` for 24h history retrieval

## Visual Design Rules

### IP Cell States
- **Online + Known**: Green (#A6E22E) with solid border
- **Online + Unknown**: Cyan (#66D9EF) with solid border
- **Offline**: Dashed border + configurable transparency
- **Ping in progress**: Animated halo using CSS keyframes
- **Free IP**: Distinct color from occupied states

### Theme Colors (Monokai)
- Background: `#272822`
- Text: `#F8F8F2`
- Accents: `#A6E22E` (green), `#F92672` (pink), `#66D9EF` (cyan)

## Configuration System

The application is driven by a YAML configuration file ([consigne-parametrage.md](consigne-parametrage.md)) with these sections:
- `network`: CIDR, gateway, DNS
- `ip_classes`: Define known IPs with metadata
- `scan`: Intervals, parallelization settings
- `ports`: Port scan ranges
- `locations`, `hosts`: Categorical data
- `history`: Retention period
- `ui`: Display preferences, transparency
- `colors`: Custom color mapping
- `network_advanced`: ARP, timeout settings
- `filters`: Default filter states
- `database`: SQLite path

## Testing Requirements

When implementing backend features, ensure tests cover ([tests-backend.md](tests-backend.md)):
- Network module unit tests: `test_ping()`, `test_port_scan()`, `test_classification()`
- SQLAlchemy models: `test_sqlalchemy_models()`
- API endpoints: `test_api_get_ip()`, `test_api_update_ip()`
- Scheduler: `test_scheduler()`
- Integration: Full network scan simulation, WebSocket notification flow

## Docker Setup

The application should run as a single Docker service:
- Combined backend + frontend container
- Volume mount for `config.yaml`
- Volume mount for `db.sqlite`
- Exposed ports for web access and WebSocket

## Implementation Notes

- **Parallelization**: Ping operations must be parallelized for performance
- **Real-time updates**: WebSocket is critical for live UI updates during scans
- **MAC vendor lookup**: Use ARP data to populate vendor information
- **Port scanning**: Respect intervals defined in YAML to avoid network overload
- **Classification logic**: Follow the 10-step workflow in [workflow-scan.md](workflow-scan.md)
- **Responsive design**: Grid layout must be fluid with collapsible columns
