Store Intelligence System (Apex Retail)

An end-to-end pipeline that takes raw CCTV video and produces actionable store intelligence metrics via a REST API.

Project Setup (5 Commands)

To run the entire system on a clean machine:

# 1. Start the Intelligence API & Database in the background
docker compose up -d --build

# 2. Setup your local python environment
python -m venv .venv

# 3. Activate the environment (Windows)
.venv\Scripts\activate

# 4. Install the computer vision dependencies
pip install -r pipeline/requirements.txt

# 5. Add Video Clips
# Create the `add_files/Store 1/` directory (it is excluded from GitHub) and place the CCTV video clips (.mp4) inside it.
# The expected filenames are: "CAM 1 - zone.mp4", "CAM 2 - zone.mp4", "CAM 3 - entry.mp4", "CAM 5 - billing.mp4"

# 6. Run the Detection Pipeline
python pipeline/detect.py

View The Live Dashboard (Bonus Part E)

While detect.py is running, open the following file in your web browser to watch the real-time store metrics update dynamically: 👉 dashboard/index.html

Automated Testing (Part C)

The project includes a full pytest suite simulating edge cases (Empty stores, queue spikes, graceful degradation). Run it with: pytest tests/

Known Limitations

Store 1 Calibration: The current detection pipeline (pipeline/zones.py and pipeline/detect.py) has been explicitly hardcoded and calibrated to process Store 1's specific camera angles. To scale this to all 40 stores, the pipeline would need to be updated to dynamically ingest pixel coordinate mappings from store_layout.json rather than relying on static variables.

North Star Metric & POS Data: The True Conversion Rate (North Star Metric) is calculated dynamically by joining the CCTV entry events with the add_files/POS - sample transactionsb1e826f.csv file. Even though the dates in the sample POS file do not chronologically align with the Store 1 CCTV video clips, the backend mathematical join logic perfectly satisfies the hackathon's core architectural requirement.