Tessera — Architecture Overview

User Layer What users see and interact with v1 + v2

Single-Metric Portletv1

One governed metric per portlet. Tab-switched chart views by metric shape. Cache age always visible. Placed on NS home dashboard by role or user.

ECharts (not JET)one script → all instancesserver-render + client initinline styles (portlet CSP)

Custom portlet via SuiteScript 2.1 — render(params) writes HTML to params.portlet.html
One script deployment serves all portlet instances. Portlet Config record ID passed as deployment parameter — identifies metric and definition version
Tab model by metric shape: Summary · Trend · Meter · Distribution · Composition · Funnel — not all tabs on all metrics
ECharts option objects constructed server-side, serialized inline — no client-side data fetching at render time
Element IDs namespaced by Portlet Config record ID — multiple Tessera portlets coexist without collision
Override indicator: amber badge when definition is not system-recommended. Tooltip shows override note and acknowledging user
Cache age always displayed — computed from Metric Result computed_at. Cache miss → "No data yet", not an error

Multi-Metric Portletv1

Multiple governed metrics inside one custom dashboard portlet. Compact summary view per metric — KPI value, trend spark, status indicator.

EChartssame portlet scriptmultiple Portlet Configs

Same Portlet script and deployment model as single-metric — Portlet Config record drives layout mode
Each metric resolves its own Resolution Policy and definition version independently
Compact layout: KPI value + trend spark + cache age per metric. Full tab view accessed via drill-through
Override indicators preserved per metric — each metric's governance status independently visible

Portlet Group SPAv2

Multi-metric workspace with grid layouts, cross-metric views, and detail drill-down with tabular export. Suitelet-based — opens outside the portlet frame.

AG Grid CommunitySuiteletECharts

Full-page Suitelet — not constrained by portlet iframe dimensions or inline-style CSP
Configurable metric groupings with grid layout (v2 Portlet Group record)
AG Grid drill-down — three-tier: <5k direct render, <50k server-side pagination, >50k async M/R export
Role-based export gating — not all roles can export raw component-level data

Tessera Adminv1

Full administration surface — Metric Wizard, Status Dashboard, Approval Domain manager, Segment manager, Benchmark manager, Metric Comparison workflow, portlet placement, and audit trail.

Suiteletcustom record UIthree-tab status dashboard

Metric Wizard — 6-step guided flow: Formula Pattern picker → component configuration (template, primary window, comparison offset, filters) → dimension scope → pre-flight result card → Controller sign-off. Wizard state persists as draft record — survives timeout and logout
Status Dashboard — three tabs: (1) Metric Definitions — all active metrics, version status, approval state; (2) Cache & CRL — last refresh run, stale result count, per-metric cache age, CRL run history; (3) Audit Trail — all governance events, override log, version change history, sign-off records
Approval Domain Manager — catch-all domain at install, carve-out flow for sub-domains, overlap validation on save, approver assignment with role verification
Segment Manager — hierarchy editor, leaf/rollup type assignment, NS Dimension Value mapping, reparent via explicit Move Segment action (triggers M/R reindex — not a direct field edit)
Benchmark Manager — Benchmark Series creation, Data Point entry by industry × revenue band × percentile, series status and vintage management
Metric Comparison workflow (v2) — initiate comparison between two definitions, review AI-generated diff, record resolution decision, generate Resolution Policy
Portlet Placement — place portlets on dashboards by role or user, Portlet Config record created, definition assigned directly. Resolution Policy recommendation is v2.

Application Layer — MDL · MLL · Engines Metric definition, lineage, query execution, caching, governance routing v1

Named Layers (reserved acronyms)

Metric Definition Layer (MDL)core layer

The governed schema — 18 custom record types storing everything that defines, computes, governs, and audits a metric. The source of truth every other component reads from.

18 custom recordsimmutable after approvaleffective datingversion chains

