Rewrite README with clearer structure.

Author: sree-sanak

README.md

@@ -1,93 +1,80 @@
 # Dynamic Pricing
 
-## Introduction
+**Measure the revenue impact of time-of-day menu pricing on a Deliveroo restaurant.**
 
-This project is a mix of three parts: a webhook that satifies the requirements of the [Deliveroo Orders API](https://api-docs.deliveroo.com/docs/introduction), a simple Order Management System that interacts directly with the Orders DB, and Jupyter Notebooks for data analysis to measure the impact of Dynamic Pricing.
+Most restaurants set one price and leave it. But demand isn't flat — lunch rushes look nothing like a 3pm lull, and weekends diverge from weekdays. This repo ingests live orders from Deliveroo, normalizes them into a Postgres schema, and ships a notebook analysis layer to segment orders by time window, day of week, and pricing period — so "before" and "after" are directly comparable on the same store.
 
-## Deliveroo
+## Architecture
 
-All the Deliveroo related decisions in this codebase are based on requirements from [Deliveroo Orders API](https://api-docs.deliveroo.com/docs/introduction).
+Three pieces, each independently useful:
 
-## Requirements
+```
+Deliveroo Orders API ──webhook──> Flask app ──> PostgreSQL
+                                      |              ^
+                                      v              |
+                                OAuth2 sync         OMS
+                                (status ACKs)   (upsert layer)
+                                                     |
+                                                     v
+                                             Jupyter notebooks
+                                             (metrics + plots)
+```
+
+1. **Webhook** (`src/dynamic_pricing/webhook/`) — Flask endpoints (`/dev-webhook`, `/prod-webhook`) that receive order events, validate `pos_item_id` on every line, ACK `order.status_update` events back to Deliveroo via OAuth2 client-credentials, and forward the payload to the OMS.
+2. **Order Management System** (`src/dynamic_pricing/core/`) — SQLAlchemy upsert layer over seven related tables (customers, partners, orders, items, modifiers, order_items, order_item_modifiers). `db_init.py` provisions the schema; `order_manager.py` handles webhook-driven and backfill inserts.
+3. **Analysis** (`src/dynamic_pricing/analysis/`) — metrics and plotters for orders-per-interval, revenue-per-interval, prep-time, day-of-week splits, and a popularity-vs-profitability menu matrix (Star / Puzzle / Cash Cow / Dud). Three notebooks: wraps, non-wraps, and a Prophet seasonality pass.
 
-- Python 3.10
-- Key Dependencies: See `requirements.txt`
+## Tech stack
 
-## Installation
+Python 3.10 - Flask 2.2 - gunicorn - PostgreSQL - SQLAlchemy 2.0 - psycopg - pandas - plotly - prophet - JupyterLab - pytest - pytest-postgresql - black - pylint - pre-commit.
 
-You can install the Dynamic Pricing API by cloning the repository and installing the required dependencies.
+## Quick start
 
 ```bash
-git clone https://github.com/Sree5835/dynamic_pricing
+git clone https://github.com/zalatar242/dynamic_pricing
 cd dynamic_pricing
-```
-
-## Creating a virtual environment within the project
 
-Using a virtual environment allows for a clean and isolated environment for you to install project dependencies and run code. To create a virtual environment within the project, run (depending on whether your Python command is `python` or `python3`):
-
-```
 python -m venv .venv
-```
+source .venv/bin/activate    # Windows: .venv\Scripts\activate
 
-You can activate your virtual environment with:
-
-```
-source .venv/bin/activate
-```
-
-With Windows, use:
+pip install -r requirements.txt
+pip install .
 
-```
-.venv\Scripts\activate
+cp .env.sample .env          # fill in Deliveroo creds + DB vars
+pre-commit install
 ```
 
-You can then install all dependencies and build within the virtual environment when activated. To deactivate, run:
+Initialize the schema (destructive — drops existing tables):
 
+```bash
+python src/dynamic_pricing/core/db_init.py
 ```
-deactivate
-```
-
-## Installing Dependencies
 
-This project not only has exter dependencies in `requirements.txt`, it also has a dynamic_pricing package that is set up using the `setup.py`. Therefore, to install all depdencies and build, run:
+Run the webhook locally, or via Procfile for production:
 
+```bash
+python src/dynamic_pricing/webhook/app.py
+gunicorn src.dynamic_pricing.webhook.app:app
 ```
-pip install -r requirements.txt
-pip install .
-```
-
-## Set up pre-commit
 
-This repository uses the pre-commit library to enable pre-commit hooks with the project. These hooks allow for various checks to be completed when you run git commit, ensuring that no un-linted and un-formatted code is persisted to the remote repositories. We have two main hooks set up:
+## Testing
 
-    Black (formatter)
-    Pylint (linting)
-
-You only need to set up pre-commit once when you clone this repo, by running:
-
-```
-pre-commit install
+```bash
+pytest                                      # unit tests
+pytest --cov=src --cov-report=html          # coverage report
 ```
 
-## Setting environment variables
+`pytest-postgresql` spins up an ephemeral Postgres for DB tests — no external database required.
 
-This repository contains an `.env.example` file with example environment variables for usage in the code. The code will attempt to read from `.env` file at the top level of the repository. To ensure this file is present, run:
+## Docker
 
-```
-cp .env.example .env
+```bash
+docker build -t dynamic_pricing .
+docker run -p 80:80 --env-file .env dynamic_pricing
 ```
 
-## Running test
+Point Deliveroo's webhook configuration at `http(s)://<host>/dev-webhook` (sandbox) or `/prod-webhook` (production).
 
-This project uses `pytest` as the unit testing framework. To run the unit tests, you can run:
+## Environment
 
-```
-pytest
-```
-
-We use pytest-cov as our coverage plugin. To run pytest and generate a HTML coverage report, you can run:
-
-```
-pytest --cov=src --cov-report=html
-```
+See `.env.sample`: `DEV_CLIENT_ID` / `DEV_SECRET` and `PROD_CLIENT_ID` / `PROD_SECRET` (Deliveroo OAuth2), `AWS_DB_*` (Postgres), `PARTNER1` / `PARTNER2` (tracked restaurants). All Deliveroo integration follows the [Orders API](https://api-docs.deliveroo.com/docs/introduction) spec.