A deep dive into building a full-stack, multi-agent AI platform that transforms fragmented community data into real-time, actionable decisions — powered by Gemini, RAG, WebSockets, and a clean Next.js + FastAPI architecture.

Repo: github.com/Yogendra1823/CommunityAI · Demo credentials: admin@community.ai / admin123 (admin) and citizen@community.ai / citizen123 (citizen)

Table of Contents

• The Problem Nobody Wants to Talk About

• The Idea: What Is CommunityAI?

• Project Vision

• A Visual Tour

• Architecture Overview

• Google AI at the Core

• Key Features

• Real-World Use Cases

• User Experience by Role

• Technical Stack and Why Each Choice Matters

• Engineering Challenges

• Lessons Learned

• Future Roadmap

• Impact

• Try It Yourself

• Conclusion

The Problem Nobody Wants to Talk About

It is 8:14 in the morning in a mid-sized city. A flooded intersection has just brought traffic on the main arterial road to a standstill. Three kilometers away, a sanitation crew is routing around an abandoned vehicle that has been reported four times in the last two weeks — but no one has connected those complaints into a single assignable task. A hospital across town is seeing an uptick in respiratory cases, but public health officials won't notice the trend until they compile their monthly report three weeks from now. Meanwhile, a citizen fires off a complaint through a mobile app — and receives an automated "your request has been received" message that means nothing and leads nowhere.

This is not a story about a broken city. This is Tuesday morning in most cities around the world.

The problem is not a lack of data. Cities today are drowning in it. Traffic sensors, citizen complaint portals, environmental monitoring networks, social media feeds, emergency dispatch logs, satellite imagery — it is all there. The problem is that it is fragmented, siloed, and disconnected from the people who need to act on it.

Traditional civic dashboards show you numbers. They tell you how many potholes were reported this month. What they don't do is tell you why the northwest quadrant is generating 300% more infrastructure complaints than average, what the likely cascade effect is if those reports go unaddressed for two weeks, or which five reports in today's queue should be escalated immediately because they represent a systemic infrastructure failure.

That gap — between data and decision — is where communities lose money, time, and ultimately, trust.

This is the problem I set out to solve.

The Idea: What Is CommunityAI?

CommunityAI is an AI-Powered Decision Intelligence Platform designed to close the gap between raw community data and smart, actionable decisions. It is not a ticketing system. It is not a simple dashboard. It is a full-stack, multi-agent AI application that ingests community issues in real time, applies intelligent triage, predicts patterns, coordinates workflows, and gives every stakeholder — from a citizen on the street to a government department head — the right information at the right time.

The core thesis is simple: communities should not need to wait for a human to connect the dots.

When a citizen submits a report with a photo of a cracked water pipe, CommunityAI immediately:

1. Analyzes the image using computer vision to confirm and categorize the issue

2. Assigns a severity score using AI triage

3. Generates a plain-language summary

4. Routes the report to the appropriate department

5. Triggers an intelligent agent to generate a resolution plan

6. Notifies the citizen when status changes — in real time

And all of this happens without a single manual step.

What makes CommunityAI different from existing tools is the intelligence layer. Every report is not just stored — it is understood. Every resolution is not just logged — it feeds future predictions. Every workflow is not just tracked — it is automated.

Project Vision

The immediate version of CommunityAI is built for community-scale deployment. But the architecture is designed to scale far beyond that.

Phase 1 — Community Layer (Current) Towns, residential communities, housing associations, and local NGOs deploying the platform to manage citizen-reported issues and coordinate response teams.

Phase 2 — Municipal Layer City governments adopting the platform to manage cross-departmental case workflows, predict infrastructure failure, and allocate maintenance budgets using AI forecasting.

Phase 3 — Regional Intelligence Network Multiple communities and municipalities sharing anonymized trend data, enabling regional-level pattern recognition — flood predictions, disease surveillance, supply chain disruption alerts.

Phase 4 — Nationwide Decision Intelligence A federated network of CommunityAI deployments, each operating independently but contributing to a national intelligence layer that can detect and respond to macro-level community crises before they become emergencies.

