Stackly

Inspiration

It's easy to spin up infrastructure, but over time, resources stack and become too many layers to navigate.

The documentation problem compounds every time something goes wrong. An incident happens, someone needs to understand the topology fast, and the most current "documentation" is a Slack message from eight months ago. Runbooks, if they exist, reference resource names that have since changed. The engineer on call is reverse-engineering the infrastructure in real time.

Stackly was built around a specific question: what if connecting your DigitalOcean account could produce a complete, accurate, immediately useful documentation package — health assessment, cost breakdown, compliance report, runbooks, resource catalog — without anyone having to write a single line of it?

What It Does

Stackly is a web app and AI agent system. The web app handles the user interface, authentication, and scan management. The agent handles the actual work — querying the DigitalOcean API, analyzing what it finds, and generating the documentation. The two systems communicate over a REST API; the agent runs independently on DigitalOcean Gradient ADK.

Core Capabilities:

One-click DigitalOcean connection — Stackly uses DigitalOcean's OAuth flow. Users click Connect, authorize access in the DigitalOcean dashboard, and are redirected back.

Configurable scope discovery — Users choose which resource categories to include in a scan: compute (Droplets, Kubernetes clusters), storage (Volumes, Spaces buckets), networking (Load Balancers, Firewalls, Reserved IPs, Domains), and databases (managed PostgreSQL, MySQL, Redis, MongoDB).

Weighted compliance scoring — Five compliance checks run against every applicable resource: automated backups, monitoring alert policies, firewall coverage, SSL/TLS configuration, and resource tagging.

Environment-aware cost attribution — Monthly costs are extracted from each resource's size metadata and grouped two ways: by resource type (compute, storage, networking, databases) and by environment (production, staging, development, untagged — inferred from resource tags). Idle resources are identified separately: powered-off Droplets, Volumes with no attached Droplet, Reserved IPs with no assigned Droplet. These appear as a dedicated list with their monthly cost, making the quick wins obvious.

LLM-grounded resource assessment — Every resource in the inventory is sent to the language model with its actual state data — status, tags, region, purpose, size. The model returns a one-to-two sentence operational assessment and a pass/warning/fail rating for each one. A Droplet that's powered off gets a fail. A database with no tags in a production account gets a warning. The assessments are grounded in what the resource actually is, not generic advice.

Executive Summary — Generated in both HTML and Markdown. The HTML version renders a health score gauge, cost breakdown bars, compliance check results, resource inventory table, and two Chart.js charts (cost by type, health score by resource type) — all built from the scan data, no manual input.

Resource Catalog — Every discovered resource in a single table: type, name, ID, region, status, inferred purpose, monthly cost, tags, LLM rating, and LLM assessment. Available in four formats from the same underlying data: a searchable HTML page with a live filter, a styled Excel workbook with alternating row fills, a CSV for import into any tool, and a JSON file for programmatic use.

Operational Runbooks — Four runbooks generated by the LLM using the actual resource names and IDs from the scan: Disaster Recovery Procedure, Scaling Production Environment, Database Backup and Restore, and New Developer Access Setup.

Infrastructure Slideshow — An 8-slide interactive HTML presentation built from the scan data: Overview, Compute, Storage, Networking, Databases, Security and Compliance, Cost Analysis, and Recommendations. The LLM writes each slide's bullets using actual metrics — not "infrastructure is healthy" but "3 of 5 production Droplets have no monitoring configured." Charts are rendered with Chart.js. The slideshow is keyboard-navigable and self-contained.

Full deliverables bundle — Every generated file — two summary formats, four catalog formats, two runbook formats, the slideshow, and the raw scan JSON — packaged into a single stackly_report.zip download.

Contextual AI assistant — A chat interface that knows the scan.

Live scan progress — Scans stream progress updates to the frontend via Server-Sent Events.

How It Was Built

Stackly is two independently deployed systems that communicate over HTTP.

Frontend and API — The frontend is React with Vite, TypeScript, Tailwind CSS, and TanStack Query for server state. The backend is Node.js with Express and better-sqlite3. Both are deployed on DigitalOcean App Platform as separate components behind a shared ingress

Agent architecture — The Python agent runs on Gradient ADK and exposes a single run entrypoint. The action field in the request payload determines the role: scan triggers the full three-phase pipeline, assist routes to the AI assistant. The agent is stateless between calls — all intermediate data is written to DigitalOcean Spaces under a scans/{scan_id}/ prefix and read back by each subsequent phase.