Structural Core (R1–6): Metric Definition · Query Component · Filter/Scope · Dimension Scope · Minor Change Log · Metric Result
Governance (R7, R10): Approval Domain · Portlet Config · Metric Comparison (R8, v2) · Resolution Policy (R9, v2)
Shared Library (R11–12): Query Template (4 v1 templates — record + code deployment) · Formula Pattern (8 v1 patterns — data change to add)
Benchmark (R13–14): Benchmark Series · Benchmark Data Point
Segment (R15): adjacency list + materialized path strings for recursive-free rollup queries
Query Template Slot (R16): named slot definitions per Query Template record
Verification Source Library (R17): pre-built verification source types for Wizard pre-flight (Step 5)
Event Log (R18): append-only domain event store — cache invalidation events and metric lifecycle status transitions
Metric Definition immutable after Controller sign-off — material changes create a new version requiring re-approval. Minor changes (display name, thresholds, chart type) logged without re-approval
Version chain: Effective From / Effective To / Scheduled Effective Date — all system-managed

Metric Lineage Layer (MLL)core layer

Reads MDL records and renders a plain-English lineage trace for every metric — what it computes, what it includes, what it excludes, and why. Powers Controller sign-off review and dashboard detail views.

reads MDL recordsSIL-assisted summariesprovisional patent candidate

Reads: Metric Definition, Query Component (Component Label — never the Role letter), Filter/Scope, Formula Pattern, Query Template MLL description templates
Renders: metric-level plain English summary, per-component lineage blocks, filter conditions in plain language, formula explanation with component value breakdown
Used in: Metric Wizard pre-flight step, Controller sign-off review, portlet "View definition" detail, Metric Comparison AI diff input (v2)
Constant components rendered inline ("trailing 90 days") — no separate lineage block
Role letter (A/B/C) is machine-facing only — Component Label always shown to users

Engines

Query Engineengine

Reads Query Component + Filter/Scope records, resolves Query Template slots, assembles and executes SuiteQL, combines component scalars via mathjs formula evaluation.

N/query SuiteQLmathjs evaltwo-source routing

Three component paths: Structured (template slot resolution → SuiteQL), Raw SuiteQL (execute directly), Constant (read value, no query)
Three-tier query strategy: Tier 1 (AccountPeriodActivity) for period-end balances — no dimension filter; Tier 1.5 (PostingAccountActivity) for class/department/location-filtered aggregations ~88ms; Tier 2 (TransactionAccountingLine → Transaction → AccountingPeriod) for transaction-type filters. Confirmed in sandbox validation 2026-06-02. See tessera_platform_validation.md.
Period resolver reads AccountingPeriod records to derive comparison windows (sply, sqly_td, lqtd, lytd_fy…) — no raw date arithmetic
Negate field: prefixes -SUM() for credit-normal accounts — sign convention explicit and auditable
mathjs evaluates Formula Pattern formula string against component scalar map → final metric result

Cache & Refresh Engine (CRL)engine

Manages metric result freshness. Closed-period results stored permanently — never recomputed. Open-period results marked as stale by transaction events and recomputed on the next scheduled run.

Map/ReduceUser Event scriptsevent-driven

Scheduled refresh: Map/Reduce script processes all active metrics on configured cadence — architecture design pending
Event-driven: User Event scripts on key transaction record types mark open-period Metric Results as stale on post/approve. Closed-period results never touched
Closed-period immutability: once a period closes, Metric Result records for that period are permanent. Substantially reduces GU consumption and aligns with accounting-grade positioning
On-demand refresh: escape hatch for open-period results — v2 (requires client-side Restlet call)
Per-metric transaction type trigger configuration — which record types mark which metrics stale — open design item (Query Layer design session)

Resolution Engineengine

[v2] Enforces Metric Resolution Policy at portlet placement. Determines which definition is surfaced to which user, handles override acknowledgment, writes the permanent override record. In v1, portlet configuration assigns a definition directly — no policy resolution.

reads R9 Resolution Policy (v2)writes R10 Portlet Config

[v2] At portlet placement: reads applicable Resolution Policy for user's Approval Domain scope, recommends preferred definition
Override flow: non-preferred definition requires written rationale. Records override, acknowledged-by, override date on Portlet Config — permanent record
Override indicator surfaced in portlet header — users always know which definition is in use and whether it is system-recommended

Export Engineengine · v2

Role-gated export of metric results and drill-down data. Three-tier handling: direct render, server-side pagination, or async Map/Reduce job based on row count.

AG Grid CommunityMap/Reduce asyncrole-based gating

