How we validate architectural topologies dynamically
Designing a flexible graph validation engine that checks semantic relationships and topological paths instead of static node IDs.
01The challenge of validating dynamic architectural designs
Teaching system design interactively is difficult because there are many valid ways to build the same system. If we validate a student's diagram by checking for specific node coordinates or exact text matches (e.g. node.label === "Auth Service"), the validation will fail if the student names the node differently or places it in a different position. We need a validation system that checks the logical relationships (topology) between nodes, rather than static strings.
02Converting visual canvases into graph adjacency lists
To validate the diagram, we first convert the visual layout of nodes and edges into a graph adjacency list. An adjacency list maps each node ID to a list of its connected target nodes. This converts the visual diagram into a structured format that we can easily traverse and analyze using graph algorithms, letting us check paths and connections programmatically.
03Implementing semantic matchers for architectural rules
We write validation rules using semantic matchers that check for logical patterns. For example, a "Load Balancer Rule" verifies that all incoming client traffic passes through a load balancer before reaching any compute nodes. Instead of checking for specific node IDs, the matcher looks for node categories (e.g., Client, Load Balancer, Compute), checking if the connections form the correct path, regardless of where they are placed.
04Fuzzy matching with tech stack aliases
To give students more freedom, we support fuzzy matching using tech stack aliases. Each node has a category (like Cache) and an alias (like Redis or Memcached). The validation engine checks the category rather than the specific tech stack. This allows students to use either Redis or Memcached to satisfy a caching requirement, making the validator flexible and supportive of different design choices.