How deco-cx/deco works
Project type and purpose
• Deco is a full-stack, Git-based visual CMS and web-app framework for Deno + HTMX + Tailwind.
• It provides:
– A local editor daemon (with real-time CRDT sync, SSE, git integration)
– A rendering/runtime server (Fresh-style SSR routes, HTMX interactivity)
– A TypeScript-driven engine (schema, manifest, import maps)
– A UI layer (Preact/JSX components, Tailwind CSS)
– Observability (OpenTelemetry metrics, traces)
– Caching (file-system, Redis, tiered)
File structure
Top-level directories reveal the architecture:
• daemon/ – local editor process: file watchers, git, SSE, tunnels, CRDT, workers
• engine/ – core TS engine: manifest builder, schema parser, importmap, decofile fetcher
• runtime/ – HTTP server and Fresh integration: routes, islands, middlewares, handlers, fetch wrappers
• blocks/, components/ – reusable building blocks & UI widgets for the editor and runtime
• observability/ – OTel instrumentation, probes, logging
• runtime/caches/ – cache implementation layers (FS, Redis, LRU, tiered)
• plugins/ – Fresh & style plugins for build pipeline
• scripts/ – dev tooling, bundlers, CI/CD, codemods
Key insights from README
• Highlights a visual content editor built on TS Props ↔ UI generator
• Emphasizes real-time staging, immutable releases, roles/permissions
• Lists external hosting options (Deno Deploy, edge providers)
• Mentions a community ecosystem of deco.store apps (Shopify, VTEX, etc.)
Main components
A. Client Browser
– HTMX requests, SSE events, CSS/JS assets, live editor UI
B. Local Editor Daemon
– File-system watcher ↔ Git CLI ↔ CRDT engine ↔ SSE & HTTP API ↔ Tunnel to public URL
– Worker pool (deno run, isolates) for build tasks
C. TypeScript Engine
– Schema parser, manifest builder, importmap generator, decofile fetcher
– Exposed as library to both daemon (build) and runtime (render)
D. Runtime Server
– HTTP server (Fresh) with routes (render, invoke, previews)
– Middlewares (caching, logging, feature flags)
– Render pipeline: server-side JSX → HTML + HTMX
– Cache layers (file system / Redis)
E. Observability
– OTel instrumentation in daemon & runtime
– Metrics & traces → hyperdx or external collector
F. Storage & External Services
– Git repo for site code & content JSON
– External apps/integrations (Shopify, Algolia, etc.)
– Hosting platforms (Deno Deploy, edge hosts)
Relationships & interactions
• Browser ↔ Runtime via HTTP (page loads, HTMX)
• Browser ↔ Daemon via SSE (live updates), HTTP API (editor actions)
• Daemon ↔ Git (commit, push, pull)
• Daemon ↔ Engine (build TS Props → editor schema)
• Runtime ↔ Engine (resolve imports, schemas, manifests at startup)
• Runtime ↔ Cache (read/write cached assets & loader results)
• Handler code ↔ External services (via clients/*.ts modules)
• Both Daemon & Runtime → Observability collector
Architectural patterns & design principles
• Modular monolith subdivided by concern (editor, engine, runtime, observability)
• CRDT + SSE for real-time collaboration in editor
• Pluggable schema & manifest pipeline for type-driven UI
• Fresh/HTMX for minimal JS + progressive enhancement
• Tiered cache abstraction supporting FS & Redis