# ricardocasares/elm-against-humanity architecture

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

- Interactive diagram: https://gitdiagram.com/ricardocasares/elm-against-humanity
- Repository: https://github.com/ricardocasares/elm-against-humanity

## Overview

##### Project Type and Purpose
- This is a single‐page front‐end application template built with Elm, TypeScript, Vite, TailwindCSS (plus DaisyUI), and Bun as the package/runtime manager.
- It compiles Elm code (src/*.elm) and TS/CSS into a static bundle, serves static JSON “decks” from public/, and runs entirely in the browser.

##### Top‐Level Components
- Source Code
– src/ directory: Elm modules (Main.elm, InteropDefinitions.elm, Translations.elm, etc.) plus supporting main.ts and main.css.
– public/: static JSON assets (deck-*.json) and index.html template.
– tests/: Elm specs for validating logic.
- Configuration
– elm.json, elm-tooling.json: Elm compiler and tooling settings.
– package.json & bun.lockb: JS/TS dependencies.
– vite.config.ts: Vite plugins (Elm, Tailwind/DaisyUI).
- Build & Dev Tools
– Bun: runtime for scripts (bunx, bun dev).
– Vite: dev server, HMR, production build.
– Tailwind/DaisyUI: CSS utility frameworks (driven by main.css).
- CI/CD
– .github/workflows/ci.yml: run Elm tests, linting, build.
– .github/workflows/deploy.yml: publish static bundles to your hosting.

##### System Interactions & Data Flow
a. Developer Workflow
- Code changes in src/ or public/ → Bun/Vite dev server (HMR).
- Elm compiler + Tailwind/DaisyUI plugin produce in‐memory JS + CSS bundle.
- Browser loads index.html → initializes Elm app via JS wrapper (main.ts).
- Elm ports (InteropPorts.elm, InteropDefinitions.elm) bridge Elm ↔ JavaScript for tasks like DOM APIs or localStorage.
- Elm code fetches localized deck JSON from public/ to render content in different languages.
b. Production Build
- Vite uses elm‐plugin and tailwind plugin to compile Elm, TS & CSS → dist/ (static assets).
- CI pipeline runs Elm tests (tests/MainSpec.elm) → If green, triggers deploy.
- Deploy workflow uploads dist/ to static hosting (e.g., Netlify, GitHub Pages).

##### Architectural Patterns & Principles
- Elm Architecture (Model-View-Update) as the core application pattern.
- Ports for well‐defined Elm ↔ JS interop, keeping Elm code pure.
- Single page application: a single index.html loading a self-contained bundle.
- Separation of concerns:
- src/Elm for pure UI logic
- src/TS for bootstrap & interop
- src/CSS + Tailwind for styling
- public/ for static data

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Developer Environment"
        Dev["Developer (IDE/Terminal)"]:::external
        GitHub["GitHub"]:::external
    end

    subgraph "Source Repositories"
        MainElm["Main.elm"]:::code
        InteropDef["InteropDefinitions.elm"]:::code
        InteropPorts["InteropPorts.elm"]:::code
        Translations["Translations.elm"]:::code
        JSBoot["main.ts"]:::code
        CSS["main.css"]:::code
        HTML["index.html"]:::code
        JSONEN["deck-en.json"]:::data
        JSONES["deck-es.json"]:::data
        JSONPL["deck-pl.json"]:::data
        TestSpec["MainSpec.elm"]:::code
        ElmJson["elm.json"]:::config
        ElmTooling["elm-tooling.json"]:::config
        Package["package.json"]:::config
        BunLock["bun.lockb"]:::config
        ViteConfig["vite.config.ts"]:::config
    end

    subgraph "Build System"
        Bun["Bun (bun dev / bunx)"]:::tool
        Vite["Vite (Dev Server & Build)"]:::tool
        ElmComp["Elm Compiler"]:::tool
        Tailwind["Tailwind/DaisyUI Engine"]:::tool
    end

    subgraph "CI/CD"
        CI["GitHub Actions - CI"]:::ci
        DeployWF["GitHub Actions - Deploy"]:::ci
    end

    subgraph "Production Hosting"
        Cloud["Static Hosting"]:::cloud
    end

    subgraph "Runtime (Browser)"
        Browser["Browser"]:::runtime
        ElmApp["Elm App (MVU)"]:::runtime
        Ports["Elm Ports (JS Interop)"]:::runtime
    end

    %% Developer workflow
    Dev -->|"push code"| GitHub
    GitHub --> CI
    Dev -->|"run bun dev"| Bun
    Bun --> Vite
    Vite -->|"compile Elm"| ElmComp
    Vite -->|"process CSS"| Tailwind
    Vite -->|"bundle JS/CSS"| Browser

    %% CI/CD workflow
    CI -->|"run tests"| TestSpec
    CI -->|"build dist"| Vite
    CI --> DeployWF
    DeployWF -->|"upload dist"| Cloud

    %% Runtime interactions
    Browser -->|"loads index.html"| HTML
    HTML -->|"includes bootstrap"| JSBoot
    HTML -->|"includes styles"| CSS
    JSBoot -->|"init Elm app"| ElmApp
    ElmApp <-->|"ports interop"| Ports
    ElmApp -->|"fetch decks"| JSONEN
    ElmApp -->|"fetch decks"| JSONES
    ElmApp -->|"fetch decks"| JSONPL
    Cloud -->|"serves bundle & JSON"| Browser

    %% Click Events
    click MainElm "https://github.com/ricardocasares/elm-against-humanity/blob/main/src/Main.elm"
    click InteropDef "https://github.com/ricardocasares/elm-against-humanity/blob/main/src/InteropDefinitions.elm"
    click InteropPorts "https://github.com/ricardocasares/elm-against-humanity/blob/main/src/InteropPorts.elm"
    click Translations "https://github.com/ricardocasares/elm-against-humanity/blob/main/src/Translations.elm"
    click JSBoot "https://github.com/ricardocasares/elm-against-humanity/blob/main/src/main.ts"
    click CSS "https://github.com/ricardocasares/elm-against-humanity/blob/main/src/main.css"
    click HTML "https://github.com/ricardocasares/elm-against-humanity/blob/main/index.html"
    click JSONEN "https://github.com/ricardocasares/elm-against-humanity/blob/main/public/deck-en.json"
    click JSONES "https://github.com/ricardocasares/elm-against-humanity/blob/main/public/deck-es.json"
    click JSONPL "https://github.com/ricardocasares/elm-against-humanity/blob/main/public/deck-pl.json"
    click TestSpec "https://github.com/ricardocasares/elm-against-humanity/blob/main/tests/MainSpec.elm"
    click ElmJson "https://github.com/ricardocasares/elm-against-humanity/blob/main/elm.json"
    click ElmTooling "https://github.com/ricardocasares/elm-against-humanity/blob/main/elm-tooling.json"
    click Package "https://github.com/ricardocasares/elm-against-humanity/blob/main/package.json"
    click BunLock "https://github.com/ricardocasares/elm-against-humanity/blob/main/bun.lockb"
    click ViteConfig "https://github.com/ricardocasares/elm-against-humanity/blob/main/vite.config.ts"
    click CI "https://github.com/ricardocasares/elm-against-humanity/blob/main/.github/workflows/ci.yml"
    click DeployWF "https://github.com/ricardocasares/elm-against-humanity/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#0284C7
    classDef config fill:#E0F2F4,stroke:#0E7490
    classDef tool fill:#D1FAE5,stroke:#059669
    classDef ci fill:#FFEDD5,stroke:#EA580C
    classDef runtime fill:#FEF9C3,stroke:#CA8A04
    classDef data fill:#E5E7EB,stroke:#6B7280
    classDef external fill:#F3F4F6,stroke:#9CA3AF
    classDef cloud fill:#E0F2F4,stroke:#64748B,font-style:italic,stroke-dasharray: 5 5
```
