# cloudflare/saffron architecture

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

- Interactive diagram: https://gitdiagram.com/cloudflare/saffron
- Repository: https://github.com/cloudflare/saffron

## Overview

##### Project Type and Purpose
- This is an open-source Rust workspace that implements a cron expression parser and compiler, plus polyglot deliverables:
- saffron – the core parser/compiler crate
- saffron-c – C bindings for embedding in native runtimes (e.g. Cloudflare Workers API)
- saffron-web – WebAssembly build for in-browser UIs (cron dash)
- saffron-worker – Rust Cloudflare Worker fallback endpoint

##### Analyzing the File Structure
- Root contains CI/CD (GitHub Actions), .gitignore, rust-toolchain, LICENSE, README.md
- Top-level workspace members:
- saffron/ (src, benches, examples, fuzz targets)
- saffron-c/ (Cargo.toml, include/saffron.h, cbindgen, src/lib.rs)
- saffron-web/ (Cargo.toml, webpack.config.js, jest.config.js, scripts/wasm-build.mjs, src/lib.rs, tests)
- saffron-worker/ (Cargo.toml, worker code + metadata, wrangler.toml)

##### Key Insights from README
- Two logical layers: Parser (AST/describe) and Compiler (compact representation, O(1) match, future-times iterator)
- Four build targets deliver the same core logic across C, JS/WebAssembly, and Workers

