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:

python3 append_load.py new_record.json

The JSON should follow this schema:

{
  "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:

  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)