Network Visualization Component

Relevant source files

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

• frontend/app/components/NetworkVisualization.tsx
• ARCHITECTURE.md
• AI_RULES.md
• INTEGRATION_SUMMARY.md
• TESTING_GUIDE.md
• frontend/tests/app/page.test.tsx

The Network Visualization Component renders an interactive 3D graph representing financial assets as nodes and their correlations as edges. It serves as the primary visual interface for exploring complex asset relationships within both the production Next.js frontend and the non-production Gradio demo. Sources: ARCHITECTURE.md:16-30, INTEGRATION_SUMMARY.md:41-45

The component uses Plotly (Plotly.js in frontend, Plotly Python in backend) to generate 3D scenes where assets are positioned deterministically. It allows users to rotate, zoom, and hover over elements to view metadata such as asset symbols, names, and relationship strengths. Sources: AI_RULES.md:12-14, INTEGRATION_SUMMARY.md:41-45

Architecture and Data Flow

The component operates within a decoupled architecture. In the production path, the Next.js frontend fetches visualization data from a FastAPI backend via a dedicated REST endpoint. In the non-production path, the Gradio UI calls the core logic directly to generate Plotly figure objects. Sources: ARCHITECTURE.md:40-70

Production Data Request Flow

The following diagram illustrates how the visualization data travels from the core logic to the React component:

Functional Logic and Data Structures

The component processes two primary data structures: nodes and edges. Nodes represent financial entities (Equity, Bond, Commodity, Currency), while edges represent the discovered relationships between them. Sources: ARCHITECTURE.md:144-155, frontend/tests/app/page.test.tsx:48-68

Visualization Data Schema

Field	Type	Description
nodes	Array	List of assets with 3D coordinates and visual attributes.
edges	Array	List of connections between nodes with strength metrics.
network_density	Number	Metric representing the ratio of actual to potential connections.

Sources: frontend/tests/app/page.test.tsx:48-68, INTEGRATION_SUMMARY.md:23-26

Node Attributes

Each node contains specific visual and financial properties used for rendering:

• Coordinates: x, y, and z values calculated deterministically to ensure layout consistency (often using seed=42).
• Visuals: color assigned based on AssetClass and size determined by asset importance or market impact.
• Metadata: symbol, name, and id for user identification on hover.

Sources: ARCHITECTURE.md:162-167, frontend/tests/app/page.test.tsx:51-61, AUDIT_REPORT.md:40-44

Implementation Details

Rendering Engine

The application mandates the use of Plotly as the exclusive library for all graphical representations. This ensures consistent interactive behavior, including 3D scene manipulation and camera controls. Sources: AI_RULES.md:12-14, 38-40

Coordinate Calculation

Relationship discovery logic generates the graph structure before visualization. The AssetRelationshipGraph logic in src/logic/asset_graph.py computes 3D positions, ensuring that related assets appear in proximity or follow specific layout algorithms. Sources: ARCHITECTURE.md:160-165, AUDIT_REPORT.md:40-44

Component Testing and Validation

Testing for the visualization component covers data processing, loading states, and accessibility. The test suite validates that the component handles empty datasets, rapid updates, and missing node/edge references without crashing. Sources: TESTING_GUIDE.md:131-143, frontend/tests/app/page.test.tsx:210-230

Key test areas include:

• Node Data Processing: Ensuring coordinates, colors, and sizes are correctly mapped from the API response.
• Edge Processing: Validating connections, styling, and relationship strength representation.
• Loading States: Verifying that a spinner or status message appears while getVisualizationData is pending.
• Accessibility: Checking for proper ARIA roles (e.g., role="status" for empty states) and semantic HTML.

Sources: TESTING_GUIDE.md:134-143, frontend/tests/app/page.test.tsx:110-120, 260-275

Conclusion

The Network Visualization Component is the central analytical tool of the Financial Asset Relationship Database. It transforms abstract relational data into a tangible 3D environment, allowing users to identify clusters, sector affinities, and systemic risks through interactive exploration. By adhering to a strict Plotly-based rendering standard and deterministic positioning, it provides a reliable and consistent user experience across different deployment environments. Sources: ARCHITECTURE.md:17-25, AI_RULES.md:12-14, INTEGRATION_SUMMARY.md:41-45