MinMaxHub is a serverless application built on AWS. The system is organized around domain-driven services that communicate through a single REST API gateway.
High-Level Overview
Code
All API routes are served through a single API Gateway. Each domain (Nodes, Entities, Suggestions, Votes, Consensus, Users, Media, Rules) has its own set of endpoints under a dedicated root path.
Domain Boundaries
| Domain | Root Path | Responsibility |
|---|---|---|
| Nodes | /nodes | Content hierarchy and taxonomy (the tree structure) |
| Entities | /entities | Content pages with layout templates |
| Suggestions | /suggestions | User-submitted content proposals |
| Votes | /votes | Community voting on suggestions |
| Consensus | /consensus | Materialized winners, page assembly, moderation |
| Users | /users | User profiles and ranks |
| Media | /media | Image uploads and optimization |
| Rules | /rules | JSON Schema registry for content types |
Authentication
Protected endpoints use Cognito-based authorization. Include the ID Token in the Authorization header:
Code
Public endpoints (content pages, node browsing) do not require authentication. See each domain's API reference for which routes are public vs. protected.
Error Handling
All API responses follow a consistent envelope format. Errors return structured JSON with an appropriate HTTP status code:
| Status | Meaning |
|---|---|
400 | Bad Request -- invalid input or missing required fields |
401 | Unauthorized -- missing or invalid authentication token |
403 | Forbidden -- authenticated but not permitted for this action |
404 | Not Found -- resource does not exist |
409 | Conflict -- duplicate resource or optimistic lock failure |
422 | Unprocessable Entity -- input is well-formed but fails validation |
500 | Internal Server Error |
Content Delivery
Entity pages are pre-rendered as static HTML and cached at the edge. When consensus is recomputed for an entity, the cached page is automatically invalidated. The next visitor triggers a fresh render with updated content, which is then cached again.
This means:
- Read performance is not affected by the complexity of the write path.
- Public pages are served from cache with no database queries on most requests.
- Fresh content appears within seconds of consensus computation completing.