Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• IMPLEMENTATION_PLAN.md
• AGENTS.md
• Cargo.toml
• crates/cli/src/main.rs
• crates/error/src/response.rs
• crates/error/src/codes.rs

Horizon is a self-hostable Configuration Management Database (CMDB) designed to provide comprehensive visibility into an organization's IT infrastructure. It employs a three-tier architecture consisting of a presentation layer (web and desktop interfaces), a business logic layer (API server with AI inference capabilities), and a data persistence layer (PostgreSQL and Redis). The system is built using Rust, prioritizing security, performance, and automation.

Sources: README.md:15-20, IMPLEMENTATION_PLAN.md:27-31

High-Level System Structure

The project is organized as a Rust workspace with multiple specialized crates. This modular approach separates concerns such as the REST API, cross-platform agents, database interactions, and shared utilities.

The diagram above illustrates the interaction between the primary components, including the data flow from collectors (Agents) to the central processing hub (API Server).
Sources: IMPLEMENTATION_PLAN.md:29-31, AGENTS.md:165-172

Core Components

Component	Technology	Responsibility
API Server	Axum, Tokio, Tower	Handles RESTful requests, authentication, and orchestrates business logic.
Database	PostgreSQL, Sea-ORM	Persistent storage for assets, software inventory, and relationship mapping.
Cache	Redis	Session management, rate limiting, and temporary data caching.
Agent	Rust (Native)	Lightweight service for automated hardware and software discovery.
Desktop App	Tauri, React	Cross-platform desktop interface for managing multiple server profiles.

Sources: IMPLEMENTATION_PLAN.md:38-45, IMPLEMENTATION_PLAN.md:417-425, README.md:31-35

Backend Architecture

The backend is built using the Axum web framework and the Tokio async runtime. It utilizes a "Crate-level" granularity for imports and adheres to strict error-handling patterns.

API Processing Flow

The API server utilizes a middleware-heavy pipeline for security and request management. This includes JWT validation, RBAC enforcement, and rate limiting using Redis sorted sets.

Error Handling and Responses

Horizon implements a standardized API response format through the ApiResponse enum. This ensures that every client request receives a consistent structure containing success status, data, and metadata (like request IDs and timestamps).

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", tag = "status")]
pub enum ApiResponse<T> {
    Success {
        data: T,
        #[serde(flatten, skip_serializing_if = "Option::is_none")]
        meta: Option<ResponseMeta>,
    },
    Error {
        code: String,
        message: String,
        details: Option<serde_json::Value>,
        request_id: Option<String>,
        meta: Option<ResponseMeta>,
    },
}

Sources: crates/error/src/response.rs:104-135, crates/error/src/codes.rs:18-26

Data Persistence and CLI

The database layer uses Sea-ORM for entity management and migrations. The CLI tool (horizon) serves as the primary entry point for administrative tasks, including database initialization and server execution.

CLI Command Structure

The CLI is built using clap and provides several subcommands for system management:

• serve: Starts the API server and runs migrations automatically.
• migrate: Manages database schema versions (up, rollback, dry-run).
• validate: Verifies that required environment variables are correctly configured.

Sources: crates/cli/src/main.rs:15-25, crates/cli/src/main.rs:70-85

Database Configuration

Database connections are managed through environment variables, which the CLI builds into a PostgreSQL connection string.

Environment Variable	Description	Default
HORIZON_DATABASE_HOST	Database host address	localhost
HORIZON_DATABASE_PORT	Database port	5432
HORIZON_DATABASE_NAME	Database schema name	horizon
HORIZON_DATABASE_SSL_MODE	SSL requirement level	require

Sources: crates/cli/src/main.rs:35-50, crates/cli/src/main.rs:56-62

Security Framework

The architecture implements a "defense-in-depth" strategy using the RustCrypto ecosystem.

• Encryption at Rest: Sensitive data is protected using XChaCha20-Poly1305 via the chacha20poly1305 crate.
• Identity Security: Passwords use Argon2id hashing; MFA is supported via TOTP.
• Communication: mTLS is planned for all agent-server communications, utilizing server-issued certificates and Ed25519 signatures.
• Memory Safety: The zeroize crate is used to clear sensitive data from memory after use.

Sources: IMPLEMENTATION_PLAN.md:52-65, IMPLEMENTATION_PLAN.md:149-155, README.md:183-195

Agent Architecture

Agents are lightweight (<50MB memory) Rust binaries designed to run on Linux, Windows, and macOS. They collect system metrics and inventory data, which are then transmitted to the API server as Protocol Buffers messages.

The agent maintains an offline queue in a local SQLite database to ensure data integrity during network outages.
Sources: IMPLEMENTATION_PLAN.md:280-310, IMPLEMENTATION_PLAN.md:320-330

Conclusion

Horizon's architecture balances modularity with high-security standards. By leveraging Rust's type system and a crate-based workspace, it provides a scalable foundation for IT asset management, network mapping, and vulnerability tracking. The combination of automated agents and AI-powered inference providers allows for intelligent pattern recognition across complex infrastructure data.