# deco-cx/deco architecture

> Architecture diagram of the GitHub repository deco-cx/deco, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deco-cx/deco
- Repository: https://github.com/deco-cx/deco

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client UI Layer
    subgraph "Client Browser"
        Browser(["Client Browser"]):::client
    end

    %% Editor Subsystem (Blue)
    subgraph "Editor Subsystem"
        DE["Daemon Main Entrypoint\n(daemon/main.ts)"]:::editor
        FW["File Watcher & Git Integration\n(daemon/fs/api.ts, daemon/git.ts)"]:::editor
        CR["CRDT Engine\n(daemon/realtime/crdt/)"]:::editor
        SSE["SSE & HTTP API for Editor\n(daemon/sse/api.ts, daemon/sse/channel.ts)"]:::editor
        WPK["Worker Pool (deno isolates)\n(daemon/workers/denoRun.ts, daemon/workers/isolate.ts)"]:::editor
    end

    %% TypeScript Engine (Green)
    subgraph "TypeScript Engine"
        ENG["Engine Core\n(engine/mod.ts)"]:::engine
        SP["Schema Parser\n(engine/schema/parser.ts)"]:::engine
        SB["Schema Builder\n(engine/schema/builder.ts)"]:::engine
        MB["Manifest Builder\n(engine/manifest/manifestBuilder.ts)"]:::engine
        MG["Manifest Generator\n(engine/manifest/manifestGen.ts)"]:::engine
        IM["ImportMap Builder\n(engine/importmap/builder.ts)"]:::engine
        DF["Decofile Fetcher\n(engine/decofile/fetcher.ts)"]:::engine
        DP["Decofile Provider\n(engine/decofile/provider.ts)"]:::engine
    end

    %% Runtime Server (Orange)
    subgraph "Runtime Server"
        RS["Runtime Server Core\n(runtime/mod.ts)"]:::runtime
        FI["Fresh Integration Plugin\n(runtime/fresh/plugin.ts)"]:::runtime
        IS["Islands\n(runtime/fresh/islands/)"]:::runtime
        HT["HTMX Renderer\n(runtime/htmx/Renderer.tsx)"]:::runtime
        HTM["HTMX Module\n(runtime/htmx/mod.tsx)"]:::runtime
        RH["Render Route\n(runtime/routes/render.tsx)"]:::runtime
        RI["Invoke Route\n(runtime/routes/invoke.ts)"]:::runtime
        RHAN["Handler\n(runtime/handler.tsx)"]:::runtime
        MWL["Liveness Middleware\n(runtime/middlewares/liveness.ts)"]:::runtime
        MWT["General Middleware\n(runtime/middleware.ts)"]:::runtime
        CF["FS Cache Layer\n(runtime/caches/fileSystem.ts)"]:::runtime
        CRD["Redis Cache Layer\n(runtime/caches/redis.ts)"]:::runtime
        CT["Tiered Cache Layer\n(runtime/caches/tiered.ts)"]:::runtime
    end

    %% UI Components (Cyan)
    subgraph "UI Components"
        COMPS["components/"]:::ui
        BLOCKS["blocks/"]:::ui
    end

    %% Observability (Purple)
    subgraph "Observability"
        OI["OTel Config & Context\n(observability/otel/config.ts)"]:::obs
        OC["HTTP Instrumentation\n(observability/http.ts)"]:::obs
        PM["Probes & Metrics\n(observability/probes/reqCount.ts)"]:::obs
        MM["OTel Metrics\n(observability/otel/metrics.ts)"]:::obs
    end

    %% Storage & External Services (Gray)
    subgraph "Storage & External"
        GIT["Git Repository"]:::storage
        EXT["External Services\n(clients/)"]:::storage
        HOST["Hosting Platforms"]:::storage
    end

    %% Plugins & Scripts (Light Gray)
    subgraph "Plugins & Scripts"
        PLUG["Build & Dev Plugins\n(plugins/)"]:::misc
        SCRIPTS["Dev & CI Scripts\n(scripts/)"]:::misc
    end

    %% Connections
    Browser -->|"HTTP: GET/HTMX"| RS
    Browser -->|"SSE /events"| SSE
    Browser -->|"HTTP API"| SSE

    %% Editor Interactions
    FW --> DE
    DE --> FW
    DE --> CR
    DE --> SSE
    DE --> WPK
    DE -->|"git push/pull"| GIT
    DE -->|"build pipeline"| ENG

    %% Engine internals
    ENG --> SP
    ENG --> SB
    ENG --> MB
    ENG --> MG
    ENG --> IM
    ENG --> DF
    ENG --> DP

    %% Runtime uses Engine
    RS -->|"resolve imports/schemas"| ENG
    FI --> RS
    IS --> RS
    HT --> RS
    HTM --> RS
    RH --> RS
    RI --> RS
    RHAN --> RS
    MWL --> RS
    MWT --> RS

    %% Runtime caches
    RS -->|"read/write"| CF
    RS -->|"read/write"| CRD
    RS -->|"read/write"| CT

    %% Runtime external calls
    RHAN -->|"invoke clients"| EXT
    RS --> HOST

    %% Observability flows
    DE --> OC
    DE --> OI
    RS --> OC
    RS --> OI
    OC --> PM
    OI --> MM

    %% Storage
    GIT --> DE

    %% UI layer
    COMPS --> RS
    BLOCKS --> RS
    COMPS --> DE
    BLOCKS --> DE

    %% Plugins & Scripts usage
    PLUG --> ENG
    PLUG --> RS
    SCRIPTS --> DE
    SCRIPTS --> ENG
    SCRIPTS --> RS

    %% Click Events
    click DE "https://github.com/deco-cx/deco/blob/main/daemon/main.ts"
    click FW "https://github.com/deco-cx/deco/blob/main/daemon/fs/api.ts"
    click FW "https://github.com/deco-cx/deco/blob/main/daemon/git.ts"
    click CR "https://github.com/deco-cx/deco/tree/main/daemon/realtime/crdt/"
    click SSE "https://github.com/deco-cx/deco/blob/main/daemon/sse/api.ts"
    click SSE "https://github.com/deco-cx/deco/blob/main/daemon/sse/channel.ts"
    click WPK "https://github.com/deco-cx/deco/blob/main/daemon/workers/denoRun.ts"
    click WPK "https://github.com/deco-cx/deco/blob/main/daemon/workers/isolate.ts"
    click ENG "https://github.com/deco-cx/deco/blob/main/engine/mod.ts"
    click SP "https://github.com/deco-cx/deco/blob/main/engine/schema/parser.ts"
    click SB "https://github.com/deco-cx/deco/blob/main/engine/schema/builder.ts"
    click MB "https://github.com/deco-cx/deco/blob/main/engine/manifest/manifestBuilder.ts"
    click MG "https://github.com/deco-cx/deco/blob/main/engine/manifest/manifestGen.ts"
    click IM "https://github.com/deco-cx/deco/blob/main/engine/importmap/builder.ts"
    click DF "https://github.com/deco-cx/deco/blob/main/engine/decofile/fetcher.ts"
    click DP "https://github.com/deco-cx/deco/blob/main/engine/decofile/provider.ts"
    click RS "https://github.com/deco-cx/deco/blob/main/runtime/mod.ts"
    click FI "https://github.com/deco-cx/deco/blob/main/runtime/fresh/plugin.ts"
    click IS "https://github.com/deco-cx/deco/tree/main/runtime/fresh/islands/"
    click HT "https://github.com/deco-cx/deco/blob/main/runtime/htmx/Renderer.tsx"
    click HTM "https://github.com/deco-cx/deco/blob/main/runtime/htmx/mod.tsx"
    click RH "https://github.com/deco-cx/deco/blob/main/runtime/routes/render.tsx"
    click RI "https://github.com/deco-cx/deco/blob/main/runtime/routes/invoke.ts"
    click RHAN "https://github.com/deco-cx/deco/blob/main/runtime/handler.tsx"
    click MWL "https://github.com/deco-cx/deco/blob/main/runtime/middlewares/liveness.ts"
    click MWT "https://github.com/deco-cx/deco/blob/main/runtime/middleware.ts"
    click CF "https://github.com/deco-cx/deco/blob/main/runtime/caches/fileSystem.ts"
    click CRD "https://github.com/deco-cx/deco/blob/main/runtime/caches/redis.ts"
    click CT "https://github.com/deco-cx/deco/blob/main/runtime/caches/tiered.ts"
    click OI "https://github.com/deco-cx/deco/blob/main/observability/otel/config.ts"
    click OC "https://github.com/deco-cx/deco/blob/main/observability/http.ts"
    click PM "https://github.com/deco-cx/deco/blob/main/observability/probes/reqCount.ts"
    click MM "https://github.com/deco-cx/deco/blob/main/observability/otel/metrics.ts"
    click COMPS "https://github.com/deco-cx/deco/tree/main/components/"
    click BLOCKS "https://github.com/deco-cx/deco/tree/main/blocks/"
    click PLUG "https://github.com/deco-cx/deco/blob/main/plugins/deco.ts"
    click PLUG "https://github.com/deco-cx/deco/blob/main/plugins/fresh.ts"
    click PLUG "https://github.com/deco-cx/deco/blob/main/plugins/styles.ts"
    click SCRIPTS "https://github.com/deco-cx/deco/tree/main/scripts/"

    %% Styles
    classDef editor fill:#D0E8FF,stroke:#0366d6,color:#034694
    classDef engine fill:#E6FFED,stroke:#22863A,color:#176F2C
    classDef runtime fill:#FFECB5,stroke:#D18616,color:#8A4500
    classDef storage fill:#F0F0F0,stroke:#888888,color:#444444
    classDef obs fill:#F5E6FF,stroke:#9F6ADE,color:#6B27AE
    classDef client fill:#CDEFFF,stroke:#2C7BE5,color:#084298
    classDef ui fill:#E0F7FA,stroke:#00ACC1,color:#006064
    classDef misc fill:#F8F9FA,stroke:#6C757D,color:#343A40
```
