bulltrackers-module 1.0.293 → 1.0.295

package/functions/computation-system/layers/extractors.js

@@ -120,8 +120,8 @@ class DataExtractor {
         return "Buy"; 
     }
 
-    static getLeverage(position) { return position ? (position.Leverage || 1) : 1; }
-    static getOpenRate(position) { return position ? (position.OpenRate || 0) : 0; }
+    static getLeverage(position)    { return position ? (position.Leverage    || 1) : 1; }
+    static getOpenRate(position)    { return position ? (position.OpenRate    || 0) : 0; }
     static getCurrentRate(position) { return position ? (position.CurrentRate || 0) : 0; }
     static getStopLossRate(position) {
         const rate = position ? (position.StopLossRate || 0) : 0; 
@@ -207,7 +207,7 @@ class HistoryExtractor {
                     });
                 }
                 const asset = assetsMap.get(instId);
-                const open = new Date(t.OpenDateTime);
+                const open  = new Date(t.OpenDateTime);
                 const close = new Date(t.CloseDateTime);
                 const durationMins = (close - open) / 60000;
                 if (durationMins > 0) {
@@ -287,25 +287,25 @@ class InsightsExtractor {
         return insights.find(i => i.instrumentId === instrumentId) || null;
     }
 
-    static getTotalOwners(insight) { return insight ? (insight.total || 0) : 0; }
-    static getLongPercent(insight) { return insight ? (insight.buy || 0) : 0; }
-    static getShortPercent(insight) { return insight ? (insight.sell || 0) : 0; }
+    static getTotalOwners(insight)   { return insight ? (insight.total  || 0) : 0; }
+    static getLongPercent(insight)   { return insight ? (insight.buy    || 0) : 0; }
+    static getShortPercent(insight)  { return insight ? (insight.sell   || 0) : 0; }
     static getGrowthPercent(insight) { return insight ? (insight.growth || 0) : 0; }
 
     static getLongCount(insight) {
-        const total = this.getTotalOwners(insight);
+        const total  = this.getTotalOwners(insight);
         const buyPct = this.getLongPercent(insight);
         return Math.floor(total * (buyPct / 100));
     }
 
     static getShortCount(insight) {
-        const total = this.getTotalOwners(insight);
+        const total   = this.getTotalOwners(insight);
         const sellPct = this.getShortPercent(insight);
         return Math.floor(total * (sellPct / 100));
     }
 
     static getNetOwnershipChange(insight) {
-        const total = this.getTotalOwners(insight);
+        const total  = this.getTotalOwners(insight);
         const growth = this.getGrowthPercent(insight);
         if (total === 0) return 0;
         const prevTotal = total / (1 + (growth / 100)); 

package/functions/computation-system/paper.md

@@ -0,0 +1,93 @@
+# The BullTrackers Computation System: An Advanced DAG-Based Architecture for High-Fidelity Financial Simulation
+
+## Abstract
+
+This paper details the design, implementation, and theoretical underpinnings of the BullTrackers Computation System, a proprietary high-performance execution engine designed for complex financial modeling and user behavior analysis. The system leverages a Directed Acyclic Graph (DAG) architecture to orchestrate interdependent calculations, employing Kahn’s Algorithm for topological sorting and Tarjan’s Algorithm for cycle detection. Key innovations include "Content-Based Dependency Short-Circuiting" for massive optimization, a "System Epoch" and "Infrastructure Hash" based auditing system for absolute reproducibility, and a batch-flushing execution model designed to mitigate Out-Of-Memory (OOM) errors during high-volume processing. We further explore the application of this system in running advanced psychometric and risk-geometry models ("Smart Money" scoring) and how the architecture supports self-healing workflows through granular state management.
+
+## 1. Introduction
+
+In modern financial analytics, derived data often depends on a complex web of varying input frequencies—real-time price ticks, daily portfolio snapshots, and historical trade logs. Traditional linear batch processing protocols fail to capture the nuances of these interdependencies, often leading to race conditions or redundant computations.
+
+The BullTrackers Computation System was devised to solve this by treating the entire domain logic as a **Directed Acyclic Graph (DAG)**. Every calculation is a node, and every data requirement is an edge. By resolving the topography of this graph dynamically at runtime, the system ensures that:
+1.  Data is always available before it is consumed (referential integrity).
+2.  Only necessary computations are executed (efficiency).
+3.  Changes in code or infrastructure propagate deterministically through the graph (auditability).
+
+## 2. Theoretical Foundations
+
+The core utility of the system is its ability to turn a collection of loosely coupled JavaScript classes into a strictly ordered execution plan.
+
+### 2.1 Directed Acyclic Graphs (DAGs)
+We model the computation space as a DAG where $G = (V, E)$.
+*   **Vertices ($V$)**: Individual Calculation Units (e.g., `NetProfit`, [SmartMoneyScore](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/layers/profiling.js#24-236)).
+*   **Edges ($E$)**: Data dependencies, where an edge $(u, v)$ implies $v$ requires the output of $u$.
+
+### 2.2 Topological Sorting (Kahn’s Algorithm)
+To execute the graph, we must linearize it such that for every dependency $u \rightarrow v$, $u$ precedes $v$ in the execution order. We implement **Kahn’s Algorithm** within [ManifestBuilder.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/context/ManifestBuilder.js) to achieve this:
+1.  Calculate the **in-degree** (number of incoming edges) for all nodes.
+2.  Initialize a queue with all nodes having an in-degree of 0 (independent nodes).
+3.  While the queue is not empty:
+    *   Dequeue node $N$ and add it to the `SortedManifest`.
+    *   For each neighbor $M$ dependent on $N$, decrement $M$'s in-degree.
+    *   If $M$'s in-degree becomes 0, enqueue $M$.
+4.  This generates a series of "Passes" or "Waves" of execution, allowing parallel processing of independent nodes within the same pass.
+
+### 2.3 Cycle Detection (Tarjan’s Algorithm)
+A critical failure mode in DAGs is the introduction of a cycle (e.g., A needs B, B needs A), effectively turning the DAG into a DCG (Directed Cyclic Graph), which is unresolvable.
+If Kahn’s algorithm fails to visit all nodes (indicating a cycle exists), the system falls back to **Tarjan’s Strongly Connected Components (SCC) Algorithm**. This uses depth-first search to identify the exact cycle chain (e.g., `Calc A -> Calc B -> Calc C -> Calc A`), reporting the "First Cycle Found" to the developer for immediate remediation.
+
+## 3. System Architecture & "Source of Truth"
+
+The architecture is centered around the **Manifest**, a dynamic, immutable registry of all capabilities within the system.
+
+### 3.1 The Dynamic Manifest
+Unlike static build tools, the Manifest is built at runtime by [ManifestLoader.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/topology/ManifestLoader.js) and [ManifestBuilder.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/context/ManifestBuilder.js). It employs an **Auto-Discovery** mechanism that scans directories for calculation classes.
+*   **Static Metadata**: Each class exposes `getMetadata()` and `getDependencies()`.
+*   **Product Line Filtering**: The builder can slice the graph, generating a subgraph relevant only to specific product lines (e.g., "Crypto", "Stocks"), reducing overhead.
+
+### 3.2 Granular Hashing & The Audit Chain
+To ensure that "if the code hasn't changed, the result shouldn't change," the system implements a multi-layered hashing strategy ([HashManager.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/topology/HashManager.js)):
+1.  **Code Hash**: The raw string content of the calculation class.
+2.  **Layer Hash**: Hashes of shared utility layers (`mathematics`, `profiling`) used by the class.
+3.  **Dependency Hash**: A composite hash of all upstream dependencies.
+4.  **Infrastructure Hash**: A hash representing the underlying system environment.
+5.  **System Epoch**: A manual versioning flag to force global re-computation.
+
+This results in a `Composite Hash`. If this hash matches the `storedHash` in the database, execution can be skipped entirely.
+
+## 4. Execution Engine: Flow, Resilience & Optimization
+
+The `WorkflowOrchestrator` acts as the runtime kernel, utilizing [StandardExecutor](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/executors/StandardExecutor.js#16-257) and [MetaExecutor](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/executors/MetaExecutor.js#12-83) for the heavy lifting.
+
+### 4.1 Content-Based Dependency Short-Circuiting
+A major optimization (O(n) gain) is the **Content-Based Short-Circuiting** logic found in [WorkflowOrchestrator.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/WorkflowOrchestrator.js):
+Even if an upstream dependency *re-runs* (e.g., its timestamp changed), its *output* might be identical to the previous run.
+1.  The system tracks `ResultHash` (hash of the actual output data).
+2.  When checking dependencies for Node B (which depends on A), if A has re-run but its `ResultHash` is unchanged from what B used last time, B **does not need to re-run**.
+3.  This effectively stops "change propagation" dead in its tracks if the data change is semantically null.
+
+### 4.2 Batch Flushing & OOM Prevention
+Financial datasets (processing 100k+ users with daily portfolios) often exceed Node.js heap limits. The [StandardExecutor](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/executors/StandardExecutor.js#16-257) implements a **Streaming & Flushing** architecture:
+*   **Streams** inputs (Portfolio/History) using generators (`yield`), preventing loading all users into memory.
+*   **Buffers** results in a `state` object.
+*   **Flushes** to the database (Firestore/Storage) every $N$ users (e.g., 5000), clearing the internal buffer helps avoid Out-Of-Memory crashes.
+*   **Incremental Sharding**: It manages shard indices dynamically to split massive result sets into retrievable chunks.
+
+### 4.3 Handling "Impossible" States
+If a dependency fails or is missing critical data, the Orchestrator marks dependent nodes as `IMPOSSIBLE` rather than failing them. This allows the rest of the graph (independent branches) to continue execution, maximizing system throughput even in a partially degraded state.
+
+## 5. Advanced Application: Psychometrics & Risk Geometry
+
+The capabilities of this computation engine are best demonstrated by the [profiling.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/layers/profiling.js) layer it powers. Because the DAG ensures all historical and portfolio data is perfectly aligned, we can run sophisticated O(n^2) or O(n log n) algorithms on user data reliably.
+
+### 5.1 "Smart Money" & Cognitive Profiling
+The system executes a [UserClassifier](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/layers/profiling.js#382-399) that computes:
+*   **Risk Geometry**: Using the **Monotone Chain** algorithm to compute the Convex Hull of a user's risk/reward performance (Efficient Frontier analysis).
+*   **Psychometrics**: Detecting "Revenge Trading" (increasing risk after losses) and "Disposition Skew" (holding losers too long).
+*   **Attribution**: Separating "Luck" (market beta) from "Skill" (Alpha) by comparing performance against sector benchmarks.
+
+These complex models depend on the *guarantee* provided by the DAG that all necessary history and price data is pre-computed and available in the [Context](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/simulation/Fabricator.js#20-69).
+
+## 6. Conclusion
+
+The BullTrackers Computation System represents a shift from "Action-Based" to "State-Based" architecture. By encoding the domain logic into a Directed Acyclic Graph, we achieve a system that is self-healing, massively scalable via short-circuiting and batching, and capable of supporting deep analytical models. It provides the robustness required for high-stakes financial simulation, ensuring that every decimal point is traceable, reproducible, and verifiable.

package/functions/computation-system/persistence/RunRecorder.js

@@ -43,14 +43,14 @@ async function recordRunAttempt(db, context, status, error = null, detailedMetri
     const timings = rawExecStats.timings || {};
 
     const runEntry = {
-        runId: runId,
+        runId:           runId,
         computationName: computation,
-        pass: String(pass),
-        workerId: workerId,
-        targetDate: targetDate,
-        triggerTime: now.toISOString(),
-        durationMs: detailedMetrics.durationMs || 0,
-        status: status,
+        pass:            String(pass),
+        workerId:        workerId,
+        targetDate:      targetDate,
+        triggerTime:     now.toISOString(),
+        durationMs:      detailedMetrics.durationMs || 0,
+        status:          status,
         
         // [NEW] Trigger Context
         trigger: {
@@ -60,12 +60,12 @@ async function recordRunAttempt(db, context, status, error = null, detailedMetri
 
         // [IDEA 2] Enhanced Execution Stats
         executionStats: {
-            processedUsers: rawExecStats.processedUsers || 0,
-            skippedUsers:   rawExecStats.skippedUsers || 0,
+            processedUsers: rawExecStats.processedUsers     || 0,
+            skippedUsers:   rawExecStats.skippedUsers       || 0,
             // Explicitly break out timings for BigQuery/Analysis
             timings: {
-                setupMs:      Math.round(timings.setup || 0),
-                streamMs:     Math.round(timings.stream || 0),
+                setupMs:      Math.round(timings.setup      || 0),
+                streamMs:     Math.round(timings.stream     || 0),
                 processingMs: Math.round(timings.processing || 0)
             }
         },
@@ -73,8 +73,8 @@ async function recordRunAttempt(db, context, status, error = null, detailedMetri
         outputStats: {
             sizeMB: sizeMB,
             isSharded: !!detailedMetrics.storage?.isSharded,
-            shardCount: detailedMetrics.storage?.shardCount || 1,
-            keysWritten: detailedMetrics.storage?.keys || 0 
+            shardCount:  detailedMetrics.storage?.shardCount || 1,
+            keysWritten: detailedMetrics.storage?.keys       || 0 
         },
 
         anomalies: anomalies,
@@ -84,9 +84,9 @@ async function recordRunAttempt(db, context, status, error = null, detailedMetri
     if (error) {
         runEntry.error = {
             message: error.message || 'Unknown Error',
-            stage: error.stage || 'UNKNOWN',
-            stack: error.stack ? error.stack.substring(0, 1000) : null,
-            code: error.code || null
+            stage:   error.stage   || 'UNKNOWN',
+            stack:   error.stack    ? error.stack.substring(0, 1000) : null,
+            code:    error.code    || null
         };
     }
 

package/functions/generic-api/admin-api/index.js

@@ -0,0 +1,233 @@
+/**
+ * @fileoverview Admin API Router
+ * Sub-module for system observability, debugging, and visualization.
+ * Mounted at /admin within the Generic API.
+ */
+
+const express = require('express');
+const pLimit = require('p-limit');
+const { getManifest } = require('../../computation-system/topology/ManifestLoader');
+const { normalizeName } = require('../../computation-system/utils/utils');
+
+/**
+ * Factory to create the Admin Router.
+ * @param {object} config - System configuration.
+ * @param {object} dependencies - { db, logger, ... }
+ * @param {object} unifiedCalculations - The injected calculations package.
+ */
+const createAdminRouter = (config, dependencies, unifiedCalculations) => {
+    const router = express.Router();
+    const { db, logger } = dependencies;
+
+    // --- 1. TOPOLOGY VISUALIZER ---
+    // Returns nodes/edges for React Flow or Cytoscape
+    router.get('/topology', async (req, res) => {
+        try {
+            // Build manifest using the INJECTED calculations object
+            // Passing [] for productLines ensures we get the FULL graph
+            const manifest = getManifest([], unifiedCalculations, dependencies);
+            
+            const nodes = [];
+            const edges = [];
+
+            manifest.forEach(calc => {
+                // Nodes
+                nodes.push({
+                    id: calc.name,
+                    data: { 
+                        label: calc.name,
+                        layer: calc.category,
+                        pass: calc.pass, // Visualization can group columns by Pass
+                        isHistorical: calc.isHistorical,
+                        type: calc.type
+                    },
+                    position: { x: 0, y: 0 } // Frontend handles layout (e.g. Dagre)
+                });
+
+                // Dependency Edges (Calc -> Calc)
+                if (calc.dependencies) {
+                    calc.dependencies.forEach(dep => {
+                        edges.push({
+                            id: `e-${dep}-${calc.name}`,
+                            source: normalizeName(dep),
+                            target: calc.name,
+                            type: 'default',
+                            animated: false
+                        });
+                    });
+                }
+                
+                // Root Data Edges (Data -> Calc)
+                if (calc.rootDataDependencies) {
+                    calc.rootDataDependencies.forEach(root => {
+                        // Ensure a node exists for the root data type
+                        const rootId = `ROOT_${root.toUpperCase()}`;
+                        if (!nodes.find(n => n.id === rootId)) {
+                            nodes.push({
+                                id: rootId,
+                                type: 'input', // Special React Flow type
+                                data: { label: `${root.toUpperCase()} DB` },
+                                position: { x: 0, y: 0 }
+                            });
+                        }
+
+                        edges.push({
+                            id: `e-root-${root}-${calc.name}`,
+                            source: rootId,
+                            target: calc.name,
+                            animated: true,
+                            style: { stroke: '#ff0072' } // Highlight data flow
+                        });
+                    });
+                }
+            });
+
+            res.json({ 
+                summary: { 
+                    totalNodes: nodes.length, 
+                    totalEdges: edges.length 
+                }, 
+                nodes, 
+                edges 
+            });
+        } catch (e) {
+            logger.log('ERROR', '[AdminAPI] Topology build failed', e);
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 2. STATUS MATRIX (Calendar View) ---
+    // ?start=2023-01-01&end=2023-01-30
+    router.get('/matrix', async (req, res) => {
+        const { start, end } = req.query;
+        if (!start || !end) return res.status(400).json({ error: "Start (YYYY-MM-DD) and End dates required." });
+
+        try {
+            const startDate = new Date(start);
+            const endDate = new Date(end);
+            const dates = [];
+            
+            // Generate date range
+            for (let d = new Date(startDate); d <= endDate; d.setDate(d.getDate() + 1)) {
+                dates.push(d.toISOString().slice(0, 10));
+            }
+
+            const limit = pLimit(20); // Concurrent Firestore reads
+            const matrix = {};
+
+            await Promise.all(dates.map(date => limit(async () => {
+                // Fetch Global Status and Root Data Availability
+                const [statusSnap, rootSnap] = await Promise.all([
+                    db.collection('computation_status').doc(date).get(),
+                    db.collection('system_root_data_index').doc(date).get()
+                ]);
+
+                // Flatten status for frontend (calcName -> { status: 'COMPLETED' | 'IMPOSSIBLE' })
+                const statusData = statusSnap.exists ? statusSnap.data() : {};
+                const rootData = rootSnap.exists ? rootSnap.data() : { status: { hasPortfolio: false } };
+
+                // Clean up status map
+                const cleanStatus = {};
+                Object.keys(statusData).forEach(key => {
+                    const entry = statusData[key];
+                    if (typeof entry === 'object') {
+                        if (entry.hash && entry.hash.startsWith('IMPOSSIBLE')) cleanStatus[key] = 'IMPOSSIBLE';
+                        else cleanStatus[key] = 'COMPLETED';
+                    } else if (entry === 'IMPOSSIBLE') {
+                        cleanStatus[key] = 'IMPOSSIBLE';
+                    } else if (entry === true || typeof entry === 'string') {
+                        cleanStatus[key] = 'COMPLETED';
+                    }
+                });
+
+                matrix[date] = {
+                    dataAvailable: rootData.status || {}, // e.g. { hasPortfolio: true }
+                    calculations: cleanStatus
+                };
+            })));
+
+            res.json(matrix);
+        } catch (e) {
+            logger.log('ERROR', '[AdminAPI] Matrix fetch failed', e);
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 3. FLIGHT RECORDER (Inspection) ---
+    // Look up execution details for a specific Calc + Date
+    router.get('/inspect/:date/:calcName', async (req, res) => {
+        const { date, calcName } = req.params;
+        try {
+            // We search across all potential passes (1-5) because we might not know which one it belongs to
+            const passes = ['1', '2', '3', '4', '5'];
+            let executionRecord = null;
+
+            // Run in parallel to find the record fast
+            await Promise.all(passes.map(async (pass) => {
+                if (executionRecord) return; // Optimization
+                const ref = db.doc(`computation_audit_ledger/${date}/passes/${pass}/tasks/${calcName}`);
+                const snap = await ref.get();
+                if (snap.exists) {
+                    executionRecord = { pass, ...snap.data() };
+                }
+            }));
+
+            if (!executionRecord) {
+                return res.status(404).json({ 
+                    status: 'NOT_FOUND', 
+                    message: `No execution record found in ledger for ${calcName} on ${date}` 
+                });
+            }
+
+            // Also fetch the "Contract" if it exists (for volatility analysis)
+            const contractSnap = await db.collection('system_contracts').doc(calcName).get();
+            
+            res.json({
+                execution: executionRecord,
+                contract: contractSnap.exists ? contractSnap.data() : null
+            });
+
+        } catch (e) {
+            logger.log('ERROR', `[AdminAPI] Inspect failed for ${calcName}`, e);
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 4. ANOMALY DETECTOR ---
+    // Finds recent crashes and chronic failures
+    router.get('/anomalies', async (req, res) => {
+        try {
+            const [dlqSnap, statsSnap] = await Promise.all([
+                db.collection('computation_dead_letter_queue').orderBy('finalAttemptAt', 'desc').limit(50).get(),
+                db.collection('computation_audit_logs').orderBy('failureCount', 'desc').limit(20).get()
+            ]);
+
+            const recentCrashes = [];
+            dlqSnap.forEach(doc => recentCrashes.push({ id: doc.id, ...doc.data() }));
+
+            const chronicFailures = [];
+            statsSnap.forEach(doc => {
+                const d = doc.data();
+                if (d.failureCount > 0) {
+                    chronicFailures.push({
+                        computation: doc.id,
+                        failures: d.failureCount,
+                        successes: d.successCount || 0,
+                        lastError: d.lastRunStatus
+                    });
+                }
+            });
+
+            res.json({
+                recentCrashes,
+                chronicFailures
+            });
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    return router;
+};
+
+module.exports = createAdminRouter;

package/functions/generic-api/helpers/api_helpers.js

@@ -1,10 +1,31 @@
 /**
  * @fileoverview API sub-pipes.
- * REFACTORED: Fixed Category Resolution to match ManifestBuilder logic.
- * Implements Status-Based Availability Caching and Smart Date Resolution.
+ * REFACTORED: API V3 - Status-Aware Data Fetching.
+ * UPDATED: Added GZIP Decompression support for fetching compressed results.
  */
 
 const { FieldPath } = require('@google-cloud/firestore');
+const zlib = require('zlib'); // [NEW] Required for decompression
+
+// --- HELPER: DECOMPRESSION ---
+/**
+ * Checks if data is compressed and inflates it if necessary.
+ * @param {object} data - The raw Firestore document data.
+ * @returns {object} The original (decompressed) JSON object.
+ */
+function tryDecompress(data) {
+    if (data && data._compressed === true && data.payload) {
+        try {
+            // Firestore returns Buffers automatically for Blob types
+            return JSON.parse(zlib.gunzipSync(data.payload).toString());
+        } catch (e) {
+            console.error('[API] Decompression failed:', e);
+            // Return empty object or original data on failure to avoid crashing response
+            return {};
+        }
+    }
+    return data;
+}
 
 // --- AVAILABILITY CACHE ---
 class AvailabilityCache {
@@ -147,6 +168,7 @@ const buildCalculationMap = (unifiedCalculations) => {
 
 /**
  * Sub-pipe: pipe.api.helpers.fetchUnifiedData
+ * UPDATED: Uses tryDecompress to handle compressed payloads.
  */
 const fetchUnifiedData = async (config, dependencies, calcKeys, dateStrings, calcMap) => {
     const { db, logger } = dependencies;
@@ -191,7 +213,8 @@ const fetchUnifiedData = async (config, dependencies, calcKeys, dateStrings, cal
             snapshots.forEach((doc, idx) => {
                 const { date, key } = chunk[idx];
                 if (doc.exists) {
-                    response[date][key] = doc.data();
+                    // [UPDATED] Decompress data if needed
+                    response[date][key] = tryDecompress(doc.data());
                 } else {
                     response[date][key] = null;
                 }
@@ -321,8 +344,11 @@ async function getComputationStructure(computationName, calcMap, config, depende
             .collection(compsSub).doc(computationName);
         const doc = await docRef.get();
         if (!doc.exists) { return { status: 'error', computation: computationName, message: `Summary flag was present for ${latestStoredDate} but doc is missing.` }; }
-        const fullData = doc.data();
+        
+        // [UPDATED] Decompress data for structure inspection
+        const fullData = tryDecompress(doc.data());
         const structureSnippet = createStructureSnippet(fullData);
+        
         return { status: 'success', computation: computationName, category: category, latestStoredDate: latestStoredDate, structureSnippet: structureSnippet, };
     } catch (error) {
         logger.log('ERROR', `API /structure/${computationName} helper failed.`, { errorMessage: error.message });

package/functions/generic-api/index.js

@@ -2,12 +2,16 @@
  * @fileoverview Main entry point for the Generic API module.
  * Export the 'createApiApp' main pipe function.
  * REFACTORED: API V3 - Status-Aware Data Fetching.
+ * UPDATED: Added Admin API Mount.
  */
 
 const express = require('express');
 const cors = require('cors');
 const { buildCalculationMap, createApiHandler, getComputationStructure, createManifestHandler, getDynamicSchema } = require('./helpers/api_helpers.js');
 
+// [NEW] Import Admin Router
+const createAdminRouter = require('./admin-api/index');
+
 /**
  * In-Memory Cache Handler
  * Wrapper that adds TTL cache to GET requests.
@@ -71,8 +75,11 @@ function createApiApp(config, dependencies, unifiedCalculations) {
     app.use(cors({ origin: true }));
     app.use(express.json());
 
+    // --- [NEW] MOUNT ADMIN API ---
+    // This injects the dependencies and the calculations package into the admin router
+    app.use('/admin', createAdminRouter(config, dependencies, unifiedCalculations));
+
     // --- Main API V3 Endpoint ---
-    // createApiHandler now initializes the AvailabilityCache internally
     const originalApiHandler = createApiHandler(config, dependencies, calcMap);
     const cachedApiHandler = createCacheHandler(originalApiHandler, dependencies);
     

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulltrackers-module",
-  "version": "1.0.293",
+  "version": "1.0.295",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [