Architecture

High-level overview of the Pharos system design, storage tiering, and protocol.

Project Pharos is a highly performant, read-optimized client-server ecosystem based on RFC 2378 (Phonebook Protocol).

System Overview

The following diagram illustrates the high-level architecture of Pharos, showing the interaction between CLI clients and the server components.

graph TD
    subgraph Clients
        PH[ph CLI - People]
        MDB[mdb CLI - Machines]
        SCAN[pharos-scan - Discovery]
    end

    subgraph "Pharos Server"
        TCP[TCP Listener :2378]
        Parser[RFC 2378 Parser]
        Auth[Auth Manager - SSH Keys]
        Metrics[Metrics Engine - Prometheus]
        StorageTrait[Storage Trait]
        
        subgraph "Storage Backends"
            Mem[MemoryStorage - Dev]
            File[FileStorage - Home Lab]
            LDAP[LdapStorage - Enterprise]
        end
    end

    PH -->|RFC 2378| TCP
    MDB -->|RFC 2378| TCP
    SCAN -->|mDNS / Port Probes| LAN((Local Network))
    LAN --> SCAN
    SCAN -->|RFC 2378| TCP
    TCP --> Parser
    Parser --> Auth
    Auth --> StorageTrait
    StorageTrait --> Mem
    StorageTrait --> File
    StorageTrait --> LDAP
    
    Metrics -.->|Observe| StorageTrait
    Metrics -.->|Observe| TCP

Storage Tiering Logic

🏠 Home Lab: Persistent File Storage

Pharos uses a file-level, restart-survivable JSON storage engine optimized for LXC containers. This ensures high performance with minimal configuration.

graph LR
    File[FileStorage]
    File -.->|Persistent| JSON[(Local JSON File)]

Core Protocol: RFC 2378 (Modified)

Pharos implements the Phonebook Protocol with extensions for modern infrastructure management and secure authentication.

Message Flow

  1. QUERY: Client sends a search string.
  2. DISCRIMINATE: Server identifies if the target is a person or machine.
  3. AUTH (if Write): Server issues an SSH challenge. Client signs and returns.
  4. RESPONSE: Server returns records in Ph format.
sequenceDiagram
    participant Client
    participant Server
    participant Auth
    participant Storage

    Client->>Server: QUERY "name=John"
    Server->>Storage: Search(people, "John")
    Storage-->>Server: [Records]
    Server-->>Client: 200: [Ph Records]

    Note over Client,Server: Write Operation
    Client->>Server: ADD "name=Jane"
    Server->>Auth: Challenge(SSH-Key)
    Auth-->>Client: Challenge
    Client-->>Auth: Signed-Response
    Auth-->>Server: Verified
    Server->>Storage: Commit(Jane)
    Server-->>Client: 200: Success

Core Components

1. Pharos Server (pharos-server)

The backend engine handling connection lifecycle, protocol parsing, and storage abstraction.

  • Protocol: RFC 2378 (Ph) with auth extension.
  • Authentication: SSH-key based challenge-response for Write operations.
  • Metrics: Integrated Prometheus scrape point (:9090/metrics) and health monitoring.

2. CLI Clients

  • ph: Optimized for human contact management.
  • mdb: Optimized for machine/infrastructure asset management.
  • pharos-scan: Automated discovery engine using mDNS and port probes to identify and provision assets into Pharos.
  • All clients support automatic authentication via local SSH private keys and share a common async core.

3. Storage Tiering

  • Development: Zero-configuration in-memory storage.
  • Home Lab: File-level, restart-survivable JSON storage (optimized for LXC).
  • Enterprise: LDAP-backed storage utilizing standard schemas (inetOrgPerson, ipHost).

Multi-Tenant & Triple-Tier Security

Pharos implements a flexible security model designed to scale from a single user’s “YOLO Lab” to a multi-tenant Enterprise environment.

🏠 Home Lab: The “YOLO” Security Model

In Home Lab environments, Pharos prioritizes speed and accessibility.

  • Open Access: Read operations are anonymous and unauthenticated.
  • SSH Challenge: Write operations still require a valid signature from an authorized SSH key for basic safety.
  • Use Case: Single-user labs or trusted home networks.

The Dual-Site Ecosystem

Pharos distinguishes between documentation (static) and management (dynamic) to ensure high availability and security.

graph LR
    User((User))
    Agent((AI Agent))
    
    subgraph "Public Internet"
        Marketing[Marketing Site / Docs]
        Marketing -.->|Self-Help| User
    end
    
    subgraph "Private Network / Lab"
        Server[Pharos Server]
        Console[Pharos Console]
        Pulse[pharos-pulse Agents]
        
        Console --- Server
        Pulse -->|Heartbeat| Server
        Console -.->|WebMCP| Agent
        Agent -.->|Tool Calls| Console
        User --- Console
    end

1. Marketing & Documentation (iamrichardd.com/pharos/)

  • Type: Static Site (Astro/MDX).
  • Purpose: Architecture guides, “How-To” tutorials, and open-source advocacy.
  • Why: Ensures that even if your Pharos server is down, you still have access to the documentation on how to fix it.

2. Pharos Console (pharos-console)

  • Type: Dynamic Web Application & MCP Server.
  • Purpose: Real-time TUI/Web dashboard, SSH key management, and AI Agent orchestration.
  • Features:
    • WebMCP Bridge: Allows your browser to act as a secure proxy for AI Agents.
    • MDB Search: High-performance inventory querying with visual search results.
    • Enrollment: One-click provisioning for new nodes.