Architecture

Technical overview of Scanopy's system design, components, and data flows.

Components

Server

Purpose: Central hub for data storage, API, and web UI serving

Responsibilities:

• Store network discovery data in PostgreSQL
• Serve REST API for daemons and UI
• Generate topology visualizations
• Manage user authentication and sessions
• Orchestrate scheduled discoveries
• Handle organization and user management
• Provide real-time updates via Server-Sent Events

Implementation:

• Language: Rust
• Framework: Axum (async web framework)
• Database: PostgreSQL 17 with sqlx
• Authentication: tower-sessions + OIDC (openidconnect crate)
• Frontend bundling: Integrated Svelte build in Docker image

Runs as: Docker container (recommended) or standalone binary

Daemon

Purpose: Distributed discovery agent that scans networks and reports findings

Responsibilities:

• Scan IPv4 addresses on configured subnets
• Detect open TCP ports
• Identify services via pattern matching
• Connect to Docker socket for container discovery
• Report host interfaces and capabilities
• Send heartbeats to maintain connection
• Execute scheduled discovery tasks

Implementation:

• Language: Rust
• Network scanning: Custom async TCP scanner with tokio
• Docker API: bollard crate for Docker socket communication
• Service detection: Pattern matching engine with 200+ definitions
• Configuration: JSON file + environment variables + CLI args

Runs as: Docker container (Linux only) or standalone binary (all platforms)

UI

Purpose: Web-based interface for viewing and managing network data

Responsibilities:

• Display interactive topology diagrams
• Provide CRUD interfaces for all entities
• Monitor discovery sessions in real-time
• Manage users and organizations
• Configure discovery schedules
• Export topology visualizations

Implementation:

• Framework: Svelte 5 + SvelteKit
• State management: Svelte stores with derived reactivity
• Visualization: @xyflow/svelte for topology rendering
• Forms: svelte-forms with custom validation
• Styling: Tailwind CSS
• Real-time: Native EventSource for SSE

Runs as: Static files served by the server (bundled in Docker image)

Data Flows

Discovery Flow (Pull Mode)

Discovery Flow (Push Mode)

Same as Pull mode, except in step 3 the server initiates the connection to the daemon instead of the daemon polling.

Discovery Pipeline

Network Scan

Docker Discovery

---

For implementation details, see the source code.