# lesam24/sams-toolbox architecture

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

- Interactive diagram: https://gitdiagram.com/lesam24/sams-toolbox
- Repository: https://github.com/lesam24/sams-toolbox

## Overview

Sam’s Toolbox is a self-hosted web app for everyday utilities. A user opens the dashboard, selects a tool, and uses its page; the URL shortener additionally creates persisted short codes and redirects visitors while counting clicks. PDF merging and reading are separate workflows, with merging delegated to a PDF utility and reading rendered through a viewer. The README also lists a QR-code generator as coming soon, so it is not represented as a working subsystem. Some client-to-API wiring is not shown in the excerpts and is marked unverified.

Main entry points: [`src/components/layout/DashboardLayout.tsx`](https://github.com/lesam24/sams-toolbox/blob/master/src/components/layout/DashboardLayout.tsx) (Dashboard layout), [`src/app/page.tsx`](https://github.com/lesam24/sams-toolbox/blob/master/src/app/page.tsx) (Tool dashboard), [`src/components/layout/Sidebar.tsx`](https://github.com/lesam24/sams-toolbox/blob/master/src/components/layout/Sidebar.tsx) (Sidebar navigation), [`src/app/tools/pdf-merger/page.tsx`](https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-merger/page.tsx) (Merger page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard and navigation"]
  node_home["Tool dashboard<br/>[page.tsx]"]
  node_catalog["Tool catalog<br/>[tools.ts]"]
  node_shortcuts["Software shortcuts<br/>[shortcuts.ts]"]
  node_shell["Dashboard layout"]
  node_sidebar["Sidebar navigation<br/>[Sidebar.tsx]"]
  node_theme["Theme toggle<br/>[ThemeToogle.tsx]"]
end

subgraph group_pdf["PDF tools"]
  node_mergepage["Merger page<br/>[page.tsx]"]
  node_merger["PDF merger UI<br/>[PdfMerger.tsx]"]
  node_pdfengine["PDF merge engine<br/>[pdf.ts]"]
  node_readerpage["Reader page<br/>[page.tsx]"]
  node_reader["PDF reader UI<br/>[PdfReader.tsx]"]
  node_viewer["PDF viewer<br/>[PdfViewer.tsx]"]
end

subgraph group_urls["URL shortener"]
  node_urlpage["Shortener page<br/>[page.tsx]"]
  node_urlui["Shortener UI<br/>[UrlShortener.tsx]"]
  node_urlapi["URL creation API<br/>[route.ts]"]
  node_redirect["Short-code redirect<br/>[route.ts]"]
end

subgraph group_data["URL persistence"]
  node_urlstore[("Short URL table<br/>[schema.ts]")]
end

node_user(("Tool user"))
node_browserstore[("Browser local storage")]

node_user -->|"opens"| node_home
node_home -->|"lists tools"| node_catalog
node_home -->|"lists shortcuts"| node_shortcuts
node_home -->|"renders in"| node_shell
node_shell -->|"renders"| node_sidebar
node_sidebar -->|"lists tools"| node_catalog
node_sidebar -->|"renders"| node_theme
node_user -.->|"opens"| node_mergepage
node_mergepage -->|"renders in"| node_shell
node_mergepage -->|"renders"| node_merger
node_merger -->|"merges PDFs"| node_pdfengine
node_user -.->|"opens"| node_readerpage
node_readerpage -->|"renders in"| node_shell
node_readerpage -->|"renders"| node_reader
node_reader -->|"renders"| node_viewer
node_user -.->|"opens"| node_urlpage
node_urlpage -->|"renders in"| node_shell
node_urlpage -->|"renders"| node_urlui
node_urlui -.->|"submits URL"| node_urlapi
node_urlapi -->|"checks and inserts"| node_urlstore
node_user -.->|"visits short code"| node_redirect
node_redirect -->|"reads and counts"| node_urlstore
node_theme -->|"saves preference"| node_browserstore

click node_home "https://github.com/lesam24/sams-toolbox/blob/master/src/app/page.tsx"
click node_catalog "https://github.com/lesam24/sams-toolbox/blob/master/src/lib/tools.ts"
click node_shortcuts "https://github.com/lesam24/sams-toolbox/blob/master/src/lib/shortcuts.ts"
click node_shell "https://github.com/lesam24/sams-toolbox/blob/master/src/components/layout/DashboardLayout.tsx"
click node_sidebar "https://github.com/lesam24/sams-toolbox/blob/master/src/components/layout/Sidebar.tsx"
click node_theme "https://github.com/lesam24/sams-toolbox/blob/master/src/components/layout/ThemeToogle.tsx"
click node_mergepage "https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-merger/page.tsx"
click node_merger "https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-merger/PdfMerger.tsx"
click node_pdfengine "https://github.com/lesam24/sams-toolbox/blob/master/src/lib/pdf.ts"
click node_readerpage "https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-reader/page.tsx"
click node_reader "https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-reader/PdfReader.tsx"
click node_viewer "https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-reader/PdfViewer.tsx"
click node_urlpage "https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/url-shortener/page.tsx"
click node_urlui "https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/url-shortener/UrlShortener.tsx"
click node_urlapi "https://github.com/lesam24/sams-toolbox/blob/master/src/app/api/urls/route.ts"
click node_redirect "https://github.com/lesam24/sams-toolbox/blob/master/src/app/%5Bcode%5D/route.ts"
click node_urlstore "https://github.com/lesam24/sams-toolbox/blob/master/src/lib/db/schema.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_catalog,node_shortcuts,node_shell,node_sidebar,node_theme,node_user toneBlue
class node_mergepage,node_merger,node_pdfengine,node_readerpage,node_reader,node_viewer,node_browserstore toneAmber
class node_urlpage,node_urlui,node_urlapi,node_redirect toneMint
class node_urlstore toneRose
```

## Components

### Dashboard and navigation

- [Tool dashboard](https://github.com/lesam24/sams-toolbox/blob/master/src/app/page.tsx): `src/app/page.tsx`
- [Tool catalog](https://github.com/lesam24/sams-toolbox/blob/master/src/lib/tools.ts): `src/lib/tools.ts`
- [Software shortcuts](https://github.com/lesam24/sams-toolbox/blob/master/src/lib/shortcuts.ts): `src/lib/shortcuts.ts`
- [Dashboard layout](https://github.com/lesam24/sams-toolbox/blob/master/src/components/layout/DashboardLayout.tsx): `src/components/layout/DashboardLayout.tsx`
- [Sidebar navigation](https://github.com/lesam24/sams-toolbox/blob/master/src/components/layout/Sidebar.tsx): `src/components/layout/Sidebar.tsx`
- [Theme toggle](https://github.com/lesam24/sams-toolbox/blob/master/src/components/layout/ThemeToogle.tsx): `src/components/layout/ThemeToogle.tsx`

### PDF tools

- [Merger page](https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-merger/page.tsx): `src/app/tools/pdf-merger/page.tsx`
- [PDF merger UI](https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-merger/PdfMerger.tsx): `src/app/tools/pdf-merger/PdfMerger.tsx`
- [PDF merge engine](https://github.com/lesam24/sams-toolbox/blob/master/src/lib/pdf.ts): `src/lib/pdf.ts`
- [Reader page](https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-reader/page.tsx): `src/app/tools/pdf-reader/page.tsx`
- [PDF reader UI](https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-reader/PdfReader.tsx): `src/app/tools/pdf-reader/PdfReader.tsx`
- [PDF viewer](https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/pdf-reader/PdfViewer.tsx): `src/app/tools/pdf-reader/PdfViewer.tsx`

### URL shortener

- [Shortener page](https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/url-shortener/page.tsx): `src/app/tools/url-shortener/page.tsx`
- [Shortener UI](https://github.com/lesam24/sams-toolbox/blob/master/src/app/tools/url-shortener/UrlShortener.tsx): `src/app/tools/url-shortener/UrlShortener.tsx`
- [URL creation API](https://github.com/lesam24/sams-toolbox/blob/master/src/app/api/urls/route.ts): `src/app/api/urls/route.ts`
- [Short-code redirect](https://github.com/lesam24/sams-toolbox/blob/master/src/app/%5Bcode%5D/route.ts): `src/app/[code]/route.ts`

### URL persistence

- [Short URL table](https://github.com/lesam24/sams-toolbox/blob/master/src/lib/db/schema.ts): `src/lib/db/schema.ts`

### Other components

- **Tool user**
- **Browser local storage**

## Connections

- Tool user → Tool dashboard: opens (evidence: `README.md`)
- Tool dashboard → Tool catalog: lists tools (evidence: `src/app/page.tsx`)
- Tool dashboard → Software shortcuts: lists shortcuts (evidence: `src/app/page.tsx`)
- Tool dashboard → Dashboard layout: renders in (evidence: `src/app/page.tsx`)
- Dashboard layout → Sidebar navigation: renders (evidence: `src/components/layout/DashboardLayout.tsx`)
- Sidebar navigation → Tool catalog: lists tools (evidence: `src/components/layout/Sidebar.tsx`)
- Sidebar navigation → Theme toggle: renders (evidence: `src/components/layout/Sidebar.tsx`)
- Tool user → Merger page: opens
- Merger page → Dashboard layout: renders in (evidence: `src/app/tools/pdf-merger/page.tsx`)
- Merger page → PDF merger UI: renders (evidence: `src/app/tools/pdf-merger/page.tsx`)
- PDF merger UI → PDF merge engine: merges PDFs (evidence: `src/app/tools/pdf-merger/PdfMerger.tsx`)
- Tool user → Reader page: opens
- Reader page → Dashboard layout: renders in (evidence: `src/app/tools/pdf-reader/page.tsx`)
- Reader page → PDF reader UI: renders (evidence: `src/app/tools/pdf-reader/page.tsx`)
- PDF reader UI → PDF viewer: renders (evidence: `src/app/tools/pdf-reader/PdfReader.tsx`)
- Tool user → Shortener page: opens
- Shortener page → Dashboard layout: renders in (evidence: `src/app/tools/url-shortener/page.tsx`)
- Shortener page → Shortener UI: renders (evidence: `src/app/tools/url-shortener/page.tsx`)
- Shortener UI → URL creation API: submits URL
- URL creation API → Short URL table: checks and inserts (evidence: `src/app/api/urls/route.ts`)
- Tool user → Short-code redirect: visits short code
- Short-code redirect → Short URL table: reads and counts (evidence: `src/app/[code]/route.ts`)
- Theme toggle → Browser local storage: saves preference (evidence: `src/components/layout/ThemeToogle.tsx`)
