Two records. One failed pickup. Two different explanations.
“Pickup cancelled by customer.”
“Pickup failed because the courier was unavailable.”
If you have ever contacted support about a failed return pickup, you can probably imagine the next question:
Which explanation should I trust?
We built ReturnTrail for WeMakeDevs × FalkorDB Graph Hacks to explore a more useful starting point: connect the records, preserve their original words, and show what still needs clarification.
I’m Om Singh Jadon, and my teammate is Ajeet Gadekar. Together, we are Code101 from India.
Our biggest lesson was this:
Marking a follow-up task as resolved does not mean the entire case is resolved—especially when new evidence arrives.
🎬 Watch the working project
The walkthrough shows the original conflicting records, their graph connections, an AI investigation, a manual task outcome, and a fresh review after another source is added.
The problem we chose
ReturnTrail helps a shopper prepare an evidence-linked support conversation about a disputed return pickup.
The difficult part is often reconstructing the context:
- Do two statements describe the same pickup attempt?
- Which document recorded each claim?
- What did an earlier support explanation actually cover?
- Does that explanation still cover the records after another document arrives?
Our output is a reviewable case brief containing original claims, source connections, follow-up questions, and the history of manual explanations.
The current prototype uses four fictional practice cases and bounded fictional text additions. We have not measured real-world dispute outcomes or validated commercial demand.
Product capture using fictional records and a local FalkorDB instance. Case API responses were not mocked for this capture.
Why the pickup attempt belongs in the graph
An order can have more than one pickup attempt.
A customer cancellation on Monday and an unavailable courier on Wednesday do not necessarily contradict each other. Comparing the text without connecting it to the correct attempt could produce a misleading finding.
Our graph connects:
- A case to its order, item, and return request.
- Each pickup attempt to its return request.
- Each statement to the pickup it describes.
- Each statement to the document that recorded it.
- Each follow-up action to its reviewed documents.
- Each manual clarification to its follow-up action.
For CASE-001, the two conflicting statements both describe PICKUP-001. That shared connection makes the comparison relevant.
CASE-002 demonstrates the opposite: different explanations refer to separate attempts, so the supported rule does not flag them as a same-attempt disagreement.
The Cypher behind the evidence
Here is the evidence query documented in our repository:
MATCH (c:Case {id:$caseId})-[:HAS_ORDER]->(o:Order)-[:CONTAINS]->(i:Item)
MATCH (c)-[:HAS_RETURN]->(r:ReturnRequest)-[:RETURNS]->(i)
MATCH (p:PickupAttempt)-[:ATTEMPTS]->(r)
MATCH (s:SupportStatement)-[:ABOUT]->(p)
MATCH (s)-[:RECORDED_IN]->(d:EvidenceDocument)
RETURN DISTINCT c.id AS caseId, o.id AS orderId, i.id AS itemId,
r.id AS returnId, p.id AS pickupId, s.id AS statementId,
s.claimedStatus AS claimedStatus, s.text AS statement,
d.id AS evidenceId, d.sourceType AS sourceType
ORDER BY evidenceId, statementId;
The backend selects the authorized workspace graph and binds the case ID.
Both ownership paths—through the order/item and through the return/item—must match. Matching an identifier alone does not grant access to another workspace.
FalkorDB supplies the evidence traversal and stored workflow context. Java applies explicit rules to the returned records.
The visible graph proof comes from executed queries. Our animated 3D parcel experience illustrates the story separately.
What an earlier explanation actually covers
Our most useful design decision was connecting each saved action to the documents it reviewed:
Case → Action → REFERENCES → EvidenceDocument
A manual reply is linked through:
Action → HAS_CLARIFICATION → ClarificationRecord
This lets us ask a more precise question than “Was the task resolved?”
Does the reviewed source set, including its evidence revision, match the current source set?
Coverage requires:
- A nonempty current source set.
- Matching evidence IDs.
- A matching evidence revision.
Suppose a task reviewed DOC-001 and DOC-002. A user records a manual explanation and resolves that task.
Then DOC-003 arrives.
The earlier task remains resolved in history, but it did not review DOC-003. The application makes that boundary visible and can prepare a fresh follow-up for the updated source set.
We preserve the earlier record instead of rewriting it as though it had reviewed information that did not exist yet.
A matching source set still does not independently verify a manual explanation. It establishes the explanation’s recorded context.
Read the ContextCoverage implementation →
Context lab: preview how the evidence changes the question
Context lab lets a user temporarily set aside one source and inspect the result.
For CASE-001, excluding DOC-001 leaves only the courier-unavailable claim. Our bounded disagreement rule no longer has two conflicting reasons to compare.
The application runs a parameterized, read-only graph query with a source exclusion. It returns the remaining connections and evaluates that result.
Original records and saved tasks stay unchanged.
This preview does not establish that the excluded document is false or that the remaining claim is true.
It shows how the available evidence changes the supported next question.
CASE-004 extends the demonstration: add a reviewed fictional source to a case with an earlier manual reply, then inspect the changed coverage.
The agent’s job is bounded
Our Spring Boot backend exposes four investigation tools:
get_case_evidenceget_case_clarificationsget_case_findings-
prepare_followup_action, when a finding is pending
The AI workflow must retrieve current evidence and saved context before proceeding to findings and a local follow-up action.
The backend enforces the sequence and renders the final report from tool results.
The model does not generate arbitrary Cypher or determine who caused the failed pickup. These are application tool calls; we did not build an MCP server.
We also provide Review rules & prepare question, which performs the deterministic workflow without a model request.
Users can record an explicit manual outcome, inspect the history, and export a fresh brief.
No support message is sent automatically, and no refund is issued.
Designed for people who do not know graph databases
The interface uses familiar language:
- Evidence: read the original words.
- Connections: understand which records belong together.
- Context lab: preview how a source changes the assessment.
- Investigation: inspect findings and completed tool results.
- Follow-up tasks: record a manual outcome.
- Case brief: export the information for a support conversation.
- History: see what changed and when.
Guest access lets someone explore immediately. Optional Google and GitHub sign-in provide account entry.
We used a playful parcel theme, animated connections, and a lamp-inspired sign-in page, while keeping the source text and task states explicit.
Our stack
| Layer | Technology and role |
|---|---|
| Frontend | React and Vite for the interface |
| Backend | Java and Spring Boot for APIs, authorization, rules, and workflow enforcement |
| Graph database | FalkorDB for connected evidence and saved task/reply context |
| AI | Groq with openai/gpt-oss-120b for the constrained tool-calling investigation |
| Deployment | Combined frontend/backend on Render, with FalkorDB Cloud |
The graph is central to retrieving evidence and understanding what a saved explanation covered.
Removing it removes those traversals and the stored source/task/reply connections.
What we tested—and what those tests establish
We tested distinctions that could otherwise produce misleading behavior: same versus different attempts, unknown reasons, changed source context, stale writes, and workspace isolation.
| Recorded check | Scope |
|---|---|
| 93 backend tests successful; 2 skipped | Hosted default suite at commit 275fb37; zero failures or errors |
| 14 frontend tests passed | Domain, draft, and public-video input boundaries |
| Five public API workflow groups passed | Hosted application and external FalkorDB; synthetic writes, history, retries, version protection, and guest isolation |
| One real hosted AI investigation passed | Four model requests, all four required tools in order, and one OPEN local follow-up |
Our validation record separates mocked contracts, actual graph checks, and the hosted model request.
The twenty labelled synthetic rule fixtures are a regression set, not a real-world accuracy benchmark.
A deployment lesson: readiness has a limited meaning
When we enabled OAuth providers, the graph readiness endpoint stayed UP while the homepage returned HTTP 500.
The authorization resolver was treating an ordinary page path as a possible provider path. At the root URL, this produced an empty registration ID.
We reproduced the exception, restricted lookup to OAuth authorization routes, and added three regression tests.
That changed our release check: we verify the homepage, sign-in shell, provider redirects, and a fresh guest workflow alongside database readiness.
The free preview also has session and data-retention limits. It is intended for fictional evaluation data; exporting a brief remains useful.
Read the deployment boundaries →
Try the part that changes the next action
Open ReturnTrail as a guest and start with CASE-001:
- Compare the original claims in Evidence.
- Inspect their source paths in Connections.
- Set aside a source in Context lab and compare the assessment.
- Prepare a question and record a fictional manual outcome.
- Add a reviewed fictional source through Evidence inbox.
- Inspect the changed coverage and review the updated evidence.
- Export the Case brief and inspect History.
Then try CASE-002 and CASE-004.
The useful outcome is whether the connected context supports another question—and which sources make that question necessary.
What comes next
We want to observe nontechnical users completing this workflow and speak with support operators about the information they need.
Those observations should guide the next version before we claim that ReturnTrail saves time or fits a real support process.
The lesson we are taking forward is specific:
A saved answer needs a record of the evidence it covered. When that evidence changes, the application should make the boundary visible.
Built by Om Singh Jadon and Ajeet Gadekar, Team Code101, India, for WeMakeDevs × FalkorDB Graph Hacks.
Track: Agents That Act on Connected Data.
Connect with us
Explore: Live application · Demo video · Repository · Cypher queries
Top comments (0)