VisualGrid Documentation

What is VisualGrid?

VisualGrid (VG) is a Temporal Directed Property Graph Explorer for the g3nretailstack ecosystem. It provides a read-only browser for traversing the DynamoDB tables of all 20 microservices (20 tables total) as an interactive property graph.

VisualGrid does not store or modify any service data. It reads directly from each service's DynamoDB table via cross-service IAM grants and presents records as graph nodes with separated DDB keys and enriched metadata (doc links, MCP links, service codes, record types). Root-only access — all fields returned unredacted.

How It Fits

g3nretailstack is composed of 20 microservices, each with its own DynamoDB single-table design. Understanding the live data topology across services requires navigating PK/SK patterns, GSI structures, and cross-service references. VisualGrid solves this by:

1. Unifying the view -- All 20 service tables appear as a single property graph with consistent node structure.
2. Providing context -- Each node includes metadata linking back to service documentation, RECAP files, and MCP protocol definitions.
3. Root-only access -- Operators and engineers authenticate via scrypt secret code; all fields returned unredacted.

Key Concepts

• Node: A single DynamoDB item, rendered with ddb_keys (PK/SK/GSI keys), properties (all attributes), and metadata (service context).
• Entry Nodes: Top-level starting points for graph traversal showing all 20 service tables.
• Children: Items that share a PK with the current node, navigated by SK prefix patterns from the graph registry.

Further Reading

• Endpoint Reference (calls.md) -- Detailed request/response documentation for all 7 endpoints.
• Access Surfaces (surfaces.md) -- Root mode: capabilities and use cases.
• MCP Protocol -- Machine-readable protocol definition.
• OpenAPI Spec -- OpenAPI 3.0.3 specification.