How jmr533/wcbracket works
1. Overall shape
- This is a small Vercel-hosted app with a static browser frontend and a serverless API backend.
- The main architectural split is:
- index.html, script.js, styles.css, logic.js for the client/UI and local business logic
- api/ for server-side auth and persisted state
- Redis as the persistent backing store
2. Frontend/UI layer
- index.html is the entry page.
- script.js appears to drive user interactions and API calls.
- styles.css handles presentation.
- logic.js is likely shared domain logic for bracket behavior and/or scoring rules, kept separate from the UI so it can be reused in tests or server-side code.
3. Domain logic boundary
- logic.js is the key “business rules” module in the repository.
- For an architecture diagram, treat this as the core bracket logic layer between the UI and any persisted state.
- test.mjs suggests this logic is validated independently of the browser, which is a good sign that the domain rules are meant to be deterministic and reusable.
4. Serverless API layer
- The api/ directory contains Vercel serverless functions.
- api/state.js is the persistence/state endpoint.
- api/auth.js is the authentication endpoint.
- This implies the browser does not talk directly to Redis; it goes through the API layer.
5. Redis persistence
- api/_redis.js is a shared helper for connecting to Redis.
- The README explicitly says to add Upstash Redis in Vercel, so Redis is the canonical data store for app state.
- This is a classic serverless pattern: stateless functions, external managed datastore.
6. Authentication model
- api/_auth.js and api/auth.js indicate an admin authentication flow.
- The README says the admin entry point is reached via /?admin=1 and requires ADMIN_PASSWORD.
- That means the admin UI is intentionally hidden from normal navigation and likely protected by a password-based login flow rather than full user accounts.
7. State flow
- The typical flow is:
- browser loads static assets
- user interacts with the bracket UI
- client calls api/state.js to read or write the current bracket state
- server function uses Redis to persist/retrieve that state
- This makes the application stateful across sessions while keeping the frontend itself deployable as static content.
8. Admin entry point
- The admin path is not linked publicly, which suggests a separate operational mode rather than a separate application.
- The admin=1 query flag likely toggles administrative controls in the frontend, while the backend enforces password-based access via the auth API.
- For a diagram, represent this as an alternate entry path into the same frontend, with elevated access to state management.
9. Environment and deployment
- The repo is designed for Vercel deployment.
- Environment configuration depends on ADMIN_PASSWORD plus the Upstash Redis integration.
- .env.example exists to document local/dev configuration, and the README’s setup steps confirm the app expects runtime configuration from the hosting platform.
10. Operational dependencies
- External services matter here:
- Vercel hosts the frontend and serverless functions
- Upstash Redis stores the bracket state
- There are no signs of a traditional always-on backend server, database migrations, or background workers; the architecture is request/response driven.
11. Recommended diagram boundaries
- Draw three main boxes:
- Browser client: HTML/CSS/JS plus bracket logic
- Serverless API: auth and state endpoints
- Redis datastore: persistent state
- Show auth as a gate into admin operations, and state endpoints as the main data path between client and storage.
12. What this repo is not
- It does not appear to be a monolithic backend app or a multi-service distributed system.
- It also does not look like a framework-heavy frontend app; the structure suggests a lightweight, single-page or single-screen experience with just enough backend to persist state and protect admin actions.
Main entry points: script.js UI Script · index.html Entry Page · auth.js Auth API · state.js State API
Components 12
Browser Client
Static frontend plus shared bracket logic
- Entry Page · Main page loaded by the browser
index.html - UI Script · Handles interactions and API calls
script.js - Styles · Visual styling for the interface
styles.css - Bracket Logic · Shared deterministic bracket and scoring logic
logic.js - Admin Mode · Hidden admin access path enabled via query flag
Serverless API
Vercel functions for auth and persisted state
- Auth API · Password-based admin authentication endpoint
api/auth.js - State API · Reads and writes persisted bracket state
api/state.js - Auth Helper · Authentication helper used by API routes
api/_auth.js - Redis Helper · Shared Redis connection helper for API routes
api/_redis.js
External Services
Deployment and persistence dependencies
- Redis Store · Upstash Redis backing store for app state
- Vercel Runtime · Hosts the static frontend and serverless functions
- Env Config · Runtime settings such as admin password and Redis credentials
.env.example
Connections 13
- Vercel Runtime → Entry Page: serves · Deploys the static entry page
- Entry Page → UI Script: loads · Browser loads the interaction script
- Entry Page → Styles: loads · Browser loads stylesheet
- UI Script → Bracket Logic: uses · Client delegates bracket behavior to shared logic
- UI Script → State API: calls · Reads and writes current bracket state
- UI Script → Auth API: calls · Submits admin password during login
- Admin Mode → UI Script: enables · Query flag switches the UI into admin mode
- Auth API → Auth Helper: uses · Authentication endpoint relies on shared auth helper
- State API → Redis Helper: uses · State endpoint relies on shared Redis helper
- Auth API → Env Config: reads · Uses admin password configuration
- State API → Env Config: reads · Uses runtime datastore configuration
- Redis Helper → Redis Store: connects · Persists bracket state in Redis
- UI Script → Bracket Logic: validates · Keeps UI actions aligned with deterministic rules