# benlf1/littlelink architecture

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

- Interactive diagram: https://gitdiagram.com/benlf1/littlelink
- Repository: https://github.com/benlf1/littlelink

## Overview

##### Project type and purpose
- LittleLink is a minimalist, self-hosted, static “link tree” site generator. It comprises only HTML, CSS, fonts, and images—no build step or front-end framework. It can be served directly via any static-site host or via a simple container.

##### File structure
- Top-level assets:
- index.html, privacy.html – the two pages served
- css/ – style.css (theme logic), reset.css, brands.css (100+ branded button styles)
- fonts/, images/ – static resources
- Config and infra:
- docker/ – Dockerfile, compose.yaml, .dockerignore for containerized hosting
- .github/workflows/contrast-check.yml – CI job for accessibility checks on brand CSS
- No JS source code—pure vanilla HTML/CSS.

##### README insights
- Describes theming (auto/light/dark via CSS variables), accessibility (contrast checks), performance (100/100 metrics), and multiple deploy targets: Vercel, Netlify, Amplify, GitHub Pages, Docker.
- Points out an optional “LittleLink-Server” project for dynamic back-ends, but core is static.

##### Main components & relationships
a. Components
1. Developer Workstation (dev tools, git CLI)
2. GitHub Repository (source: HTML/CSS/fonts/images + Docker assets + CI workflows)
3. Continuous Integration (GitHub Actions: contrast-check.yml)
4. Build/Package Artifact (in this case, just source files; optionally built Docker image)
5. Hosting Environment(s):
– Static-site hosts (Vercel/Netlify/Amplify/GitHub Pages)
– Docker Container (built from docker/Dockerfile, served on localhost:8080 or any container host)
6. CDN/Edge Cache (e.g., automatically provided by Vercel/Netlify)
7. End User Browser (mobile/desktop)
8. External Service: Fathom Analytics (privacy-focused analytics insert)
b. Relationships & Data Flows
– Developer pushes to GitHub → triggers GitHub Actions → runs contrast/accessibility checks → on success, artifacts deployed
– CI (or manual Docker build) → produces Docker image → pushed to container registry (optional) or deployed directly
– Hosting Environment pulls static assets (or container) → serves via CDN
– End User Browser sends HTTP(S) requests → CDN/Host returns HTML/CSS/fonts/images
– Browser executes Fathom Analytics snippet → analytics data sent to Fathom
c. Architectural patterns & principles
– Static-first: no server-side logic, minimal attack surface, excellent performance & caching
– Theming via CSS variables, no JavaScript dependency
– Accessibility as a first-class citizen: CI checks for contrast ratios
– Deploy-anywhere: Git-driven, zero config required beyond dropping files
d. Key technologies
– HTML5, CSS3 (variables, resets)
– Docker (Dockerfile, docker-compose)
– GitHub Actions for CI
– Static-site hosts (Vercel, Netlify, Amplify, GitHub Pages)
– Fathom Analytics

##### Detail without over-splitting
- Every folder’s purpose under “source” (css/, fonts/, images/, pages)
- Docker folder as its own sub-component in the builder step
- Contrast-check CI job as part of quality gates

