# LAN Graph Architecture

## Overview
- **Scanner**: Discovers live IPv4 hosts in the local subnet by pinging each address in the primary CIDR range discovered from `ip -4 addr`. Reverse DNS lookups enrich each host node. When SSH is reachable using key-based authentication, the scanner also runs `ip neigh show` remotely to learn neighbor MAC/IP and infers host-to-host connections.
- **Data Model**: `HostNode` stores IP, DNS name, reachability, last-seen timestamp, and optionally gathered SSH services; `ConnectionEdge` links nodes with a typed relation (e.g., `gateway`, `neighbor`, `ssh`) to drive the visualization. `ScanResult` aggregates nodes, edges, CIDR, gateway, and timestamp.
- **Web Visualization**: FastAPI serves the API plus a D3.js front-end. `/api/scan` triggers a fresh scan (or accepts `cidr` override) and returns the JSON graph. Static assets live under `frontend/` and render the nodes/edges with `d3-force` to deliver a Visio-like topology.
- **CLI/Server**: Typing `lan-graph scan` runs a JSON scan, and `lan-graph serve` launches FastAPI (uvicorn) to host the visual overview and API.

## Security & SSH
- Scanner defaults to `ssh -o BatchMode=yes -o ConnectTimeout=5` to honor the user's request for key-based auth and to avoid prompting for passwords.
- SSH user/key can come from the calling environment via `SSH_USER` and `SSH_KEY_PATH` or CLI flags so credentials are not hard-coded.

## Extensibility Points
- Additional probing (SMB, HTTP) can be added via `Scanner.probe_tcp_port` helpers.
- Visualization can be enhanced by swapping the D3 force layout for hierarchical or layered diagrams.