# Layerz

> Layerz is the API-first financial projection engine. It separates business logic (versioned, structured code) from data (editable Excel), enabling AI agents to programmatically build, compute, and export audit-ready financial models. Think "Figma for financial models" — design the structure once, generate perfect Excel workbooks on demand.

## What Layerz Does

Layerz lets you create structured financial meta-models where every assumption is explicit, every formula is transparent, and every output is traceable. Models are built from typed items (assumptions, formulas, layers, balances) organized in a section-first hierarchy. The compute engine evaluates all items in dependency order, and the export pipeline generates self-contained Excel workbooks with live formulas, editable assumption cells, and proper financial formatting.

Unlike spreadsheets, Layerz models never break when you change structure. Add a timeline, insert an item, modify a formula — the engine re-resolves all dependencies automatically.

## Use Cases

Layerz is used to build any financial projection model programmatically:

- **SaaS Revenue Model** — MRR, churn rate, expansion revenue, unit economics, LTV/CAC
- **Startup Runway** — Burn rate, funding rounds, hiring plan, cash runway milestones
- **LBO Analysis** — Debt tranches, leverage ratios, interest schedules, equity returns, IRR
- **Manufacturing P&L** — Raw materials, labor costs, production capacity, gross margins, capex
- **Consulting Agency** — Utilization rates, day rates, headcount planning, project pipeline
- **Infrastructure Project** — Capex schedule, depreciation, operating cash flows, IRR/NPV
- **Fintech Lending** — Loan book growth, default rates, net interest margin, provisions
- **Real Estate Development** — Construction costs, rental income, vacancy rates, cap rates
- **E-commerce** — GMV, conversion rates, average order value, fulfillment costs, contribution margin

## Why AI Agents Use Layerz

- **Deterministic & Auditable** — Every formula is transparent. Results are reproducible. No hidden cells.
- **Structured, Not Flat** — Typed items with explicit dependencies. No cell-reference guessing.
- **Compute on Demand** — One API call evaluates the entire model in dependency order.
- **Open Excel Output** — Export audit-ready .xlsx with live formulas. No vendor lock-in.
- **Version-Controlled Logic** — Model structure is code. Version it, diff it, branch it.
- **Multi-Timeline** — Monthly, yearly, quarterly, constant periods with automatic cross-timeline projection.

## Key Concepts

- **Model** — Named container with timelines and ordered items. Pre-loaded with default sections (P&L, Cash flow, Balance sheet).
- **Timelines** — Four types: `constant` (single value), `monthly`, `yearly`, `quarterly`. Each has start/end dates.
- **Items** — Six roles: `assumption` (input), `formula` (computed), `callup` (copy), `layer` (sum container), `balance` (cumulative), `section` (structural).
- **Compute** — Evaluates all items via topological sort. Returns values indexed by UID.
- **Lists** — Parametric dimensions (e.g., departments, products) with per-element values and formulas.

## Authentication

API key format: `lz_<40 hex>`. Pass as `Authorization: Bearer <key>`. Generate keys at app.layerz.cc → Avatar → Layerz for Agents.

Rate limit: 120 requests/min per IP.

## Core Endpoints

- `POST /api/v1/models` — Create model (with default sections and timelines)
- `GET /api/v1/models/:id` — Get model detail with all items and timelines
- `POST /api/v1/models/:id/items` — Add a single item (assumption, formula, layer, etc.)
- `POST /api/v1/models/:id/items/batch` — Batch add up to 100 items with temp_id resolution
- `PATCH /api/v1/models/:id/items/:uid` — Update item fields (values, formula, name)
- `GET /api/v1/models/:id/compute` — Evaluate all items, return computed values
- `GET /api/v1/models/:id/snapshot` — Download full model (CLI sync)
- `PUT /api/v1/models/:id/snapshot` — Upload full model with optimistic concurrency
- `POST /api/v1/models/:id/versions` — Create version snapshot
- `POST /api/v1/models/:id/items/reorder` — Reorder items within model or layer

## CLI

Install: `npm run build:cli` → `node cli/dist/layerz.js`

Key commands: `create`, `add-item`, `validate`, `compute`, `export`, `pull`, `push`, `diff`.

The CLI works with `.layerz.json` files locally and syncs to the server via push/pull. Ideal for coding agents (Claude Code, Cursor, Windsurf).

## Formula Functions

`MAX`, `MIN`, `IF`, `ABS`, `POW`, `IRR`, `NPV`, `PMT`, `IPMT`, `PPMT`, `AND`, `OR`, `NOT`, `EDATE`, `IN_PERIOD`

Lag syntax: `uid_Y-1` (previous year), `uid_M-1` (previous month), `uid_Q-1` (previous quarter).

## Links

- [Full API & CLI Reference](https://app.layerz.cc/llms-full.txt)
- [Agent Integration Guide](https://app.layerz.cc/for-agents)
- [Get Started](https://app.layerz.cc)