data/BUSINESS.md

# Truck Freight Forwarding Commission Agent - Business Reference

## What This Business Is

You are a **freight forwarding commission agent** operating in Kerala, India. You act as a middleman between **shippers** (companies that need goods transported) and **truck drivers/owners**. You don't own trucks -- you match loads with available vehicles and earn a commission on each load.

## How It Works

1. **Shippers** contact you with goods that need to be moved (e.g., from Thiruvananthapuram to Mumbai).
2. You find a **truck/driver** available for the route.
3. You negotiate a **freight charge** with the shipper (what the shipper pays).
4. You agree on a **driver freight** (what the driver gets paid).
5. The **difference** is your **commission/profit**.
6. You manage payments: collect from shipper, pay the driver, keep your cut.

## Key Financial Fields

- **freight_charged**: Total amount charged to the shipper (in INR)
- **advance_received**: Advance payment received from shipper before/during transit
- **paid_to_driver**: Amount paid to the truck driver
- **commission**: Your profit = freight_charged - paid_to_driver (approximate)
- **pending_from_shipper**: Money still owed by shipper (balance freight not yet collected)
- **pending_to_driver**: Money still owed to driver
- **driver_freight**: Sometimes used to record the agreed freight rate with driver

## Status Types

- **settled**: All payments complete -- shipper paid in full, driver paid in full
- **commission received**: Shipper handled driver payment directly; you only collected your commission
- **commission adjusted**: Commission was adjusted (partial or special arrangement)
- **commission due**: Commission is pending/not yet received
- **pending collection**: Balance freight still needs to be collected from shipper
- **partially pending**: Some payment still outstanding (either side)
- **fully pending from shipper**: No payment received from shipper yet
- **assigned vehicle**: Vehicle assigned but load details/financials not yet finalized
- **loaded / in transit**: Truck has loaded and is on the road
- **partial**: Incomplete record -- some details missing
- **available vehicle**: Truck is available, looking for a load
- **pending lead**: Potential load/shipper lead, not yet confirmed
- **handled directly by shipper**: Shipper managed everything; you were just a referral
- **reconciled**: Settled after some back-and-forth adjustments

## Major Shippers (Regular Clients)

| Shipper | Typical Routes | Notes |
|---|---|---|
| Kahn Transport | Thiruvananthapuram → Mumbai, Cochin → Mumbai | Frequent full loads, 34k-55k freight |
| Agarwal Packers and Movers | Trivandrum → Mumbai/Chennai/Hyderabad/Theni/Thirupathy | Regular client, various routes |
| Sahara Packers | Thiruvananthapuram → Mumbai/Palakkad, Adoor → Cochin | Part loads and full loads |
| Ambika Packers | Thiruvananthapuram → Kalpetta/Thrissur/Cochin | Regular |
| Century Polymers | Kollam → Bangalore/Chennai | Commission-based |
| DRS | Thiruvananthapuram → Coimbatore/Mumbai | Regular |
| Superstar | Marthandam → Chennai, Pathanamthitta → Cochin | Regular |
| Chips | Thiruvananthapuram → Palakkad | Regular |
| Indian CBE | Thiruvananthapuram → Coimbatore | Regular |
| KTC | Thiruvananthapuram → Coimbatore/Hyderabad | Regular |
| ATC | Thiruvananthapuram → Mumbai | Occasional |
| TCI | Thiruvananthapuram → Bangalore | Occasional |
| Filatex | Thiruvananthapuram → Palakkad | Occasional |
| Dryfish John | Kollam → Tiruchirappalli | Commission-based |
| Sun Packers | Changanassery → Coimbatore | Occasional |
| Thangavel | Thiruvananthapuram → Erode | Occasional |
| Nafees Alappuzha | Perumathura → Tiruchirappalli | Occasional |
| Shivaprasad | Thiruvalla → Tanjavur | Occasional |
| Jinu Coin | Trivandrum → Chennai | Occasional |
| Balmer Thuni | Kottarakara → Bangalore | Occasional |
| Pasupathy | Thiruvananthapuram → Coimbatore | Occasional |
| Badadosth | Thiruvananthapuram → Vellore | Contact lead |
| Sulphi Baddest | Thiruvananthapuram → Chennai | Pending lead |
| Gem | Bangalore | Direct handling |