The long-term vision is a world where no community leader has to make a critical resource allocation decision without AI-assisted intelligence. Not because AI replaces human judgment, but because it gives humans better inputs to make faster, more confident decisions.

A Visual Tour

Screenshots from the running application, in the order a new user would encounter them.

Login — one-click demo access Standard email/password auth, plus one-click Admin and Citizen demo buttons so evaluators can explore without creating an account.

Executive dashboard — AI decision intelligence (admin) Real-time analytics, an AI categorization chart, a high-severity inbox, and critical alert counts, all powered by Gemini triage.

Moderation queue — admin workflow Every report arrives already triaged with a severity badge. Admins move cases to In Progress or Resolved, and each action fires a real-time WebSocket notification to the citizen.

Knowledge base — RAG document ingestion Admins paste in community guidelines and policies. The backend embeds them with text-embedding-004 into the pgvector store, instantly grounding the AI assistant.

Community reports — citizen view Citizens track every report they've filed, with location, live status badge, and date, fetched directly from the API.

Community feed — live issue tracking A public, real-time feed of every community issue, with filter tabs, severity scores, AI summaries, visual tags, and a stats bar showing live open/in-progress/resolved counts.

Report an issue — AI-powered submission Citizens submit a title, description, location, and optional photo. Gemini analyzes the image, categorizes the issue, and assigns a severity score automatically.

Settings — citizen profile management Account and security settings, with a role badge confirming permission level. All changes persist through the users API.

Architecture Overview

CommunityAI is built on a clean, layered architecture with clear separation of concerns between the presentation layer, application logic, AI processing, and data persistence.

The Data Flow

Every interaction in CommunityAI follows a deliberate pipeline:

1. Report Ingestion — A citizen submits a report (text + optional image) through the Next.js frontend.

2. AI Triage (synchronous) — The FastAPI backend immediately passes the report title, description, and image to the Gemini Flash model. The AI returns a structured JSON response: category, severity score (1–100), plain-language summary, and visual tags.

3. Persistence — The triaged report is saved to the PostgreSQL database hosted on NeonDB's serverless Postgres.

4. Real-Time Broadcast — A WebSocket manager broadcasts the new report to all connected admin clients instantly.

5. Background Agent (asynchronous) — A separate background task triggers the AI agent to generate a detailed resolution plan.

6. Status Updates — When an admin changes a report status, the backend fires another WebSocket event, and all citizen clients update their notification feeds live.

7. RAG Chat — When a user asks the AI assistant a question, the query is embedded, a vector similarity search finds the most relevant knowledge chunks, and Gemini synthesizes a grounded answer.

Database Design

The PostgreSQL schema is organized around five core entities:

Multi-tenancy is enforced at the database query level — every report query is filtered by community_id, ensuring complete data isolation between communities.

Google AI at the Core

CommunityAI is deeply integrated with Google's AI ecosystem. Here is an honest breakdown of what is implemented versus what is on the roadmap.

Implemented

Gemini Flash 2.5

The backbone of the AI triage system. Every report submission triggers a Gemini call with a carefully engineered prompt that requests structured JSON output:

def triage_report(title: str, description: str, image_base64: str = None) -> AITriageResult:
    client = genai.Client(api_key=settings.GEMINI_API_KEY)
    prompt = f"""
    Analyze the following community report.
    Title: {title}
    Description: {description}

    Categorize it into one of: Infrastructure, Sanitation, Safety, Utilities, Environment, Other.
    Assign a severity score from 1-100 (100 = life-threatening, 1 = minor).
    Provide a 1-sentence summary.
    Extract up to 5 visual tags if an image is provided.
    """

    response = client.models.generate_content(
        model='gemini-2.5-flash',
        contents=contents,
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            response_schema=AITriageResult,
            temperature=0.1,
        ),
    )
    return AITriageResult.model_validate_json(response.text)

The use of response_schema with a Pydantic model is a critical design choice. It forces Gemini to return structured, validated JSON rather than free-form text, eliminating an entire class of parsing errors.

