> ## Documentation Index
> Fetch the complete documentation index at: https://dhanurgo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Investor Revenue Share

> Three-pool expense model and revenue split calculations

# Investor Revenue Share

When a host has investors/co-hosts who own vehicles, trip earnings are split according to a revenue sharing agreement.

## Core Concept

Each investor has:

* **Owner share** (e.g., 20%) — The host's cut
* **Investor share** (e.g., 80%) — The investor's cut
* **Revenue inclusions** — Which earnings line items are included in the split
* **Expense treatment** — How vehicle expenses affect the split

## Revenue Adjustment (Inclusion Toggles)

Before splitting, certain revenue items can be excluded from the calculation:

| Toggle            | Default      | If Excluded                      |
| ----------------- | ------------ | -------------------------------- |
| Trip Price        | Included     | Never excluded (always on)       |
| Delivery Fees     | Included     | Host keeps 100% of delivery fees |
| Extras            | Included     | Host keeps extras revenue        |
| Tolls             | **Excluded** | Host absorbs toll costs          |
| Late Fees         | Included     | Host keeps late fees             |
| Gas Reimbursement | **Excluded** | Host absorbs gas costs           |
| EV Charging       | **Excluded** | Host absorbs EV charging         |
| Cleaning Fees     | Included     | Host keeps cleaning fees         |
| Cancellation Fees | Included     | Host keeps cancellation fees     |
| Additional Usage  | Included     | Host keeps usage charges         |
| Boost Earnings    | Included     | Host keeps boost earnings        |

```
Adjusted Revenue = Total Earnings
    - (if tolls excluded: tolls_and_tickets)
    - (if gas excluded: gas_reimbursement)
    - (if EV excluded: on_trip_ev_charging + post_trip_ev_charging)
    - (if delivery excluded: delivery)
    - (if extras excluded: extras)
    - (if late fees excluded: late_fee)
    - ... etc for each toggled-off item
```

## Three-Pool Expense Model

Vehicle expenses are handled through three "pools":

### Pool A: Investor Covers

Expenses the investor pays directly. These are **subtracted from the investor's share after the split**.

Example: Investor pays for insurance directly → deducted from their payout.

### Pool B: Deduct Before Split

Expenses deducted from gross revenue **before** the split ratio is applied. Both parties share the cost proportionally.

Example: A $100 repair with 80/20 split → Revenue reduced by $100, then split. Investor effectively pays $80, host pays $20.

### Pool C: Split Proportionally

Expenses split at a custom ratio (which may differ from the revenue split ratio).

Example: Maintenance split 50/50 regardless of the 80/20 revenue split.

## Expense Treatment Cascade

Settings are applied in priority order:

1. **Per-vehicle per-category** override (highest priority)
2. **Per-vehicle default** treatment
3. **Investor-level default** treatment
4. **System fallback**: `investor_covers`

## Worked Example

**Setup:**

* Investor share: 80%, Host share: 20%
* Tolls: excluded, Gas: excluded, all others: included
* Expense treatment: "deduct\_before\_split" (Pool B)

**Trip earnings:**

| Item              | Amount   |
| ----------------- | -------- |
| Trip price        | \$285.00 |
| Delivery          | \$25.00  |
| Extras            | \$15.00  |
| Tolls             | \$8.50   |
| Gas reimbursement | \$12.00  |
| Total earnings    | \$345.50 |

**Step 1: Adjust revenue (exclude tolls + gas)**

```
Adjusted = $345.50 - $8.50 (tolls) - $12.00 (gas) = $325.00
```

**Step 2: Deduct expenses (Pool B)**

Vehicle had a \$50 oil change this period:

```
After expenses = $325.00 - $50.00 = $275.00
```

**Step 3: Apply split**

```
Investor share = $275.00 x 80% = $220.00
Host share     = $275.00 x 20% = $55.00
```

**Step 4: Subtract charges**

Investor has a \$15 parking violation charge:

```
Investor payout = $220.00 - $15.00 = $205.00
```

## Per-Vehicle Overrides

Each vehicle assigned to an investor can have different:

* Revenue inclusion toggles (independent of investor defaults)
* Expense treatment (override the investor's default)
* Per-category expense treatment (e.g., "maintenance" → split\_proportionally, "insurance" → investor\_covers)

This allows fine-grained control when an investor owns multiple vehicles with different agreements.

## Key Files

| File                                       | Purpose                                   |
| ------------------------------------------ | ----------------------------------------- |
| `src/lib/calculations/investorEarnings.ts` | Three-pool expense model implementation   |
| `src/lib/calculations/vehicleRevenue.ts`   | Revenue adjustment with inclusion toggles |
| `src/lib/db/investors.ts`                  | Investor CRUD + payment creation          |
| `src/lib/db/schema/investors.ts`           | Type definitions                          |