Index of Stavily Detailed Architecture

This page provides a comprehensive overview of the Stavily platform’s detailed architecture through visual diagrams and explanations. Explore the core components, system interactions, and workflow paradigms that power Stavily’s automation capabilities.

API-Driven Two-Agent Architecture

This diagram illustrates the separation of concerns between the Sensor and Action agents and their interaction with the Orchestrator.

graph TD
    subgraph "Stavily Orchestrator"
        Orchestrator["⚙️ Orchestrator Core"]
        AgentAPI["📡 Public Agent API /agents/v1/*"]
        Orchestrator -- "Manages all instructions" --> AgentAPI
    end

    subgraph "External Systems"
        MonitoringTools["📈 Monitoring Tools (Prometheus, Grafana, etc.)"]
        CloudProviders["☁️ Cloud Providers (AWS, Azure, GCP)"]
        Infrastructure["💻 General Infrastructure"]
    end

    subgraph "Sensor Agent Domain"
        SensorAgent["🕵️ Sensor Agent"]
        SensorAgent -- "1. Polls for instructions (e.g., check metric)" --> AgentAPI
        MonitoringTools -- "2. Provides metrics/events to" --> SensorAgent
        CloudProviders -- "3. Provides state/logs to" --> SensorAgent
        SensorAgent -- "4. Reports results/data back" --> AgentAPI
    end

    subgraph "Action Agent Domain"
        ActionAgent["🤖 Action Agent"]
        ActionAgent -- "1. Polls for instructions (e.g., restart service)" --> AgentAPI
        ActionAgent -- "2. Executes remediation actions on" --> CloudProviders
        ActionAgent -- "3. Executes commands on" --> Infrastructure
        ActionAgent -- "4. Reports action results back" --> AgentAPI
    end

    style SensorAgent fill:#cde4f6,stroke:#333,stroke-width:2px
    style ActionAgent fill:#d5f5e3,stroke:#333,stroke-width:2px

This diagram illustrates the separation of concerns between the Sensor and Action agents and their interaction with the Orchestrator. Sensor agents poll for instructions to collect data from monitoring tools and cloud providers, reporting results back via the API. Action agents similarly poll for remediation instructions and execute actions on infrastructure, ensuring a secure, API-driven architecture.

System Architecture Overview

graph TB
    subgraph "Cloud Orchestrator (agents.stavily.com)"
        UI[SvelteKit Dashboard]
        PubAPI[Public API Gateway **Agent Communication**]
        PrivAPI[Private API Gateway Internal Services ONLY]
        WF[Workflow Service]
        AF[Agent Fleet Service Two-Agent Management]
        GPR[Git Plugin Registry]
        AC[Audit & Compliance]
    end

    subgraph "Customer Infrastructure"
        SA1[Sensor Agent 1 **Go Binary - Docker/VM**]
        AA1[Action Agent 1 **Go Binary - Docker/VM**]
        SA2[Sensor Agent 2 **Go Binary - Docker/VM**]
        AA2[Action Agent 2 **Go Binary - Docker/VM**]
    end

    subgraph "Plugin Ecosystem"
        GH[GitHub Repos]
        GL[GitLab Repos]
        PR[Private Repos]
    end

    subgraph "Data Layer"
        PG[(PostgreSQL)]
        RD[(Redis)]
    end

    UI --> PrivAPI
    PrivAPI --> WF
    AF --> PubAPI

    %% CRITICAL: All agents connect only to Public API at agents.stavily.com
    SA1 -->|Plugin Config & Updates| PubAPI
    AA1 -->|Plugin Config & Updates| PubAPI
    SA2 -->|Plugin Config & Updates| PubAPI
    AA2 -->|Plugin Config & Updates| PubAPI

    %% API-driven workflow coordination
    PubAPI --> AF
    AF --> WF

    %% Orchestrator manages all plugin repos
    ORC -->|Orchestrator-Managed| GH
    ORC -->|Orchestrator-Managed| GL
    ORC -->|Orchestrator-Managed| PR
    ORC -->|Deploy Plugins| SA1
    ORC -->|Deploy Plugins| AA1

    GPR --> GH
    GPR --> GL
    GPR --> PR
    WF --> PG
    AC --> PG
    AF --> RD

The system architecture overview shows how the Stavily platform is structured, with the orchestrator managing agents deployed in customer environments. Agents connect only to the public API, and plugins are managed through Git repositories for extensibility. The data layer includes PostgreSQL for persistent storage and Redis for caching, supporting the workflow and audit services.

Workflow Paradigm Overview

graph TD
    subgraph "Trigger Sources"
        T1[Prometheus Alert System Monitoring]
        T2[Git Commit Code Changes]
        T3[File Change Configuration Updates]
        T4[API Call External Integration]
        T5[Database Event Data Changes]
        T6[Schedule Time-Based]
    end

    subgraph "Action Logic"
        A1[Restart Service Infrastructure Mgmt]
        A2[Run Tests Quality Assurance]
        A3[Backup Data Data Protection]
        A4[Send Notification Communication]
        A5[Update Config System Adjustment]
        A6[Scale Resources Performance Tuning]
    end

    subgraph "Output Handling"
        O1[Slack Notification Team Alert]
        O2[Email Report Stakeholder Update]
        O3[Log Results Audit Trail]
        O4[Dashboard Update Visibility]
        O5[API Response Integration]
        O6[Alert Escalation Incident Response]
    end

    T1 --> A1
    T2 --> A2
    T3 --> A3
    T4 --> A4
    T5 --> A5
    T6 --> A6

    A1 --> O1
    A2 --> O2
    A3 --> O3
    A4 --> O4
    A5 --> O5
    A6 --> O6

This enhanced workflow paradigm illustrates the comprehensive TRIGGER → ACTION → OUTPUT pattern that powers Stavily’s automation engine. Triggers span monitoring alerts, code changes, API integrations, and scheduled events. Actions include service management, testing, data operations, and notifications. Outputs ensure proper communication, logging, and system updates, enabling robust, event-driven automation across diverse use cases.

Explore Detailed Architecture Sections

Agents Deep dive into Sensor and Action agents architecture, deployment, and communication protocols.

Control Plane Explore the web UI architecture, user interactions, and dashboard functionality.

Orchestrator Understand the core orchestration engine, workflow management, and system coordination.

Plugins Learn about the plugin ecosystem, development framework, and marketplace integration.