# abhayb97/slide-deck-visualizer architecture

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

- Interactive diagram: https://gitdiagram.com/abhayb97/slide-deck-visualizer
- Repository: https://github.com/abhayb97/slide-deck-visualizer

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application with a split between:
     - **public-facing UI pages**
     - **admin ingestion pages**
     - **server API routes**
     - a small **server-side processing/persistence layer** in `lib/`

2. **Primary domain model**
   - The repository is centered on **CSV-driven data ingestion** and the generation of several derived artifacts:
     - **snapshots**
     - **current lists**
     - **history**
     - **leaderboard data**
   - Those derived datasets are what the UI reads through API routes rather than directly from files.

3. **User-facing pages**
   - `app/page.jsx` is the root entry page.
   - `app/leaderboard/page.tsx` displays leaderboard content.
   - `app/draw/slot-machine/page.tsx` is a specialized interactive view backed by `components/SlotMachine.tsx`.
   - `app/SlideDeckVisualizer.jsx` suggests a secondary visualization component, likely for presenting generated content in a slide-like format.

4. **Admin ingestion surface**
   - `app/admin/upload/page.tsx` and `app/admin/upload-master/page.tsx` are separate admin entry points.
   - The split implies two different upload workflows:
     - **CSV upload / snapshot creation**
     - **master data upload / master processing**
   - This is the main boundary where human-managed input enters the system.

5. **API layer as the public server boundary**
   - The `app/api/*/route.ts` files form the service interface for both UI and admin workflows.
   - Key endpoints:
     - `upload-csv`, `process-csv`, `snapshot`
     - `process-master`
     - `current-lists`, `history`, `latest-snapshot`, `leaderboard`
   - The architecture is typical “thin API route, shared library logic”: routes orchestrate requests and delegate the actual work to `lib/`.

6. **Processing pipeline**
   - `lib/processCsvSnapshot.ts` and `lib/processMaster.ts` hold the core transformation logic.
   - These modules likely convert uploaded CSV/master files into normalized application data.
   - `app/api/process-csv` and `app/api/process-master` are the server endpoints that invoke those transforms.
   - This is the main compute boundary in the repo: raw input becomes structured, queryable state.

7. **Storage and persistence**
   - `lib/storage.ts` and `lib/objectStorage.ts` indicate a persistence abstraction rather than direct file handling in routes.
   - The presence of `scripts/migrate-vercel-blob-to-object-storage.mjs` shows the project previously used **Vercel Blob** and now stores data in an **object storage backend**.
   - That migration script is an important architectural clue: storage is externalized and treated as a replaceable infrastructure layer.

8. **Derived-data access layer**
   - `lib/snapshots.ts`, `lib/lists.ts`, and `lib/history.ts` encapsulate read/write behavior for the main datasets.
   - The corresponding API routes expose these as queryable resources:
     - latest snapshot
     - current lists
     - historical records
     - leaderboard
   - This suggests the UI mostly consumes precomputed state instead of computing it client-side.

9. **Frontend/data flow**
   - The typical flow is:
     1. admin uploads CSV or master data
     2. API route accepts the request
     3. `lib/process*` transforms the input
     4. `lib/storage` / `lib/objectStorage` persists the result
     5. read APIs expose the resulting snapshot/list/history/leaderboard
     6. pages/components render from those APIs
   - This is a classic ingestion → processing → persistence → read-model architecture.

10. **Static assets and templates**
   - `public/templates/snapshot-template.csv` is a user-facing input template, likely used to standardize uploads.
   - Its presence reinforces that CSV format is part of the system contract, not just an implementation detail.

11. **Runtime and framework boundaries**
   - The project is TypeScript-first in the App Router layer (`.tsx` route/page files) with some JavaScript (`app/page.jsx`, `SlideDeckVisualizer.jsx`).
   - Styling is handled through `app/globals.css` and PostCSS.
   - The architecture is server-rendered Next.js with API routes, not a separate backend service.

12. **What to show in an architecture diagram**
   - A good diagram should include these boxes and arrows:
     - **Admin UI** → **upload/process API routes** → **processing lib** → **object storage**
     - **Public UI pages/components** → **read API routes** → **snapshot/list/history/leaderboard lib** → **object storage**
     - **Migration script** → **object storage**
   - The key separation is between:
     - **interactive presentation**
     - **server-side transformation**
     - **persistent object storage**

