# ikasoba/dejamu architecture

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

- Interactive diagram: https://gitdiagram.com/ikasoba/dejamu
- Repository: https://github.com/ikasoba/dejamu

## Overview

##### Project Type and Purpose
- Dejamu is a static site generator CLI tool written for Deno.
- It initializes a new site, builds static HTML/CSS/JS by processing source files through a plugin pipeline, and can serve the output locally.

##### Top-Level Architectural Components
a. CLI Layer
- Entry point: cli/cli.ts
- Subcommands: build, serve, rebuild (cli/lib/*.ts)
- Generator scripts: cli/generator/*.ts (genBuildCode, genServeCode, etc.)
b. Core Engine
- Context & configuration: core/context.ts, core/Config.ts, core/option.ts
- Feature systems: core/features/* (CacheSystem, FileSystem, PageInfoSystem, usePageInfos)
- Plugin framework: core/plugins/* (Plugin base, plugin registry)
- Resolver subsystem: core/resolver/* (cache, dependency, specifier)
- Pre-build hooks: core/PreBuildScript.ts
c. Plugins
- Markdown, Preact, Twind, PostCSS, Static, Virtual, HotReload
- Each plugin implements a standard interface (extends DejamuPluginBase)
- Plugins live in plugins/* and are loaded dynamically by the core
d. Utils & Dependencies
- Utility modules: utils/*.ts, cli/util/*.ts, scripts/*.ts
- External deps: esbuild, marked, preact-render-to-string, nanoid, etc.
e. Output & Server
- Static files generated to a configured output directory via FileSystem feature
- Local server spun up by cli/lib/serve.ts using Deno’s HTTP API

##### Relationships and Data Flow
- The CLI invokes the generator script for the selected command.
- Generator sets up the Core Context (loads config, plugins, features).
- Core Engine runs the build pipeline:
- Pre-build scripts → Resolver → Feature Systems → Plugin transforms → Output files
- For serve mode, after build, Serve module watches files and uses HTTP server to serve output.
- Rebuild watches for changes, triggers incremental builds using the CacheSystem.

##### Architectural Patterns and Principles
- Plugin architecture: loose coupling via a base plugin interface and dynamic discovery
- Feature-based modularity: separation of concerns (caching, file IO, routing)
- Command pattern: CLI commands map to generator workflows
- Resolver pattern: abstract module resolution (specifier, dependency graph)
- Incremental build: caching layer speeds up rebuilds

##### Technologies, Frameworks, Libraries
- Deno runtime and standard library (fs, http, path)
- esbuild for JS/CSS bundling
- marked for markdown parsing
- preact-render-to-string for server-side rendering
- twind for utility-first CSS
- nanoid for unique IDs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["cli/cli.ts"]:::cli
        BuildCmd["build (cli/lib/build.ts)"]:::cli
        ServeCmd["serve (cli/lib/serve.ts)"]:::cli
        RebuildCmd["rebuild (cli/lib/rebuild.ts)"]:::cli
    end

    %% Generator Scripts
    subgraph "Generator Scripts"
        genBuild["genBuildCode (cli/generator/genBuildCode.ts)"]:::cli
        genServe["genServeCode (cli/generator/genServeCode.ts)"]:::cli
        genRebuild["genRebuildCode (cli/generator/genRebuildCode.ts)"]:::cli
        genContext["genContext (cli/generator/genContext.ts)"]:::cli
        Source["Source (cli/generator/Source.ts)"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine"
        Context["core/context.ts"]:::core
        Config["core/Config.ts"]:::core
        Option["core/option.ts"]:::core
        PreBuild["core/PreBuildScript.ts"]:::core
        subgraph "Resolver Subsystem"
            CacheRes["cache (core/resolver/cache.ts)"]:::core
            DepRes["dependency (core/resolver/dependency.ts)"]:::core
            SpecRes["specifier (core/resolver/specifier.ts)"]:::core
        end
        subgraph "Feature Systems"
            CacheFeat["CacheSystem (core/features/CacheSystem.ts)"]:::core
            FSFeat["FileSystem (core/features/FileSystem.ts)"]:::core
            PageInfoSys["PageInfoSystem (core/features/PageInfoSystem.ts)"]:::core
            UsePageInfos["usePageInfos (core/features/usePageInfos.ts)"]:::core
        end
        subgraph "Plugin Framework"
            BasePlugin["DejamuPluginBase (core/plugins/DejamuPluginBase.ts)"]:::core
            PluginReg["Plugin (core/plugins/Plugin.ts)"]:::core
        end
    end

    %% Plugins
    subgraph "Plugins"
        Md["MarkdownPlugin (plugins/md/MarkdownPlugin.tsx)"]:::plugin
        Preact["PreactPlugin (plugins/preact/PreactPlugin.tsx)"]:::plugin
        Twind["TwindPlugin (plugins/twind/TwindPlugin.tsx)"]:::plugin
        PostCSS["PostCssPlugin (plugins/postcss/PostCssPlugin.ts)"]:::plugin
        StaticP["StaticPlugin (plugins/static/StaticPlugin.ts)"]:::plugin
        Virtual["VirtualPlugin (plugins/virtual/VirtualPlugin.ts)"]:::plugin
        HotReload["HotReloadPlugin (plugins/hotReload/HotReloadPlugin.ts)"]:::plugin
        Asset["Asset (plugins/asset.ts)"]:::plugin
        Head["Head (plugins/Head.tsx)"]:::plugin
        RenderHelper["RenderHelper (plugins/render.tsx)"]:::plugin
    end

    %% Utils & Dependencies
    subgraph "Utils & Dependencies"
        CLIUtils["runDeno/task (cli/util/*.ts)"]:::utils
        GenUtils["utils/*.ts"]:::utils
        ScriptsInit["init (scripts/init.ts)"]:::utils
        ScriptsWelcome["welcome (scripts/welcome-to-dejamu.tsx)"]:::utils
        Deps["deps/*.ts"]:::external
        HTTPDep["http (deps/http.ts)"]:::external
    end

    %% Output & Server
    subgraph "Output & Server"
        OutputFS["FileSystem (core/features/FileSystem.ts)"]:::output
        HTTPServer["HTTP Server (cli/lib/serve.ts)"]:::server
    end

    %% Connections
    CLI -->|invokes| BuildCmd
    CLI -->|invokes| ServeCmd
    CLI -->|invokes| RebuildCmd

    BuildCmd --> genBuild
    ServeCmd --> genServe
    RebuildCmd --> genRebuild

    genBuild --> genContext
    genServe --> genContext
    genRebuild --> genContext
    genContext --> Context

    Context --> Config
    Context --> Option
    Context --> PreBuild
    Context --> CacheRes
    Context --> DepRes
    Context --> SpecRes

    CacheRes --> CacheFeat
    DepRes --> PageInfoSys
    SpecRes --> PageInfoSys
    PageInfoSys --> UsePageInfos

    UsePageInfos --> PluginReg
    PreBuild --> PluginReg
    Config --> PluginReg

    PluginReg --> Md
    PluginReg --> Preact
    PluginReg --> Twind
    PluginReg --> PostCSS
    PluginReg --> StaticP
    PluginReg --> Virtual
    PluginReg --> HotReload
    PluginReg --> Asset
    PluginReg --> Head
    PluginReg --> RenderHelper

    %% Plugin transforms to features
    Md -->|"transform"| FSFeat
    Preact -->|"transform"| FSFeat
    Twind -->|"transform"| FSFeat
    PostCSS -->|"transform"| FSFeat
    StaticP -->|"transform"| FSFeat
    Virtual -->|"transform"| FSFeat
    HotReload -->|"transform"| FSFeat
    Asset -->|"transform"| FSFeat
    Head -->|"transform"| FSFeat
    RenderHelper -->|"transform"| FSFeat

    FSFeat --> OutputFS
    CacheFeat --> CacheFeat

    OutputFS --> HTTPServer
    HTTPServer -->|"serve static"| OutputFS
    HTTPServer -->|"watch files"| CacheFeat
    CacheFeat -.->|triggers rebuild| RebuildCmd

    %% Click Events
    click CLI "https://github.com/ikasoba/dejamu/blob/main/cli/cli.ts"
    click BuildCmd "https://github.com/ikasoba/dejamu/blob/main/cli/lib/build.ts"
    click ServeCmd "https://github.com/ikasoba/dejamu/blob/main/cli/lib/serve.ts"
    click RebuildCmd "https://github.com/ikasoba/dejamu/blob/main/cli/lib/rebuild.ts"
    click genBuild "https://github.com/ikasoba/dejamu/blob/main/cli/generator/genBuildCode.ts"
    click genServe "https://github.com/ikasoba/dejamu/blob/main/cli/generator/genServeCode.ts"
    click genRebuild "https://github.com/ikasoba/dejamu/blob/main/cli/generator/genRebuildCode.ts"
    click genContext "https://github.com/ikasoba/dejamu/blob/main/cli/generator/genContext.ts"
    click Source "https://github.com/ikasoba/dejamu/blob/main/cli/generator/Source.ts"
    click Context "https://github.com/ikasoba/dejamu/blob/main/core/context.ts"
    click Config "https://github.com/ikasoba/dejamu/blob/main/core/Config.ts"
    click Option "https://github.com/ikasoba/dejamu/blob/main/core/option.ts"
    click PreBuild "https://github.com/ikasoba/dejamu/blob/main/core/PreBuildScript.ts"
    click PageInfoSys "https://github.com/ikasoba/dejamu/blob/main/core/features/PageInfoSystem.ts"
    click UsePageInfos "https://github.com/ikasoba/dejamu/blob/main/core/features/usePageInfos.ts"
    click CacheFeat "https://github.com/ikasoba/dejamu/blob/main/core/features/CacheSystem.ts"
    click FSFeat "https://github.com/ikasoba/dejamu/blob/main/core/features/FileSystem.ts"
    click BasePlugin "https://github.com/ikasoba/dejamu/blob/main/core/plugins/DejamuPluginBase.ts"
    click PluginReg "https://github.com/ikasoba/dejamu/blob/main/core/plugins/Plugin.ts"
    click CacheRes "https://github.com/ikasoba/dejamu/blob/main/core/resolver/cache.ts"
    click DepRes "https://github.com/ikasoba/dejamu/blob/main/core/resolver/dependency.ts"
    click SpecRes "https://github.com/ikasoba/dejamu/blob/main/core/resolver/specifier.ts"
    click Md "https://github.com/ikasoba/dejamu/blob/main/plugins/md/MarkdownPlugin.tsx"
    click Preact "https://github.com/ikasoba/dejamu/blob/main/plugins/preact/PreactPlugin.tsx"
    click Twind "https://github.com/ikasoba/dejamu/blob/main/plugins/twind/TwindPlugin.tsx"
    click PostCSS "https://github.com/ikasoba/dejamu/blob/main/plugins/postcss/PostCssPlugin.ts"
    click StaticP "https://github.com/ikasoba/dejamu/blob/main/plugins/static/StaticPlugin.ts"
    click Virtual "https://github.com/ikasoba/dejamu/blob/main/plugins/virtual/VirtualPlugin.ts"
    click HotReload "https://github.com/ikasoba/dejamu/blob/main/plugins/hotReload/HotReloadPlugin.ts"
    click Asset "https://github.com/ikasoba/dejamu/blob/main/plugins/asset.ts"
    click Head "https://github.com/ikasoba/dejamu/blob/main/plugins/Head.tsx"
    click RenderHelper "https://github.com/ikasoba/dejamu/blob/main/plugins/render.tsx"
    click CLIUtils "https://github.com/ikasoba/dejamu/blob/main/cli/util/runDeno.ts"
    click CLIUtils "https://github.com/ikasoba/dejamu/blob/main/cli/util/task.ts"
    click GenUtils "https://github.com/ikasoba/dejamu/blob/main/utils/*.ts"
    click ScriptsInit "https://github.com/ikasoba/dejamu/blob/main/scripts/init.ts"
    click ScriptsWelcome "https://github.com/ikasoba/dejamu/blob/main/scripts/welcome-to-dejamu.tsx"
    click Deps "https://github.com/ikasoba/dejamu/blob/main/deps/*.ts"
    click HTTPDep "https://github.com/ikasoba/dejamu/blob/main/deps/http.ts"
    click HTTPServer "https://github.com/ikasoba/dejamu/blob/main/cli/lib/serve.ts"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0277BD,color:#000;
    classDef core fill:#E0F2F1,stroke:#00796B,color:#000;
    classDef plugin fill:#FFF3E0,stroke:#FB8C00,color:#000;
    classDef utils fill:#F3E5F5,stroke:#8E24AA,color:#000;
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#000;
    classDef output fill:#FFF9C4,stroke:#F9A825,color:#000;
    classDef server fill:#EDE7F6,stroke:#5E35B1,color:#000;
```
