# comamoca/blog architecture

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

- Interactive diagram: https://gitdiagram.com/comamoca/blog
- Repository: https://github.com/comamoca/blog

## Overview

##### Main Components
- Content Repository: At the core is the “src” directory, which holds all website source files: markdown blog posts (in src/blog), page templates and layouts (under src/_includes/layouts), React/JSX components (in src/components), and supporting assets (images, style.css).
- Static Site Generator & Build Process: The project uses Deno (indicated by deno.json and deno.lock) along with Lume (as seen in the “plugins/lume” folder). This layer takes markdown content and JSX templates to produce static HTML pages.
- Development Environment and Tools: There are multiple configuration files and scripts (e.g., .envrc, tailwind.config.js, justfile, and Nix configuration files like flake.nix) that support development, formatting, and environment setups.
- CI/CD & Deployment: With a GitHub workflows directory (notably deploy.yaml) and instructions in the README (“nr dev”, “nix develop”), the design includes a continuous integration component that builds and deploys the site, likely to a hosting service (reference to “comamoca.pages.dev”).
- External Services: The README credits Cloudflare, which might be involved in DNS, CDN, or additional edge caching for the deployed site.

##### Relationships and Interactions
- The Source Code (Content, Templates, Components) is fed into the Static Site Generator (powered by Deno/Lume) during the build process.
- The Build Process (which might be triggered locally via “nr dev” or via GitHub Actions) compiles the markdown and template files into static HTML/CSS/JS.
- Deployment happens via the CI/CD pipeline where the generated static site is pushed to the hosting endpoint, possibly using Cloudflare and/or GitHub Pages.
- The development environment is supported by multiple tooling layers (Nix, justfile, scripts) that ensure consistency of builds and usefulness of utilities such as downloading fonts, migrating metadata, or logging.

##### Important Architectural Patterns and Technologies
- Separation of Content and Presentation: Markdown posts are separated from layout templates and React/JSX components.
- Static Site Generation: Use of a Deno-based generator (Lume) to convert markdown and templates into static pages.
- CI/CD Integration: Automated deployment using GitHub Actions.
- Modular Plugin Architecture: Custom plugins under the “plugins” directory to extend functionality (for example, link card generation).
- Use of Modern Tools: TailwindCSS for styling, Nix for reproducible development environments, and tools like “justfile” for task running.

- “Source Repository” containing “src (Content, Templates, Components)”, “assets”, “plugins”, “scripts”, and configuration files.
- “Development Environment” which includes local dev commands (nr dev, nix develop, etc.) and tooling (justfile, Nix configuration).
- “CI/CD Pipeline” representing GitHub workflows (deploy.yaml) that take source changes and trigger builds.
- “Deployment/Hosting” denoting the final deployment destination (e.g., comamoca.pages.dev) possibly tied with external services like Cloudflare.
- From “Source Repository” → “Build Process” → “Generated Static Site” → “Deployment”.

##### Detail

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Repository
    subgraph "Source Repository"
        SRC["Content Repository (src)"]:::source
        ASSETS["Assets (assets)"]:::source
        SCRIPTS["Scripts (scripts)"]:::source
    end

    %% Static Site Generator & Build Process
    subgraph "Static Site Generator & Build Process"
        DENO_JSON["deno.json"]:::build
        DENO_LOCK["deno.lock"]:::build
        LUME["Lume Plugin (plugins/lume)"]:::build
        FOOTNOTE["Footnote Plugin (plugins/lume/footnote.ts)"]:::build
    end

    %% Development Environment and Tools
    subgraph "Development Environment"
        ENVRC[".envrc"]:::dev
        TAILWIND["tailwind.config.js"]:::dev
        JUSTFILE["justfile"]:::dev
        FLKENIX["flake.nix"]:::dev
        FLKLOCK["flake.lock"]:::dev
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        WORKFLOW[".github/workflows/deploy.yaml"]:::cicd
    end

    %% Deployment/Hosting
    subgraph "Deployment/Hosting"
        DEPLOY["Deployment (comamoca.pages.dev)"]:::deploy
        CLOUDFLARE["Cloudflare (DNS/CDN)"]:::deploy
    end

    %% Relationships from Source Repository to Build Process
    SRC -->|"provides content"| LUME
    ASSETS -->|"supplies assets"| LUME
    SCRIPTS -->|"provides utilities"| LUME

    %% Relationships from Development Environment to Build Process
    ENVRC -->|"env setup"| LUME
    TAILWIND -->|"styling config"| LUME
    JUSTFILE -->|"task runner"| LUME
    FLKENIX -->|"Nix config"| LUME
    FLKLOCK -->|"Nix lock"| LUME

    %% Internal Build Process links
    DENO_JSON -->|"Deno config"| LUME
    DENO_LOCK -->|"dependency lock"| LUME
    LUME -->|"plugin extension"| FOOTNOTE

    %% Build Process to CI/CD Pipeline
    LUME -->|"build trigger"| WORKFLOW

    %% CI/CD Pipeline to Deployment
    WORKFLOW -->|"deploy pipeline"| DEPLOY
    WORKFLOW -->|"CDN/DNS integration"| CLOUDFLARE

    %% Click events for Source Repository
    click SRC "https://github.com/comamoca/blog/tree/main/src"
    click ASSETS "https://github.com/comamoca/blog/tree/main/assets"
    click SCRIPTS "https://github.com/comamoca/blog/blob/main/scripts/downloadFonts.ts"

    %% Click events for Static Site Generator & Build Process
    click DENO_JSON "https://github.com/comamoca/blog/blob/main/deno.json"
    click DENO_LOCK "https://github.com/comamoca/blog/blob/main/deno.lock"
    click LUME "https://github.com/comamoca/blog/tree/main/plugins/lume"
    click FOOTNOTE "https://github.com/comamoca/blog/blob/main/plugins/lume/footnote.ts"

    %% Click events for Development Environment and Tools
    click ENVRC "https://github.com/comamoca/blog/blob/main/.envrc"
    click TAILWIND "https://github.com/comamoca/blog/blob/main/tailwind.config.js"
    click JUSTFILE "https://github.com/comamoca/blog/tree/main/justfile"
    click FLKENIX "https://github.com/comamoca/blog/blob/main/flake.nix"
    click FLKLOCK "https://github.com/comamoca/blog/blob/main/flake.lock"

    %% Click event for CI/CD Pipeline
    click WORKFLOW "https://github.com/comamoca/blog/blob/main/.github/workflows/deploy.yaml"

    %% Styles
    classDef source fill:#f9c,stroke:#333,stroke-width:2px;
    classDef build fill:#ccf,stroke:#333,stroke-width:2px;
    classDef dev fill:#cfc,stroke:#333,stroke-width:2px;
    classDef cicd fill:#fc9,stroke:#333,stroke-width:2px;
    classDef deploy fill:#f99,stroke:#333,stroke-width:2px;
```
