# Civicly

A pothole gets repaired, but returns a few weeks later. A drain gets cleaned, yet the street floods again. Waste gets collected, but the same corner keeps overflowing.

Each complaint tells part of a story. Understanding why the problem keeps returning requires connecting that complaint with earlier repairs, inspection findings, infrastructure and service records.

I built **Civicly**, an AI-powered civic investigation platform, to explore how those connections can support better investigations. It covers recurring waterlogging, road damage and waste accumulation.

At the heart of the project is **FalkorDB**, which gives Civicly a connected memory of the city.

### What does “connected memory” mean?

Imagine investigating a damaged road with several folders on your desk. One contains complaints. Another contains repair records. A third holds water-pipe inspections. Somewhere else is a document explaining which department handles underground leaks.

You can read every folder individually, but you still need to connect the information yourself.

FalkorDB lets Civicly store those connections explicitly. A complaint belongs to an incident. That incident affects a road. A pipe runs beneath that road. A previous repair happened there. An inspection provides evidence about the pipe’s condition.

In a graph database, the records are called **nodes**, and their connections are called **relationships**. The names sound technical, but the idea is familiar: store both the information and how it fits together.

That matters because civic problems often cross departmental boundaries. A road complaint may need evidence from the water department before the road team can choose an appropriate repair.

### Following connections without jumping to conclusions  
  
One of the most important principles in Civicly is that **a connection is a reason to investigate, not proof of a cause**.

A pipe beneath a damaged road does not automatically mean the pipe is leaking. Waste near a flooded street does not automatically mean it blocked the drainage system.

FalkorDB helps Civicly find relevant connections. Inspection evidence is still needed to evaluate the possible explanations.

This distinction shapes the investigation workflow. Civicly can retain several hypotheses, record what supports or contradicts each one, and request more evidence when the answer remains uncertain. Earlier assessments stay in the history rather than disappearing when new findings arrive.

The graph becomes a record of how the investigation developed—not just a place to store its latest answer.

### How Civicly uses FalkorDB during an investigation

Civicly’s AI workflow accesses graph information through MCP tools. In plain language, MCP provides a structured way for the AI to discover available tools and request specific information.

For example, Civicly can ask for related incidents, maintenance history or infrastructure dependencies. The tools run controlled queries against FalkorDB and return relevant records.

The AI then decides what to investigate next. FalkorDB supplies the connected evidence; it does not make the model’s decisions for it.

Civicly records the selected tool, its arguments, the returned evidence and the reason for the selection. Where recorded decision paths are available, the interface connects the question, graph results and subsequent decision.

This makes the investigation easier to inspect. A user can look beyond the final explanation and examine the evidence behind it.

### A road investigation that crossed departmental boundaries

The completed road demonstration shows why these connections matter. The case involved recurring road damage and an underlying utility connection. Reviewed synthetic road and utility inspections supplied evidence about leakage and subgrade damage. FalkorDB connected those findings with the affected assets, investigation history and relevant procedures. The response needed a clear order:

1.  Isolate the pipe safely.
    
2.  Repair the leak and independently verify the utility condition.
    
3.  Proceed with the road’s subgrade repair. FalkorDB stored the task dependencies, responsible departments, exact plan approval and resulting work orders. There was also an important limit: the AI reached its configured token budget before drafting the plan. An analyst prepared the cited plan using the investigation findings, and a human approved its exact scope. The demonstration preserves that distinction rather than presenting the entire lifecycle as autonomous. All physical work and field observations were explicitly synthetic. The AI calls, MCP execution, graph persistence and application workflow were real.
    

## Bringing municipal knowledge into the investigation

### Operational records are only part of the picture. Investigators also need procedures: who owns an action, what safety checks apply and what evidence is required afterward.

Civicly uses the **FalkorDB GraphRAG SDK** to ingest and retrieve municipal documents with source citations.

A simple way to understand this is as a reference library connected to the investigation. Civicly can retrieve a relevant procedure and show where it came from, instead of presenting an unsupported instruction.

The document graph is kept separate from the main operational graph. Information retrieved from a document does not automatically become a verified fact about the physical world.

That separation helps preserve the difference between “the procedure says this should happen” and “an inspection confirms this happened.”

### Remembering progress and past findings

Investigations can pause while waiting for evidence, human review or other dependencies. They can also be interrupted by restarts or resource limits.

Civicly uses **FalkorDBSaver** to persist its LangGraph workflow checkpoints. Think of a checkpoint as a saved place in the investigation, allowing the application to recover its recorded state.

Alongside those checkpoints, Civicly retains case history: findings, rejected explanations, reports, repairs and outcomes. Future investigations can retrieve that history rather than starting with an empty record.

This is persistent context, not a claim that the system automatically learns a reliable general rule from every completed case.

## Why completed work is not the same as a solved problem

A crew marking a task complete proves that work was reported as finished. It does not necessarily prove the recurring problem has stopped.

Civicly stores work progress separately from outcome evidence.

In the road demonstration, utility verification happened before road restoration. After the work orders were completed, the case entered monitoring. Separate synthetic exposure and pavement observations then supported the verified outcome.

FalkorDB kept those stages connected while preserving their different meanings: approved action, completed work and verified resolution.  

### Making the graph visible

FalkorDB was useful during development as well as inside the application.

**FalkorDB Browser** let me run queries, explore relationships visually and check whether the stored data matched expectations. Seeing an inspection connected to its evidence and affected asset made it easier to understand and debug the workflow.

Inside Civicly, **FalkorDB Canvas** displays evidence subgraphs alongside investigation details and recorded decisions. This gives users a visual way to explore the records behind a case.

The documentation, Python client and integrations with MCP, GraphRAG and LangGraph provided useful building blocks. There was still integration work to test—especially around permissions, persistence and package compatibility—but I did not have to build every component from scratch.

### What the prototype demonstrates

Civicly is a hackathon prototype operating in a synthetic city. It demonstrates investigations across three issue categories, with different cases reaching different stages. The completed road case shows the full assisted lifecycle; other retained cases include pending approval and token-budget pauses.

The most valuable contribution of FalkorDB is the shared structure underneath those workflows. It connects what was reported, what infrastructure is involved, what the evidence says, what people approved and what happened afterward.

For Civicly, that makes a recurring complaint the beginning of a traceable investigation—with its connections, uncertainty and history available to inspect.

Explore the project on [GitHub](https://github.com/krvikash05/Civicly) or visit the [AWS-hosted demo](https://civicly-13-55-205-208.sslip.io).
