Application State Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/stores/tamv-store.ts
• src/stores/network.ts
• src/pages/Repositorio.tsx
• README.md
• supabase/functions/protocols-execute/index.ts
• package.json

The application state management in RDM Digital is designed as a federated, multi-layered system. It utilizes a custom store factory pattern to handle domain-specific states such as network health, economic balances, and AI operational status. This architecture supports a "Sovereign City" model, ensuring that critical data is synchronized across the frontend, cached via React Query, and persisted or orchestrated through Supabase Edge Functions.

The system emphasizes high-level domain separation, where stores manage the operational signals of specific modules (e.g., "Network", "Economy", "Isabella") to maintain a real-time "ECG" or operational heartbeat of the territory's digital twin.

Sources: README.md:4-15, README.md:43-46

Core Store Architecture

The project implements a bespoke state management solution via the createTamvStore utility. This pattern provides a lightweight, reactive state container that follows a subscription-based model. It uses the native useSyncExternalStore hook to bridge the store's internal state with the React lifecycle, ensuring tear-free rendering and consistent state access.

Store Factory Pattern

The createTamvStore function serves as the primary engine for state instantiation. It maintains a private state object and a set of listeners that are notified whenever the state is updated.

The state update logic prevents unnecessary re-renders by using Object.is to perform a reference check between the next and current state.

Sources: src/stores/tamv-store.ts:11-40

Store Interface Definitions

The state management system adheres to a strictly typed StoreApi interface:

Component	Description
getState	Returns the current immutable state object.
setState	Updates the state via a partial object or an updater function.
subscribe	Registers a listener callback and returns an unsubscribe function.
useStore	A React hook that accepts a selector to retrieve specific state slices.

Sources: src/stores/tamv-store.ts:3-9

Domain-Specific State: Network Store

The networkStore manages the status of federated nodes, connectivity bridges, and security features like quantum encryption. It categorizes network infrastructure into layers (L0 to L7) and calculates a real-time health score based on latency and coverage.

Network Node Structure

Nodes represent physical or virtual infrastructure within the TAMV ecosystem.

Field	Type	Description
id	string	Unique identifier (normalized to lowercase).
status	active | idle | error	Current operational status.
latency	number	Response time in milliseconds (clamped to non-negative).
layer	L0 - L7	The specific network layer (e.g., L0 for Nexus-RDM).

Sources: src/stores/network.ts:10-18, src/stores/network.ts:50-59

Health Calculation Logic

The store includes a getHealth method that derives a NetworkHealth object. It evaluates security gaps (e.g., whether the msrBridgeConnected is active) and layer coverage to determine the riskLevel.

External State Integration

Beyond local stores, the application manages state through external integrations with GitHub and Supabase.

GitHub Repository State

The RepositorioPage utilizes TanStack React Query to manage the state of fetched repositories. It performs analysis and enrichment on the fly, classifying repositories into federations.

• Deep Sync: Triggered via fetchGitHubRepos with a minimum page scan requirement.
• Edge Sync: Synchronizes local state with Supabase via the /functions/v1/github-sync endpoint.

Sources: src/pages/Repositorio.tsx:32-60, package.json:59

Edge Function Orchestration

Backend state transitions and protocol executions are handled by Supabase Edge Functions. These functions validate user authorization and manage counts for federations, repositories, and protocol executions.

Function Name	Purpose	Data Source
federation-state	Summarizes counts of federations and core repos.	federations, repositories
dashboard-summary	Aggregates active businesses and kernel versions.	businesses
telemetry-ingest	Inserts validated analytical events into the database.	analytics

Sources: supabase/functions/protocols-execute/index.ts:31-48, README.md:32-37

Utility and Helper Functions

The state management layer includes robust utility functions for data normalization and unique identification.

• clampPercentage: Ensures numerical values stay within a 0-100 range.
• clampNonNegative: Prevents negative values in metrics like latency.
• createClientId: Generates unique identifiers using crypto.randomUUID with a fallback to a timestamp-based string for legacy environments.

Sources: src/stores/tamv-store.ts:47-73, src/stores/network.ts:50-59

Summary

Application state management in this project is characterized by a "Domain-Driven" approach, where local stores handle real-time operational signals while external integrations (React Query and Supabase) manage data persistence and synchronization. The custom createTamvStore factory ensures that state remains predictable and reactive across the various modules of the RDM Digital ecosystem.