Text Embeddings (text-embedding-004)

The RAG system uses Google's text embedding model to convert knowledge base documents and user queries into 768-dimensional vectors stored in PostgreSQL via the pgvector extension.

RAG Chat Pipeline

@router.post("/ask")
async def ask_question(req: AskRequest, db: AsyncSession, current_user: User):
    query_embedding = generate_embedding(req.query)

    result = await db.execute(
        select(KnowledgeChunk)
        .order_by(KnowledgeChunk.embedding.cosine_distance(query_embedding))
        .limit(3)
    )
    chunks = result.scalars().all()

    context = "\n\n".join([f"Source: {c.source}\nContent: {c.content}" for c in chunks])
    answer = ask_community_ai(req.query, context)
    return {"answer": answer, "sources": [...]}

Multi-Agent Background Workflows

When a new report is created, a FastAPI BackgroundTask triggers an AI agent that generates a resolution plan asynchronously — analyzing category, severity, location, and historical patterns to recommend specific resolution steps and timelines.

Planned Google AI Integrations

Key Features

1. Real-Time AI Triage

Why it exists: Human dispatchers cannot read and categorize 200 reports per day without errors and delays.

How it works: Every submitted report is immediately processed by Gemini Flash with a constrained prompt demanding four structured fields: category, severity (0–100), a one-line summary, and visual tags. Low temperature (0.1) ensures classification consistency.

User benefit: Citizens see their report acknowledged and categorized in seconds. Admins see a severity-ranked inbox instead of a flat chronological list.

2. Computer Vision Integration

Why it exists: "Water leak near building 4" is ambiguous. A photo with AI-extracted tags like ["burst pipe", "water pooling", "road damage"] is actionable.

How it works: If a citizen attaches an image, the base64-encoded file is passed to Gemini alongside the text prompt. Gemini's multimodal capabilities analyze the image and generate descriptive visual tags stored with the report.

User benefit: Admins filter reports by visual tags. The community feed displays thumbnails and tag clouds, making it instantly clear what each report represents.

3. Retrieval-Augmented Generation (RAG) AI Assistant

Why it exists: Generic AI chatbots hallucinate. A community AI assistant grounded in actual community guidelines and policies is far more valuable and trustworthy.

How it works: Admins ingest documents through a knowledge base interface. Each document is embedded with text-embedding-004 and stored in pgvector. When a citizen asks a question, the query is embedded, cosine similarity retrieves the three most relevant chunks, and Gemini synthesizes an answer grounded exclusively in that context. If the context doesn't contain the answer, the system prompt instructs Gemini to say so rather than guess.

User benefit: Citizens get accurate, source-attributed answers about community rules, service hours, and waste management guidelines — without calling an office or reading a 40-page PDF.

4. Real-Time Notifications via WebSockets

Why it exists: Polling an API every 30 seconds is wasteful and creates a terrible user experience. Community decisions need to be communicated instantly.

How it works: The FastAPI backend maintains a WebSocket connection manager. When a new report is submitted, manager.broadcast_json() fires a NEW_REPORT event to all connected clients. When an admin changes status to RESOLVED, a REPORT_UPDATED event is broadcast. The Header component listens on this WebSocket and dynamically adds notifications to the bell icon with an animated red dot and unread count.

User benefit: The moment an admin resolves a citizen's report, the citizen's notification bell lights up with a personalized message — without refreshing the page.

5. Predictive Analytics

Why it exists: Reactive government is expensive. Predicting that waste complaints will spike 40% next week lets you pre-position resources rather than scramble to respond.

How it works today: The backend computes a statistically plausible 7-day forecast based on current community issue volume with a controlled random walk model — establishing the data contract and API shape while the true ML forecasting model is developed.

How it will work: Historical time-series data stored in PostgreSQL will train a Vertex AI forecasting model accounting for day-of-week patterns, seasonal trends, and categorical breakdowns.

6. Role-Based Decision Intelligence Dashboard

Why it exists: A citizen needs to track their own reports. An admin needs the community-wide picture. These are fundamentally different needs, and serving both from a single view creates cognitive overload.

