diff --git a/BUSINESS.md b/BUSINESS.md new file mode 100644 index 0000000..2be8c2b --- /dev/null +++ b/BUSINESS.md @@ -0,0 +1,163 @@ +# 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)