Set it up, call it, extend it.Set it up, call it, extend it.

Tessera RP is a Next.js application over Postgres. It reads your systems of record on a schedule, lands the raw payloads, maps them into an ERP-agnostic star schema, and serves a governed metric catalog on top. There is one HTTP surface for reading data and it does not accept SQL.

Two things follow from that and shape every integration you will write. Data comes out through a QuerySpec, which names metric and dimension ids rather than tables. Data goes in through a Connector, which knows about a source API and nothing about the warehouse.

Names and purpose below; values belong in your own environment file. Only the first three are required to boot.

Every read path — a dashboard tile, the Explore workbench, an alert evaluation, the assistant — builds a QuerySpec and hands it to the compiler. There is no endpoint that accepts SQL, because there is no code path in the product that writes any.

QuerySpec
  → zod validate            shape and types
  → resolve ids vs catalog  every metric and dimension must exist
  → append caller scope     added after the caller's own filters
  → emit SQL                engine-neutral, params bound separately

The one object you construct. Validated by zod on the way in; unknown keys are rejected.

// Relative — resolved against the tenant's clock at query time, so a
// saved dashboard means "last 30 days" forever rather than freezing a date.
{ "kind": "relative", "range": "last_90_days" }

today · yesterday · last_7_days · last_14_days · last_28_days
last_30_days · last_90_days · last_180_days · last_365_days
week_to_date · month_to_date · quarter_to_date · year_to_date
previous_week · previous_month · previous_quarter · previous_year
all_time

// Absolute — both bounds YYYY-MM-DD.
{ "kind": "absolute", "from": "2026-01-01", "to": "2026-03-31" }

// Filter
{ "dimension": "channel", "operator": "in", "value": ["DTC-US"] }

eq · neq · in · not_in · gt · gte · lt · lte
between · contains · starts_with · is_null · is_not_null

Isolation is enforced in the database, not in application code. Every tenant-scoped table has row-level security with ENABLE and FORCE; policies compare against app.current_tenant(), which reads a transaction-local setting opened by withTenant().

A forgotten WHERE tenant_id = … in application code therefore returns zero rows rather than another customer's data. That is the difference between trying to scope queries and cross-tenant reads being impossible.

Row-level data_scope is a second, finer layer. A membership row can carry {"channel":["DTC-US"]}, and the compiler appends those as mandatory filters after any the caller supplied — so a caller cannot widen their own scope by editing a payload.

Role rank gates mutations; data scope gates rows. The two are independent.

The API is authenticated by session cookie. Log in once and send the cookie with subsequent calls.

curl -i -X POST https://your-host/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"…"}'

# → Set-Cookie: erpai_session=…; HttpOnly; Secure; SameSite=Lax

The cookie holds an opaque random token; only its SHA-256 hash is stored server-side. The session carries active_tenant_id, so switching workspace is a session update rather than a re-login.

Failures return a JSON body with a stable code and a message safe to show a user.

{
  "error": {
    "code": "VALIDATION",
    "message": "That query is not valid.",
    "details": { "metrics": ["At least one metric is required"] }
  }
}

Two tiers. An address-keyed bucket runs before the session lookup so an anonymous flood stops at the edge, then a user-keyed bucket protects the tenant from one broken client.

The assistant plans a QuerySpec and runs it through the same compiler as everything else. It returns the spec it built, so an answer can always be audited or pinned to a dashboard.

{
  "question": "which channels lost contribution margin last quarter?"
}

Six members, no inheritance. A connector talks to a source API and deliberately knows nothing about the warehouse schema — which is what makes adding an ERP a contained change.

export interface Connector {
  readonly system: SourceSystem;
  readonly displayName: string;
  /** Streams this connector can supply, in dependency order. */
  readonly streams: StreamDescriptor[];

  /** Validates credentials without pulling data. Powers the Test button. */
  check(ctx: ConnectorContext): Promise<ConnectionCheckResult>;

  /**
   * Pulls one page. The runner calls this repeatedly, persisting the
   * returned cursor after each page, so an interrupted sync resumes
   * rather than restarts.
   */
  fetchPage(
    ctx: ConnectorContext,
    stream: StreamName,
    cursor: SyncCursor | null,
    mode: SyncMode
  ): Promise<StreamPage>;
}

interface RawRecord {
  sourceId: string;                    // stable PK within (tenant, source, stream)
  updatedAt: Date | null;              // the incremental watermark
  payload: Record<string, unknown>;    // untouched source payload
  deleted?: boolean;                   // set on a hard-delete tombstone
}

interface SyncCursor {
  watermark: string | null;            // high-water mark on updated-at
  pageToken?: string | null;           // for token-paginated sources
  offset?: number | null;              // for offset-paginated sources
}

The logical record types every connector maps its source objects onto — the contract between pull and transform. A connector declares which it can supply, in dependency order.

// Commercial
customers · products · sales_orders · sales_order_lines
invoices · invoice_lines · credit_memos · returns · payments
purchase_orders · purchase_order_lines · suppliers · shipments
inventory_levels · channels · currencies · fees · gl_entries

// ERP structural — an e-commerce source has none of these
legal_entities · sites · warehouses · locations
inventory_dimensions · inventory_positions · inventory_transactions

// Kept separate, deliberately
pos_transactions   // a till receipt has no order behind it
gl_accounts        // account TYPE separates P&L from balance sheet
ar_open · ap_open  // what is still OWED, not what was billed

A mapper is a pure function from one raw payload to canonical rows. It lives in lib/transform, which knows nothing about HTTP or metrics, and it is the only place a source's field names appear.

Return null for a record you cannot map. It becomes a dead-letter row, the sync continues, and the volume is surfaced in Data Admin — schema drift costs a row rather than a run.

A metric is a catalog entry in lib/semantic, not a query. Define it once and every surface — tiles, Explore, alerts, exports, the assistant — resolves the same definition, which is what makes two reports unable to disagree.

An in-process scheduler runs connector syncs and evaluates alert rules on an interval. Sync is batch and incremental — freshness is surfaced rather than hidden, and sub-minute latency would require change data capture and a different storage tier.

Logs are structured single-line JSON with deep key-based redaction, carrying requestId and tenantId on every request-scoped line. app.usage_event doubles as the metering and the coarse telemetry stream.