# hamdiheb/bookmarks architecture

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

- Interactive diagram: https://gitdiagram.com/hamdiheb/bookmarks
- Repository: https://github.com/hamdiheb/bookmarks

## Overview

##### Project type + purpose (what you’re diagramming)
This repo is a **small, static frontend web application** (no custom backend) that lets users:
- select one of **five “users”** from a dropdown,
- **read** that user’s bookmarks (reverse chronological),
- **add** a new bookmark via an accessible form,
- **like** bookmarks (persisted),
- **copy** bookmark URLs to clipboard,
- and includes **unit tests**.

##### File structure (map files to components)
Top-level files indicate a simple, module-based frontend:

- `index.html`
The **composition root**: loads CSS and JS, defines DOM structure: dropdown, form, list container, empty-state message region.

- `style.css`

- `script.js`
The **application layer / UI controller**:
- wires DOM event listeners (user selection, form submit, like click, copy click),
- calls storage functions,
- sorts bookmarks by timestamp,
- renders bookmark list and empty state,
- handles accessible UI updates.

- `storage.js`
Provided **data persistence abstraction** with these functions:
- `getUserIds()`
- `getData(userId)`
- `setData(userId, data)`
- `clearData(userId)` (dev helper)

- `example.test.js`
Unit tests (likely Jest). Indicates there’s test tooling and at least one non-trivial function that should be tested (sorting, validation, transformation, etc.).

- `package.json`
Tooling + scripts (tests, local server). Also hints at CI usage and deployment pipeline.

##### What the README adds (architecturally important requirements)
- **No authentication**: user chosen by dropdown only.
- **Per-user data isolation**: bookmarks stored per `userId`.
- **Reverse chronological ordering**: a distinct “sorting/ordering” step.
- **Like count persistence**: part of stored bookmark model (or stored side-channel keyed by bookmark id).
- **Clipboard integration**: uses `navigator.clipboard.writeText(...)`.

##### `script.js` initializes
- calls `getUserIds()`
- populates dropdown
- selects default user (or waits for selection)

##### optional UI feedback (toast/message/aria-live)

From structure + typical setup:
- **HTML + CSS + Vanilla JS (ES Modules)**
- **Browser DOM API**
- **Clipboard API**
- **Provided Storage API (`storage.js`)** (likely LocalStorage-backed)
- **Test runner** (Jest or similar; confirm from `package.json`)
- **Static hosting** (GitHub Pages/Netlify/etc.)
- **Local dev server** (e.g., `http-server`) per README note

Don’t over-rotate on CSS or UI libraries—none are indicated.

##### “Don’t overthink it” but be detailed: how to decompose into many components

- **App Init**
- **User Selector**
- **Bookmarks Repository (adapter over storage.js)**
- **Bookmark Sorting**
- **Bookmark Renderer**
- **Empty State Renderer**
- **Form Handler**
- **Like Handler**
- **Copy Handler (Clipboard integration)**

They can all map back to `script.js` in a note like: “Implemented inside script.js as functions”.

##### Optional but high-value: add a deployment/testing side panel

- Developer pushes to GitHub
- CI runs `npm test`
- On merge to main: deploy to static hosting
- Users access hosted URL

- Context at top
- Container in middle (Browser app + storage + external APIs)
- Component breakdown of `script.js` at bottom

