LANMap/CLAUDE.md

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 - Overall project objectives and deliverables
• architecture-technique.md - Technical architecture (backend modules, frontend structure, Docker setup)
• modele-donnees.md - SQLite database schema (ip and ip_history tables with required indexes)
• workflow-scan.md - 10-step scan pipeline from YAML config to WebSocket push
• 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 - UI layout (3-column design), interaction patterns, visual states
• guidelines-css.md - Monokai color palette, IP cell styling rules (solid border for online, dashed for offline, animated halo for ping)
• 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
• 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

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) 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):

• 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
• Responsive design: Grid layout must be fluid with collapsible columns