PotionWatch

Inspiration

We saw an opportunity to create a comprehensive monitoring dashboard that could visualize patterns, detect suspicious activity, and optimize resource allocation. Finally, we were inspired to solve this real-world inventory reconciliation problem that affects industries from manufacturing to supply chain logistics.

What it does

This tool will help with 4 main things:

Create a visual map of all the cauldron, their connection with their neighboring cauldrons (if any), cauldrons and market distance along with the time taken, and finally real-time levels of the cauldrons potion. It can also identify, when the cauldron is almost full or close to being full.
A time-series cauldron watch which helps visualize for every cauldron what was their overall potion levels, and when was the ticket submitted. This time-series can successfully identify significant drops in the data.
Transport tickets for each cauldron for all the dates when there was a witch who brew from that cauldron also allowing us to visualize which witch brew from it, and how much.
Our Potion Discrepancy Dashboard which is ideally a tool for answering suspicious tickets using our intelligent algorithm which can categorize the status as either 'Match' when potion brewed from the cauldron matches within a threshold with the report at the market, 'Mismatch' when it is exactly opposite of 'Match', 'Ticket Missing' when there was a drain from the cauldron but no reporting at the market (ideally bad witches :( ), and 'Drain Not Detected' when there was a ticket reported at the market but the drain was not made either due to insufficient data or some error from the witch.
Finally, our algorithm for finding optimized routes work by optimizing the witch courier routes to efficiently collect potions from multiple cauldrons and deliver them to the Enchanted Market while preventing overflow.

How we built it

1. Understanding the Problem

We started by studying the APIs provided by the challenge (/Data, /Tickets, /metadata) to understand what information we could retrieve:

/Data gives real-time potion levels for each cauldron.
/Tickets contains transport tickets from witches, representing potion collection events.
/metadata defines the overall time range, interval, and measurement units.

The core challenge was to detect and explain discrepancies between actual potion drains (from the cauldrons) and reported transport tickets.

2. Data Processing Pipeline

We designed a modular Python backend built with Flask that processes live and historical data:

Data Collection: Using the /Data API, we periodically fetch cauldron levels over time and store them in memory as time series data.
Drain Detection Algorithm:

We calculate the rate of change in potion levels.
Using a statistical threshold (std_multiplier), we dynamically detect drain events — sudden drops in level indicating a potion transfer.
Each drain event is characterized by start time, end time, total volume drained, and duration.
1. Ticket Grouping: The /Tickets API provides daily totals of potion collected. We group these by cauldron_id and date to match them against drain data.

3. Discrepancy Detection System

We then compare ticket-reported values with detected drain volumes using a classification function:

MISMATCH: Ticket and drain match do not match (outside tolerance).
MATCH: Ticket and drain match closely (within tolerance).
DRAIN_NOT_DETECTED: Ticket exists but the system found no corresponding drain or ticket volume < drain.
TICKET_MISSING: A drain event occurred, but no ticket was reported.

This system identifies missing, inconsistent, or fraudulent potion reports. We also made this logic modular, allowing thresholds like tolerance and min_duration to be tuned dynamically.

4. Backend Architecture

The backend exposes a Flask API with endpoints:

POST /compare → Runs the full discrepancy analysis pipeline.
GET /health → Basic API status check.

The /compare route accepts date ranges and parameters (std_multiplier, min_duration, tolerance) and automatically analyzes all dates between the range or from the provided date up to the current day.

5. Frontend Dashboard

We built a lightweight React dashboard (DiscrepancyViewer.jsx) that visualizes:

Summary statistics (total records, correct reports, over/under reports, phantom tickets).
A color-coded table of cauldrons and their discrepancy categories.
Dynamic highlighting of anomalies for quick inspection.

The frontend fetches data from the Flask API and renders it with smooth visual feedback, auto-refresh capabilities, and responsive design.

6. Technologies Used

Component	Tools / Libraries
Backend	Flask, Pandas, Requests, JSON, REST APIs
Frontend	React (Hooks, Fetch API, inline styling)
Visualization	Color-coded tables & summary cards
Hosting (optional)	Flask local server / containerizable setup

7. Design Philosophy

We focused on clarity, modularity, and explainability:

Every computation step (drain detection → ticket comparison → classification) is independent and testable.
The system handles both real-time and historical data.
The codebase is structured so future teams can easily plug in ML models for anomaly prediction or real-time alerting.

8. End Result

Our final system provides:

A live, API-driven view of potion logistics.
Automatic discrepancy detection with clear categories.
A dashboard that translates backend intelligence into an intuitive, actionable visualization.

It’s effectively a real-time audit and monitoring system for magical logistics, blending analytics, automation, and visual insight.

Challenges we ran into

The main challenge we ran into was to build our own potion discrepancy detection algorithm and correctly flagging them into right categories. Furthermore, with the given data, one could not identify that a cauldron was brewed by which witch at what time which essentially made the optimization a more difficult problem to solve.