docs: create comprehensive README

README.md

@@ -0,0 +1,122 @@
+# EAMCO Auto-Delivery API
+
+The **EAMCO Auto-Delivery API** is an intelligent microservice responsible for managing and automating heating oil deliveries. Using a predictive model based on weather data, it estimates when customers will need a refill and helps schedule deliveries proactively.
+
+This service is the backbone of the automatic delivery program, featuring a self-correcting algorithm that refines its predictions over time, ensuring customers never run out of oil.
+
+[![Language](https://img.shields.io/badge/Language-Python%203.11-blue)](https://www.python.org/)
+[![Framework](https://img.shields.io/badge/Framework-FastAPI-green)](https://fastapi.tiangolo.com/)
+[![Database](https://img.shields.io/badge/Database-PostgreSQL-blue)](https://www.postgresql.org/)
+
+---
+
+## Core Features
+
+- **Predictive Fuel Estimation**: The core `FuelEstimator` script calculates daily fuel consumption for each automatic delivery customer based on historical temperature data (Heating Degree Days).
+- **Intelligent K-Factor**: Each customer has a unique "K-Factor" (house consumption factor) that represents their home's specific fuel usage rate.
+- **Self-Correcting Algorithm**: After a delivery is completed, the service uses the actual gallons delivered to refine the customer's K-Factor, making future predictions progressively more accurate.
+- **Automated Delivery Ticketing**: Automatically identifies customers who are low on fuel and provides endpoints to create delivery tickets.
+- **Driver and Delivery Management**: Offers API endpoints to view upcoming deliveries for all customers or for specific drivers.
+- **Weather Integration**: Fetches daily temperature data from a weather API to feed its prediction model.
+
+## How It Works
+
+The service's intelligence lies in its daily estimation and refinement cycle:
+
+1.  **Daily Update**: A scheduled job calls the `/main/update/auto` endpoint.
+2.  **Fetch Temperature**: The service ensures it has the latest daily temperature from an external weather API.
+3.  **Estimate Consumption**: For each customer, it calculates the day's estimated fuel consumption using the temperature and the customer's unique K-Factor.
+4.  **Identify Low-Fuel Customers**: It queries for customers whose estimated remaining gallons have fallen below a certain threshold.
+5.  **Create Tickets**: The system (or a user) can then create a delivery ticket for these customers via the `/confirm/auto/create/{autoid}` endpoint.
+6.  **Confirm Delivery**: Once the delivery is made, a `PUT` request to `/confirm/auto/update/{autoid}` with the actual `gallons_delivered` is made.
+7.  **Refine K-Factor**: This is the crucial step. The service compares its predicted usage against the actual usage (based on gallons delivered) and adjusts the K-Factor, improving the accuracy of all future predictions for that customer.
+
+---
+
+## API Endpoints
+
+### Main Triggers
+
+- `GET /main/temp`
+  - **Description**: Manually triggers the fetch and storage of the current day's temperature.
+- `GET /main/update/auto`
+  - **Description**: The main cron job entry point. Triggers the daily fuel consumption update for all automatic delivery customers.
+- `GET /main/update/normal`
+  - **Description**: Triggers the daily fuel consumption update for "normal" (non-auto) customers.
+
+### Delivery & Ticket Management
+
+- `POST /confirm/auto/create/{autoid}`
+  - **Description**: Creates a new delivery ticket for an automatic delivery customer, often with pre-authorization details.
+- `PUT /confirm/auto/update/{autoid}`
+  - **Description**: Confirms a delivery by providing the actual gallons delivered. This triggers the K-Factor refinement.
+- `GET /delivery/all/customers`
+  - **Description**: Returns a list of all automatic delivery customers, ordered by who needs a delivery most urgently.
+- `GET /delivery/driver/{driver_employee_id}`
+  - **Description**: Gets a list of all pending automatic deliveries assigned to a specific driver.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- PostgreSQL database
+- Access to a weather API (configured in settings).
+
+### Installation
+
+1.  **Clone the repository and navigate into it.**
+
+2.  **Create a virtual environment and install dependencies:**
+    ```bash
+    python -m venv venv
+    source venv/bin/activate
+    pip install -r requirements.txt
+    ```
+
+3.  **Configure your environment:**
+    The application's configuration is managed by environment variables set in `settings_local.py`, `settings_dev.py`, or `settings_prod.py`. The `MODE` environment variable determines which configuration to use.
+
+### Running the Service
+
+#### For Development
+
+```bash
+export MODE=DEVELOPMENT
+uvicorn main:app --reload --host 0.0.0.0 --port <your_port>
+```
+
+The API will be available at `http://localhost:<your_port>`, with interactive docs at `http://localhost:<your_port>/docs`.
+
+#### Using Docker
+
+The project includes Dockerfiles for containerized deployment.
+
+-   **Build the image:**
+    ```bash
+    docker build -f Dockerfile.local -t eamco_auto_api:local .
+    ```
+-   **Run the container:**
+    ```bash
+    docker run -d -p <your_port>:<your_port> --env MODE=LOCAL --name auto_api eamco_auto_api:local
+    ```
+---
+
+## Project Structure
+
+```
+eamco_auto_api/
+├── app/
+│   ├── models/           # SQLAlchemy ORM models (Auto_Delivery, Tickets_Auto_Delivery)
+│   ├── routers/          # API endpoint definitions (main, confirm, delivery)
+│   ├── schema/           # Pydantic models (if any)
+│   └── script/           # Core logic (FuelEstimator, temp_getter)
+├── config.py             # Logic for loading environment-specific settings
+├── database.py           # SQLAlchemy engine and session setup
+├── main.py               # FastAPI application entry point
+├── settings_local.py     # Settings for the LOCAL environment
+├── requirements.txt      # Python dependencies
+└── README.md             # This file
+```