🏗️ SymphonyDesk Architecture Overview

SymphonyDesk is a modern, cloud-backed automation platform designed to execute secure, repeatable IT runbooks across customer environments. It combines cloud orchestration, lightweight on-prem runners, and dynamic PowerShell automation into a single cohesive system that scales elegantly from small IT teams to enterprise-grade workloads.

This document provides a high-level yet technically grounded overview of SymphonyDesk’s architecture, core components, and the engineering principles that make it a robust and reliable automation solution.

⚙️ Core Design Principles

SymphonyDesk is built around five core engineering values:

1. Simplicity

Installation and management require no infrastructure beyond a single lightweight runner and a cloud API.

2. Security

Strict API key isolation, tenant separation, and digitally controlled runbook delivery ensure customers’ automations remain protected.

3. Reliability

Every job is tracked end-to-end with timeouts, log aggregation, automatic retries, and resilient communication loops.

4. Extensibility

Runbooks are dynamically synced from a central repository, enabling continuous delivery of new automation capabilities.

5. Transparency

Every job, heartbeat, and runner status update is stored and surfaced to the UI for real-time observability.

🧩 System Components

SymphonyDesk consists of three cooperating subsystems:

1. Cloud Control Plane (API + Dashboard)

The SymphonyDesk API is built on FastAPI, chosen for its speed, async I/O performance, and strong type validation. It provides:

API Responsibilities

Authentication & tenant isolation
Runbook queuing & job lifecycle
Runbook manifest distribution
Runner heartbeats
Job logs, statuses and audit visibility
Dashboard metrics (success rates, runner uptime, job volume)

Data Storage

The cloud API stores:

/jobs/               -> queued and completed job metadata  
/runner_status/      -> last heartbeat per runner  
CLIENT_API_KEYS_JSON -> tenant-level API keys  
RUNNER_AUTH_KEY      -> runner authentication key

Storage is optimized for simplicity and resiliency in early product stages, with an upgrade path to relational or object storage as scale increases.

Tenant & Key Isolation

SymphonyDesk enforces absolute multi-tenant separation:

Client API keys are tied to a specific customer.
Runner keys authenticate only runners, never client calls.
All /run requests have customer identifiers forced server-side to eliminate spoofing.

This design prevents cross-tenant job execution by construction.

2. SymphonyRunner (On-Prem Execution Engine)

The SymphonyRunner is a lightweight Windows agent built in PowerShell 7. It securely executes automation tasks inside customer environments.

Why PowerShell 7?

Native cross-platform compatibility
Full modern security model
Improved module ecosystem
Superior job isolation and error handling

Runner Responsibilities

Authenticating to SymphonyDesk
Polling for new jobs
Executing PowerShell runbooks in a sandboxed process
Streaming logs back to the control plane
Sending periodic heartbeats
Syncing updated runbooks from manifest metadata
Enforcing safety controls like timeouts and log truncation

Execution Safety Features

Process-level timeouts eliminate infinite hangs
Output capture via redirected stdout/stderr ensures full transparency
Per-job file isolation prevents contamination across runs
Automatic log truncation prevents runaway output from crashing UI
Retry-friendly RPC layer uses robust error handling

Runner Footprint

The runner installs under:

C:\SymphonyDesk\Runner\

with subdirectories:

Runbooks\   -> dynamically downloaded scripts  
Logs\       -> job logs, runner logs, stdout/stderr captures

The runner can be deployed manually or through packaged installer (MSI/EXE) and requires no backend database, message bus, or privileged services.

3. Runbook Delivery & Versioning Layer

SymphonyDesk uses a manifest-driven architecture to keep runbooks synchronized across all customer runners.

Runbook Manifest

The API provides:

GET /runbooks/manifest?customer={id}

Each manifest entry describes:

{
  "name": "ACT-CreateRemoteMailbox",
  "version": 1,
  "checksum": "",
  "download_url": "https://raw.githubusercontent.com/.../ACT-CreateRemoteMailbox.ps1"
}

Dynamic Syncing

The runner automatically:

Downloads new runbooks
Updates changed runbooks
Persists metadata locally
Supports multiple runbook sources

This enables continuous delivery of new automations without reinstalling agents or redeploying infrastructure.

Future versions will support:

Private runbook storage (Blob/S3)
Encrypted runbooks
Customer-specific runbook routing
Parameter schemas for UI-generated forms

🔄 Job Lifecycle

A SymphonyDesk job passes through these phases:

Client → /run → Queue → Runner → Execute → Upload Logs → Complete

1. Job Submission

Jobs can be triggered from:

API integrations
Web UI
Internal systems

Jobs always specify:

runbook
parameters {}
customer

2. Queueing

Jobs are stored under a durable /jobs/ directory with:

metadata
timestamps
execution flags

3. Runner Polling

Runners ask:

GET /jobs/next?customer=Contoso

and only receive jobs for their tenant.

4. Execution

Runner executes via:

pwsh.exe -File <runbook.ps1> -Param Value

Capturing:

stdout
stderr
exit code
timing

5. Completion Callback

Runner sends results to:

POST /jobs/complete

including:

logs
success/failure
output
timestamps

6. UI Visibility

Dashboard presents:

job history
success rates
log output
runbook metadata
runner health

📊 Observability & Monitoring

SymphonyDesk provides real-time operational insights:

Runner Monitoring

last heartbeat
online/offline status
runner IP
customer association

Job Monitoring

queue depth
job duration
success/failure tracking
full execution logs

Platform Metrics

total jobs
today’s activity
failure rates
per-customer statistics

🔐 Security Overview

SymphonyDesk integrates several strong security patterns:

1. Strict API Key Separation

Client API Keys → submit jobs
Runner Key → poll/execute jobs
Never interchangeable

2. Tenant Isolation

Customer identifiers enforced server-side.

3. No Inbound Connections Required

Runners only make outbound HTTPS calls.
Zero firewall complexity.

4. Least Privilege Execution

Runner executes under local least-privilege context.
Runbooks can assume elevated contexts only when configured.

5. No Stored Credentials

Credentials are injected at runtime or via secure environment variables.

6. Auditable

All job invocations, parameters, logs, and completions are persisted.

🚀 Why SymphonyDesk Is Exceptional

SymphonyDesk combines features normally found in expensive enterprise automation platforms:

✔ Zero Infrastructure Required

Everything works with:

One runner
One cloud API
No queues, brokers, or databases needed

✔ Fully Tenant-Isolated

Architected from day one for multi-customer SaaS.

✔ Dynamic Runbook Delivery

Update automation globally without touching agents.

✔ Safe, Reliable Execution

With:

Timeouts
Log truncation
Sandboxed execution
Structured reporting

✔ Built for the Real World

🏁 Conclusion

SymphonyDesk is not just another scripting system — it is a carefully engineered automation platform built for modern IT teams who want power, simplicity, and rock-solid reliability. From its manifest-driven runbook system to its secure multi-tenant cloud control plane, SymphonyDesk provides the foundation for scalable automation at any organization.

It is a fast, safe, and flexible platform that grows as your automation requirements grow.