A brain for your system's dependencies. Ask "what breaks if I change this?" and see the blast radius before you ship.
Inspiration
Every engineering team has been here: someone changes a "small" thing, like an API response, a token format, or a database column, and something unrelated breaks days later. The knowledge needed to predict that breakage exists, but it's scattered across architecture notes, API specs, runbooks, READMEs, and people's heads.
Most "company brain" tools answer what do we know? We wanted one that answers a more useful question: what breaks if we change this?
What it does
Ripple Brain turns scattered engineering documents into a living dependency graph, then uses it to analyze proposed changes.
- Pick a component and describe a change, for example Authentication API: remove support for the legacy token format.
- Watch the ripple. The graph lights up in waves by distance: direct consumers first, then indirect dependents, such as tests and downstream services.
- Get an evidence-backed report. Affected components, why each is affected, the exact dependency path, which checks to run, and what is unknown.
- Trust but verify. Every finding links to the source document snippet it came from, and is tagged Documented, Inferred, or Unknown, so teams can tell facts from guesses.
- Teach it new things. Drop in a new document and the brain extracts components and relationships, each with a cited source, and merges them into the graph.
- Take it with you. One click copies the analysis as a Markdown change-review checklist for a ticket or pull request.
A deterministic risk score (criticality ÷ hop distance) rates the overall impact Low, Medium, or High, and the formula is visible on hover, so the number is never a black box.
How we built it
Graph first, AI second. Dependency tracing is deterministic Python, not LLM guesswork. We use NetworkX for traversal and path-finding, with a documented edge convention (dependency → consumer) covered by direction and cycle tests. The language model never decides what is connected. It only explains evidence it is handed, and it is instructed not to name any dependency that isn't in the evidence package.
- Knowledge layer: HydraDB stores the ingested source documents and retrieves the most relevant snippets for each analysis. It powers the evidence behind every finding and the source drawer.
- Reasoning layer: Gemini turns the graph evidence into a concise, structured report and extracts components and relationships from new documents, with a supporting snippet required for every edge.
- Backend: Python and FastAPI. Impact is computed instantly and returned first, so the graph animates while the report streams in.
- Frontend: a single-page interface with Tailwind CSS and Cytoscape.js, designed to be minimal and calm: dark theme, one accent color, and a hop-ordered ripple animation.
- Resilience: all storage calls sit behind an adapter with a local fallback, so the app keeps working if the network or HydraDB is unavailable.
Challenges we ran into
- Keeping the AI honest. Language models love to fill gaps. We separated what the graph proves from what the model suggests, labeled the difference in the UI, and made "Unknowns" a first-class section.
- Edge direction. Reversing a single edge silently flips "what depends on me" into "what I depend on." We fixed one convention and wrote the test before the traversal code.
- Asynchronous indexing. Documents aren't searchable the instant they're ingested, so we designed the ingest flow to show progress and fall back gracefully.
- Restraint. It was tempting to add dashboards and settings. We cut everything that didn't serve the one question the product answers.
Accomplishments that we're proud of
- A complete loop from raw documents to graph to animated impact to cited report.
- Every claim is traceable to a dependency path and a source snippet.
- The product states its own uncertainty instead of hiding it.
- A clean, minimal interface that makes a complex graph easy to read at a glance.
What we learned
- Grounding beats generation: a smaller model with good evidence outperforms a bigger model guessing.
- Showing uncertainty makes people trust the output more, not less.
- Retrieval and graph structure complement each other. Search finds relevant text, and the graph says how things connect.
What's next
- Live sources: import dependencies from code, API specs, and repositories, and connect issue trackers and chat.
- Freshness checks: detect stale or contradicted dependency records.
- Smarter ranking: rank impacts by criticality, distance, and change history, and flag missing tests or unclear ownership.
- Assisted workflows: draft change-impact tickets, suggest reviewers, and require human approval for anything consequential.
- Beyond software: the same engine can trace the effects of changing a policy, a process, or a product decision.
Limitations
Ripple Brain reports potential impact, not guarantees. Its analysis is only as complete as its dependency data, and a missing edge does not prove that no dependency exists. It never modifies code or deploys anything.
Built with
python · fastapi · networkx · hydradb · gemini · cytoscape.js · tailwindcss · javascript · html · css
Try it
- Demo scenario: Authentication API, "Remove support for the legacy token format"
- Repo: [add link]
- Video: [add link]
Log in or sign up for Devpost to join the conversation.