Neon-Desk/docs/architecture/financial-surfaces.md

Financial Surface Definitions Architecture

Overview

As of Issue #26, the financial statement mapping architecture follows a Rust-first approach where the Rust sidecar is the authoritative source for surface definitions.

All legacy TypeScript template code has been removed.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    SEC EDGAR Filing                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│              Rust Sidecar (fiscal-xbrl)                         │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ rust/taxonomy/fiscal/v1/core.surface.json               │   │
│  │ rust/taxonomy/fiscal/v1/core.income-bridge.json         │   │
│  └─────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ surface_mapper.rs - builds surface_rows                 │   │
│  │ kpi_mapper.rs - builds kpi_rows                         │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│              SQLite Database                                    │
│  filing_taxonomy_snapshot.surface_rows                          │
│  filing_taxonomy_snapshot.detail_rows                           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│              TypeScript Layer                                   │
│  financial-taxonomy.ts:aggregateSurfaceRows()                   │
│  - Reads surface_rows from DB snapshots                         │
│  - Aggregates across selected periods                           │
│  - Returns to frontend for display                              │
└─────────────────────────────────────────────────────────────────┘

Source of Truth

Authoritative Sources (Edit These)

1. rust/taxonomy/fiscal/v1/core.surface.json

   • Defines all surface keys, labels, categories, orders, and formulas
   • Example: revenue, cost_of_revenue, gross_profit, net_income

2. rust/taxonomy/fiscal/v1/core.income-bridge.json

   • Maps XBRL concepts to income statement surfaces
   • Defines component surfaces for formula derivation

Removed Files (Do NOT Recreate)

The following files have been permanently removed:

1. lib/server/financials/standard-template.ts - Template definitions (now in Rust JSON)
2. lib/server/financials/surface.ts - Fallback surface builder (no longer needed)
3. lib/server/financials/standardize.ts - Template-based row builder (replaced by Rust)

Remaining TypeScript Helpers

lib/server/financials/standardize.ts (simplified version) contains only:

• buildLtmStandardizedRows - Computes LTM values from quarterly data
• buildDimensionBreakdown - Builds dimension breakdowns from facts

These operate on already-mapped surface data from the Rust sidecar.

2. lib/server/financials/standardize.ts
   • Contains buildStandardizedRows - kept for fallback/testing only
   • Marked as @deprecated

How to Add a New Surface

1. Add to rust/taxonomy/fiscal/v1/core.surface.json:

   {
     "surface_key": "new_metric",
     "statement": "income",
     "label": "New Metric",
     "category": "surface",
     "order": 100,
     "unit": "currency",
     "rollup_policy": "direct_only",
     "allowed_source_concepts": ["us-gaap:NewMetricConcept"],
     "allowed_authoritative_concepts": ["us-gaap:NewMetricConcept"],
     "formula_fallback": null,
     "detail_grouping_policy": "top_level_only",
     "materiality_policy": "income_default"
   }
   

2. Add concept mapping to core.income-bridge.json (if needed):

   "new_metric": {
     "direct_authoritative_concepts": ["us-gaap:NewMetricConcept"],
     "direct_source_concepts": ["NewMetricConcept"],
     "component_surfaces": { "positive": [], "negative": [] },
     "component_concept_groups": { "positive": [], "negative": [] },
     "formula": "direct",
     "not_meaningful_for_pack": false,
     "warning_codes_when_used": []
   }
   

3. Rebuild the Rust sidecar:

   cd rust && cargo build --release
   

4. Re-ingest filings to populate the new surface

Key Surfaces

Income Statement

Key	Order	Description
revenue	10	Top-line revenue
cost_of_revenue	20	Cost of revenue/COGS
gross_profit	30	Revenue - Cost of Revenue
gross_margin	35	Gross Profit / Revenue (percent)
operating_expenses	40	Total operating expenses
operating_income	60	Gross Profit - Operating Expenses
operating_margin	65	Operating Income / Revenue (percent)
pretax_income	80	Income before taxes
income_tax_expense	85	Income tax provision
effective_tax_rate	87	Tax Expense / Pretax Income (percent)
ebitda	88	Operating Income + D&A
net_income	90	Bottom-line net income
diluted_eps	100	Diluted earnings per share
basic_eps	105	Basic earnings per share
diluted_shares	110	Weighted avg diluted shares
basic_shares	115	Weighted avg basic shares

Balance Sheet

See rust/taxonomy/fiscal/v1/core.surface.json for complete list.

Cash Flow Statement

See rust/taxonomy/fiscal/v1/core.surface.json for complete list.

Related Files

• rust/fiscal-xbrl-core/src/surface_mapper.rs - Surface resolution logic
• rust/fiscal-xbrl-core/src/taxonomy_loader.rs - JSON loading
• lib/server/repos/filing-taxonomy.ts - DB operations
• lib/server/financial-taxonomy.ts - Main entry point