# 💡 Core Concepts

## Overview

The Saturation API is designed to feel natural for both production teams and developers. It mirrors how real-world film and commercial productions operate, using human-readable IDs, flexible structures, and a philosophy that keeps things clear and simple.

**Design Philosophy:**

* **Human-first** — Use the same codes and names from your daily workflow.
* **Minimize friction** — Fewer calls, richer responses.
* **Stay flexible** — Adapt to *your* production style, not the other way around.


## Core Concepts

### Workspaces & Projects

* **Workspace** — Your company or organization; holds all projects, contacts, and settings.
* **Project** — A specific production, campaign, or job. Includes:
  * Multi-phase budget
  * Actual expense tracking
  * Purchase orders
  * Files & Notes


### Budgets

Budgets are hierarchical, matching production workflows:

* **Accounts** — Major categories (e.g., Above-the-Line)
* **Sub-accounts** — Nested for detail
* **Line Items** — Specific costs (quantity, rate, calculations)
* **Fringes** — Auto payroll taxes/benefits
* **Markups** — Percent or flat fees


### Phases

Track different versions of a budget:

* **Estimate** — Initial proposal
* **Working** — In-progress updates
* **Actual** — Real costs
* **Committed** — Locked POs
* **Rollups** — Compare versions (e.g., Variance)


### Actuals & Transactions

**Actuals** — Real expenses:

* Manual entries (receipts, invoices)
* Imported transactions via API
* Converted purchase orders
* Split across multiple categories


**Transactions** — Raw bank/credit card data:

* Import via CSV or API
* Review and bulk categorize
* Convert to actuals
* Maintain audit trail


### Contacts

People and companies in your production:

* **Crew** — Cast, directors, crew roles
* **Vendors** — Rentals, locations, catering
* **Clients** — Agencies, brands, studios


Contacts are workspace-level:

* One record across all projects
* Consistent IDs for reporting
* Historical spend analysis


### Human-Friendly IDs

Use `idMode=user` (human-readable) or `idMode=system` (stable UUIDs).

## Key Parameters

* **`expands`** — Pull related data in one call:



```
GET /projects/film-2025/budget?expands[]=phases&expands[]=lines.contact
```

* **`idMode`** — ID format:
  * `user` — Human-friendly (`"1100-LABOR"`)
  * `system` — UUID/nanoid


## Common Workflows

**Import a Budget:**


```
POST /projects/my-production/budget
{
  "accountId": "root",
  "lines": [{
    "type": "line",
    "accountId": "1100-LABOR",
    "phaseData": { "estimate": { "quantity": 10, "rate": 25000 } }
  }]
}
```

**Track Actuals:**


```
POST /projects/my-production/actuals
{
  "description": "Camera rental from Panavision",
  "amount": 15000,
  "date": "2024-03-15",
  "lineItemId": "2150",
  "contactId": "vendor-panavision",
  "tags": ["Day-1", "A-Camera"]
}
```

**Import & Convert Transactions:**


```
POST /projects/my-production/transactions/actualize
{
  "transactions": ["txn-001", "txn-002"],
  "lineItemId": "3100",
  "tags": ["Week-1"]
}
```

**Create a Contact:**


```
POST /contacts
{
  "name": "John Smith",
  "company": "Smith Camera Rentals",
  "type": "vendor",
  "email": "john@smithcamera.com",
  "taxId": "12-3456789"
}
```

**Create a Purchase Order:**


```
POST /projects/my-production/purchase-orders
{
  "number": "PO-001",
  "vendor": "contact-123",
  "items": [{
    "description": "Camera Package",
    "amount": 35000,
    "lineItemId": "2150"
  }]
}
```

**Split an Actual:**


```
PUT /projects/my-production/actuals/actual-001
{
  "expanded": true,
  "subActuals": [
    { "lineItemId": "2100", "amount": 10000 },
    { "lineItemId": "2200", "amount": 5000 }
  ]
}
```

## Best Practices

* Tag data by timeline, location, or department
* Use fringes for labor accuracy
* Define global variables for formulas
* Leverage `expands` to reduce calls


## Next Steps

1. Create a project
2. Import a budget
3. Apply `expands` and `idMode`
4. Integrate with existing tools