That combination is the most accurate representation of this repo’s architecture and behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================================================
    %% System Context (high-level)
    %% =========================================================
    subgraph "System Context"
        U[/"End User"/]:::actor

        subgraph "End User Device"
            B["Web Browser (Runtime)"]:::external
        end

        H(("Static Hosting Provider")):::infra
        CI(("CI/CD (on merge)")):::infra

        APPCTX["Shared Bookmarks Web App (Static Frontend)"]:::app
        CLIP(("Clipboard API\n(navigator.clipboard.writeText)")):::external
        STORECTX[("Provided Storage API\n(storage.js over browser storage)")]:::storage
    end

    U -->|"selectUser/submit/like/copy"| B
    H -->|"serves static assets\n(index.html, css, js)"| B
    B -->|"executes"| APPCTX
    APPCTX -->|"read/write per-user bookmarks\n(userId, bookmark[])"| STORECTX
    APPCTX -.->|"copy URL"| CLIP
    CI -->|"build/test/deploy"| H

    %% =========================================================
    %% Container View (what runs where)
    %% =========================================================
    subgraph "Runtime Containers (In-Browser)"
        subgraph "Static Frontend (HTML/CSS/Vanilla JS)"
            HTML["App Shell (index.html)"]:::app
            CSS["Styling (style.css)"]:::cssStyle
            JS["App Controller (script.js)"]:::app
        end

        STORE[("Client-side Persistence\n(storage.js wrapper)")]:::storage
        DOM["Browser DOM API"]:::external
        CLIP2(("Clipboard API")):::external
    end

    B -->|"loads"| HTML
    HTML -->|"loads"| CSS
    HTML -->|"loads"| JS
    JS -->|"render/update DOM"| DOM
    JS -->|"getUserIds/getData/setData"| STORE
    JS -.->|"writeText(url)"| CLIP2

    %% =========================================================
    %% Component View (decompose script.js into conceptual modules)
    %% =========================================================
    subgraph "Component Breakdown (Implemented in script.js)"
        INIT["App Init\n(load, initial state)"]:::controller

        subgraph "UI / DOM Layer"
            SEL["User Selector (Dropdown)"]:::ui
            FORM["Add Bookmark Form (Accessible)"]:::ui
            LIST["Bookmarks List Renderer"]:::ui
            EMPTY["Empty State Renderer"]:::ui
            A11Y["Accessible UI Updates\n(status/live region, focus mgmt)"]:::a11y
        end

        subgraph "Event Handlers / Controllers"
            ONUSER["onUserChange(userId)"]:::controller
            ONSUB["onFormSubmit(formData)"]:::controller
            ONLIKE["onLikeClick(bookmarkId/index)"]:::controller
            ONCOPY["onCopyClick(url)"]:::controller
        end

        subgraph "Domain / Logic"
            MODEL["Bookmark Model\n{url,title,description,createdAt,likes,(id?)}"]:::domain
            VALID["validateBookmarkInput(...)"]:::domain
            SORT["sortByCreatedAtDesc(bookmark[])"]:::domain
            HYDR["hydrateRenderModel(...)"]:::domain
        end

        subgraph "Persistence Adapter"
            REPO["Bookmarks Repository\n(adapter over storage.js)"]:::storage
            API["storage.js API\ngetUserIds/getData/setData/clearData"]:::storage
        end
    end

    %% Wiring within components
    INIT -->|"getUserIds()"| REPO
    INIT -->|"populate dropdown"| SEL
    INIT -->|"default/selected userId"| ONUSER

    SEL -->|"change event\n(userId)"| ONUSER
    FORM -->|"submit event\n(formData)"| ONSUB
    LIST -->|"like click\n(bookmarkId/index)"| ONLIKE
    LIST -->|"copy click\n(url)"| ONCOPY

    ONUSER -->|"getData(userId)"| REPO
    ONUSER -->|"sort"| SORT
    ONUSER -->|"transform"| HYDR
    ONUSER -->|"render list"| LIST
    ONUSER -->|"render empty-state"| EMPTY
    ONUSER -->|"announce status"| A11Y

    ONSUB -->|"validate"| VALID
    ONSUB -->|"build bookmark\n(createdAt, likes=0)"| MODEL
    ONSUB -->|"getData(userId)"| REPO
    ONSUB -->|"setData(userId, updated[])"| REPO
    ONSUB -->|"sort"| SORT
    ONSUB -->|"render list/empty"| LIST
    ONSUB -->|"announce status"| A11Y

    ONLIKE -->|"getData(userId)"| REPO
    ONLIKE -->|"increment likes"| MODEL
    ONLIKE -->|"setData(userId, updated[])"| REPO
    ONLIKE -->|"sort + render"| LIST
    ONLIKE -->|"announce status"| A11Y

    ONCOPY -.->|"navigator.clipboard.writeText(url)"| CLIP2
    ONCOPY -->|"announce copied"| A11Y

    REPO -->|"delegates"| API
    API -->|"reads/writes per-user data"| STORE

    %% =========================================================
    %% CI / Test & Deploy (side panel)
    %% =========================================================
    subgraph "Dev Workflow (Tooling + Quality + Deploy)"
        DEV[/"Developer"/]:::actor
        REPOHOST(("Git Repository")):::infra
        PKG["Tooling & Scripts\n(package.json)"]:::infra
        TEST["Unit Tests\n(example.test.js)"]:::test
        DOC["Requirements/Notes\n(README)"]:::infra

        DEV -->|"push PR/merge"| REPOHOST
        REPOHOST -->|"CI triggers"| CI
        CI -->|"npm test"| TEST
        CI -->|"uses scripts"| PKG
        CI -->|"deploy static site"| H
        DOC -.->|"guides CI/hosting requirements"| CI
    end

    %% =========================================================
    %% Click Events (from component_mapping)
    %% =========================================================
    click HTML "https://github.com/hamdiheb/bookmarks/blob/main/index.html"
    click CSS "https://github.com/hamdiheb/bookmarks/blob/main/style.css"
    click JS "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click INIT "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click SEL "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click FORM "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click LIST "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click EMPTY "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click A11Y "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click ONUSER "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click ONSUB "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click ONLIKE "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click ONCOPY "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click MODEL "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click VALID "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click SORT "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click HYDR "https://github.com/hamdiheb/bookmarks/blob/main/script.js"
    click REPO "https://github.com/hamdiheb/bookmarks/blob/main/storage.js"
    click API "https://github.com/hamdiheb/bookmarks/blob/main/storage.js"
    click STORE "https://github.com/hamdiheb/bookmarks/blob/main/storage.js"
    click TEST "https://github.com/hamdiheb/bookmarks/blob/main/example.test.js"
    click PKG "https://github.com/hamdiheb/bookmarks/blob/main/package.json"
    click DOC "https://github.com/hamdiheb/bookmarks/blob/main/README.md"

    %% =========================================================
    %% Styles (color is critical)
    %% =========================================================
    classDef actor fill:#ffffff,stroke:#111827,stroke-width:2,color:#111827
    classDef app fill:#dbeafe,stroke:#1d4ed8,stroke-width:2,color:#0f172a
    classDef ui fill:#bfdbfe,stroke:#1d4ed8,stroke-width:1.5,color:#0f172a
    classDef controller fill:#93c5fd,stroke:#1e40af,stroke-width:2,color:#0f172a
    classDef domain fill:#ede9fe,stroke:#6d28d9,stroke-width:2,color:#0f172a
    classDef storage fill:#ffedd5,stroke:#c2410c,stroke-width:2,color:#0f172a
    classDef external fill:#e5e7eb,stroke:#374151,stroke-width:2,color:#111827
    classDef infra fill:#f3f4f6,stroke:#4b5563,stroke-width:2,color:#111827
    classDef test fill:#dcfce7,stroke:#166534,stroke-width:2,color:#052e16
    classDef cssStyle fill:#fef9c3,stroke:#a16207,stroke-width:2,color:#0f172a
    classDef a11y fill:#cffafe,stroke:#0e7490,stroke-width:2,color:#0f172a
```
