docs: create comprehensive README

README.md

@@ -1,19 +1,124 @@
-# Eamco Authorize API
+# EAMCO Authorize API
 
-This is the authorization API for Eamco.
+**EAMCO Authorize** is a dedicated microservice for handling all payment and transaction-related operations. Built with FastAPI, it provides a secure and robust interface for processing payments through the Authorize.Net payment gateway.
 
-## Overview
+This service manages credit card authorizations, captures, and the secure handling of customer payment profiles via Authorize.Net's Customer Information Manager (CIM).
 
-[Add description here]
+[![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/)
+[![Payment Gateway](https://img.shields.io/badge/Gateway-Authorize.Net-orange)](https://www.authorize.net/)
 
-## Installation
+---
 
-[Add installation instructions]
+## Core Features
 
-## Endpoints
+- **End-to-End Payment Processing**: Handles the full lifecycle of a transaction, from pre-authorization to final capture.
+- **Authorize.Net Integration**: Uses the official `authorizenet` library for reliable and secure communication with the payment gateway.
+- **Customer Information Manager (CIM)**:
+    - Creates and manages customer profiles on Authorize.Net.
+    - Securely saves customer credit cards for future use, returning a tokenized payment profile ID.
+    - Allows transactions to be processed using a saved card ID, enhancing security and convenience.
+- **Transaction Logging**: Records every transaction attempt, success, or failure in a local PostgreSQL database for auditing and tracking.
+- **Clear API Structure**: Endpoints are organized by function (payment, transaction, auto-payments, user checks) for clarity and ease of use.
+- **Environment-Specific Configuration**: Loads different settings for `LOCAL`, `DEVELOPMENT`, and `PRODUCTION` environments.
 
-[Add endpoint details]
+---
 
-## Development
+## API Endpoints
 
-[Add dev setup]
+The API is structured into several routers:
+
+- `GET /`: Welcome endpoint.
+- `POST /api/payment`: Handles direct payment authorizations and charges.
+- `POST /api/transactions`: Manages the lifecycle of transactions, such as capturing a pre-authorized amount.
+- `POST /api/auto`: Likely handles transactions related to automated or recurring billing.
+- `POST /user/usercheck`: Performs checks related to user status or information.
+
+### Key Schemas
+
+- `TransactionAuthorize`: For pre-authorizing a new credit card.
+- `TransactionCreate`: For charging a new credit card directly.
+- `TransactionAuthorizeByCardID`: For pre-authorizing a saved credit card using its ID.
+- `TransactionCreateByCardID`: For charging a saved credit card using its ID.
+- `TransactionCapture`: For capturing a previously authorized amount.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- PostgreSQL database
+- An active Authorize.Net account with API credentials.
+
+### Installation
+
+1.  **Clone the repository:**
+    ```bash
+    # Make sure you have access to the git repository
+    git clone <your-repo-url>
+    cd eamco_authorize
+    ```
+
+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.
+
+    - **Set your Authorize.Net credentials** and database URI in the appropriate `settings_*.py` file.
+
+### Running the Service
+
+#### For Development
+
+You can run the service directly with Uvicorn, which provides live reloading. Set the `MODE` environment variable as needed.
+
+```bash
+export MODE=DEVELOPMENT
+uvicorn app.main:app --reload --host 0.0.0.0 --port 9616
+```
+
+The API will be available at `http://localhost:9616`, and interactive documentation can be found at `http://localhost:9616/docs`.
+
+#### Using Docker
+
+The project includes Dockerfiles for containerized deployment (`Dockerfile.local`, `Dockerfile.dev`, `Dockerfile.prod`).
+
+-   **Build the image (example for local):**
+    ```bash
+    docker build -f Dockerfile.local -t eamco_authorize:local .
+    ```
+-   **Run the container:**
+    ```bash
+    docker run -d -p 9616:9616 --env MODE=LOCAL --name authorize_api eamco_authorize:local
+    ```
+
+---
+
+## Project Structure
+
+```
+eamco_authorize/
+├── app/
+│   ├── __init__.py
+│   ├── crud.py           # Database create, read, update, delete operations
+│   ├── database.py       # SQLAlchemy engine and session setup
+│   ├── main.py           # FastAPI application and router inclusion
+│   ├── models.py         # SQLAlchemy ORM models
+│   ├── schemas.py        # Pydantic models for API request/response validation
+│   └── routers/          # API endpoint definitions (payment, transaction, etc.)
+├── config.py             # Logic for loading environment-specific settings
+├── settings_local.py     # Settings for the LOCAL environment
+├── settings_dev.py       # Settings for the DEVELOPMENT environment
+├── settings_prod.py      # Settings for the PRODUCTION environment
+├── Dockerfile.local      # Dockerfile for local builds
+├── requirements.txt      # Python dependencies
+└── README.md             # This file
+```