Main entry points: [`lib/lists.ts`](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/lists.ts) (Lists), [`lib/storage.ts`](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/storage.ts) (Storage), [`lib/snapshots.ts`](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/snapshots.ts) (Snapshots), [`lib/processCsvSnapshot.ts`](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/processCsvSnapshot.ts) (CSV Processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["UI"]
  node_node_home["Home<br/>page<br/>[page.jsx]"]
  node_node_leaderboard_page["Leaderboard<br/>page<br/>[page.tsx]"]
  node_node_draw_page["Slot Machine<br/>page<br/>[page.tsx]"]
  node_node_admin_upload["CSV Upload<br/>admin page<br/>[page.tsx]"]
  node_node_admin_master_upload["Master Upload<br/>admin page<br/>[page.tsx]"]
  node_node_visualizer["Deck Visualizer"]
  node_node_slot_machine["Slot Machine<br/>[SlotMachine.tsx]"]
end

subgraph group_group_api["API"]
  node_node_upload_csv_api["Upload CSV<br/>route<br/>[route.ts]"]
  node_node_process_csv_api["Process CSV<br/>route<br/>[route.ts]"]
  node_node_process_master_api["Process Master<br/>route<br/>[route.ts]"]
  node_node_snapshot_api["Snapshot<br/>route<br/>[route.ts]"]
  node_node_current_lists_api["Current Lists<br/>route<br/>[route.ts]"]
  node_node_history_api["History<br/>route<br/>[route.ts]"]
  node_node_latest_snapshot_api["Latest Snapshot<br/>route<br/>[route.ts]"]
  node_node_leaderboard_api["Leaderboard API<br/>route<br/>[route.ts]"]
end

subgraph group_group_core["Core"]
  node_node_process_csv["CSV Processor<br/>transform"]
  node_node_process_master["Master Processor<br/>transform<br/>[processMaster.ts]"]
  node_node_snapshots["Snapshots<br/>dataset helper<br/>[snapshots.ts]"]
  node_node_lists["Lists<br/>dataset helper<br/>[lists.ts]"]
  node_node_history["History Store<br/>dataset helper<br/>[history.ts]"]
  node_node_storage[("Storage<br/>persistence<br/>[storage.ts]")]
  node_node_object_storage[("Object Storage<br/>backend adapter<br/>[objectStorage.ts]")]
end

subgraph group_group_infra["Infra"]
  node_node_template["CSV Template<br/>asset"]
  node_node_migration["Storage Migration<br/>script"]
end

node_node_admin_upload -->|"upload"| node_node_upload_csv_api
node_node_admin_upload -->|"process"| node_node_process_csv_api
node_node_admin_master_upload -->|"process"| node_node_process_master_api
node_node_process_csv_api -->|"invoke"| node_node_process_csv
node_node_process_master_api -->|"invoke"| node_node_process_master
node_node_upload_csv_api -->|"persist"| node_node_storage
node_node_process_csv -->|"write"| node_node_snapshots
node_node_process_csv -->|"write"| node_node_lists
node_node_process_master -->|"write"| node_node_lists
node_node_process_master -->|"write"| node_node_history
node_node_snapshots -->|"use"| node_node_storage
node_node_lists -->|"use"| node_node_storage
node_node_history -->|"use"| node_node_storage
node_node_storage -->|"backend"| node_node_object_storage
node_node_snapshot_api -->|"read/write"| node_node_snapshots
node_node_current_lists_api -->|"read"| node_node_lists
node_node_history_api -->|"read"| node_node_history
node_node_latest_snapshot_api -->|"read"| node_node_snapshots
node_node_leaderboard_api -->|"read"| node_node_lists
node_node_home -->|"consume"| node_node_latest_snapshot_api
node_node_leaderboard_page -->|"consume"| node_node_leaderboard_api
node_node_draw_page -->|"render"| node_node_slot_machine
node_node_draw_page -->|"render"| node_node_visualizer
node_node_visualizer -->|"consume"| node_node_latest_snapshot_api
node_node_template -->|"guide"| node_node_upload_csv_api
node_node_migration -->|"migrate"| node_node_object_storage

click node_node_home "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/page.jsx"
click node_node_leaderboard_page "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/leaderboard/page.tsx"
click node_node_draw_page "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/draw/slot-machine/page.tsx"
click node_node_admin_upload "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/admin/upload/page.tsx"
click node_node_admin_master_upload "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/admin/upload-master/page.tsx"
click node_node_visualizer "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/SlideDeckVisualizer.jsx"
click node_node_slot_machine "https://github.com/abhayb97/slide-deck-visualizer/blob/main/components/SlotMachine.tsx"
click node_node_upload_csv_api "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/upload-csv/route.ts"
click node_node_process_csv_api "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/process-csv/route.ts"
click node_node_process_master_api "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/process-master/route.ts"
click node_node_snapshot_api "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/snapshot/route.ts"
click node_node_current_lists_api "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/current-lists/route.ts"
click node_node_history_api "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/history/route.ts"
click node_node_latest_snapshot_api "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/latest-snapshot/route.ts"
click node_node_leaderboard_api "https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/leaderboard/route.ts"
click node_node_process_csv "https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/processCsvSnapshot.ts"
click node_node_process_master "https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/processMaster.ts"
click node_node_snapshots "https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/snapshots.ts"
click node_node_lists "https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/lists.ts"
click node_node_history "https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/history.ts"
click node_node_storage "https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/storage.ts"
click node_node_object_storage "https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/objectStorage.ts"
click node_node_template "https://github.com/abhayb97/slide-deck-visualizer/blob/main/public/templates/snapshot-template.csv"
click node_node_migration "https://github.com/abhayb97/slide-deck-visualizer/blob/main/scripts/migrate-vercel-blob-to-object-storage.mjs"

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_node_home,node_node_leaderboard_page,node_node_draw_page,node_node_admin_upload,node_node_admin_master_upload,node_node_visualizer,node_node_slot_machine toneBlue
class node_node_upload_csv_api,node_node_process_csv_api,node_node_process_master_api,node_node_snapshot_api,node_node_current_lists_api,node_node_history_api,node_node_latest_snapshot_api,node_node_leaderboard_api toneAmber
class node_node_process_csv,node_node_process_master,node_node_snapshots,node_node_lists,node_node_history,node_node_storage,node_node_object_storage toneMint
class node_node_template,node_node_migration toneRose
```

## Components

### UI

Public and admin Next.js entry points and visual components.

- [Home](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/page.jsx): page · Root public entry page. · `app/page.jsx`
- [Leaderboard](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/leaderboard/page.tsx): page · Public leaderboard view. · `app/leaderboard/page.tsx`
- [Slot Machine](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/draw/slot-machine/page.tsx): page · Interactive draw visualization page. · `app/draw/slot-machine/page.tsx`
- [CSV Upload](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/admin/upload/page.tsx): admin page · Admin entry for CSV ingestion and snapshot creation. · `app/admin/upload/page.tsx`
- [Master Upload](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/admin/upload-master/page.tsx): admin page · Admin entry for master data ingestion. · `app/admin/upload-master/page.tsx`
- [Deck Visualizer](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/SlideDeckVisualizer.jsx): Secondary presentation component for generated content. · `app/SlideDeckVisualizer.jsx`
- [Slot Machine](https://github.com/abhayb97/slide-deck-visualizer/blob/main/components/SlotMachine.tsx): Interactive component used by the draw page. · `components/SlotMachine.tsx`

### API

Server route handlers that expose ingest and read-model operations.

- [Upload CSV](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/upload-csv/route.ts): route · API route for accepting CSV uploads. · `app/api/upload-csv/route.ts`
- [Process CSV](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/process-csv/route.ts): route · API route that triggers CSV snapshot processing. · `app/api/process-csv/route.ts`
- [Process Master](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/process-master/route.ts): route · API route that triggers master-data processing. · `app/api/process-master/route.ts`
- [Snapshot](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/snapshot/route.ts): route · API route for snapshot operations. · `app/api/snapshot/route.ts`
- [Current Lists](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/current-lists/route.ts): route · API route exposing current list data. · `app/api/current-lists/route.ts`
- [History](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/history/route.ts): route · API route exposing historical records. · `app/api/history/route.ts`
- [Latest Snapshot](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/latest-snapshot/route.ts): route · API route exposing the most recent snapshot. · `app/api/latest-snapshot/route.ts`
- [Leaderboard API](https://github.com/abhayb97/slide-deck-visualizer/blob/main/app/api/leaderboard/route.ts): route · API route exposing leaderboard data. · `app/api/leaderboard/route.ts`

### Core

Processing, persistence, and domain read/write helpers in lib/.

- [CSV Processor](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/processCsvSnapshot.ts): transform · Core CSV-to-snapshot transformation logic. · `lib/processCsvSnapshot.ts`
- [Master Processor](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/processMaster.ts): transform · Core master-data transformation logic. · `lib/processMaster.ts`
- [Snapshots](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/snapshots.ts): dataset helper · Read/write helper for snapshot records. · `lib/snapshots.ts`
- [Lists](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/lists.ts): dataset helper · Read/write helper for current list data. · `lib/lists.ts`
- [History Store](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/history.ts): dataset helper · Read/write helper for historical data. · `lib/history.ts`
- [Storage](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/storage.ts): persistence · Storage abstraction used by application logic. · `lib/storage.ts`
- [Object Storage](https://github.com/abhayb97/slide-deck-visualizer/blob/main/lib/objectStorage.ts): backend adapter · Object-storage implementation behind the storage abstraction. · `lib/objectStorage.ts`

### Infra

Static templates and migration tooling around storage.

- [CSV Template](https://github.com/abhayb97/slide-deck-visualizer/blob/main/public/templates/snapshot-template.csv): asset · Template CSV used to standardize uploads. · `public/templates/snapshot-template.csv`
- [Storage Migration](https://github.com/abhayb97/slide-deck-visualizer/blob/main/scripts/migrate-vercel-blob-to-object-storage.mjs): script · Migration script from Vercel Blob to object storage. · `scripts/migrate-vercel-blob-to-object-storage.mjs`

## Connections

- CSV Upload → Upload CSV: upload · Admin upload flow submits CSV data to the upload API.
- CSV Upload → Process CSV: process · Admin workflow can trigger CSV processing after upload.
- Master Upload → Process Master: process · Admin master workflow triggers master-data processing.
- Process CSV → CSV Processor: invoke · CSV API delegates transformation to the core processor.
- Process Master → Master Processor: invoke · Master API delegates transformation to the core processor.
- Upload CSV → Storage: persist · Uploaded input is stored through the persistence abstraction.
- CSV Processor → Snapshots: write · CSV processing produces snapshot records.
- CSV Processor → Lists: write · CSV processing updates current list data.
- Master Processor → Lists: write · Master processing updates list-oriented data.
- Master Processor → History Store: write · Master processing contributes historical records.
- Snapshots → Storage: use · Snapshot helper stores and retrieves data via storage.
- Lists → Storage: use · List helper stores and retrieves data via storage.
- History Store → Storage: use · History helper stores and retrieves data via storage.
- Storage → Object Storage: backend · Storage abstraction is implemented by object storage.
- Snapshot → Snapshots: read/write · Snapshot route serves snapshot state through the helper.
- Current Lists → Lists: read · Current-lists route serves list data through the helper.
- History → History Store: read · History route serves historical data through the helper.
- Latest Snapshot → Snapshots: read · Latest-snapshot route reads from snapshot state.
- Leaderboard API → Lists: read · Leaderboard route derives its response from list data.
- Home → Latest Snapshot: consume · Public entry page reads the latest generated snapshot.
- Leaderboard → Leaderboard API: consume · Leaderboard page renders data from the leaderboard API.
- Slot Machine → Slot Machine: render · Draw page is backed by the slot machine component.
- Slot Machine → Deck Visualizer: render · Draw-related presentation can use the slide deck visualizer.
- Deck Visualizer → Latest Snapshot: consume · Visualizer presents generated content from read APIs.
- CSV Template → Upload CSV: guide · CSV template supports the upload contract.
- Storage Migration → Object Storage: migrate · Migration script moves data into the object-storage backend.