# kevanmacgee/linkboard architecture

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

- Interactive diagram: https://gitdiagram.com/kevanmacgee/linkboard
- Repository: https://github.com/kevanmacgee/linkboard

## Overview

##### Project Type & Purpose
- Project Type: Single‐Page Application (SPA) delivered purely as static HTML/CSS/JS.
- Purpose: Let users create, categorize, drag‐and‐drop bookmarks, export/import data, and optionally install via a bookmarklet. Data lives in browser localStorage; favicon URLs are fetched from the web.

##### File Structure
- Root files (.gitignore, README.md) document status, features, issues.
- app/index.html: core SPA.
- app/linkboardResetData.json + test JSON files: sample data for import/restore.
- variants/*.html: design iterations of the same SPA.
- app/*.md and screenshots/: documentation & visuals.

##### Key Components to Model
a. Browser UI Layer
- HTML/CSS/JS loaded in the user’s browser tab (index.html).
- DOM module: renders columns/categories and links.
- Drag‐and‐drop handler module.
- Import/export module.

b. Data Layer
- Browser localStorage (persistent key–value store).
- JSON data (export/import).

c. External Services
- Favicon fetcher: HTTP requests to external domains (e.g., “https://www.google.com/s2/favicons?domain=…”).
- (Future) REST API + Database for persistence.
- (Optional) CDN/hosting layer (e.g., Cloudflare Pages) serving the static assets.

d. Bookmarklet Wrapper
- Tiny JS snippet injected into arbitrary sites.
- Loads the hosted index.html or JS payload.

##### Relationships & Data Flows
- User → Browser UI: click “Add link”, drag events → triggers JavaScript controllers.
- UI ↔ localStorage: read on load, write on add/edit/move/delete.
- UI → External Favicon Service: fetch favicon URLs for each new link.
- UI ↔ JSON Import/Export: serialize/deserialize localStorage state.
- Bookmarklet → UI loader: when invoked on any page, loads the index.html script.

##### Architectural Patterns & Principles
- SPA pattern: all UI logic lives in the client.
- MVC‐style separation at a high level:
- Model = JSON data in localStorage
- View = HTML/CSS templates in the DOM
- Controller = JS event handlers (add, drag, import/export)
- Future layering: move Model to server‐side REST API + DB.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User((User)):::actor
    Bookmarklet(("Bookmarklet Wrapper")):::client

    %% Browser Client-Side Modules
    subgraph "Browser UI Layer" 
        UIModule["UI Module\n(index.html)"]:::ui
        DOM["DOM Renderer"]:::ui
        Drag["DragDrop Controller"]:::ui
        ImportExport["Import/Export Service"]:::ui
    end

    %% Storage
    LocalStorage[(Browser localStorage)]:::storage
    ResetData["linkboardResetData.json"]:::storage
    Malicious["malicious-test.json"]:::storage
    Normal["normal-test.json"]:::storage
    Numeric["numeric-test.json"]:::storage

    %% External Services
    FaviconService(["Favicon Service\n(https://www.google.com/s2/favicons)"]):::external
    CDN["CDN/Hosting"]:::external
    RESTAPI["REST API (future)"]:::future

    %% Static Hosting Assets
    subgraph "Static Hosting (CDN/Hosting)" 
        Variants["Design Variants"]:::external
        README["README.md"]:::external
        Summary["LinkBoard-App-Summary.md"]:::external
        AppSummary["app-summary_102125_0149.txt"]:::external
        Gitignore[".gitignore"]:::external
        Issues["Codex_Top_3_Issues_102025.md"]:::external
        Report1["code-evaluation-report-2025-10-09.md"]:::external
        Report2["code-evaluation-report-2025-10-20.md"]:::external
        Screenshots["Screenshots"]:::external
        BookmarkletHost["Bookmarklet Payload"]:::external
    end

    %% Relationships
    User -->|"clicks, drag events"| UIModule
    Bookmarklet -->|"loads SPA"| UIModule

    UIModule -->|"render UI"| DOM
    UIModule -->|"setup drag/drop"| Drag
    UIModule -->|"import/export actions"| ImportExport
    UIModule -->|"saveLink()/load()"| LocalStorage
    ImportExport -->|"reads/writes JSON"| ResetData
    ImportExport -->|"reads/writes JSON"| Malicious
    ImportExport -->|"reads/writes JSON"| Normal
    ImportExport -->|"reads/writes JSON"| Numeric
    UIModule -->|"GET favicon URL"| FaviconService
    UIModule -->|"future persistence"| RESTAPI

    %% Hosting relationships
    CDN --> UIModule
    CDN --> DOM
    CDN --> Drag
    CDN --> ImportExport
    CDN --> ResetData
    CDN --> Malicious
    CDN --> Normal
    CDN --> Numeric
    CDN --> Variants
    CDN --> README
    CDN --> Summary
    CDN --> AppSummary
    CDN --> Gitignore
    CDN --> Issues
    CDN --> Report1
    CDN --> Report2
    CDN --> Screenshots
    CDN --> BookmarkletHost

    %% Click Events
    click UIModule "https://github.com/kevanmacgee/linkboard/blob/master/app/index.html"
    click Variants "https://github.com/kevanmacgee/linkboard/tree/master/variants/"
    click ResetData "https://github.com/kevanmacgee/linkboard/blob/master/app/linkboardResetData.json"
    click Malicious "https://github.com/kevanmacgee/linkboard/blob/master/app/malicious-test.json"
    click Normal "https://github.com/kevanmacgee/linkboard/blob/master/app/normal-test.json"
    click Numeric "https://github.com/kevanmacgee/linkboard/blob/master/app/numeric-test.json"
    click README "https://github.com/kevanmacgee/linkboard/blob/master/README.md"
    click Summary "https://github.com/kevanmacgee/linkboard/blob/master/LinkBoard-App-Summary.md"
    click AppSummary "https://github.com/kevanmacgee/linkboard/blob/master/app/app-summary_102125_0149.txt"
    click Gitignore "https://github.com/kevanmacgee/linkboard/blob/master/.gitignore"
    click Issues "https://github.com/kevanmacgee/linkboard/blob/master/Codex_Top_3_Issues_102025.md"
    click Report1 "https://github.com/kevanmacgee/linkboard/blob/master/app/code-evaluation-report-2025-10-09.md"
    click Report2 "https://github.com/kevanmacgee/linkboard/blob/master/app/code-evaluation-report-2025-10-20.md"
    click Screenshots "https://github.com/kevanmacgee/linkboard/tree/master/screenshots/"
    click BookmarkletHost "https://github.com/kevanmacgee/linkboard/blob/master/variants/linkboard_index.html"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef storage fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef future fill:#fff3cd,stroke:#856404,color:#856404
    classDef actor fill:#f8f9fa,stroke:#343a40,color:#343a40
    classDef client fill:#cfe2ff,stroke:#084298,color:#084298
```
