Tessera is a native SuiteApp that delivers business intelligence capabilities — governed metric definitions, data visualization, AI narration, and industry benchmarking — entirely within a NetSuite account. No data is copied, exported, or processed outside of NetSuite’s environment.
This document describes the system architecture for technical evaluators, NetSuite administrators, and integration partners. For the engineering reasoning behind these decisions — pattern choices, named influences, and alternatives considered — see Architectural Foundations.
Tessera’s architecture is shaped by three non-negotiable constraints:
1. Data never leaves NetSuite. Every computation, every query, every rendering decision happens within your NetSuite account using your existing data. There is no ETL process, no external database, no external API call during normal operation, and no scheduled sync to anything outside your account.
2. The output must be auditable. A metric that nobody can trace back to its source isn’t a metric — it’s a guess. Every number Tessera produces links back to a specific record version, applied filters, named approver, and computation timestamp. The architecture is designed around this guarantee, not around it as an afterthought.
3. Native platform primitives only. Tessera uses the SuiteCloud APIs NetSuite publishes for SuiteApp partners. No undocumented internals, no browser-level manipulation outside Tessera’s own pages, no techniques that could break on a NetSuite version upgrade.
The most significant architectural decision in Tessera is the strict separation of the read path from the write path — Command-Query Responsibility Segregation (CQRS).
Write side: The Metric Definition wizard, approval workflow, and computation engine write to the Metric Definition Layer (MDL) and the Computed Result Layer (CRL).
Read side: Dashboard portlets and the drill-down Suitelet read pre-computed Metric Result records (R6). At render time, a portlet never touches the MDL, never re-executes a query, and never performs a live computation.
This separation is what makes accounting-grade correctness achievable. A portlet that live-queries NetSuite at render time cannot make the “Controller would sign this” guarantee — the result could vary with timing, concurrent writes, or query execution differences. A portlet that reads a pre-computed, timestamped, version-linked result record can make that guarantee unconditionally.
Tessera is organized into five named layers, each with a single responsibility.
┌─────────────────────────────────────────────────────┐
│ 5. AI Narration Layer │
│ variance explanation, anomaly flagging (N/llm) │
├─────────────────────────────────────────────────────┤
│ 4. Benchmark Layer │
│ licensed peer data, segment-matched overlays │
├─────────────────────────────────────────────────────┤
│ 3. Rendering Layer │
│ Suitelet host · Apache ECharts · KPI portlets │
├─────────────────────────────────────────────────────┤
│ 2. Computed Result Layer (CRL) │
│ scheduled Map/Reduce · SuiteQL execution · │
│ slot resolver · math.js · immutable R6 storage │
├─────────────────────────────────────────────────────┤
│ 1. Metric Definition Layer (MDL) │
│ 17 custom record types · versioning · governance │
├─────────────────────────────────────────────────────┤
│ NetSuite Data Platform │
│ SuiteQL · Saved Searches · native record model │
└─────────────────────────────────────────────────────┘
The MDL is Tessera’s semantic layer — the bridge between business intent and NetSuite data structures. It is the write side of the CQRS model.
The MDL comprises 17 custom record types organized into four groups:
Structural layer (Records 1–6): Metric Definition (R1), Query Component (R2), Filter/Scope (R3), Dimension Scope (R4), Minor Change Log (R5), Metric Result (R6). These are the core computation chain.
Governance layer (Records 7–10): Approval Domain, Metric Comparison (v2), Metric Resolution Policy (v2), Dashboard Portlet Configuration. These govern who may define metrics, how conflicts are resolved, and what each role sees on their dashboard.
Shared library (Records 11–12): Query Template, Formula Pattern. These store computation behaviors as data rather than code — see Query Templates below.
Benchmark and segment library (Records 13–16, plus R17): Benchmark Series, Benchmark Data Point, Segment, Segment Join Definition, and Verification Source. These support benchmark overlays, multi-dimensional slicing, and pre-flight metric verification.
The Metric Definition record is the aggregate root of the MDL. It owns its Query Components (R2), Filter/Scope records (R3), Dimension Scope (R4), and all Metric Result records (R6). Components are not shared across definitions. This boundary enforces clean separation between metrics and prevents unintended coupling.
Metric definitions are immutable once approved. A material change — any change that would affect the computed result — creates a new version record with an effective date, mandatory change note, and named approver. The prior version remains intact, and all historical Metric Result records remain permanently associated with the version that produced them.
Minor changes (display name, description, alert thresholds, chart type) are logged on the existing record without creating a new version.
Every chart showing a metric over time renders a visible marker at each version boundary. The marker displays the change note on hover. A trend comparison across periods is always comparing the same metric computed the same way.
Formula Patterns and Query Templates are stored as custom records in NetSuite, not as hardcoded logic. A new metric type that fits an existing formula pattern and query template can be configured without a code deployment — only the custom record data changes. This is a deliberate architectural choice that extends the product’s configurability to the data layer.
Tessera ships eight Formula Patterns covering its v1 metric library: Ratio Trailing Days, Simple Aggregation, Gross Margin %, Multi-Component Sum (e.g., EBITDA), Percent Change, Running Balance, Ratio Calendar Period, and Weighted Average.
The CRL is Tessera’s computation engine. It runs on SuiteScript Map/Reduce scripts on a scheduled basis and on event-driven triggers. Its output is Metric Result records (R6) — the read model consumed by portlets.
The CRL applies different storage and refresh policies based on the period state of each metric result:
| Tier | Period state | Policy |
|---|---|---|
| Permanent | Closed accounting period | Computed once; stored permanently; never recomputed |
| Cached | Open period | Computed on schedule; stored with a visible cache timestamp |
Closed-period results are computed once and stored permanently. This is an architectural guarantee, not a cache policy. If the underlying GL data in a closed period is immutable in NetSuite, the metric result that reflects it is also immutable.
Every Metric Result record carries a computation timestamp. Every portlet displays when the underlying data was last computed. There are no metrics in Tessera that update on an unknown schedule.
The CRL executes queries using a typed slot resolver — a TypeScript module that takes a Metric Definition DTO, reads its Query Components and Filter/Scope records, selects the appropriate Query Template, populates the template’s parameter slots, and returns an executable SuiteQL statement. The resolver runs in Node.js with SuiteScript shims for local unit testing; it drops into the NetSuite environment unchanged.
Five Query Templates cover Tessera’s v1 metric library:
| Template | Use case |
|---|---|
| Ratio: Trailing Days | DSO, DPO, DIO, Cash Conversion Cycle |
| Simple Aggregation: Calendar Period | Income statement aggregations bounded by posting period |
| Simple Aggregation: Trailing Days | Trailing-window aggregations using transaction date |
| Running Balance | Point-in-time GL balance via accountPeriodActivity |
| Paired Query Comparator (v2) | Cohort metrics requiring two queries + application-layer join |
Query execution uses two NetSuite mechanisms based on metric requirements:
| Mechanism | Used when |
|---|---|
SuiteQL (N/query) |
Aggregate functions, multi-table joins, GROUP BY, period-bounded computations |
Saved Searches (N/search) |
Filterable, permission-respecting result sets where NS role scoping must be enforced at the data level |
Both mechanisms enforce NetSuite’s native permission model. A user who cannot see a record through standard NetSuite access cannot see that record contribute to a Tessera metric.
Statistical operations — standard deviation, percentile calculations, weighted averages, moving averages — are evaluated by math.js, bundled with Tessera and served from NetSuite File Cabinet. No external service calls are made at runtime.
The rendering layer reads pre-computed Metric Result records and produces the charts, KPI tiles, and drill-down views that users interact with. It never touches the computation path.
Tessera’s primary rendering surface is a SuiteScript 2.1 Suitelet. The Suitelet resolves the current user’s Dashboard Portlet Configuration (R10), reads the appropriate Metric Result records from R6, and assembles chart data and rendering instructions for the browser. Authentication is handled entirely by NetSuite’s existing session — no separate login is required.
Client-side charts are rendered using Apache ECharts. ECharts was selected over Oracle JET because its chart specifications are declarative JSON objects, which makes programmatic and AI-generated chart configuration viable. ECharts is bundled with Tessera and served from NetSuite File Cabinet; it makes no external network calls at runtime.
Tabular drill-down data is rendered using AG Grid Community Edition.
All static assets — JavaScript bundles, CSS, fonts, icons — are served from NetSuite File Cabinet. There are no CDN dependencies and no external assets loaded at runtime.
KPI tiles and chart summaries are surfaced on the standard NetSuite dashboard via native portlet scripts. Users interact with Tessera visualizations without leaving the NetSuite UI or switching browser tabs.
Drill-down from a metric tile follows a three-path model based on the Query Component’s configuration:
Tessera overlays curated industry benchmarks on metric charts as reference bands — median, 25th percentile, and 75th percentile for the user’s peer group.
At setup, users define their business model (Subscription, Services, Products, or mixed). Benchmark data is filtered to the matching segment automatically. Benchmark records are organized using Benchmark Series (R13) and Benchmark Data Point (R14) custom records, resolved at render time against the current period.
Benchmark datasets are stored as custom records within the NetSuite account. They are not fetched from external services at runtime. The benchmark data is sourced from licensed industry data providers and updated on a defined cadence.
Tessera includes AI narration that explains metric variances and flags anomalies in plain language.
AI narration uses NetSuite’s native N/llm module — Oracle’s published SuiteCloud API for invoking large language model capabilities from within SuiteScript. The call is made within the NetSuite platform infrastructure; there is no direct third-party API call made from Tessera’s SuiteScript code.
Narration is grounded in the Metric Definition context available through the MDL: the metric’s business description, its formula components, recent computation history, and benchmark position. The AI explains what changed and by how much, relative to defined reference points. It does not generate raw SuiteQL, make investment recommendations, or predict future values.
In the v3 roadmap, N/llm is also used to convert NetSuite Financial Report Builder layouts into equivalent Query Component configurations. The module is constrained to template selection output only — it selects from Tessera’s validated Query Template library. It does not generate raw SuiteQL statements.
Tessera ships with a baseline Metric Registry — a searchable data dictionary of all Query Components and Composed Metrics available in the account.
The baseline registry ships with approximately 225 Query Components and 85 Composed Metrics, organized by GL structure:
Baseline components ship read-only (is_baseline: true, system-enforced via User Event). Controllers can deactivate a baseline component or fork it — forking creates an editable custom version with a forked_from reference preserving lineage. The baseline version remains permanently as a reference.
At install time, Tessera validates the account’s actual chart of accounts against the baseline library and auto-creates corrected custom versions for any components where the baseline assumptions don’t match the account configuration.
The Registry is designed to be the authoritative answer to “what does Revenue mean in this account?” — not just a list of metrics, but a governed, versioned, named definition of every financial primitive, with sign-off attribution and a full change history.
Tessera relies entirely on NetSuite’s existing session authentication. There is no Tessera-specific login, no API key to manage, and no additional authentication surface.
A five-role capability model maps NetSuite roles to Tessera capabilities (define metrics, approve metrics, view all metrics, configure dashboards, administer the system). Role assignments use NetSuite’s native role system — there is no parallel permission system to maintain.
Portlet scripts execute as the current logged-in user, enforcing NetSuite’s native record-level permissions at query time.
All Tessera data — metric definitions, computed results, benchmark datasets, narration outputs — resides within the NetSuite account.
License keys are validated offline using HMAC verification against a per-account key stored in the Tessera Account Configuration custom record. No license server call is made during normal operation.
Tessera uses only APIs published by Oracle for SuiteCloud partners:
| API | Purpose |
|---|---|
N/search |
Saved search execution |
N/query |
SuiteQL execution |
N/record |
Custom record read/write |
N/url |
URL and deep-link resolution |
N/currentRecord |
Current record context in client scripts |
N/llm |
AI narration and report layout interpretation |
N/task |
Scheduled Map/Reduce task management |
N/log |
Audit and error logging |
No restricted APIs. No undocumented internal namespaces. No DOM manipulation outside Tessera’s own Suitelet-rendered pages.
Tessera does not require SuiteCloud Plus governance.
Tessera is packaged and deployed using the SuiteCloud Development Framework (SDF). Every NetSuite object — scripts, deployments, custom record type definitions, portlet configurations, baseline library records — is defined as SDF XML and version-controlled in the product repository.
tessera_*) that will not collide with customer customizationsLanguage: TypeScript (strict mode). Type errors are caught at compile time.
Testing: The slot resolver — the core computation logic module — has 79 unit tests written against it before any NetSuite sandbox was available. Tests use @oracle/suitecloud-unit-testing (Oracle’s published Jest-based SuiteScript testing framework) with full NS module mocking. Tests run on every commit.
CI: GitHub Actions runs TypeScript compilation and the full test suite on every push.
Design-first: All 17 custom record types, all 5 query templates, the six-step wizard UX, the portlet rendering model, and the security role model were fully designed and documented before production coding began. The design process is documented in the repository’s engineering provenance record.
| Requirement | Details |
|---|---|
| NetSuite edition | Standard or OneWorld |
| SuiteCloud Developer feature | Not required |
| SuiteCloud Plus governance | Not required |
| External services (runtime) | None |
| Browser | Any NetSuite-supported browser |