a. Main Components
- Core Parser/Compiler (saffron crate)
- C API Layer (saffron-c)
- WebAssembly Module (saffron-web)
- Edge Worker Service (saffron-worker)
- External Consumers: Browser UI, Cloudflare Runtime, CLI/examples/tests
b. Relationships & Data Flow
- Core library → linked/compiled into each target crate
- Browser UI loads WASM → invokes parse/describe/compile APIs
- Fallback: Browser → HTTP call → saffron-worker on edge → responds with description/validation
- Cloudflare internal Cron Trigger service uses saffron-c bindings in the runtime
c. Architectural Patterns
- Monorepo/workspace with a single source of truth (Rust code)
- Polyglot delivery via language-specific wrappers (C, WASM, Worker)
- Micro-library approach (each crate is a thin adapter around core logic)
d. Key Technologies
- Rust/Cargo workspace, cbindgen for C headers
- wasm-pack/webpack for WebAssembly bundling
- Cloudflare Wrangler for worker deployment
- Jest for Web tests, GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Workspace & CI/CD
    subgraph "Workspace & CI/CD"
        direction TB
        CI["GitHub Actions CI/CD"]:::cloud
        RT["rust-toolchain"]:::config
        GHWF[".github/workflows"]:::cloud
    end

    %% Core Parser/Compiler
    subgraph "Core Parser/Compiler (saffron)" 
        direction TB
        Core["saffron crate"]:::crate
        subgraph "Source Files"
            direction TB
            Lib["lib.rs"]:::file
            Parse["parse.rs"]:::file
            subgraph "describe/"
                direction TB
                DescribeMod["mod.rs"]:::file
                English["english.rs"]:::file
            end
        end
        subgraph "Pipelines & Examples"
            direction TB
            Benches["benches/cron.rs"]:::file
            ExamplesDesc["examples/describe.rs"]:::file
            ExamplesFuture["examples/future-times.rs"]:::file
            Fuzz["fuzz/fuzz_targets/default.rs"]:::file
        end
    end

    %% Polyglot Delivery Crates
    subgraph "C API Layer (saffron-c)"
        direction TB
        CC["saffron-c crate"]:::crate
        CBindgen["cbindgen.toml"]:::file
        Header["include/saffron.h"]:::file
        CSrc["src/lib.rs"]:::file
    end

    subgraph "WebAssembly Module (saffron-web)"
        direction TB
        WASM["saffron-web crate"]:::crate
        WLib["src/lib.rs"]:::file
        BuildScript["scripts/wasm-build.mjs"]:::file
        Webpack["webpack.config.js"]:::file
        JestCfg["jest.config.js"]:::file
        PackageJSON["package.json"]:::file
        Tests["tests/saffron.test.js"]:::file
    end

    subgraph "Edge Worker Service (saffron-worker)"
        direction TB
        WorkerCrate["saffron-worker crate"]:::crate
        WLib2["src/lib.rs"]:::file
        WorkerJS["worker/worker.js"]:::file
        Metadata["worker/metadata_wasm.json"]:::file
        Wrangler["wrangler.toml"]:::file
    end

    %% External Consumers
    Browser["Browser UI"]:::external
    CloudflareRuntime["Cloudflare Runtime"]:::service
    CLIExamples["CLI / Examples / Tests"]:::external

    %% Connections
    CI -->|"build & test"| Core
    RT --> Core
    GHWF --> Core

    Core -->|"links to"| CC
    Core -->|"bundles to WASM"| WASM
    Core -->|"embedded in worker"| WorkerCrate

    Browser -->|"loads WASM & calls parse/describe/compile"| WASM
    Browser -->|"HTTP fallback parse/describe"| WorkerCrate
    CloudflareRuntime -->|"uses C bindings"| CC
    CLIExamples -->|"direct use"| Core

    %% Click Events
    click Lib "https://github.com/cloudflare/saffron/blob/main/saffron/src/lib.rs"
    click Parse "https://github.com/cloudflare/saffron/blob/main/saffron/src/parse.rs"
    click DescribeMod "https://github.com/cloudflare/saffron/blob/main/saffron/src/describe/mod.rs"
    click English "https://github.com/cloudflare/saffron/blob/main/saffron/src/describe/english.rs"
    click Benches "https://github.com/cloudflare/saffron/blob/main/saffron/benches/cron.rs"
    click ExamplesDesc "https://github.com/cloudflare/saffron/blob/main/saffron/examples/describe.rs"
    click ExamplesFuture "https://github.com/cloudflare/saffron/blob/main/saffron/examples/future-times.rs"
    click Fuzz "https://github.com/cloudflare/saffron/blob/main/saffron/fuzz/fuzz_targets/default.rs"
    click CBindgen "https://github.com/cloudflare/saffron/blob/main/saffron-c/cbindgen.toml"
    click Header "https://github.com/cloudflare/saffron/blob/main/saffron-c/include/saffron.h"
    click CSrc "https://github.com/cloudflare/saffron/blob/main/saffron-c/src/lib.rs"
    click WLib "https://github.com/cloudflare/saffron/blob/main/saffron-web/src/lib.rs"
    click BuildScript "https://github.com/cloudflare/saffron/blob/main/saffron-web/scripts/wasm-build.mjs"
    click Webpack "https://github.com/cloudflare/saffron/blob/main/saffron-web/webpack.config.js"
    click JestCfg "https://github.com/cloudflare/saffron/blob/main/saffron-web/jest.config.js"
    click PackageJSON "https://github.com/cloudflare/saffron/blob/main/saffron-web/package.json"
    click Tests "https://github.com/cloudflare/saffron/blob/main/saffron-web/tests/saffron.test.js"
    click WLib2 "https://github.com/cloudflare/saffron/blob/main/saffron-worker/src/lib.rs"
    click WorkerJS "https://github.com/cloudflare/saffron/blob/main/saffron-worker/worker/worker.js"
    click Metadata "https://github.com/cloudflare/saffron/blob/main/saffron-worker/worker/metadata_wasm.json"
    click Wrangler "https://github.com/cloudflare/saffron/blob/main/saffron-worker/wrangler.toml"

    %% Styles
    classDef crate fill:#FFDFAF,stroke:#E27F00,stroke-width:2px
    classDef file fill:#F0F0F0,stroke:#CCCCCC,stroke-width:1px
    classDef folder fill:#E8F4FF,stroke:#2978B5,stroke-width:1px
    classDef cloud fill:#D3F9D8,stroke:#34A853,stroke-width:2px,stroke-dasharray: 5 5
    classDef config fill:#FFF4CF,stroke:#F4B400,stroke-width:1px
    classDef external fill:#FBE7C6,stroke:#EA7600,stroke-width:1px,stroke-dasharray: 2 2
    classDef service fill:#E2F0CB,stroke:#7FB069,stroke-width:1px
```
