LocalGov.AI - AI-Powered Civic Technology Platform

Overview

LocalGov.AI is a civic technology platform that makes local government information accessible by translating dense legal language into plain English. You ask a question about a local law, ordinance, or policy in your own words, and the app streams back an explanation in real time.

Problem Statement

Government policies and legal documents are usually written in jargon that most people can't parse. That puts a wall between citizens and the laws that actually affect their daily lives.

Solution

LocalGov.AI uses the Google Gemini 2.0 Flash API to turn dense legal text into plain language. Responses stream back as they're generated so you're not staring at a spinner. A caching layer makes repeated queries about 95% faster, and the answers are tailored to specific locations across 500+ cities.

Key Features

Version 2.0 - Latest Features

Streaming Responses (SSE)

• Real-time character-by-character AI responses using Server-Sent Events
• Immediate feedback instead of blocking waits
• Enhanced user experience with live updates

Smart Caching System

• 95% faster repeated queries with intelligent 1-hour TTL cache
• Custom ResponseCache class with automatic cleanup
• Cache key generation from query + location
• Background cleanup every 10 minutes

User Authentication & Personalization

• Secure PKCE (Proof Key for Code Exchange) authentication flow
• Supabase Auth with email verification
• Search history tracking with timestamps
• Bookmark system for saving important responses
• Account management with GDPR-compliant deletion

Location Intelligence

• 500+ city autocomplete suggestions
• Location-specific legal information
• Smart location detection

Modern UI/UX

• Toast notifications for all actions (success, error, info)
• Keyboard shortcuts (Cmd/Ctrl + K for quick search)
• Loading skeletons instead of spinners
• Dark/Light theme with system detection
• Markdown rendering for rich formatted responses
• Framer Motion animations for smooth transitions
• Mobile-first responsive design

Tech Stack

Frontend

• Next.js 14.2.35 - App Router with React Server Components
• TypeScript 5.8.3 - Strict mode for complete type safety
• React 18.2.0 - Latest component architecture
• Tailwind CSS 3.3.3 - Custom design system
• shadcn/ui + Radix UI - 50+ reusable components
• Framer Motion 12.16.0 - Smooth animations and transitions
• react-markdown - Beautiful formatted AI responses
• react-hook-form + Zod - Type-safe form validation
• Sonner - Modern toast notifications

Backend & Infrastructure

• Google Gemini 2.0 Flash - Advanced AI language model
• Supabase - PostgreSQL database with real-time updates
• Supabase Auth - PKCE authentication flow
• Vercel - Edge deployment with global CDN
• Server-Sent Events - Streaming response implementation

Technical Implementation

Streaming API Architecture

• Built custom /api/search endpoint with Server-Sent Events (SSE)
• Real-time response streaming using async generators
• Proper error handling and connection management
• Automatic response accumulation and storage

Advanced Caching System

• Custom ResponseCache class with Map-based storage
• Time-to-live (TTL) expiration set to 1 hour
• Intelligent cache key generation from query + location
• Background cleanup process every 10 minutes
• Returns cached responses as streams for consistency
• 95% performance improvement on repeated queries

Authentication & Database

• PKCE-based OAuth flow (most secure for client-side apps)
• Supabase PostgreSQL with real-time capabilities
• Auto-refresh token mechanism
• Session persistence with localStorage
• Protected routes with middleware session checking

Database Schema

-- Search History Table
CREATE TABLE search_history (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  query TEXT NOT NULL,
  location TEXT NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Bookmarks Table
CREATE TABLE bookmarks (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  title TEXT NOT NULL,
  query TEXT NOT NULL,
  location TEXT NOT NULL,
  content TEXT NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Middleware & Security

• Rate limiting: 30 requests per 60 seconds per IP
• IP-based tracking using x-forwarded-for headers
• Content Security Policy (CSP) for XSS protection
• GDPR-compliant account deletion with cascading data removal
• Data encryption in transit and at rest via Supabase

What I Learned

A few things I picked up building this:

• Streaming: Getting Server-Sent Events working for real-time data delivery
• Caching: Writing a custom cache with TTL and automatic cleanup
• Authentication: Implementing the PKCE flow for a client-side app
• AI Integration: Wiring up the Gemini API with context-aware prompting
• Component Architecture: Composing UI from shadcn/ui and Radix primitives
• Database Design: PostgreSQL schemas with proper foreign key relationships
• Performance: Code splitting, lazy loading, and edge deployment
• User Experience: Toast notifications, loading states, and keyboard shortcuts
• Security: Rate limiting, CSP headers, and GDPR compliance

Impact

LocalGov.AI puts government policy within reach of anyone, so people can understand their local laws and regulations without needing a lawyer.

Results:

• 95% Performance Improvement: Smart caching for repeated queries
• Real-Time Responses: Streaming SSE for immediate feedback
• 500+ Cities Supported: Location-specific legal information
• 50+ UI Components: Comprehensive component library
• PKCE Authentication: Bank-level security for user data
• GDPR Compliant: Complete data privacy and user control
• Production Ready: Deployed on Vercel with global edge distribution

Architecture Highlights

79 TypeScript/TSX Files organized in a clean, scalable structure:

• App Router with Next.js 14 for optimal routing
• 50+ shadcn/ui Components for consistent design
• Custom Hooks for logic separation
• API Routes for streaming search and auth callbacks
• Middleware for rate limiting and security
• TypeScript Strict Mode for complete type safety