How it works: After authentication, the system checks the user's role and routes them to a completely distinct interface. The admin sees category distribution charts, high-severity alert inboxes, AI triage status, and forecast panels. The citizen sees personal report history, the community feed, and the AI assistant.

7. Workflow Automation — The Status Pipeline

Why it exists: Without a clear status pipeline, reports get lost. Citizens need to know their issue is being addressed, and admins need accountability.

How it works: Every report follows a four-state pipeline: OPEN → IN_PROGRESS → RESOLVED → CLOSED. Admins have two action buttons on open reports: Mark In Progress (acknowledges the issue, notifies the citizen) and Mark as Resolved (closes the loop, triggers a resolution notification). Status changes propagate via WebSockets to all relevant clients instantly.

Real-World Use Cases

Flood Prediction and Infrastructure Failure

The problem: A neighborhood submits increasing drainage-related complaints over three months. Individually each looks minor. Collectively they signal that the storm drain system is approaching failure.

How CommunityAI helps: The categorization engine tags all drainage reports as Infrastructure. The analytics layer detects the upward trend and surfaces an alert: "Drainage infrastructure complaints in Sector 3 have increased 280% over 60 days. High probability of storm drain failure before seasonal rainfall."

Expected outcome: The maintenance crew is dispatched proactively. The drain is cleared before the rains come, averting a flooded road and the associated economic disruption.

Waste Collection Optimization

The problem: Waste collection follows a fixed schedule regardless of actual accumulation. Some areas overflow on day 3. Others are collected on day 7 with bins only half-full.

How CommunityAI helps: Citizen reports of overflowing bins, tagged by sector and severity, create a real-time picture of collection demand. The analytics dashboard reveals which sectors consistently generate high-severity sanitation complaints before the scheduled window.

Expected outcome: Dynamic collection routing, 20–30% reduction in fuel costs, elimination of overflow incidents in high-density areas.

Healthcare Resource Planning

The problem: A local health officer notices an uptick in respiratory complaints from citizens in the eastern zone, but the connection to health service demand takes weeks to surface through traditional channels.

How CommunityAI helps: Environmental reports tagged air_quality and pollution trigger cross-referencing with historical health service request patterns. An AI agent generates an early warning: "Air quality complaints in the eastern zone have increased 60% over 14 days. Healthcare demand predicted to increase 25% in the next 10 days."

Expected outcome: Health officers pre-position mobile clinics and ensure adequate medication stock before demand spikes.

Emergency Response Coordination

The problem: During a crisis — earthquake, chemical spill, severe weather — emergency teams receive hundreds of reports simultaneously. Manually triaging them is too slow.

How CommunityAI helps: Every incoming report during a declared emergency is automatically triaged by Gemini. Reports with severity scores above 80 are instantly surfaced in the Emergency Response Team dashboard with AI-generated summaries and resolution plans.

Expected outcome: Emergency teams focus on the highest-impact interventions from the first minute of a crisis, rather than spending the first 30 minutes sorting through unstructured reports.

User Experience by Role

The Citizen

Maria opens the CommunityAI app and sees a live community feed showing dozens of active issues in her neighborhood, color-coded by category and severity. She taps "Report Issue," types a short description of a broken streetlight near the school crossing, and attaches a photo from her phone. Within seconds, the AI has categorized it as Safety, assigned a severity score, and generated a summary. She receives a notification when the admin moves it to In Progress, and another when it is resolved. The entire lifecycle is transparent, trackable, and communicated.

The Government Administrator

Raj opens his admin dashboard and sees a real-time picture of the community. The high-severity inbox shows reports requiring immediate attention. The category distribution chart reveals a spike in Utility complaints in the north zone this week. He clicks into the Moderation Queue, reviews the AI summary for each report, and begins moving critical ones to In Progress. When he marks one as Resolved, he knows the citizen has already been notified. The knowledge base interface lets him add a new waste management guideline that the AI assistant will immediately reference.

The Emergency Response Officer (roadmap role)

