This document is the authoritative technical reference for the Hellcats MVP system (frontend + Firebase). It is designed to remain useful long-term, including for maintainers who were not involved in the original implementation.
This is intentionally verbose. The focus is clarity, deterministic behavior, and maintainability, not minimal text length.
The MVP system is a lightweight, cost-free application that tracks participants, event placements, and computes an MVP candidate using transparent rules. It is built for small groups where:
Explicit non-goals (things intentionally not implemented):
These choices reduce complexity and keep the system easy to operate.
The system uses a static frontend hosted on GitHub Pages and a shared cloud state stored in Firestore. All clients subscribe to the same Firestore document and render the same state.
Browser (HTML/CSS/JS)
- renders UI
- authenticates anonymously
- checks password gate (admin-only for this wiki page)
- subscribes to Firestore state via real-time listener
- writes updates back to Firestore
Firestore (Cloud)
- stores shared application state in state/main
- stores password/admin hashes in config/security
- stores undo snapshot in state/undoThe architecture is intentionally “backendless”. Firestore provides managed storage + real-time updates. GitHub Pages provides globally available static hosting.
GitHub Pages serves static files only. There is no server-side computation. This provides:
Important implication: Because the site is static, all runtime logic must run in the browser. For Firebase usage without a bundler, the application imports Firebase SDK modules from the official CDN.
The MVP system uses a minimal set of Firebase services:
request.auth != null for security rulesOther services (Hosting, Functions, Storage, etc.) are not required for this system and remain disabled unless needed later.
The system uses Firebase anonymous authentication. This creates an authenticated session without user accounts.
The goal is not identity management; it is to ensure Firestore requests have request.auth != null,
enabling simple security rules.
User accounts add friction (registration, password resets, permissions) and increase maintenance burden. For a small group application, anonymous auth + a password gate is sufficient.
The password gate is a UI overlay that blocks access until a correct password is provided. The password is never stored in the source code. Validation is done by hashing the input (SHA-256) and comparing to the stored hash in Firestore.
config/security
passwordHash: string // sha256(password) - used by the MVP app / normal wiki pages
adminHash: string // sha256(adminPassword) - used for admin-only access
This page is admin-only: it validates against adminHash (not passwordHash).
Storing plaintext passwords is a security anti-pattern. Hashing prevents accidental disclosure and avoids storing secrets in clear text. SHA-256 is sufficient for this small-group threat model. If stronger protection is desired later, a salted hash scheme can be introduced.
The application state is stored as a single document to simplify reasoning and synchronization:
state/main
persons: Person[]
events: Event[]
mvpCooldown: numberPerson
id: string
name: string
title: boolean
blocked: boolean
mvpCount: number
cooldownLeft: number
placements: Placement[]
Placement
event: number
place: numberA single document avoids partial updates and complicated joins. It also makes backup/export trivial: the entire system can be restored by replacing one document. This scales well for small datasets (dozens of persons, hundreds of events). If you ever approach Firestore document size limits, you would split the model into collections, but that is out of scope for now.
The frontend subscribes to the state document using Firestore’s real-time listener (onSnapshot).
Whenever the document changes, all clients receive the update and re-render the UI.
Writes update the top-level fields of state/main. This is simple and deterministic,
but simultaneous conflicting edits can cause last-write-wins behavior.
Admin mode is session-local. Unlocking admin enables destructive operations: import, reset, undo. This separation reduces accidental data loss.
Admin unlock validates the admin password by comparing SHA-256(input) to config/security.adminHash.
If successful, an admin flag is stored in sessionStorage.
Admin mode is not persisted in Firestore and is not shared across users.
Export produces a JSON file containing the entire current application state. Import replaces the entire state with a JSON payload.
Import is destructive (overwrite). Therefore it is restricted to admin mode and paired with an automatic undo snapshot.
Undo is implemented as snapshot restore. Before import or reset, the system stores the current state as a snapshot
in state/undo. Undo writes the snapshot back to state/main.
Rules must allow anonymous-auth users to access state, and allow reading config/security for hashing checks.
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /state/{doc} {
allow read, write: if request.auth != null;
}
match /config/{doc} {
allow read: if true;
}
}
}
This wiki is hosted on GitHub Pages and mapped to wiki.zabini.org using a DNS CNAME record.
Enforce HTTPS in GitHub Pages settings.
CNAME
Name: wiki
Target: fp1892.github.io/assets/wiki.css returns 200./documentations-background-image.jpg exists and returns 200.config/security.adminHash exists and matches SHA-256(admin password).When extending the system, preserve transparency, determinism, and low operational overhead.