Project SENTRY: Web Frontend Architecture & Jamstack Workstation
1. Monorepo Architecture & Technology Stack
Project SENTRY adopts a decoupled monorepo architecture where the public analytical workstation resides in web/ while the private econometric and spatial downscaling engines reside in src/. The static presentation layer is completely isolated from the backend Python execution environment, compiling via Astro v5 and Vite into zero-server-cost, pre-rendered static HTML, CSS, JavaScript, and sanitized JSON contracts.
sentry/
├── docs/ # Technical documentation suite
│ ├── 01_architecture_and_methodology.md
│ ├── 02_data_dictionary_and_sources.md
│ └── ... [5 more chapters: 03–07]
├── src/ # Econometric & spatial core
│ ├── models/ # DFM, ElasticNet, MIDAS, Spatial
│ ├── pipelines/ # Nowcasting & telemetry
│ └── ... [2 more packages: features, sentry]
└── web/ # Jamstack web platform
├── public/ # Static assets & JSON data contracts
│ ├── data/ # Multi-horizon data contracts
│ └── ... [2 more folders: scripts, fonts]
├── src/ # Workstation UI & React islands
│ ├── components/ # ECharts & analytical visualizers
│ ├── pages/ # Workstation & docs routes
│ └── ... [2 more folders: data, layouts]
├── astro.config.mjs # SSG build configuration
├── package.json # Workspace dependencies
└── ... [2 more configuration files]
2. The Open Core Contract & Data Sanitization Policy
To guarantee mathematical integrity while ensuring zero exposure of proprietary scraper code, internal directory structures, or infrastructure credentials, Project SENTRY enforces a strict data isolation barrier:
- Client Isolation: The web workstation fetches exclusively pre-computed, static JSON payloads hosted under
web/public/data/. The client runtime makes zero database queries, evaluates no serverless functions, and executes no dynamic server code. - Deterministic Sanitization: The nowcasting pipeline (
src/pipelines/run_nowcast.py) evaluates all outgoing string fields against regular expression filters (_PRIVATE_PATH_RE), stripping absolute Windows/Unix filesystem paths (C:\WORKSPACE\...,/home/...), internal tokens, and raw API secrets. - Aggregated Analytical Bounds: Data contracts publish only aggregated regional and provincial growth projections, 95% conformal prediction intervals (), directional probabilities, and row-normalized spatial weights.
Static JSON Contract Manifest
| File Name | Typical Size | Record Scope | Description |
|---|---|---|---|
summary_metrics.json |
~0.5 KB | 1 summary record | National real GDP projection, weighted growth, spatial , and maximum conservation residual (). |
provincial_ppa_latest.json |
~61 KB | 117–135 jurisdictions | Provincial Product Accounts (PPA) with baseline, reconciled levels, growth, conformal intervals, and cluster classifications. |
spatial_spillovers.json |
~8 KB | 18 regions | Administrative regions with baseline GRDP, nowcast growth, domestic demand components, and spatial transmission spillovers. |
ragged_edge_convergence.json |
~1.2 KB | 4 countdown horizons | 90-day countdown intervals (), displaying information accumulation and interval compression. |
model_scorecards.json |
~8 KB | 4 constituent models | Out-of-sample empirical metrics (MAE, RMSE, directional accuracy, 95% coverage, Diebold-Mariano statistics). |
spatial_gravity_matrix.json |
~9.6 KB | 18×18 flow matrix | Row-normalized Commodity Flow Survey (CFS) trade matrix () and bilateral maritime corridors. |
pipeline_status.json |
~2.7 KB | 6 tracked series | Real-time release poller status, publication lags (), automated retraining signals, and CI telemetry logs. |
3. Dual Workstation Operating Modes
Project SENTRY caters to both executive decision-makers requiring high-level synthesis and technical econometricians conducting granular empirical audits.
3.1 LITE Mode (Policymaker & Executive View)
- High-Density Macro KPIs: Real GDP projection, primary economic growth engine, spatial coupling coefficient (), and exact Stone's hierarchy conservation status.
- Regional Economic Growth Grid: 18-region card matrix with dynamic growth badges (, , ) and interactive selection updating the regional policy briefing.
- Regional Policy Briefing: Contextual breakdown of supply-chain transmission spillovers ( via maritime corridors) and domestic demand resilience ( within tight conformal bounds).
- Embedded Sub-National Hierarchical Accounts (135 Jurisdictions):
- Fully integrated within the LITE interface without requiring mode switching.
- Interactive search bar filtering across all provinces and Highly Urbanized Cities (HUCs).
- Cluster classification filter (Urban, Industrial, Agricultural).
- Clean pagination displaying reconciled PPA levels, nowcast growth, and exact regional additivity.
- 10-Column Data Grid Architecture: Minimum table width () with
border-separate border-spacing-0andwhitespace-nowrapguarantees unclipped presentation across all viewports. - React Portal Tooltip System (
TooltipInfo.tsx):- Mounts directly to
document.bodyviacreatePortal, completely bypassing parentoverflow-x-autoscrolling containers and Chromium table layout stacking context restrictions. - Employs coordinate measuring with horizontal viewport boundary clamping (
Math.max(12, Math.min(window.innerWidth - 272, left))) to prevent off-screen overflow. - Intercepts and stops click event propagation (
e.stopPropagation()), preventing tooltip interaction from inadvertently toggling TanStack table column sort handlers. - Provides descriptive econometric and administrative definitions across all 10 columns (Jurisdiction, Region, Cluster, Predicted Level, PSA Benchmark, Residual Error, YoY Growth, 95% Conformal Bound, Residual , Directional Probability).
- Mounts directly to
3.2 POWER USER Mode (Econometric Terminal)
The Power User terminal exposes 7 specialized client-side React islands:
- MacroTerminal: Macroeconomic KPI matrix, conformal fan chart, and regional growth distribution.
- SimplexWeightTuner: Real-time quadratic programming weight adjustment () recalculating nowcasts live across all 18 administrative regions.
- ConstituentInspector: Deep econometric evaluation across DFM, ElasticNet, LightGBM, and MIDAS models with Diebold-Mariano test statistics and feature attributions.
- SpatialGravityMap: Interactive SVG spatial network displaying inter-island bilateral commodity flows () and cross-regional spillover corridors.
- RaggedEdgeStepper: Information arrival simulator demonstrating how missing data diminishes from 94.2% to 0% and predictive intervals compress monotonically by 88.5% over the 90-day countdown.
- FanChart: High-resolution distribution-free Split Conformal Prediction interval visualizer (80% and 95% coverage bands).
- TelemetryView: Live pipeline monitoring dashboard displaying statistical vintage freshness, execution latencies, model drift metrics, and GitHub Actions telemetry.
4. Multi-Horizon Time Horizon Architecture & Live Nowcast Integration
4.1 Macroeconomic Horizon Taxonomies
Project SENTRY operationalizes five distinct annual horizons spanning benchmarked historical evaluations through unobserved forward nowcasts:
| Horizon | Vintage Classification | Ground Truth Status | Residual Tracking | Econometric Role |
|---|---|---|---|---|
| 2026 | Active Live Nowcast |
Unobserved (PSA Apr 2027) | UNOBSERVED (Inactive) |
Pure forward nowcast assimilating real-time high-frequency indicators, satellite radiance, and spatial spillovers. |
| 2025 | Preliminary Benchmark |
Preliminary PPA Accounts | Active ( | |
| c-1 5-5 9-11 9h-2L532 67 19 159h-2c-5 0-9-4-11-9l-5-22c-1-6 2-12 8-13z"/>−y) | Benchmarked out-of-sample evaluation against preliminary regional and provincial releases. | |||
| 2024 | Verified Benchmark |
Official PSA Verified Accounts | Active ( | |
| c-1 5-5 9-11 9h-2L532 67 19 159h-2c-5 0-9-4-11-9l-5-22c-1-6 2-12 8-13z"/>−y) | Authoritative baseline accounts with exact Stone linear balance and Denton disaggregation (). | |||
| 2023 | Historical Baseline |
Official PSA Verified Accounts | Active ( | |
| c-1 5-5 9-11 9h-2L532 67 19 159h-2c-5 0-9-4-11-9l-5-22c-1-6 2-12 8-13z"/>−y) | Post-pandemic monetary tightening evaluation window under BSP rate hike cycle. | |||
| 2022 | Historical Baseline |
Official PSA Verified Accounts | Active ( | |
| c-1 5-5 9-11 9h-2L532 67 19 159h-2c-5 0-9-4-11-9l-5-22c-1-6 2-12 8-13z"/>−y) | Post-lockdown economic recovery baseline and regional convergence validation. |
4.2 Hierarchical Data Contract Layout
To ensure scalable, version-controlled multi-horizon execution, data contracts are partitioned into vintage-specific subdirectories under web/public/data/, with a root index contract and backwards-compatible symlinks/mirrors:
web/public/data/
├── vintages_index.json # Manifest catalog & active horizon
├── 2026/ # Active Live Nowcast (default)
│ ├── summary_metrics.json
│ ├── provincial_ppa_latest.json
│ └── ... [4 more contracts: spillovers, ragged-edge, scorecards, gravity]
├── 2025/ # 2025 Preliminary benchmarked vintage
├── 2024/ # 2024 Verified baseline vintage
├── 2023/ # 2023 Historical baseline vintage
├── 2022/ # 2022 Historical recovery vintage
└── *.json # Mirrored root files for legacy clients
vintages_index.json
{
"default_vintage": "2026",
"available_vintages": ["2022", "2023", "2024", "2025", "2026"],
"vintage_metadata": {
"2026": { "type": "live_nowcast", "ground_truth": "unobserved", "release_date": "2027-04" },
"2025": { "type": "preliminary", "ground_truth": "preliminary_ppa", "release_date": "2026-04" },
"2024": { "type": "verified_benchmark", "ground_truth": "verified_ppa", "release_date": "2025-04" },
"2023": { "type": "historical_benchmark", "ground_truth": "verified_ppa", "release_date": "2024-04" },
"2022": { "type": "historical_benchmark", "ground_truth": "verified_ppa", "release_date": "2023-04" }
},
"exported_at": "2026-09-19T17:17:37.105973+00:00"
}
4.3 Client-Side Reactive State Machine & Caching
The workstation coordinates multi-horizon state dynamically across React islands and the Astro layout shell:
- Default Horizon Resolution: On initial client hydration,
WorkstationContainer.tsxqueries/data/vintages_index.jsonto extractdefault_vintage(defaulting to2026), subsequently hydrating all 6 contracts from/data/<vintage>/. - Zero-Latency In-Memory Cache (
cacheRef): To prevent network overhead or UI jitter when switching between horizons, previously loaded vintage bundles (VintageBundle) are memoized in an in-memory cache ref (Record<number, VintageBundle>). Subsequent toggles execute synchronously in . - Cross-Island Event Bus (
horizon-change): Horizon switching dispatches a decoupled window-levelCustomEvent('horizon-change', { detail: { year, label } }). The Astro layout header (Layout.astro) listens to this event to update the persistent top navigation badge (#header-horizon) without requiring parent React wrapper re-renders. - Conditional Presentation Logic:
- When Horizon = 2026 (Live Nowcast):
- Prominent warning banners render in both
LiteOverview.tsxandMacroTerminal.tsx. - Data table renders amber badge
PENDING PSA RELEASE (APR 2027)for Ground Truth. - Residual column displays
UNOBSERVED. - Non-parametric conformal intervals and directional expansion probabilities () remain fully operational.
- Prominent warning banners render in both
- When Horizon ∈ {2022, 2023, 2024, 2025} (Historical Benchmarks):
- Data table renders realized PSA output levels.
- Residual column displays exact signed error () and percentage discrepancy with color-coded precision thresholds ().
- When Horizon = 2026 (Live Nowcast):
5. KaTeX Mathematical Typography & Interactive Clipboard Export
To bridge the gap between academic econometrics and interactive software, Project SENTRY embeds formatted mathematical equations directly into its modal specification sheets (SpotlightModal.tsx and powerUserSheets.ts):
- In-Situ KaTeX Rendering: Mathematical operators, state-space equations, Lagrangian disaggregation objectives, and conformal interval formulations are rendered via
katex.renderToString(). - Interactive "Copy LaTeX" Button: Every specification sheet features a one-click copy button that copies the raw LaTeX source code to the user's clipboard, providing visual confirmation (
"Copied!") for seamless inclusion in academic papers and policy reports.
% Example: Lagrangian Denton Disaggregation Specification
\min_{p} \sum_{t} \left( \frac{p_t}{I_t} - \frac{p_{t-1}}{I_{t-1}} \right)^2
\quad \text{subject to} \quad
\sum_{i \in R_r} p_{i, t} = \widehat{\text{GRDP}}_{r, t}, \quad \epsilon \le 10^{-6}