fisrt

CLAUDE.md

@@ -0,0 +1,122 @@
+# 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