How abhayb97/slide-deck-visualizer works
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: lists.ts Lists · storage.ts Storage · snapshots.ts Snapshots · processCsvSnapshot.ts CSV Processor
Components 24
UI
Public and admin Next.js entry points and visual components.
- Home · Root public entry page.
app/page.jsx - Leaderboard · Public leaderboard view.
app/leaderboard/page.tsx - Slot Machine · Interactive draw visualization page.
app/draw/slot-machine/page.tsx - CSV Upload · Admin entry for CSV ingestion and snapshot creation.
app/admin/upload/page.tsx - Master Upload · Admin entry for master data ingestion.
app/admin/upload-master/page.tsx - Deck Visualizer · Secondary presentation component for generated content.
app/SlideDeckVisualizer.jsx - Slot Machine · Interactive component used by the draw page.
components/SlotMachine.tsx
API
Server route handlers that expose ingest and read-model operations.
- Upload CSV · API route for accepting CSV uploads.
app/api/upload-csv/route.ts - Process CSV · API route that triggers CSV snapshot processing.
app/api/process-csv/route.ts - Process Master · API route that triggers master-data processing.
app/api/process-master/route.ts - Snapshot · API route for snapshot operations.
app/api/snapshot/route.ts - Current Lists · API route exposing current list data.
app/api/current-lists/route.ts - History · API route exposing historical records.
app/api/history/route.ts - Latest Snapshot · API route exposing the most recent snapshot.
app/api/latest-snapshot/route.ts - Leaderboard API · API route exposing leaderboard data.
app/api/leaderboard/route.ts
Core
Processing, persistence, and domain read/write helpers in lib/.
- CSV Processor · Core CSV-to-snapshot transformation logic.
lib/processCsvSnapshot.ts - Master Processor · Core master-data transformation logic.
lib/processMaster.ts - Snapshots · Read/write helper for snapshot records.
lib/snapshots.ts - Lists · Read/write helper for current list data.
lib/lists.ts - History Store · Read/write helper for historical data.
lib/history.ts - Storage · Storage abstraction used by application logic.
lib/storage.ts - Object Storage · Object-storage implementation behind the storage abstraction.
lib/objectStorage.ts
Infra
Static templates and migration tooling around storage.
- CSV Template · Template CSV used to standardize uploads.
public/templates/snapshot-template.csv - Storage Migration · Migration script from Vercel Blob to object storage.
scripts/migrate-vercel-blob-to-object-storage.mjs
Connections 26
- 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.