Domains

Suggestions

Copy page

The Suggestions domain implements the "Chaos" half of the architecture. It captures competing user inputs -- proposed content changes that the community evaluates through voting. Every suggestion is validated against a JSON Schema before storage, enforcing data integrity.

How Suggestions Work

A suggestion proposes a value for a specific section of an entity page. Unlike collaborative editors that track character-by-character patches, MinMaxHub uses atomic object replacement: a suggestion provides the entire value for a section (e.g., the complete stats block for a spell), validated as a whole before storage.

Targeting

Every suggestion has precise coordinates:

Coordinate	Field	Example
Page	entityId	"Fireball" entity
Section	topicKey	"stats-block" layout section
Item	itemKey	"spell-fireball" for collections, null for singletons

Operations

Operation	Target	Description
SET	Singleton	Replace the content of a single section
ADD	Collection	Propose adding a new item to a list
UPDATE	Collection	Propose changing an existing item
DELETE	Collection	Propose removing an item (no value needed)

Validation

Every non-DELETE suggestion is validated before storage:

1. The entity's layout is checked to find the targeted topic.
2. The appropriate JSON Schema rule is resolved.
3. The submitted value is validated against the schema.
4. If the collection uses "closed" mode, only predefined item keys are accepted.
5. If the item has locked fields, submitted values must match the defaults for those fields.

Invalid suggestions are rejected with detailed error messages.

Suggestion Lifecycle

Code
Submission --> Validation --> Storage (active) --> Voting --> Consensus --> Merge

1. User submits a suggestion.
2. System validates against the entity layout and JSON Schema.
3. Stored with active status and a score of 0.
4. Community casts votes, updating scores.
5. Consensus computation ranks suggestions by Wilson Score.
6. The winning suggestion's status becomes merged.

Suggestion Fields

Field	Type	Description
suggestionId	UUID	Unique identifier
authorId	string	User who created the suggestion
entityId	string	Target entity
topicKey	string	Target layout section
itemKey	string or null	Target item (null for singletons)
operation	SET, ADD, UPDATE, or DELETE	Operation type
value	object	Schema-validated content
status	active, rejected, merged, spam, or deleted	Lifecycle state
score	number	Wilson Score
upvotes / downvotes	number	Vote tallies
createdAt / updatedAt	ISO date	Timestamps
createdBy / updatedBy	object	{ userId, username, photoUrl }

Editing and Deletion

• Only the original author can update a suggestion's value. Updated values are re-validated against the schema.
• Only the original author can delete their suggestion. Deletion is a soft operation -- the suggestion is marked as deleted with a timestamp, preserving the audit trail.

API Endpoints

Method	Endpoint	Purpose	Auth
GET	/suggestions?entityId={id}	List suggestions for an entity	Required
GET	/suggestions/{suggestionId}	Get a single suggestion	Required
GET	/suggestions/target?entityId={id}&topicKey={key}&itemKey={key}	Get competing suggestions for a target	Required
GET	/suggestions/author/{userId}	Get a user's suggestions	Required
POST	/suggestions	Create a new suggestion	Required
PATCH	/suggestions/{suggestionId}	Update a suggestion's value	Required
DELETE	/suggestions/{suggestionId}	Soft-delete a suggestion	Required