Three-phase scan pipeline — Phase one: the discovery agent calls the DigitalOcean API with the OAuth token from the request, builds the full resource inventory, and writes inventory.json to Spaces. Phase two: the analyzer agent reads the inventory, runs compliance checks, calculates weighted health scores, attributes costs by type and environment, identifies unused resources, and calls the LLM for per-resource assessments, then writes analysis.json. Phase three: the documentation generator reads both files and produces all nine deliverables, uploading each to Spaces and returning a manifest of signed URLs.

LLM calls — All model calls go through the Gradient client, which wraps the OpenAI-compatible API.

HTML generation — All HTML deliverables share a single Python format-string shell that embeds the Stackly design system.

Document formats — Excel files are built with openpyxl: styled column headers, alternating row fills, auto-sized column widths. CSV files use Python's csv.DictWriter. The ZIP bundle is assembled in memory with zipfile.ZipFile — each deliverable is downloaded from Spaces and written into the archive, then the archive is uploaded back to Spaces in a single write.

Data persistence — SQLite via better-sqlite3 stores projects, scans, resources, and health checks. The schema migrates at startup. When a scan completes, the agent's result is written back to the scans table — resource count, health score, duration, and deliverable URLs stored as a metadata row in the resources table.

What It Solves

Compliance gaps are invisible until they cause an incident — A Droplet with no backup policy looks identical to one with backups in the dashboard. A load balancer forwarding HTTP instead of HTTPS doesn't announce itself. Stackly runs five compliance checks across every resource on every scan and surfaces failures by name and severity, before they become the reason something is down at 2am.

Runbooks rot — A runbook written when the infrastructure was set up references resource names, IDs, and connection strings that may have changed a dozen times since. Stackly generates runbooks from the current scan data — the doctl commands use the actual Droplet IDs and cluster names that exist right now, not the ones that existed when someone last updated a Confluence page.

Sharing infrastructure context is expensive — Explaining the infrastructure to a new engineer, an auditor, a board member, or an investor requires pulling data from multiple places and assembling it into something coherent. Stackly produces a shareable package — HTML reports, Excel catalog, slideshow — that communicates the full picture without requiring the person who built it to be in the room.

Who It's For

Engineering leads who want a current, honest assessment of their infrastructure's health and cost without spending an afternoon in the dashboard.

DevOps and SRE engineers who need compliance visibility, cost attribution, and production-ready runbooks without building the tooling themselves.

CTOs and founders preparing for board meetings, investor diligence, or SOC 2 audits who need infrastructure documentation that reflects reality, not a snapshot from six months ago.

New engineers joining a team who need to understand what's running, where, and why — without a two-hour walkthrough from the person who built it.

Agencies and consultants managing DigitalOcean infrastructure for multiple clients who need a repeatable, automated way to produce documentation and health reports for each account.

Use Cases

Incident post-mortem A database connection failure takes down a production service for 40 minutes. During the post-mortem, the team runs a Stackly scan to document the infrastructure state at the time of the incident. The compliance section surfaces that the affected database cluster had no monitoring alert policy configured — the failure wasn't detected until a user reported it. The finding goes into the post-mortem as a P1 action item, with the runbook step for configuring alert policies already written.

New team member onboarding A backend engineer joins a four-person startup. On day one, the engineering lead shares the latest Stackly scan. The new engineer reads the executive summary to understand the topology — two production Droplets behind a load balancer, one managed PostgreSQL cluster, one Redis instance, Spaces for file storage. They use the resource catalog to find the specific resource IDs and regions they'll need. They follow the New Developer Access Setup runbook to configure SSH keys, database credentials, and firewall rules. They're productive by the end of the day.

What's Next

Scan scheduling — Run scans automatically on a daily, weekly, or monthly cadence. Receive a notification when the health score drops below a threshold or a new compliance failure appears.

Scan diffing — Compare any two scans side by side: new resources, removed resources, health score delta, cost change, compliance regressions. Useful for tracking the impact of infrastructure changes over time.

Multi-account management — Connect multiple DigitalOcean accounts under a single Stackly workspace. Generate per-account reports or a consolidated view across all accounts.

Terraform export — Generate a Terraform configuration from the discovered resources. Useful for teams that want to move toward infrastructure-as-code without starting from scratch.