Under 5k rows: direct AG Grid render with client-side export
5k–50k rows: server-side pagination within AG Grid
Over 50k rows: async Map/Reduce export job — user notified on completion
Export access gated by NetSuite role

Semantic Intelligence Layer (SIL) AI-assisted language, comparison, shape advisory — within NetSuite's trust boundary v1 · v2 · v3

Plain English Generatorv1

Generates plain-English metric summaries from MDL records for Controller review at sign-off. Translates Raw SuiteQL components from code to business language.

N/llm Standard tier

Reads structured Filter/Scope, Query Component, Formula Pattern — constructs natural language description of what the metric computes, includes, and excludes
For Raw SuiteQL: translates query code to plain English — Controller reviews and confirms before sign-off
Generated at definition time, confirmed by Controller at sign-off, stored permanently on Metric Definition record — not regenerated on demand
Required for all metrics — no metric can be approved without a confirmed plain English summary

Metric Diff Enginev1

Plain-English explanation of differences between two metric definitions, including what those differences likely explain about the numeric delta. Input to Metric Comparison record.

N/llm Standard tier

Reads both definitions' plain English summaries + computed delta (Result A − Result B)
Generates structured diff: what is different, and what that likely explains about the numeric gap
Output stored on Metric Comparison record — admin reviews before approving the comparison

Chart Shape Advisorv1 rules · v2 full

Maps metric characteristics to optimal chart types. v1: static rule engine. v2: three-stage pipeline (column typing → capability inventory → ranked recommendation) with LLM rationale.

rule engine (v1)N/llm Standard tier (v2)

Nine chart families: Line, Area, Bar/Column, Combo, Meter, Treemap, Funnel, Circle, Bubble
Cardinality warnings: >8 segments on bar, >6 on donut/pie (hard redirect), >10 on treemap, >6 on funnel
lower_is_better flag from Formula Pattern drives color direction on gauge and KPI card
For Tessera-native metrics, column typing largely pre-solved from metric metadata

Saved Search Converterv2

Alternate Metric Wizard entry point. Translates a NetSuite Saved Search to a governed Tessera metric. Output passes through full approval flow — not a parallel ungoverned path.

N/searchN/llm Standard tier

NS saved search formula language out of scope for auto-translation — flagged as Raw SuiteQL for human review
Pre-flight: side-by-side comparison of saved search result vs. Tessera computed. Discrepancies block sign-off — silent conversion not permitted
Output passes through same Metric Wizard approval flow as a hand-built metric

Natural Language Queryv3

Converts natural language questions to governed metric queries using vector-embedded metric metadata. Requires full SIL Semantic Layer build — v3 dependency.

OCI Generative AIvector storeSemantic Layer

OCI Generative AI (Advanced tier) for complex NL → SuiteQL generation
Vector store for embedding-based retrieval of metric definitions and segment metadata
Outputs a governed metric query — not raw ad-hoc data access

Data Layer 100% native NetSuite storage — no external database, no ETL, no replication lag, no data movement live · NS native

Tessera Custom Records18 types · NS native

All MDL records stored as native NetSuite custom record types. Metric definitions, query components, results, governance records, segment hierarchy, benchmarks — everything lives in native NetSuite storage. No external database exists.

customrecord_tess_*native NS record typesN/record CRUDN/query read

All 18 MDL record types deployed as NetSuite custom records — no external database, no separate data store of any kind
Metric Result records are the primary read target for portlet rendering — the portlet never queries transaction tables directly at render time
Formula Pattern records are shared library records — adding a new formula pattern is a data change (create a record). Query Template records require both a new record and a code deployment to the resolver (handler logic lives in code, not the record).
Segment records: adjacency list FK + materialized path strings — rollup queries via LIKE '%|id|%', no recursive SQL needed
All governance events (approvals, overrides, comparisons, resolution policies) are native NS records — fully auditable via standard NetSuite tools

NetSuite Analytical Tablesread-only · SuiteQL

Source tables queried by the Query Engine to compute metric components. Same tables NetSuite uses for its own reports — same period boundaries, same posting rules, same subsidiary hierarchy.

N/query SuiteQLread-onlyno data movement

