The Context Graph is an interactive graph-based visualization and navigation tool that maps all semantic and operational assets in your Oxy project and their relationships. It provides a complete, visual understanding of how data flows through your system by showing connections between data assets, automations, and AI agents.

What is the Context Graph?

The Context Graph feature creates a visual knowledge graph of your entire Oxy project, displaying:

Data Assets: Tables, Views, Topics, Entities, SQL Queries
Automation Assets: Workflows, Apps, Automations
AI Assets: Agents (both default and routing agents)

Each asset appears as a node in an interactive graph, with edges showing how they depend on, reference, or contain each other.

Key Components

Node Types

The Context Graph visualizes 9 different types of nodes:

Node Type	Description	Visual Representation
`table`	Database tables from connected datasources	Color-coded node
`view`	Semantic views (business data models)	Color-coded node
`topic`	Collections of related views	Color-coded node
`entity`	Semantic entities (customer, order, product, etc.)	Color-coded node
`agent`	AI agents (default or routing types)	Color-coded node
`workflow`	Workflow automations	Color-coded node
`app`	Standalone app files (.app.yml)	Color-coded node
`automation`	Automation files (.automation.yml)	Color-coded node
`sql_query`	SQL query files referenced in workflows/agents	Color-coded node

Edge Types

Edges represent relationships between nodes:

Edge Type	Description
`uses`	General dependency relationship
`contains`	Topic contains views
`derived_from`	View derived from source table
`references`	Reference relationships between entities
`routes to`	Routing agent routes to another agent
`fallback`	Fallback routing for routing agents

Semantic Layer Foundation

The Context Graph builds upon Oxy’s semantic layer concepts:

Views (.view.yaml)

Logical data models that abstract database tables, defining business concepts through Entities, Dimensions, and Measures. They enable consistent, governed access to data.

Topics (.topic.yaml)

Collections of related views organized by business domain. Topics provide logical grouping for data discovery and include base views and default filters for consistent querying.

Entities

Represent distinct business objects (customers, orders, products, etc.) and enable automatic relationship discovery between views. Entities can be primary (main subject) or foreign (references).

Dimensions & Measures

Dimensions: Attributes and properties of entities
Measures: Aggregations and calculations (count, sum, average)

How to Use the Context Graph

Accessing the Context Graph View

Navigate to the Context Graph page in the Oxy IDE to see the interactive graph visualization of your project.

Exploring the Graph

View All Assets: The graph displays all assets in a force-directed layout, making it easy to see the overall structure
Identify Relationships: Edges connect related nodes, showing data lineage and dependencies
Color Coding: Different node types use different colors for quick identification

Focus and Filter

Use the “Focus” dropdown to filter by specific asset types:

Auto: Show all assets
Agents: Show only AI agents and their connections
Workflows: Show only workflows and related assets
Apps: Show only app files and their dependencies
Automations: Show only automation files
Topics: Show only topics and their contained views
Views: Show only semantic views
SQL Queries: Show only SQL query files
Tables: Show only database tables
Entities: Show only semantic entities

When a type is selected, the graph highlights that type and their directly connected assets.

Dive Into Details

Click any node to:

Highlight Connections: See all incoming and outgoing edges for that node
View Metadata: Right sidebar opens showing:
- Node name and description
- File path
- Full file content preview
Open in IDE: Click “Open in IDE” button to edit the file directly

Understanding Data Lineage

The Context Graph makes it easy to trace how data flows through your system:

Database Tables → Views → Topics → Agents/Workflows

You can see:

Which views are built on which tables
Which topics contain which views
Which agents have access to which topics
How workflows use semantic queries and SQL
Dependencies between different automations

Use Cases

Data Governance & Understanding

Visualize Structure: See your complete semantic layer at a glance
Understand Relationships: Discover how business concepts connect
Identify Issues: Find orphaned or unused assets
Documentation: Use as living documentation of your data architecture

Impact Analysis

Before making changes, use the Context Graph to:

See what will be affected if you modify a view or topic
Understand downstream dependencies
Plan refactoring with confidence
Avoid breaking changes

AI Context

The Context Graph helps with AI agent development:

Agent Understanding: Agents use the context graph to understand available data
Semantic Context: Topics provide semantic context for natural language queries
Routing: Routing agents can intelligently route between topics and workflows

Development Workflow

Speed up development by:

Quick Navigation: Jump directly to relevant assets
File Preview: See file content before opening
IDE Integration: One-click access to edit files
System Understanding: Understand how changes affect the broader system

Technical Architecture

Graph Structure

The Context Graph follows this structure:

ContextGraph {
  nodes: ContextGraphNode[]
  edges: ContextGraphEdge[]
}

ContextGraphNode {
  id: string
  type: NodeType
  label: string
  data: NodeMetadata
}

ContextGraphEdge {
  source: string
  target: string
  type: EdgeType
}

Graph Building Process

The Context Graph service:

Fetches all databases and file trees
Parses views, topics, agents, workflows, apps, automations, and SQL queries
Builds nodes for each asset type
Constructs edges by analyzing dependencies and references
Returns the complete graph for visualization

UI Components

The Context Graph visualization uses:

React Flow: Interactive graph rendering with force-directed layout
Custom Node Rendering: Color-coding and styling by node type
Connection Graph: Relationship traversal and highlighting
Detail Panel: Sidebar with node information and file preview

Examples

Example: Tracing a Data Flow

Imagine you have a customer analytics agent. Using the Context Graph, you can trace:

Database Table: customers table in your database
View: customer_view.view.yaml derived from customers table
Topic: customer_analytics.topic.yaml contains customer_view
Agent: customer_agent.agent.yml has access to customer_analytics topic

This visual trace helps you understand exactly where your agent’s data comes from.

Example: Impact Analysis

Before renaming an entity in a view:

Click on the view node in the Context Graph
See all topics that contain this view
See all agents that use those topics
Understand the full scope of impact before making changes

File Locations

The Context Graph feature is implemented in:

Types: /web-app/src/types/contextGraph.ts
API Service: /web-app/src/services/api/contextGraph.ts
UI Components: /web-app/src/pages/context-graph/
React Hook: /web-app/src/hooks/api/contextGraph/useContextGraph.ts
Semantic Specs: /crates/semantic/specs/ (view.md, topic.md, entity.md)

Best Practices

Regular Review: Periodically review the Context Graph to understand your project’s evolution
Before Major Changes: Always check the Context Graph before refactoring or renaming assets
Onboarding: Use the Context Graph to help new team members understand the project structure
Documentation: Reference Context Graph screenshots in project documentation
Cleanup: Use the Context Graph to identify and remove unused assets

The Context Graph is your visual map to understanding, navigating, and maintaining your Oxy data project. It transforms abstract configurations into a concrete, explorable graph that makes complex relationships immediately clear.

Get Started

Getting Started with Agents

Core Concepts

Semantic Layer

Deployment

AWS Deployment

Authentication

Data Sources

Models

Analytics

Apps

Reference

MCP Server

Migration

​What is the Context Graph?

​Key Components

​Node Types

​Edge Types

​Semantic Layer Foundation

​Views (.view.yaml)

​Topics (.topic.yaml)

​Entities

​Dimensions & Measures

​How to Use the Context Graph

​Accessing the Context Graph View

​Exploring the Graph

​Focus and Filter

​Dive Into Details

​Understanding Data Lineage

​Use Cases

​Data Governance & Understanding

​Impact Analysis

​AI Context

​Development Workflow

​Technical Architecture

​Graph Structure

​Graph Building Process

​UI Components

​Examples

​Example: Tracing a Data Flow

​Example: Impact Analysis

​File Locations

​Best Practices