Freshroots Replenishment Copilot

Live app: https://freshroots-copilot.streamlit.app/ (Raghav and procurement)
Ops dashboard: https://freshroots-dashboard.vercel.app/ (read-only, live)

Twice a week, a scheduled job reads sales and stock from Supabase, checks the data, applies Raghav's 5 written rules to every SKU, and saves one recommendation per SKU. Raghav approves, overrides or rejects each one in a web app. Procurement downloads only the approved rows as a CSV and imports it into Zoho Inventory. The system never places an order.

The component map is at docs/component_map.png, and the data mapping and every assumption are in docs/data_mapping.md.

#	Component	Where
C1	Scheduled run (Mon & Thu 07:00 IST + manual + "Run now")	.github/workflows/run.yml, run.py, copilot/pipeline.py
C2	5 seed tables	supabase/migrations/001_init.sql, scripts/seed.py
C3	Validation gate	copilot/validate.py
C4	Fix gaps, sign off	App pages Data gaps and Sign-off
C5	5 rules in order	copilot/engine.py, config.json
C6	Store results	runs, recommendations, decisions, data_gaps, backtest_results (copilot/db.py)
C7	Two queues + reasons	App page Queues
C8	Approve / override / reject	Buttons on Queues (copilot/service.py)
C9	Download draft POs	App page Export
C10	Backtest (kill gate)	copilot/backtest.py, app page Backtest
C11	On-order stock read from Zoho open POs	copilot/zoho_sync.py (sync_on_order), plugged into run_pipeline()
C12	Approved rows become draft POs in Zoho	copilot/zoho_push.py (push_drafts), app page Zoho

---

Deploy guide (step by step, no coding needed)

You need free accounts on GitHub, Supabase and Streamlit Community Cloud. You also need Python 3.11 on your computer for one step (step 2).

1. Create the Supabase project and run the migration

1. Go to https://supabase.com, then New project. Name it freshroots-copilot, pick the Mumbai region (ap-south-1), and save the database password somewhere safe.
2. In the left menu, open SQL Editor, then New query.
3. Open supabase/migrations/001_init.sql from this repo, copy all of it, paste it in, and click Run. You should see "Success. No rows returned". The script is safe to run again.
4. Open Table Editor. You should see 11 tables, each marked "RLS enabled".

2. Add the keys to .env, then load the data

1. In Supabase, go to Project Settings → API (or API Keys). Copy:

   • the Project URL
   • the service_role key (in newer projects, the secret key; if that one is rejected, use the legacy service_role key)

   Never share this key or put it in a browser. It bypasses all security.

2. In the project folder, copy .env.example to .env and paste the two values in.

3. Open a terminal in the project folder and run:

   python3.11 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   python scripts/seed.py
   

   You should see skus 15, weekly_sales 240 and so on. Re-running it is safe: rows are upserted, and sign-offs are kept.

4. Optional check: python run.py --run-date 2026-10-22 should print run 1: ok, 15 recommendations.

3. Push to GitHub and add the two secrets

1. Create a private repo named freshroots-copilot on GitHub, then push this folder to it. .env is git-ignored and will not be uploaded.
2. In the repo, go to Settings → Secrets and variables → Actions → New repository secret. Add:
   • SUPABASE_URL
   • SUPABASE_SERVICE_ROLE_KEY

4. Enable the workflow and trigger it once by hand

1. Open the repo's Actions tab. If asked, click I understand my workflows, go ahead and enable them.
2. Click Replenishment run → Run workflow → Run workflow.
3. After 1–2 minutes the run should turn green. It turns red when the data has gaps (the run is blocked, by design) or when something errors. Open the app's Data gaps page to see why.
4. From then on it runs by itself every Monday and Thursday at 07:00 IST.

5. Deploy on Streamlit Community Cloud

1. Go to https://share.streamlit.io, then Create app → Deploy a public app from GitHub. Pick the freshroots-copilot repo, branch main, and main file app.py.
2. Under Advanced settings → Secrets, paste:

   SUPABASE_URL = "https://YOUR-PROJECT.supabase.co"
   SUPABASE_SERVICE_ROLE_KEY = "your-service-role-key"
   

   Set Python version to 3.11, then click Deploy.
3. After it starts, go to Settings → Sharing, set the app to private ("Only specific people can view this app"), and invite Raghav's and procurement's email addresses. The app has no login of its own; Streamlit's private sharing is the access control.

6. Raghav signs off the assumptions

1. Raghav opens the app and goes to Sign-off.
2. He reads each of the 6 assumptions and clicks Sign. If he disagrees with a value, it is changed in config.json (via a pull request). The changed assumption's sign-off is then cleared automatically, and he signs again.
3. Until all 6 are signed, every page shows "UNSIGNED ASSUMPTIONS: not for procurement" and Export is disabled. Runs still work.

This is the beginning of the README. Read the rest at the original. Read the full README ↗