MinMaxHub is a collaborative game-build encyclopedia -- Wikipedia meets Reddit for tabletop and video game content. Users suggest content, the community votes on it, and a consensus algorithm produces the "truth" that is served publicly as static pages.
The Core Loop
Every piece of content in MinMaxHub follows a four-step lifecycle:
Code
- Suggest. An authenticated user submits a suggestion targeting a specific section of a page (a "topic"). The suggestion contains a complete replacement value for that section, validated against a JSON Schema before storage.
- Vote. Other users cast upvotes or downvotes on competing suggestions. Votes update aggregate scores atomically.
- Compute Consensus. An admin triggers consensus computation for an entity. The system ranks all eligible suggestions using the Wilson Score algorithm and materializes the winners into a dedicated consensus store.
- Serve. Entity pages are pre-rendered as static HTML. When consensus changes, the cached page is automatically invalidated so the next visitor gets fresh content.
Two-Path Mental Model
The architecture is split into two distinct data paths that never mix:
| Path | Nickname | Purpose | Data Source |
|---|---|---|---|
| Read path | Order | Serve public content via static pages | Consensus data |
| Write path | Chaos | Capture community input (suggestions + votes) | Suggestions and Votes |
Read path (Order): Consensus documents are the single source of truth for what visitors see. Pages are assembled from pre-computed consensus items with no voting math or joins at read time.
Write path (Chaos): Suggestions and votes are high-volume, personalized, and democratic. This data is never read directly for public display -- it flows through the consensus computation step first.
This separation means public pages can be aggressively cached and served from the edge, while the write path handles the messier business of community collaboration without affecting read performance.
Authentication
MinMaxHub uses AWS Cognito for authentication. All write operations (creating suggestions, voting, uploading media) require a valid authentication token.
To authenticate API requests, include the Cognito ID Token in the Authorization header:
Code
Public read endpoints (viewing content pages, browsing the node tree) do not require authentication.
Key Concepts
| Concept | Description |
|---|---|
| Node | A point in the content hierarchy -- either a folder (for organizing) or an entity node (for content pages). Nodes form a tree that defines the site's taxonomy and URL structure. |
| Entity | A content page created under an entity node (e.g., "Bard", "Fireball"). Entities have layout templates that define which topics and content types they support. |
| Suggestion | A proposed value for a specific section of an entity page. Suggestions compete with each other and are ranked by community votes. |
| Vote | An upvote (+1) or downvote (-1) on a suggestion. Votes feed into the Wilson Score algorithm. |
| Consensus | The materialized "winner" for each section of an entity page, determined by the Wilson Score algorithm. This is what visitors see. |
| Rule | A JSON Schema document that defines the shape of a content type (e.g., "Spell", "Hero Card"). Rules are used for both form generation and validation. |
| Topic | A section within an entity's layout. Topics can be singletons (one value) or collections (a list of items). |