# sam-goodwin/alchemy architecture

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

- Interactive diagram: https://gitdiagram.com/sam-goodwin/alchemy
- Repository: https://github.com/sam-goodwin/alchemy

## Overview

##### Project Type and Purpose
- Its purpose is to let developers declare, create, update, and delete cloud and local resources via memoized async functions, running anywhere (node, Bun, browser, serverless, durable workflows).

##### File Structure
- Top-level directories:
- alchemy/             → Core library source
- alchemy-web/         → Documentation website (Vitepress)
- examples/            → Consumer projects demonstrating usage on AWS, Cloudflare, Redwood, Vite, Workers, etc.
- stacks/              → Reusable stack definitions or scripts
- scripts/             → Build and smoke test scripts
- Within alchemy/src:
- Core modules: alchemy.ts, apply.ts, destroy.ts, context.ts, state.ts, secret.ts, env.ts, serde.ts
- Provider modules: aws/, cloudflare/, dns/, fs/, github/, neon/, os/, stripe/, upstash/
- AI tooling: ai/
- Web‐centric helpers: web/ (Astro, Vitepress, Tailwind)
- Internal: internal/docs, util/, test/
- Configuration and CI:
- tsconfig*.json, package.json (core & web), .github/workflows, .gitignore, bun.lock, biome.json

##### README for Additional Insights
- README emphasizes zero dependencies, pure ESM, async-native resources, embeddability, extensibility, AI-first ethos.
- High-level example shows an “app” context, resource function invocation (e.g., `Worker()`), and `app.finalize()`.
- Features list confirms modular provider architecture.

