⚡ Zerops Copilot

"Break free from infrastructure drag." An AI operations copilot and visual control plane for your Zerops projects — inspect, understand and generate infrastructure through a beautiful dashboard and a natural-language assistant backed by the real Zerops CLI.

Built for The Zerops Challenge (WeMakeDevs, Aug 8–9 2026).

---

✨ What it does

Feature	What you see
Architecture Map	Your live Zerops project rendered as an interactive topology graph — frontend → API → databases → caches, with health status, CPU/RAM usage, animated connections and a scanline "mission control" feel. Click any service to inspect containers, ports, env vars and live runtime logs.
Copilot Chat	A Gemini-powered assistant with function calling that executes the real zcli against your account. Ask "show me my projects", "any errors in my api logs?", "how much am I using?" — every answer shows the exact command that ran (e.g. zcli service log -P … -S …).
Recipe Studio	Describe an app in plain English — "a RAG chatbot with vector search" — and get a complete, validated Zerops import recipe with a visual architecture preview, one copy away from deployment.
Live + Demo modes	Connect your own Zerops token for live introspection, or explore with a built-in deterministic demo workspace so the demo never breaks.

🏗 Architecture (4 services on Zerops — the app runs on the platform it manages)

                ┌─────────────────────────────────────────────┐
   Browser ───▶ │ web   (Next.js 15 runtime)                 │
                │   · dashboard UI                          │
                │   · proxies /api → api (same-origin)      │
                └──────────────────┬──────────────────────────┘
                                   │ HTTP (internal)
                ┌──────────────────▼──────────────────────────┐
                │ api   (Node.js 22)                          │
                │   · Gemini function-calling loop            │
                │   · serialized zcli executor (real CLI)     │
                │   · recipe engine (YAML generation)         │
                └───────┬─────────────────────────┬───────────┘
                        │ SQL                       │ cache / sessions
                ┌───────▼──────────┐        ┌───────▼──────────┐
                │ db (PostgreSQL)  │        │ cache (Valkey)   │
                │  · chat history  │        │  · zcli result   │
                │  · settings      │        │    caching       │
                └──────────────────┘        └──────────────────┘

• PostgreSQL — chat history + project state (via pg; falls back to in-memory locally).
• Valkey (Redis) — TTL caching of zcli reads so repeated "show projects" calls are fast (via ioredis).
• zcli, serialized — the API shells out to the real @zerops/zcli (node bin/zcli.js), queued behind a mutex because concurrent zcli runs collide on Windows state files. This is how the Copilot reads your actual projects.
• Gemini (function calling) — 5 tools: list_projects, get_project_architecture, get_service_logs, get_project_usage, generate_recipe. Each tool maps to a real zcli invocation surfaced in the UI as a command stream.

🔑 How Zerops is used (judging notes)

• 4 separate services (web, api, db, cache) wired through private networking env refs (${db_hostname}, ${cache_hostname}…) — no hard-coded endpoints.
• Dogfooding: this repository is a Zerops recipe. zerops-project-import.yml provisions the whole project; each app service has its own zerops.yaml with readinessCheck, initCommands (npm ci --omit=dev) and multi-container-ready configs.
• Deep platform integration: the product manages the platform via its own official CLI — not a mock.

🤖 AI disclosure

• Gemini (Google AI Studio API, free tier, gemini-2.5-flash) powers Copilot Chat and recipe generation via function calling.
• AI coding assistants (Claude/Codebuff-style agent) were used extensively to write this codebase; every feature was verified by running the API, CLI probes and production builds locally.
• The recipe engine validates AI output and falls back to curated templates — AI suggestions never bypass validation.

🚀 Run it locally

npm install
cp .env.example apps/api/.env.local     # add ZEROPS_TOKEN / GEMINI_API_KEY
npm run dev                               # API on :4000, dashboard on :3000

Open http://localhost:3000 → click Connect (Zerops PAT from settings/token-management) or use Demo Mode.

🛰 Deploy to Zerops (the fun part)

zcli login <token>
zcli project project-import                          # creates web+api+db+cache
zcli push web --zerops-yaml-path apps/web/zerops.yaml
zcli push api --zerops-yaml-path apps/api/zerops.yaml

Then in the Zerops GUI: open the api service → env vars → add ZEROPS_TOKEN (and optionally GEMINI_API_KEY). The dashboard will then show itself on the architecture map. 🤯

🧱 Monorepo layout

apps/web        Next.js dashboard (Tailwind v4, hand-rolled SVG architecture graph)
apps/api        Express API — zcli executor, Gemini loop, recipe engine, storage
packages/shared TypeScript contract shared by both apps
zerops-project-import.yml   project recipe (4 services)
apps/*/zerops.yaml          per-service build/deploy pipelines

📜 License

MIT — hackathon project, have fun with it.