PostingAccountActivity — Default Tier 1.5 for all period-end aggregations. Supports class, department, location. ~88ms. Confirmed in sandbox validation 2026-06-02.
AccountPeriodActivity — Tier 1 fallback when no dimension filter needed. ~44ms. Subset of PostingAccountActivity columns.
TransactionAccountingLine — Tier 2 for transaction-type filters. ~300–1400ms. No period field — period obtained via Transaction.postingperiod join. Confirmed in sandbox validation.
transactionLine — P&L aggregations: revenue, COGS, expense. All income statement components
transaction — header-level joins: type, posting status, trandate, entity
AccountingPeriod — period resolver reads this to derive comparison windows

NetSuite Master Dataread-only · NS native

Accounts, subsidiaries, classes, departments, locations, custom segments — all native NetSuite records. Read by the Metric Wizard for picker configuration. Decision-time dimension fields sourced exclusively from here.

N/searchSuiteQLnative NS records

Account picker: active non-summary GL accounts — ~262 in typical mid-market account
Subsidiary hierarchy: read at metric definition time; OneWorld detection drives intercompany warnings
Class / Department / Location / Custom Segments: the only valid Tessera dimension types — decision-time fields stamped on the transaction at posting, period-protected by NetSuite
Entity-attribute fields (Customer Category etc.): valid as Filter/Scope conditions only, not as governed dimensions

File Cabinetlibrary hosting · NS native

All external JavaScript libraries served from NetSuite File Cabinet — no CDN calls at runtime. Enterprise reliability, consistent with NetSuite CSP constraints.

ECharts bundleAG Grid Communitymathjsno CDN at runtime

ECharts — declarative JSON option objects make AI-generated chart specs viable; the spec is data, not imperative code. Chosen over Oracle JET for this reason
AG Grid Community Edition — tabular data display and three-tier export
mathjs — Formula Pattern formula string evaluation at compute time
All library references resolved at File Cabinet URLs — no external calls at runtime, no CDN dependency, no version drift

Platform NetSuite execution environment — all Tessera logic runs natively, zero external infrastructure NS 26.x · SS 2.1

SuiteScript 2.1runtime

All Tessera application logic executes in SuiteScript 2.1. Five script types matched to their execution context and constraints.

Portlet — dashboard rendering. Called by NS on page load; writes HTML to params.portlet.html
Suitelet — Admin UI, Portlet Group SPA (v2), drill-down (v2). Full-page server-rendered responses
User Event (beforeSubmit / afterSubmit) — data integrity gates: Formula Pattern mathjs validation on save, Metric Definition immutability enforcement, Approval Domain overlap validation, Segment path maintenance, transaction event detection for CRL stale marking
Map/Reduce — CRL scheduled refresh fleet, async export jobs, Segment reindex (tessera_segment_reindex.js) on reparent
RESTlet — on-demand cache refresh trigger (v2), called from portlet client-side

NetSuite Module Ecosystem (N/*)APIs

Seven native NS modules used across Tessera's script types. No external API dependencies — every call stays within the NetSuite execution environment.

N/query — SuiteQL execution. Primary interface for all Query Engine reads against analytical and master data tables
N/search — Saved search reads. Metric Wizard pickers (accounts, subsidiaries, classes), Saved Search Converter (v2)
N/record — Custom record CRUD. MDL record creation and updates, wizard draft persistence, result record writes
N/file — File Cabinet access. Library loading (ECharts, AG Grid, mathjs) and export file generation
N/llm — Standard tier LLM. Plain English Generator, Metric Diff Engine, Raw SuiteQL translator. All AI calls stay within NetSuite's trust boundary
N/task — Map/Reduce scheduling. CRL refresh fleet initiation, async export job queuing, segment reindex triggering
N/runtime — Execution context and current user. Role-based access gating, Approval Domain scope resolution, portlet identity

OCI Generative AIAdvanced tier · v2+

Oracle Cloud Infrastructure AI for v2+ advanced SIL features requiring higher capability than N/llm Standard — NL query, vector-based semantic retrieval.

Natural Language Query (v3) and advanced Saved Search translation (v2) where N/llm Standard is insufficient
Vector store for embedding-based retrieval of metric definitions and segment metadata
Accessed via SuiteScript — remains within Oracle's infrastructure boundary, consistent with NS data residency