##### Detailed Checklist
– Clear labels for:
- App Context & Lifecycle
- Resource Executor (apply/destroy)
- State Store
- Provider Plugin Interface
- Individual Provider Modules
- Consumer projects & Docs
- Invocation of resource functions
- Read/write of state files
- Plugin registration and execution
- Core vs. Providers vs. Consumers vs. Docs

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Engine
    subgraph "Core Engine"
        direction TB
        AppContext["App Context"]:::core
        Context["Context Manager"]:::core
        Apply["Resource Executor (Apply)"]:::core
        Destroy["Resource Executor (Destroy)"]:::core
        StateManager["State Manager"]:::core
        FileStateStore["File-System State Store"]:::core
        Serde["Serialization/Deserialization"]:::core
    end

    %% Provider Modules
    subgraph "Provider Modules"
        direction TB
        AWS["AWS"]:::provider
        Cloudflare["Cloudflare"]:::provider
        DNS["DNS"]:::provider
        FSProv["FS"]:::provider
        GitHub["GitHub"]:::provider
        Neon["Neon"]:::provider
        OS["OS"]:::provider
        Stripe["Stripe"]:::provider
        Upstash["Upstash"]:::provider
        ESBuild["ESBuild"]:::provider
    end

    %% AI and Web Helpers
    AI["AI Toolkit"]:::ai
    WebHelpers["Web Helpers"]:::providers

    %% Consumers
    subgraph "Consumers & Tools"
        direction TB
        Docs["Web Docs & Site"]:::docs
        Examples["Consumer Examples"]:::consumer
        CLIScripts["CLI Scripts"]:::util
        StackRunners["Stack Runners"]:::util
        Utilities["Utilities"]:::util
        InternalDocs["Internal Docs"]:::util
    end

    %% Relationships
    AppContext -->|"manages lifecycle"| Apply
    AppContext -->|"manages lifecycle"| Destroy
    Apply -->|"writes state"| StateManager
    Destroy -->|"writes state"| StateManager
    StateManager -->|"persists to"| FileStateStore
    Apply -->|"uses interface"| AWS
    Apply -->|"uses interface"| Cloudflare
    Apply -->|"uses interface"| DNS
    Apply -->|"uses interface"| FSProv
    Apply -->|"uses interface"| GitHub
    Apply -->|"uses interface"| Neon
    Apply -->|"uses interface"| OS
    Apply -->|"uses interface"| Stripe
    Apply -->|"uses interface"| Upstash
    Apply -->|"uses interface"| ESBuild
    Destroy -->|"uses interface"| AWS
    Destroy -->|"uses interface"| Cloudflare
    Destroy -->|"uses interface"| DNS
    Destroy -->|"uses interface"| FSProv
    Destroy -->|"uses interface"| GitHub
    Destroy -->|"uses interface"| Neon
    Destroy -->|"uses interface"| OS
    Destroy -->|"uses interface"| Stripe
    Destroy -->|"uses interface"| Upstash
    Destroy -->|"uses interface"| ESBuild
    Serde -->|"serializes data for"| Apply
    Serde -->|"deserializes data for"| Destroy
    AI -->|"generates/modifies providers"| AWS
    AI -->|"generates/modifies providers"| Cloudflare
    AI -->|"generates/modifies providers"| DNS
    AI -->|"generates/modifies providers"| FSProv
    AI -->|"generates/modifies providers"| GitHub
    AI -->|"generates/modifies providers"| Neon
    AI -->|"generates/modifies providers"| OS
    AI -->|"generates/modifies providers"| Stripe
    AI -->|"generates/modifies providers"| Upstash
    AI -->|"generates/modifies providers"| ESBuild
    Docs -->|"imports"| AppContext
    Docs -->|"imports"| Apply
    Docs -->|"imports"| ProviderModules
    Examples -->|"imports"| AppContext
    Examples -->|"imports"| ProviderModules
    CLIScripts -->|"runs via"| AppContext
    StackRunners -->|"runs via"| AppContext
    Utilities -->|"supports"| CoreEngine
    InternalDocs -->|"documents"| CoreEngine

    %% Click Events
    click AppContext "https://github.com/sam-goodwin/alchemy/blob/main/alchemy/src/alchemy.ts"
    click Context "https://github.com/sam-goodwin/alchemy/blob/main/alchemy/src/context.ts"
    click Apply "https://github.com/sam-goodwin/alchemy/blob/main/alchemy/src/apply.ts"
    click Destroy "https://github.com/sam-goodwin/alchemy/blob/main/alchemy/src/destroy.ts"
    click StateManager "https://github.com/sam-goodwin/alchemy/blob/main/alchemy/src/state.ts"
    click FileStateStore "https://github.com/sam-goodwin/alchemy/blob/main/alchemy/src/fs/file-system-state-store.ts"
    click Serde "https://github.com/sam-goodwin/alchemy/blob/main/alchemy/src/serde.ts"
    click AWS "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/aws/"
    click Cloudflare "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/cloudflare/"
    click DNS "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/dns/"
    click FSProv "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/fs/"
    click GitHub "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/github/"
    click Neon "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/neon/"
    click OS "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/os/"
    click Stripe "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/stripe/"
    click Upstash "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/upstash/"
    click ESBuild "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/esbuild/"
    click AI "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/ai/"
    click WebHelpers "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/web/"
    click Docs "https://github.com/sam-goodwin/alchemy/tree/main/alchemy-web/"
    click Examples "https://github.com/sam-goodwin/alchemy/tree/main/examples/"
    click CLIScripts "https://github.com/sam-goodwin/alchemy/tree/main/scripts/"
    click StackRunners "https://github.com/sam-goodwin/alchemy/tree/main/stacks/"
    click Utilities "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/util/"
    click InternalDocs "https://github.com/sam-goodwin/alchemy/tree/main/alchemy/src/internal/docs/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef provider fill:#DFFFD0,stroke:#2e8b57,stroke-width:1px
    classDef consumer fill:#F0F0F0,stroke:#555,stroke-width:1px
    classDef docs fill:#F3D1FF,stroke:#800080,stroke-width:1px
    classDef util fill:#FFE0B2,stroke:#d2691e,stroke-width:1px
    classDef ai fill:#E8D0FF,stroke:#800080,stroke-width:1px
```
