Building OutageLens AI: Tracing Service Failures with FalkorDB

How graph databases can connect service dependencies, incidents, and resolutions to make technical investigations easier.

Modern applications rarely operate in isolation. A customer portal may depend on an API gateway, which relies on an authentication service, which connects to a database. When one component fails, understanding what else might be affected can quickly become complicated.

That is the problem I explored with OutageLens AI, my project for Graph Hacks 2026. It is a graph-powered service investigation dashboard built using FalkorDB Cloud, Python, FastAPI, React, and Cypher.

The idea is simple: represent service dependencies, incidents, and resolutions in a connected graph, then use graph traversal to investigate potential failure paths and retrieve relevant context.

Project repository: https://github.com/VANSH-AGARWAL-collab/outagelens-ai

Why FalkorDB?

When investigating a service failure, knowing which component is affected is only the beginning. Engineers also need to understand which services depend on it, how far an impact might propagate, and whether related incidents have documented resolutions.

These questions involve relationships between multiple entities.

FalkorDB provides a graph-based approach to representing these connections and querying them using Cypher. Instead of manually reconstructing dependency chains, the application can traverse relationships in the graph to identify connected services.

For OutageLens AI, FalkorDB is the central data layer behind the investigation workflow.

Modeling service dependencies as a graph

I created a FalkorDB Cloud graph named outagelens.

The demonstration graph contains this service dependency chain:

Customer Portal → API Gateway → Auth Service → Authentication DB

The graph uses three main relationship types:

• DEPENDS_ON connects a caller to the component it relies on.
• AFFECTS connects an incident to an affected service.
• RESOLVED_BY connects an incident to a resolution record.

The graph also includes an example incident, INC-1001, and a linked resolution, RES-1001.

This structure connects the application's service topology with incident information. Rather than storing dependency relationships and incident records as disconnected data, the graph makes their connections available for traversal and investigation.

The incident and resolution records used in the demonstration are synthetic examples, not data collected from a production system.

Tracing upstream dependencies with Cypher

One of the key problems OutageLens AI addresses is finding services that depend directly or indirectly on a selected component.

Consider an investigation targeting Auth Service. In the demonstration topology, API Gateway is one hop away, while Customer Portal is two hops away.

A variable-length Cypher relationship pattern can traverse these dependency paths:

MATCH path = (caller)-[:DEPENDS_ON*1..10]->(root)
WHERE (root:Service OR root:Database)
  AND (root.name = $service_id OR root.id = $service_id)
RETURN caller, labels(caller)[0], path,
       length(path) AS depth
ORDER BY depth ASC

The pattern *1..10 allows paths containing between one and ten relationships. The depth value indicates how many relationships separate a caller from the selected component.

Relationship direction is important. Since DEPENDS_ON points from a caller to its dependency, the traversal finds callers whose dependency paths lead to the selected component.

This approach makes it possible to explore multiple levels of dependencies without hardcoding a fixed service chain into the investigation logic.

Connecting dependencies to incident history

Finding connected services provides only part of the picture. An investigation becomes more useful when it can also retrieve relevant incident and resolution information.

A second graph query matches incidents affecting identified entities and optionally retrieves linked resolutions:

MATCH (target)
WHERE (target:Service OR target:Database)
  AND target.name IN $entity_names
MATCH (inc:Incident)-[:AFFECTS]->(target)
OPTIONAL MATCH (inc)-[:RESOLVED_BY]->(res:Resolution)
RETURN DISTINCT inc, res, target

The OPTIONAL MATCH clause allows an incident to be returned even when no resolution is linked to it.

Together, these queries demonstrate how graph traversal can connect service dependencies with related incident records. The backend prepares the resulting information for presentation in the frontend, helping users explore connected context in one workflow.

Under the hood: How OutageLens AI works

The application has three main components.

React and Vite — Frontend

The frontend provides the dashboard and graph visualization used to explore services and investigation results.

Python and FastAPI — Backend

The backend exposes API endpoints that connect the frontend to the graph database. The documented endpoints include /health, /graph, and /investigate.

FalkorDB Cloud — Graph database

FalkorDB stores the graph and executes the Cypher queries used for dependency traversal and incident retrieval.

This separation keeps database access in the backend and allows the frontend to present the returned graph and investigation results.

What the demonstration shows

In the documented demonstration scenario, investigating Auth Service returns two upstream services: API Gateway and Customer Portal. The maximum upstream dependency depth is two hops, and the results include incident INC-1001 and resolution RES-1001.

The graph endpoint also exposes the demonstration topology for visualization.

These results illustrate the implemented workflow on a small synthetic graph. They should not be interpreted as proof of production outage detection, measured reductions in debugging time, or a verified root-cause diagnosis.

Challenges and lessons learned

One important consideration in graph-based investigation is relationship direction. A dependency edge points from a caller to the component it uses, so identifying upstream callers requires traversing paths that terminate at the selected component. Getting this direction right is essential to interpreting the results correctly.

Another lesson is the value of connecting topology with incident history. A dependency graph can show how services relate to one another, while linked incident and resolution records add context that can help an engineer investigate further.

The project also highlights the importance of distinguishing graph-based investigation from definitive root-cause analysis. Finding a dependency path can identify potentially relevant components, but confirming the actual cause of an incident requires additional evidence.

What's next?

OutageLens AI provides a foundation for several potential improvements:

• Live telemetry ingestion: Incorporate service events and tracing data to keep the graph updated.
• More realistic testing: Evaluate traversal correctness and query performance against larger dependency graphs and varied incident scenarios.
• Context-grounded explanations: Explore natural-language explanations based on retrieved graph evidence.
• Safer remediation workflows: Introduce controlled runbook execution with appropriate validation and human approval.

These are future development directions rather than capabilities claimed by the current demonstration.

Final thoughts

OutageLens AI explores how graph databases can make connected service information easier to investigate.

By representing service dependencies, incidents, and resolutions in FalkorDB, the project demonstrates how Cypher traversal can reveal upstream relationships and retrieve relevant incident context through a unified workflow.

The current implementation uses synthetic demonstration data, but the approach provides a starting point for more advanced service investigation tools that incorporate live telemetry, larger graphs, and additional evidence.

For Graph Hacks 2026, this project has been an opportunity to explore the practical role of graph databases in connecting operational data and making dependency relationships easier to understand.

Explore the project on GitHub: https://github.com/VANSH-AGARWAL-collab/outagelens-ai

Built for Graph Hacks 2026 — FalkorDB.