## Common Routes

| Route | Typical Freight (INR) | Distance/Type |
|---|---|---|
| Thiruvananthapuram → Mumbai | 34,000 - 55,000 | Long haul, full load |
| Cochin → Mumbai | 34,000 - 35,000 | Long haul, full load |
| Trivandrum → Chennai | 17,000 - 24,000 | Medium haul |
| Thiruvananthapuram → Coimbatore | 7,000 - 12,000 | Short haul |
| Thiruvananthapuram → Palakkad | 6,000 - 14,500 | Short haul |
| Kollam → Bangalore | 11,000 - 21,000 | Medium haul |
| Thiruvananthapuram → Hyderabad | 28,000 - 38,000 | Long haul |
| Thiruvananthapuram → Bangalore | 17,000 | Medium haul |
| Trivandrum → Mysore | 16,500 | Medium haul |
| Thiruvananthapuram → Thrissur | 5,500 | Short haul |
| Thiruvananthapuram → Erode | 12,000 | Medium haul |
| Thiruvananthapuram → Kochi/Cochin | 4,500 - 7,000 | Very short haul |
| Trivandrum → Theni | 9,000 | Short haul |
| Trivandrum → Vellore | TBD | Medium haul |

## Business Snapshot (as of last data entry)

- **Total records**: 62 (mix of loads, leads, available vehicles)
- **Settled loads**: 18
- **Pending/partial/assigned**: 22
- **Total freight charged**: Rs. 8,88,500
- **Total advance received**: Rs. 4,58,800
- **Total paid to drivers**: Rs. 5,83,425
- **Total commission earned**: Rs. 38,215
- **Pending from shippers**: Rs. 21,700
- **Pending to drivers**: Rs. 5,500

## Data Collection Method

Data is collected from **WhatsApp conversations** with the user. The user shares load details, payment updates, and business information via WhatsApp, which gets recorded into the ledger.

## How to Add New Records

Use the `append_load.py` script:

```bash
python3 append_load.py new_record.json
```

The JSON should follow this schema:
```json
{
  "id": "unique-id",
  "date": "YYYY-MM-DD",
  "vehicle": "VEHICLE_NUMBER or -",
  "from": "Origin city",
  "to": "Destination city",
  "via": ["optional", "via", "cities"],
  "shipper": "Shipper name",
  "load_type": "Full load / Part load / Mixed",
  "item": "Goods description or null",
  "deliveries": ["multi-drop", "locations"],
  "freight_charged": 0,
  "advance_received": 0,
  "paid_to_driver": 0,
  "commission": 0,
  "pending_from_shipper": 0,
  "pending_to_driver": 0,
  "status": "settled",
  "notes": "Any additional context"
}
```

The script auto-regenerates the CSV and summary files.

## Git Workflow

- Repo: Forgejo at `forgejo-oa09toasww4dgii9cj3gpzda.187.127.164.61.sslip.io`
- User: `iamcoolvivek007`
- Repo name: `data`
- After making changes, commit and push:
  ```bash
  cd /root/data
  git add -A
  git commit -m "description of changes"
  git push
  ```

## Notes for Future AI Agents

- This is a **commission agent** business, not a trucking fleet owner
- The user's income comes from the **spread** between what shippers pay and what drivers receive
- Many loads are **commission-only** where the shipper pays the driver directly and the user just takes a commission
- **Kahn Transport** and **Agarwal Packers** appear to be the biggest/most frequent shippers
- The user operates primarily in **Kerala** (Thiruvananthapuram, Kollam, Cochin, etc.) with loads going to Mumbai, Chennai, Bangalore, Coimbatore, Hyderabad, and other South Indian cities
- Some records are not actual loads but **leads** (potential business) or **available vehicles** (trucks looking for loads)
- The data may have incomplete records (marked as "partial") where the user hasn't filled in all details yet
- Currency is **INR** (Indian Rupees)