- Identifies static assets and their flow from dev to end-user
- Shows the CI/CD pipeline and quality checks
- Illustrates multiple hosting options and runtime environments
- Highlights external analytics integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Source Control
    subgraph "Developer Environment" 
        Dev["Developer Workstation"]:::user
    end

    subgraph "GitHub Repository"
        RepoRoot["Repository Root"]:::storage
        subgraph ".github"
            CIWorkflow["contrast-check.yml"]:::ci
            PRTemplate["PULL_REQUEST_TEMPLATE.md"]:::ci
            Funding["FUNDING.yml"]:::ci
        end
        README["README.md"]:::storage
        LICENSE["LICENSE.md"]:::storage
        VersionFile["VERSION.md"]:::storage
        Gitignore[".gitignore"]:::storage
    end

    %% Continuous Integration
    CI["GitHub Actions Runner"]:::compute

    %% Source Assets
    subgraph "Source Assets"
        subgraph "Pages"
            Index["index.html"]:::frontend
            Privacy["privacy.html"]:::frontend
        end
        subgraph "Styles & Theming"
            StyleCSS["style.css"]:::frontend
            ResetCSS["reset.css"]:::frontend
            BrandsCSS["brands.css"]:::frontend
        end
        Fonts["fonts/"]:::storage
        Images["images/"]:::storage
        Icons["icons/"]:::storage
    end

    %% Docker Build Path
    subgraph "Docker Context"
        DockerDir["docker/"]:::compute
        Dockerfile["Dockerfile"]:::compute
        Compose["compose.yaml"]:::compute
        DockerIgnore[".dockerignore"]:::compute
        DockerReadme["README.md"]:::compute
    end
    DockerDir --> Dockerfile
    DockerDir --> Compose
    DockerDir --> DockerIgnore
    DockerDir --> DockerReadme

    %% Build & Deployment
    subgraph "Build & Deployment"
        Artifact["Static Artifact / Docker Image"]:::storage
        Registry["Container Registry (optional)"]:::storage
        StaticHosts["Static-site Hosts"]:::cloud
        ContainerHost["Container Host"]:::cloud
        CDN["CDN / Edge Cache"]:::cloud
    end

    %% End User & External
    Browser["End User Browser"]:::user
    Fathom["Fathom Analytics"]:::external

    %% Relationships
    Dev -->|push code| RepoRoot
    RepoRoot --> CI
    CIWorkflow -.-> CI
    PRTemplate -.-> CI
    CI -->|run contrast checks| CI
    CI -->|on success| Artifact
    RepoRoot --> Artifact
    DockerDir -->|build image| Artifact
    Artifact -->|push| Registry
    Registry -->|deploy container| ContainerHost
    Artifact -->|deploy static files| StaticHosts
    StaticHosts --> CDN
    ContainerHost --> CDN
    CDN -->|serve assets| Browser
    Browser -->|fetch assets| CDN
    Browser -->|send analytics| Fathom

    %% Click Events
    click RepoRoot "https://github.com/benlf1/littlelink/blob/main//.gitignore"
    click README "https://github.com/benlf1/littlelink/blob/main//README.md"
    click LICENSE "https://github.com/benlf1/littlelink/blob/main//LICENSE.md"
    click VersionFile "https://github.com/benlf1/littlelink/blob/main//VERSION.md"
    click CIWorkflow "https://github.com/benlf1/littlelink/blob/main/.github/workflows/contrast-check.yml"
    click PRTemplate "https://github.com/benlf1/littlelink/blob/main/.github/PULL_REQUEST_TEMPLATE.md"
    click Funding "https://github.com/benlf1/littlelink/blob/main/.github/FUNDING.yml"
    click Index "https://github.com/benlf1/littlelink/blob/main//index.html"
    click Privacy "https://github.com/benlf1/littlelink/blob/main//privacy.html"
    click StyleCSS "https://github.com/benlf1/littlelink/blob/main//css/style.css"
    click ResetCSS "https://github.com/benlf1/littlelink/blob/main//css/reset.css"
    click BrandsCSS "https://github.com/benlf1/littlelink/blob/main//css/brands.css"
    click Fonts "https://github.com/benlf1/littlelink/tree/main//fonts/"
    click Images "https://github.com/benlf1/littlelink/tree/main//images/"
    click Icons "https://github.com/benlf1/littlelink/tree/main//images/icons/"
    click Dockerfile "https://github.com/benlf1/littlelink/tree/main//docker/Dockerfile"
    click Compose "https://github.com/benlf1/littlelink/blob/main//docker/compose.yaml"
    click DockerIgnore "https://github.com/benlf1/littlelink/blob/main//docker/.dockerignore"
    click DockerReadme "https://github.com/benlf1/littlelink/blob/main//docker/README.md"

    %% Styles
    classDef frontend fill:#E8F1F2,stroke:#036B76,stroke-width:1px
    classDef compute fill:#D0E6FA,stroke:#1F5FA6,stroke-width:1px
    classDef cloud fill:#DFF7E0,stroke:#2F8F3E,stroke-width:1px
    classDef storage fill:#FFF4D6,stroke:#D99E00,stroke-width:1px
    classDef user fill:#F2E8FA,stroke:#6A1F92,stroke-width:1px
    classDef ci fill:#FDE2E1,stroke:#D93025,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:1px,stroke-dasharray: 2 2
```
