# merge4victor/word-cloud-generator architecture

> Architecture diagram of the GitHub repository merge4victor/word-cloud-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/merge4victor/word-cloud-generator
- Repository: https://github.com/merge4victor/word-cloud-generator

## Overview

##### What this project is (type + purpose)
This is a **single-binary Go web application** that:
- Serves a **browser UI** (HTML/CSS/JS) for uploading/pasting text.
- Exposes an **HTTP JSON API** (`POST /api`) that accepts text and returns data used to render a **word cloud**.
- Uses **Godeps** for dependency pinning (`Godeps/Godeps.json`) and a **Makefile** for build/test/release automation.

So the “system” is primarily: **Browser → Go HTTP server → word cloud generation logic → response (JSON and/or HTML)**. There is no obvious external database or message queue in the tree.

##### Read the file tree as architecture clues
Top-level items mapped to responsibilities:

##### Runtime / application entrypoint
- `main.go` (+ `main_test.go`): app bootstrap; likely HTTP routing, server start on `:8888`, wiring handlers.
- `wordyapi/api.go` (+ tests): core API handler/business logic (word extraction, counting, weighting, output structure).

##### Asset bundling into the binary

- `Makefile`: build orchestration (`make`, `make test`, `make rice`, `make run`, cross-platform artifacts into `./artifacts`).
- `Godeps/`: dependency snapshotting (pre-Go modules workflow).
- `vendor/`: vendored dependencies used by the app at build time.
- `hooks/git-pre-commit.hook`: standardized local dev checks.
- `gauntlt/` (+ `xss.attack`): security testing (likely DAST-style checks) that can be shown as part of the delivery pipeline.

##### Web Browser (Client)
- Loads `GET /` (or similar)
- Submits text via UI (form upload or paste)
- Calls `POST /api` with JSON payload

##### Go Web App (Single Process / Single Binary)
- **HTTP Server / Router** (in `main.go`)
- **UI Handler**
- Renders `templates/upload.tmpl`
- Serves embedded static assets (`static/*`) via go.rice
- **API Handler** (in `wordyapi/api.go`)
- Accepts JSON: `{"text":"..."}`
- Produces response for word cloud (word list + weights/frequencies; exact format inferred)
- **Word Cloud / Text Processing Logic**
- Tokenization, normalization, counting, ranking
- (Even if implemented inside `wordyapi/api.go`, call it out as a logical component)

- As a dependency of the UI Handler:

##### Browser → Go App
- `HTTP GET /` → returns HTML (from `templates/upload.tmpl`)
##### Browser → Go App
- `HTTP POST /api` with `Content-Type: application/json` → returns JSON payload (word list/frequencies)
##### Inside Go App
- Router → UI Handler → Template Renderer → Embedded Templates
- Router → API Handler → Text Processing → JSON Encoder → HTTP Response

If the front-end uses client-side word cloud rendering (likely given `jqcloud.css`), show:
- “JS Word Cloud Renderer” (in Browser) consuming the `/api` response.

##### Important patterns / principles present
- **Single deployable artifact**: one Go binary (daemon on `:8888`)
- **Separation of concerns**:
- `main.go`: wiring + server lifecycle
- `wordyapi/`: API/business logic
- `templates/` + `static/`: presentation assets
- **Embedded static/template assets** using **go.rice** (packaging pattern)