Priya monitors the CommunityAI dashboard during a severe weather event. The platform automatically elevates reports with flood-related tags. She can see a real-time count of affected areas, AI-generated resolution plans for each cluster of reports, and the resource allocation status across response teams — all without stale data, thanks to the WebSocket-powered live feed.

Here's how those three journeys compare at a glance:

Technical Stack and Why Each Choice Matters

Key Trade-Off Discussions

Why FastAPI over Django or Express? FastAPI's async architecture is a natural fit for AI workloads where you are making concurrent calls to external APIs. Every report ingestion involves an I/O-bound Gemini call — async handling means the server processes multiple submissions simultaneously without blocking. Django's synchronous ORM would create a bottleneck at scale.

Why pgvector over Pinecone or Weaviate? For community-scale deployment, a specialized vector database adds unnecessary infrastructure complexity. pgvector runs inside the same PostgreSQL instance — no additional service to deploy, manage, or pay for. At thousands of embeddings, cosine similarity performance is excellent. Only at hundreds of thousands of embeddings would migration to a dedicated vector store be justified.

Why NeonDB? Serverless Postgres with database branching is a productivity game-changer. You can branch the database like a Git branch, test schema migrations without touching production, and the serverless autoscaling means zero cost during idle periods.

Engineering Challenges

Challenge 1: Clean Role-Based Architecture Without Over-Engineering

The temptation in building a multi-role platform is to create an elaborate permission matrix from day one. The practical reality for an MVP is that you need role separation — but not a full RBAC framework with dynamic permissions.

Solution: A simple role.name check at the API level, combined with conditional sidebar rendering on the frontend. The check is intentionally placed in the API layer (not just the UI), so a tech-savvy citizen cannot bypass UI restrictions to call admin APIs. Adding a new role is a database record and a few conditional blocks — not a refactor.

Challenge 2: Structuring AI Output for Reliability

Free-form LLM output is unpredictable. If you ask Gemini to "categorize this report," you might get "Infrastructure", "INFRASTRUCTURE", "infrastructure issue", or "This report appears to relate to infrastructure." All semantically identical — all potentially breaking downstream logic.

Solution: Using Gemini's response_schema parameter with a Pydantic model enforces strict structured output. The model returns exactly the fields defined in the schema with the exact types specified. Temperature 0.1 — as close to deterministic as LLM output gets. This eliminated an entire class of parsing bugs.

Challenge 3: Real-Time Updates at Community Scale

WebSockets require careful lifecycle management. In a Next.js App Router environment with React Server Components, managing WebSocket connections across client components requires deliberate architecture.

Solution: WebSocket connections are opened in useEffect hooks in client components, with proper cleanup on unmount. The backend WebSocket manager uses an asyncio.Lock() to prevent race conditions during broadcast to multiple concurrent connections. The connection is deliberately simple — no rooms, no namespacing — because community-scale deployments don't require Socket.io-style event bus complexity.

Challenge 4: Managing AI Context and Reducing Hallucinations

Early versions of the AI chat assistant had a hallucination problem. Without grounding, Gemini would confidently answer questions about community policies using generic knowledge rather than actual community-specific rules.

Solution: The RAG pipeline is strictly grounded — the system prompt explicitly instructs Gemini to answer only from the provided context and to respond with "I cannot answer this based on the provided guidelines" if the context is insufficient. Only admin-verified community documents enter the vector store.

Challenge 5: Seeding Realistic Test Data

Demo quality matters. Two reports look like a toy. Twenty-five varied, realistic, time-scattered reports across different categories and statuses look like a real platform.

Solution: A Python seed script (scripts/seed_mock_reports.py) connects to the database, locates the admin user's community ID, and inserts 25 reports with randomized categories, severities, statuses, locations, and creation timestamps scattered across the past 30 days. Scattered timestamps make analytics charts meaningful.

Lessons Learned

On AI Integration: Structured AI output is not optional — it is a prerequisite for production reliability. The moment you stop using response_schema or its equivalent, you introduce a failure mode that will manifest at the worst possible time.

