Introduction
NOS BBQ 'O Matic is not a recipe app. It is a strictly typed, state-driven project management environment for coordinating group meat consumption.
The Problem
Standard cookout planning relies on unstructured, asynchronous data streams (WhatsApp groups). This leads to critical failure states, such as overlapping potato salads, untracked dietary violations, and unoptimized LKR budget splits. NOS resolves these merge conflicts before they happen.
System Architecture
Events are strictly controlled via a rigid state machine to prevent unauthorized scope creep and preserve financial integrity.
1. The Blueprint (Setup)
The Host (Root User) defines the schema. 2 Apps, 3 Mains, 1 Dessert. Invites are generated.
2. Pitch Pool (Proposals Open)
Guests authenticate and submit parsed recipes into the temporary holding queue.
3. Admin Curation
The Host merges the best pitches into the main branch.
4. The Vibe Check
The group runs a QA pass. Any vetos require a text-based reason.
5. Finalized
The repo is locked. The grill is hot. Expenses are actively logged to the ledger.
6. Settling
A strict global mutation freeze. Debts are calculated, and participants are required to resolve their negative balances.
Live Pricing Telemetry
We don't guess costs. NOS routes every parsed ingredient through the live Sri Lankan Food Repo API. If the price of pork goes up, your dashboard budget updates in real-time.
Dietary Matrix Guard
Dietary requirements are not suggestions, they are system constraints. When a user marks "No Seafood" as a Dealbreaker, any proposed recipe containing shrimp will instantly trigger an AI-audited cross-contamination alert on the Host's dashboard.
The Veto Protocol
To prevent infinite loops of indecision, blind downvoting is disabled in the UI. If a guest executes a `VETO` on a proposed menu item, the schema strictly requires a non-null string payload explaining why (e.g., "I am deathly afraid of mayonnaise"). The Root User can then hot-swap the item to resolve the conflict.
Financial Command Center
Once physical execution begins, NOS pivots from a food planner into a deterministic accounting engine. The ledger maintains an immutable audit trail of every Rupee spent, uploaded receipt, and logged expense.
Pot Contributions
Visual representation of capital deployment. The global pot is dynamically divided by the active headcount to establish the exact baseline `perPersonShare`.
Master Audit Trail
Full CSV export capabilities ensure that all records can be independently verified outside the application environment. Disputes are handled via soft-deletes with mandatory string-based rejection reasons.
Algorithmic Settlement
The dreaded "who owes what to whom" matrix is resolved via a greedy settlement algorithm that calculates the path of least resistance to zero out the global debt graph.
Personal Wallet Banner
Upon accessing the ledger, users are immediately greeted with their personal net status (Owed vs. Owes). This eliminates the friction of users having to parse the global matrix to find their specific obligations.
Zero-Trust Settlement Auth
You cannot unilaterally declare your own debts paid. For a suggested transfer to be marked `COMPLETED` and alter the global math, the `markPaid()` action must be invoked exclusively by the Host (Root User) or the Receiver of the funds. Debtors remain in an "Awaiting Confirmation" state until verified.
State Enforcement (Ledger Lock)
A financial matrix is useless if the parameters are constantly shifting. The Host maintains the authority to trigger a state transition from `FINALIZED` to `SETTLING`.
Invoking the Ledger Lock disables all UI endpoints for adding, editing, or deleting expenses. It establishes a psychological and programmatic point-of-no-return, ensuring the global debt graph remains static while users process their real-world peer-to-peer transfers.
The Phantom Protocol
Sometimes your friends are slow to authenticate. The math cannot wait for them.
The Phantom Protocol allows the Host to inject unregistered physical entities into the digital environment. These placeholders are assigned specialized signatures (e.g., [email protected]). This preserves the mathematical integrity of the `perPersonShare` and active headcount prior to the user formally claiming their identity.
Runtime Guide: Sausage Execution
A step-by-step guide to compiling a standard cylindrical protein payload without triggering a catastrophic memory (juice) leak.
1. Hardware Provisioning
Initialize the primary heat cluster (charcoal or gas). Establish a dual-zone thermal gradient. Target environment temperature for the direct heat zone: 180°C.
2. Payload Deployment
Deploy the sausage links to the indirect heat sector first. Ensure evenly distributed spacing to avoid thermal throttling.
3. Asynchronous Polling Loop
Initiate a runtime loop. Every `n` ticks (approx. 2 minutes), invoke the rotate() method using the Spatula middleware. This ensures uniform compilation of the Maillard reaction layer.
4. State Validation (QA)
Perform an internal state check using a thermal probe pointer. Assert that coreTemp >= 71°C.
WARNING: Do not pierce the outer casing prematurely with a fork process. This will cause an unrecoverable data loss event (all the juices will leak into the fire).
5. Graceful Shutdown
Terminate the heat process. Route the payload to a staging buffer (cutting board) for a 5-minute timeout. This allows internal pressure parameters to normalize before invoking the slice() function.