##### Technologies to label
- Language/runtime: **Go**
- Asset bundling: **go.rice**
- Dependency mgmt: **Godeps + vendor/**
- Testing: `*_test.go`, **goconvey** (dev tool)
- Security testing: **gauntlt** (`gauntlt/xss.attack`)
- Build: **Makefile** (cross-platform artifacts)

##### Center: Go Web App (single binary)
- Router/Server
- UI Handler → Templates/Static (embedded)
- API Handler (`wordyapi`) → Text processing
##### Bottom/side: Build & Packaging
- Makefile pipeline (test → rice embed → build artifacts)
- Godeps/vendor feeding compilation
- gauntlt tests as a security gate

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Runtime (Container+Component)
    %% =========================
    U["User"]:::external

    subgraph "Client (Runtime)"
        B["Web Browser"]:::client
        subgraph "Browser UI"
            UIHTML["UI Entry (index.html)"]:::clientComp
            UICSS["Word Cloud Styling (jqcloud.css)"]:::clientComp
            UIRender["JS Word Cloud Renderer"]:::clientComp
        end
    end

    subgraph "Go Web App (Single Binary, HTTP :8888)"
        APP["word-cloud-generator (Go)"]:::server

        subgraph "HTTP Layer"
            Router["HTTP Server / Router (net/http)"]:::serverComp
        end

        subgraph "UI Delivery"
            UIH["UI Handler"]:::serverComp
            Tmpl["Template Renderer"]:::serverComp
            StaticH["Static Assets Handler"]:::serverComp
        end

        subgraph "API"
            APIH["API Handler (POST /api)"]:::api
            TextProc["Word Cloud / Text Processing\n(tokenize/normalize/count/rank)"]:::logic
            JSONEnc["JSON Encoder"]:::serverComp
        end

        subgraph "Embedded Resources (go.rice)"
            RiceBox["Embedded Asset Store (rice-box)"]:::embed
            StaticDir["Static Assets (embedded)"]:::embed
            TmplDir["Templates (embedded)"]:::embed
            UploadTmpl["upload.tmpl"]:::embed
        end
    end

    %% Runtime flows (vertical)
    U -->|"uses"| B
    B -->|"GET /"| Router
    Router -->|"routes"| UIH
    UIH -->|"renders"| Tmpl
    Tmpl -->|"loads"| RiceBox
    RiceBox -->|"reads"| TmplDir
    TmplDir -->|"contains"| UploadTmpl
    Router -->|"routes GET /static/*"| StaticH
    StaticH -->|"loads"| RiceBox
    RiceBox -->|"reads"| StaticDir
    StaticDir -->|"serves"| UIHTML
    StaticDir -->|"serves"| UICSS

    B -->|"POST /api (JSON: {text})"| Router
    Router -->|"routes"| APIH
    APIH -->|"calls"| TextProc
    TextProc -->|"produces word-list+weights"| JSONEnc
    JSONEnc -->|"HTTP 200 (JSON)"| B
    B -->|"renders cloud"| UIRender

    %% =========================
    %% Build / Delivery Pipeline
    %% =========================
    subgraph "Build / Quality / Release"
        Dev["Developer Workstation"]:::tool
        GitHook["Git Pre-commit Hook"]:::tool
        Make["Makefile Pipeline"]:::tool

        subgraph "Build Stages"
            Tests["Unit Tests\n(main_test.go, api_test.go)"]:::toolStep
            RiceGen["Asset Embedding\n(make rice)"]:::toolStep
            Compile["Compile (Go build)"]:::toolStep
            Artifacts["Artifacts Output\n(./artifacts)"]:::toolStep
        end

        subgraph "Dependencies & Pinning"
            Godeps["Godeps Snapshot"]:::deps
            Vendor["Vendored Dependencies"]:::deps
        end

        subgraph "Security Testing"
            Gauntlt["Gauntlt Runner"]:::sec
            XSS["xss.attack Spec"]:::sec
            GauntltDocs["Gauntlt README"]:::sec
        end
    end

    %% Pipeline flows (dashed, vertical)
    Dev -->|"git commit"| GitHook
    GitHook -.->|"runs checks"| Make
    Make -->|"make test"| Tests
    Make -->|"make rice"| RiceGen
    RiceGen -.->|"generates/updates"| RiceBox
    Make -->|"build"| Compile
    Godeps -.->|"pins"| Vendor
    Vendor -.->|"linked into"| Compile
    Compile -->|"outputs"| Artifacts
    Make -->|"security gate"| Gauntlt
    Gauntlt -->|"executes"| XSS
    Gauntlt -.->|"docs/setup"| GauntltDocs

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click Router "https://github.com/merge4victor/word-cloud-generator/blob/master/main.go"
    click UIH "https://github.com/merge4victor/word-cloud-generator/blob/master/main.go"
    click APIH "https://github.com/merge4victor/word-cloud-generator/blob/master/wordyapi/api.go"
    click TextProc "https://github.com/merge4victor/word-cloud-generator/blob/master/wordyapi/api.go"
    click RiceBox "https://github.com/merge4victor/word-cloud-generator/blob/master/rice-box.go"
    click UploadTmpl "https://github.com/merge4victor/word-cloud-generator/blob/master/templates/upload.tmpl"
    click StaticDir "https://github.com/merge4victor/word-cloud-generator/tree/master/static/"
    click UIHTML "https://github.com/merge4victor/word-cloud-generator/blob/master/static/index.html"
    click UICSS "https://github.com/merge4victor/word-cloud-generator/blob/master/static/jqcloud.css"
    click Tests "https://github.com/merge4victor/word-cloud-generator/blob/master/main_test.go"
    click Tests "https://github.com/merge4victor/word-cloud-generator/blob/master/wordyapi/api_test.go"
    click Make "https://github.com/merge4victor/word-cloud-generator/tree/master/Makefile"
    click Godeps "https://github.com/merge4victor/word-cloud-generator/blob/master/Godeps/Godeps.json"
    click Vendor "https://github.com/merge4victor/word-cloud-generator/tree/master/vendor/"
    click GitHook "https://github.com/merge4victor/word-cloud-generator/blob/master/hooks/git-pre-commit.hook"
    click XSS "https://github.com/merge4victor/word-cloud-generator/blob/master/gauntlt/xss.attack"
    click GauntltDocs "https://github.com/merge4victor/word-cloud-generator/blob/master/gauntlt/README.md"

    %% =========================
    %% Styles (color is critical)
    %% =========================
    classDef external fill:#111827,stroke:#374151,color:#F9FAFB,stroke-width:1px
    classDef client fill:#DBEAFE,stroke:#2563EB,color:#0B1220,stroke-width:1px
    classDef clientComp fill:#EFF6FF,stroke:#3B82F6,color:#0B1220,stroke-width:1px

    classDef server fill:#DCFCE7,stroke:#16A34A,color:#052e16,stroke-width:1px
    classDef serverComp fill:#ECFDF5,stroke:#22C55E,color:#052e16,stroke-width:1px
    classDef api fill:#FEF3C7,stroke:#F59E0B,color:#111827,stroke-width:1px
    classDef logic fill:#E0E7FF,stroke:#6366F1,color:#111827,stroke-width:1px
    classDef embed fill:#FFE4E6,stroke:#FB7185,color:#111827,stroke-width:1px

    classDef tool fill:#F3F4F6,stroke:#6B7280,color:#111827,stroke-width:1px
    classDef toolStep fill:#FFFFFF,stroke:#9CA3AF,color:#111827,stroke-width:1px
    classDef deps fill:#E5E7EB,stroke:#4B5563,color:#111827,stroke-width:1px
    classDef sec fill:#FFEDD5,stroke:#F97316,color:#111827,stroke-width:1px
```