On System Design: Designing for role separation early — even when the MVP only has two roles — saves enormous refactoring effort later. The cost of adding a third role to a well-structured system is a database record and a sidebar menu entry. The cost of retrofitting roles into an unstructured system is a rewrite.

On Real-Time Systems: WebSockets feel like magic when they work. The engineering discipline required — proper cleanup, error handling, reconnection logic — is significant. Start simple, and only add complexity when the simple version demonstrably breaks.

On RAG Quality: The quality of a RAG system is determined entirely by the quality of the knowledge base. An empty knowledge base produces a useless assistant. The admin knowledge ingestion interface is not a secondary feature — it is a core part of the product.

On Demo vs. Production: A hackathon MVP must be honest about what is implemented versus what is simulated. The 7-day forecast in the current version is a statistically plausible simulation, not a trained ML model. Labeling it clearly maintains credibility while demonstrating the product's potential.

Future Roadmap

The long-term vision stays the same: a world where no community leader has to make a critical resource allocation decision without AI-assisted intelligence.

Impact

The equity dimension deserves special emphasis. Traditional complaint systems, whether intentionally or not, often prioritize reports from more vocal or well-connected community members. An AI triage system that assigns severity based purely on the content and context of the report — not the identity of the reporter — creates a more equitable response system by design.

Try It Yourself

The full source is on GitHub, along with setup instructions for Docker Compose, manual installation, and configuration: github.com/Yogendra1823/CommunityAI

The repo ships with 25 pre-seeded, realistic community reports so you can explore the full platform immediately:

Conclusion

CommunityAI started as an answer to a question I kept asking: Why is it so hard for a community to act on what it already knows?

The technology to solve this problem exists. Gemini can triage and categorize any report in seconds. WebSockets can deliver real-time updates to thousands of citizens instantly. RAG can give community members accurate, grounded answers without a call center. PostgreSQL with pgvector can power a capable knowledge retrieval system without a dedicated vector database.

What was missing was the integration — the architectural thinking to bind these capabilities together into a coherent, role-aware, real-time platform that serves everyone from a rural citizen reporting a pothole to a city official allocating infrastructure budgets.

That is what CommunityAI represents. Not a finished product, but a proof of what is possible when you take AI seriously as a decision-support layer rather than a novelty feature.

The communities that will thrive in the next decade are not necessarily the ones with the most data. They are the ones that learn to think with their data — to connect the dots between a citizen's morning complaint and a systemic infrastructure failure, between a cluster of environmental reports and a public health crisis, between today's resource allocation and next month's service demand.

Decision intelligence is not a luxury. It is an infrastructure investment. And it is now possible for any community — not just wealthy cities with multi-million-dollar IT budgets — to access it.

If you are a developer, explore the codebase, star the repo, and help extend the platform to new use cases and new communities: github.com/Yogendra1823/CommunityAI

If you are a city official, urban planner, or community leader, I invite you to imagine what your work would look like with this kind of intelligence at your fingertips.

Let's build smarter communities — together.

Social copy

LinkedIn

CommunityAI is an AI-Powered Decision Intelligence Platform I built to close the gap between fragmented community data and real-time actionable decisions. It uses Google Gemini for multimodal triage, RAG with pgvector for a grounded AI assistant, WebSockets for live updates, and a clean FastAPI + Next.js architecture. Full write-up, screenshots, and architecture breakdown below — code is open source.

🔗 github.com/Yogendra1823/CommunityAI

#AI #GoogleAI #Gemini #SmartCities #RAG #FastAPI #NextJS #BuildWithGemini

Dev.to / Hashnode

What happens when you combine Google Gemini, Retrieval-Augmented Generation, WebSocket real-time streams, and a multi-agent AI backend with a modern Next.js frontend? You get CommunityAI — a decision intelligence platform that turns citizen reports into coordinated, AI-triaged, live-tracked community action. Complete architecture walkthrough, engineering trade-offs, and the open-source repo inside.

CommunityAI was built for the Google Meet the Builders Hackathon. Source, screenshots, and setup instructions: github.com/Yogendra1823/CommunityAI