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

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 integrations it holds credentials for
• Report the subnets it has interfaces on
• Maintain server connection via periodic polling (each poll implicitly updates the daemon's health status)
• Execute scheduled discovery tasks

Runs as: Docker container (Linux only), or a native background service on Linux, macOS, Windows, and FreeBSD (installed via scanopy-daemon install)

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

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

Data Flows

DaemonPoll Mode

DaemonPoll is the default mode. The daemon initiates all connections to the server, making it ideal for daemons behind NAT or firewalls.

Initialization (DaemonPoll)

Runtime Polling (DaemonPoll)

Discovery Flow (DaemonPoll)

1. User triggers a scan via the UI or API — the server creates a discovery session in Pending state
2. On its next polling cycle, the daemon receives the pending session as part of the request-work response
3. The server transitions the session to Starting to prevent re-dispatch to other polls
4. The daemon executes the discovery: self-report, the network scan, and every integration it holds a credential for
5. The daemon sends periodic progress updates to the server, including discovered entities
6. The server processes entities immediately — deduplicating and persisting via upsert
7. The server broadcasts progress to the UI via SSE
8. The daemon sends a terminal phase (Completed or Failed) to end the session

ServerPoll Mode

ServerPoll mode is for DMZ deployments where the daemon cannot make outbound connections. The server initiates all connections to the daemon. Requires the daemon to be network-accessible from the server.

Initialization (ServerPoll)

Runtime Polling (ServerPoll)

Discovery Flow (ServerPoll)

Mode Comparison

Discovery Pipeline

Network Scanning

Network scanning runs in three phases:

1. ARP Discovery — The daemon sends ARP broadcasts across configured subnets to discover active hosts. This is the primary mechanism for finding devices on the local network, returning IP and MAC address pairs.
2. Deep Scanning — Each discovered host is scanned in detail:
   • TCP and UDP port scanning on configurable port lists
   • DNS reverse lookup for hostname resolution
   • SNMP queries for system information (if credentials are configured)
   • Service detection by matching open ports against service definitions
3. Grace Period — A brief window after deep scanning completes to catch any late ARP responses. Newly discovered hosts receive a full deep scan before the session completes.

The UI displays real-time progress across all three phases via Server-Sent Events.

Integration Discovery

For each credential it holds, the daemon probes the credential's targets, then collects from every target that answered. Every integration that reaches a host writes into the same host record as the network scan, so the server receives one host per machine rather than one per source. What credentials add lists what each integration reports.

---

For implementation details, see the source code.