Arrow Architecture

Arrow Architecture

This document provides an overview of Arrow’s system architecture, explaining how the various components work together to deliver a comprehensive device management solution.

System Overview

Arrow is designed as a modular, scalable platform that connects users, devices, and external services through a centralized management interface. The architecture follows a client-server model where the Arrow Console serves as the primary user interface, communicating with backend services that orchestrate device management, VPN connectivity, and third-party integrations.

User Journey

The following diagram illustrates a typical user interaction flow through the Arrow system:

sequenceDiagram
    participant User
    participant Console
    participant Backend
    participant Integrations
    participant Device

    User->>Console: Access Arrow Console
    Console->>Backend: Authenticate (Zitadel)
    Backend-->>Console: Session Token
    User->>Console: Create Device Request
    Console->>Backend: Submit Request
    Backend->>Integrations: Create Shipment (EasyPost)
    Integrations-->>Backend: Tracking Info
    Backend->>Device: Provision & Configure
    Device->>Backend: Register with VPN (Netbird)
    Device-->>Console: Status Updates
    Console-->>User: Device Ready

Core Components

Arrow Console

The Arrow Console is the web-based management interface accessible at /console. It provides:

• Dashboard: Overview of device status, pending requests, and system health
• Device Management: Create requests, monitor devices, configure settings
• User Administration: Manage user accounts, roles, and permissions
• VPN Configuration: Set up and manage VPN peers and networks
• VM Management: Deploy and control virtual machines on Arrow devices
• Reporting: View logs, audit trails, and analytics

The console is built with Svelte 5, providing a fast and responsive user experience with real-time updates.

Arrow Manager

Arrow Manager is the on-device application that runs on each Arrow device. It handles:

• VM Deployment: Install and manage virtual machines locally
• Configuration Management: Apply device settings and policies
• Network Management: Configure network interfaces, WiFi hotspot, and failover
• Local Access: Provide a local management interface during device setup
• Health Monitoring: Report device status back to the console

Backend Services

The Arrow backend is built on PocketBase, a Go-based framework that provides:

• RESTful API: Endpoints for all console and device operations
• Real-time Subscriptions: WebSocket connections for live updates
• Authentication: Session management and JWT token handling
• Business Logic: Device provisioning workflows, approval processes
• Integration Orchestration: Coordination with external services

Database

Arrow uses SQLite as its primary database, managed by PocketBase. This provides:

• Reliability: ACID-compliant transactions
• Performance: Fast read operations for dashboard queries
• Simplicity: No separate database server required
• Portability: Easy backup and migration

Backend Structure

The backend is organized into API modules, hooks, middleware, and background services:

API Modules

The following API modules are registered in main.go:

Category	Modules
Device Management	device_requests, device_settings, device_licensing, device_location, device_lookup, device_cleanup, device_complete, device_shipments
VPN & Network	vpn, netbird
Authentication	zitadel, admin_impersonation
Shipping & Tracking	easypost, blues (GPS)
VM Management	vm_images, vm_build_monitor, vm_complete
KVM & Remote Access	kvm_devices, kvm_signaling, signaling
Licensing	licensing
Analytics & Logging	analytics, influxdb, logging, build_logs
Infrastructure	infrastructure (asset management, Hetzner)
Integrations	helpscout, quickbooks, resend, simplex, cellular
Other	software, software_updates, releases, arrow_control_updates, templates, notifications, onboarding, invoices, contact, favicons

Hooks

Hooks provide event-driven logic that triggers on record changes:

Hook	Purpose
RegisterUserPermissionsHooks	Manages user permission assignments
RegisterUserRoleValidationHooks	Validates user role changes
RegisterDeviceRequestDeletionHooks	Handles cascading cleanup when device requests are deleted
RegisterDeviceUserAccessHooks	Controls per-device user access permissions
RegisterDeviceAccessControlHooks	Enforces device-level access control policies
RegisterOrgAccessControlHooks	Enforces organization-level access control
RegisterNotificationTriggers	Triggers automatic notifications on relevant events

Middleware

Middleware	Purpose
ImagingStationIPWhitelist	Restricts imaging station routes to whitelisted IP addresses

Background Services

These services run continuously in the background:

Service	Purpose
StartShipmentStatusSync	Periodically syncs device shipment statuses
TrackingSyncService	Syncs EasyPost delivery/dropoff tracking information via cron
StartCertificateRenewalCron	Automatically renews VPN certificates before expiration

