updated readme

README.md

@@ -0,0 +1,111 @@
+# EAMCO VoIP.ms Controller
+
+The **EAMCO VoIP.ms Controller** is a simple but powerful microservice for dynamically managing call routing for a business phone line hosted with VoIP.ms. It provides a clean, secure API to change where incoming calls are directed, allowing for easy switching between an office phone system and on-call cell phones.
+
+This service abstracts away the complexities of the VoIP.ms API, providing a task-oriented interface for day-to-day phone management.
+
+[![Language](https://img.shields.io/badge/Language-Python-blue)](https://www.python.org/)
+[![Framework](https://img.shields.io/badge/Framework-FastAPI-green)](https://fastapi.tiangolo.com/)
+[![VoIP Provider](https://img.shields.io/badge/Provider-VoIP.ms-e31d33)](https://voip.ms/)
+
+---
+
+## Use Case
+
+This service is designed to solve a common business problem: "Where should our main phone number ring?"
+
+-   **During business hours**, calls should go to the main office SIP account (the VoIP phones on desks).
+-   **After hours or on weekends**, calls should be forwarded to an on-call employee's cell phone.
+-   **If the primary on-call person is unavailable**, calls should be routed to a secondary backup number.
+
+This API allows for these changes to be made with a single, simple API call, which can be triggered from a script, a web dashboard, or even a physical button (like an IoT dash button).
+
+## Core Features
+
+-   **Dynamic Call Routing**: Instantly change the routing for a configured DID (phone number).
+-   **VoIP.ms API Abstraction**: Provides a simple interface over the powerful but complex VoIP.ms API. All communication with VoIP.ms is handled by the `voipms_client.py`.
+-   **Pre-configured Destinations**: Easily switch between routing to:
+    -   A main SIP/IAX account.
+    -   A primary cell phone number.
+    -   A secondary cell phone number.
+-   **Routing History**: Logs every successful routing change to a PostgreSQL database for auditing purposes.
+-   **Secure and Simple**: Built with FastAPI, providing automatic interactive documentation and a robust server.
+
+---
+
+## API Endpoints
+
+All routing endpoints are `POST` requests.
+
+-   `POST /route/main`
+    -   **Description**: Routes the main business line to the primary office SIP account. Use this to direct calls to the office phones.
+
+-   `POST /route/cellphone1`
+    -   **Description**: Forwards the main business line to the pre-configured primary cell phone.
+
+-   `POST /route/cellphone2`
+    -   **Description**: Forwards the main business line to the pre-configured secondary (backup) cell phone.
+
+-   `GET /test/forwardings` & `GET /test/did`
+    -   **Description**: Helper endpoints for testing the connection to the VoIP.ms API and retrieving diagnostic information.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+-   Python 3.10+
+-   A running PostgreSQL database.
+-   A VoIP.ms account with API access enabled.
+-   At least one DID (phone number) configured in your VoIP.ms account.
+-   Call Forwarding entries set up in the VoIP.ms portal for the cell phones you want to use.
+
+### 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.
+
+    You **must** fill in the following values in your chosen settings file:
+    -   `voipms_api_username`
+    -   `voipms_api_password`
+    -   `target_did`: The main phone number you want to control.
+    -   `target_sip_account`: The SIP account for your office phones.
+    -   `target_cellphone_1`: The primary cell phone number for forwarding.
+    -   `target_cellphone_2`: The secondary cell phone number.
+
+### Running the Service
+
+```bash
+export MODE=DEVELOPMENT
+uvicorn app.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`.
+
+---
+
+## Project Structure
+
+```
+eamco_voipms/
+├── app/
+│   ├── __init__.py
+│   ├── database.py       # SQLAlchemy engine and session setup
+│   ├── main.py           # FastAPI application, endpoints, and logic
+│   ├── models.py         # SQLAlchemy model for the call log
+│   └── voipms_client.py  # Client for communicating with the VoIP.ms API
+├── config.py             # Logic for loading environment-specific settings
+├── settings_dev.py       # Development-specific settings
+├── requirements.txt      # Python dependencies
+└── README.md             # This file
+```