# jmr533/wcbracket architecture

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

- Interactive diagram: https://gitdiagram.com/jmr533/wcbracket
- Repository: https://github.com/jmr533/wcbracket

## Overview

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`](https://github.com/jmr533/wcbracket/blob/main/script.js) (UI Script), [`index.html`](https://github.com/jmr533/wcbracket/blob/main/index.html) (Entry Page), [`api/auth.js`](https://github.com/jmr533/wcbracket/blob/main/api/auth.js) (Auth API), [`api/state.js`](https://github.com/jmr533/wcbracket/blob/main/api/state.js) (State API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser Client"]
  node_index["Entry Page<br/>html shell<br/>[index.html]"]
  node_script["UI Script<br/>client logic<br/>[script.js]"]
  node_styles["Styles<br/>presentation<br/>[styles.css]"]
  node_logic["Bracket Logic<br/>domain rules<br/>[logic.js]"]
  node_admin_entry(("Admin Mode<br/>alternate entry"))
end

subgraph group_api["Serverless API"]
  node_auth_api["Auth API<br/>serverless fn<br/>[auth.js]"]
  node_state_api["State API<br/>serverless fn<br/>[state.js]"]
  node_auth_helper["Auth Helper<br/>shared util<br/>[_auth.js]"]
  node_redis_helper["Redis Helper<br/>shared util<br/>[_redis.js]"]
end

subgraph group_infra["External Services"]
  node_upstash[("Redis Store<br/>persistent store")]
  node_vercel{{"Vercel Runtime<br/>hosting platform"}}
  node_config["Env Config<br/>deployment config<br/>[.env.example]"]
end

node_vercel -->|"serves"| node_index
node_index -->|"loads"| node_script
node_index -->|"loads"| node_styles
node_script -->|"uses"| node_logic
node_script -->|"calls"| node_state_api
node_script -->|"calls"| node_auth_api
node_admin_entry -.->|"enables"| node_script
node_auth_api -->|"uses"| node_auth_helper
node_state_api -->|"uses"| node_redis_helper
node_auth_api -->|"reads"| node_config
node_state_api -->|"reads"| node_config
node_redis_helper -->|"connects"| node_upstash
node_script -.->|"validates"| node_logic

click node_index "https://github.com/jmr533/wcbracket/blob/main/index.html"
click node_script "https://github.com/jmr533/wcbracket/blob/main/script.js"
click node_styles "https://github.com/jmr533/wcbracket/blob/main/styles.css"
click node_logic "https://github.com/jmr533/wcbracket/blob/main/logic.js"
click node_auth_api "https://github.com/jmr533/wcbracket/blob/main/api/auth.js"
click node_state_api "https://github.com/jmr533/wcbracket/blob/main/api/state.js"
click node_auth_helper "https://github.com/jmr533/wcbracket/blob/main/api/_auth.js"
click node_redis_helper "https://github.com/jmr533/wcbracket/blob/main/api/_redis.js"
click node_config "https://github.com/jmr533/wcbracket/blob/main/.env.example"

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_index,node_script,node_styles,node_logic,node_admin_entry toneBlue
class node_auth_api,node_state_api,node_auth_helper,node_redis_helper toneAmber
class node_upstash,node_vercel,node_config toneMint
```

## Components

### Browser Client

Static frontend plus shared bracket logic

- [Entry Page](https://github.com/jmr533/wcbracket/blob/main/index.html): html shell · Main page loaded by the browser · `index.html`
- [UI Script](https://github.com/jmr533/wcbracket/blob/main/script.js): client logic · Handles interactions and API calls · `script.js`
- [Styles](https://github.com/jmr533/wcbracket/blob/main/styles.css): presentation · Visual styling for the interface · `styles.css`
- [Bracket Logic](https://github.com/jmr533/wcbracket/blob/main/logic.js): domain rules · Shared deterministic bracket and scoring logic · `logic.js`
- **Admin Mode**: alternate entry · Hidden admin access path enabled via query flag

### Serverless API

Vercel functions for auth and persisted state

- [Auth API](https://github.com/jmr533/wcbracket/blob/main/api/auth.js): serverless fn · Password-based admin authentication endpoint · `api/auth.js`
- [State API](https://github.com/jmr533/wcbracket/blob/main/api/state.js): serverless fn · Reads and writes persisted bracket state · `api/state.js`
- [Auth Helper](https://github.com/jmr533/wcbracket/blob/main/api/_auth.js): shared util · Authentication helper used by API routes · `api/_auth.js`
- [Redis Helper](https://github.com/jmr533/wcbracket/blob/main/api/_redis.js): shared util · Shared Redis connection helper for API routes · `api/_redis.js`

### External Services

Deployment and persistence dependencies

- **Redis Store**: persistent store · Upstash Redis backing store for app state
- **Vercel Runtime**: hosting platform · Hosts the static frontend and serverless functions
- [Env Config](https://github.com/jmr533/wcbracket/blob/main/.env.example): deployment config · Runtime settings such as admin password and Redis credentials · `.env.example`

## Connections

- 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