Integration Architecture

Arrow connects with multiple external services to provide comprehensive functionality:

graph TB
    subgraph Arrow Platform
        Console[Arrow Console]
        Backend[Backend Services]
        DB[(SQLite Database)]
    end

    subgraph External Services
        Netbird[Netbird VPN]
        Zitadel[Zitadel Auth]
        EasyPost[EasyPost Shipping]
        Blues[Blues Notecard]
        HelpScout[HelpScout Support]
        QuickBooks[QuickBooks Billing]
        Resend[Resend Email]
        Mapbox[Mapbox Geocoding]
    end

    subgraph Devices
        Device1[Arrow Device 1]
        Device2[Arrow Device 2]
        DeviceN[Arrow Device N]
    end

    Console --> Backend
    Backend --> DB
    Backend --> Netbird
    Backend --> Zitadel
    Backend --> EasyPost
    Backend --> Blues
    Backend --> HelpScout
    Backend --> QuickBooks
    Backend --> Resend
    Backend --> Mapbox

    Device1 --> Netbird
    Device2 --> Netbird
    DeviceN --> Netbird

    Device1 --> Backend
    Device2 --> Backend
    DeviceN --> Backend

Integration Details

Service	Purpose
Netbird	VPN orchestration - manages secure connections between devices and the console
Zitadel	Authentication and authorization - handles user identity and access control
EasyPost	Shipment management - creates shipping labels and tracks device deliveries
Blues Notecard	GPS tracking - provides device location data via cellular connectivity
HelpScout	Support integration - creates and manages customer support tickets
QuickBooks	Billing integration - syncs billing data and invoices
Resend	Email notifications - sends transactional emails and alerts
Mapbox	Geocoding - converts addresses and displays device locations on maps

Network Architecture

Arrow devices support multiple network connectivity options with automatic failover:

graph TD
    A[Arrow Device] --> B{Connection Type}
    B -->|Primary| C[Ethernet]
    B -->|Failover| D[Cellular]
    B -->|Setup| E[WiFi Hotspot]
    C --> F[Netbird VPN]
    D --> F
    E --> G[Arrow Manager Access]
    F --> H[Arrow Console]
    F --> I[Virtual Machines]
    I --> J[Client Applications]

Connection Types

Connection	Use Case
Ethernet	Primary connection for stable, high-bandwidth connectivity
Cellular	Automatic failover when ethernet is unavailable
WiFi Hotspot	Local access point for initial device setup and Arrow Manager access

VPN Topology

All Arrow devices connect through Netbird VPN, providing:

• Zero-Trust Security: Each device authenticates individually
• Mesh Networking: Devices can communicate directly when needed
• NAT Traversal: Works behind firewalls without port forwarding
• Split Tunneling: Only Arrow traffic goes through VPN

Device Lifecycle Flow

The following diagram shows the complete device lifecycle from request to active management:

flowchart TD
    A[Device Request Created] --> B{Approved?}
    B -->|Yes| C[Device Provisioned]
    B -->|No| D[Request Denied]
    C --> E[Shipment Created]
    E --> F[Device Shipped]
    F --> G[Device Delivered]
    G --> H[VPN Setup]
    H --> I[VM Deployment]
    I --> J[Device Active]
    J --> K[Monitoring & Management]
    K --> L{End of Life?}
    L -->|No| K
    L -->|Yes| M[Device Decommissioned]

Lifecycle Stages

1. Request Created: User submits a device request through the console
2. Approval: Admin or manager reviews and approves the request
3. Provisioning: Backend configures the device with appropriate settings
4. Shipment: EasyPost integration creates shipping label and tracking
5. Delivery: Device arrives at destination with tracking updates
6. VPN Setup: Device registers with Netbird and establishes secure connection
7. VM Deployment: Virtual machines are deployed based on configuration
8. Active Management: Device is monitored and managed through the console
9. Decommissioning: Device is removed from inventory at end of life

Security Architecture

Arrow implements multiple layers of security:

• Authentication: Zitadel provides enterprise-grade identity management
• Authorization: Role-based access control (Admin, Manager, User)
• Encryption: All traffic encrypted via HTTPS and VPN
• API Security: Token-based authentication for all API calls
• Audit Logging: Complete audit trail of all actions

Next Steps

• Installation - Set up your own Arrow instance
• Environment Variables - Configure Arrow for your environment
• VPN Management - Learn about VPN configuration