How ritabrata777/civiclens works
Project type and purpose
• Civic Lens is a full-stack, web-based civic grievance redressal platform.
• Frontend & backend tightly integrated via Next.js App Router and Server Actions.
• Integrates AI microservices (Python) for image/text analysis, a relational database (SQLite), and blockchain (Ethereum/Polygon) for immutable audit trails.
File structure
• Top-level directories:
• src/app, src/components, src/frontend, src/lib, src/hooks – Next.js UI and business code
• python_backend & ml/scripts – Python microservices for AI tasks
• contracts, scripts, hardhat.config.* – Smart contract development and deployment
• src/db, scripts/*.js – Database models (SQLite via better-sqlite3) and migration/seed scripts
• public, files, cache – Static assets, documentation, cached ML models
• Configuration: next.config.ts, tailwind.config.ts, hardhat.config.cjs/cts, Dockerfile in python_backend.
• Build/deploy: Vercel ignore, package.json, Docker for Python.
README for technical insights
• Next.js 15 + TypeScript + Tailwind + Shadcn/UI
• Python scripts use sentence-transformers, imagehash, OpenCV
• Smart contracts in Solidity via Hardhat; Ethers.js for interaction
• DB: SQLite for local relational store
• Child processes used to invoke Python from Node.js
Main components
a. Frontend (Next.js App)
• Pages and components under src/app and src/components
• Client-side interactions, forms (login, report issue), maps, image lightbox
b. Backend (Next.js Server Actions & API Routes)
• Server Actions for account creation, issue CRUD
• API route /api/verify-voter invoking Python microservice
c. AI Microservices
• Python processes for:
• Duplicate detection (BERT + perceptual hashing)
• Violation detection (YOLO)
• Voter-ID OCR
• Invoked via child_process from Node.js (ml/scripts & python_backend/app.py)
d. Database
• SQLite accessed via better-sqlite3 (src/lib/db.ts)
• Tables: User, Issue, Transaction (blockchain log)
e. Blockchain Node
• Local Ganache or Polygon Amoy Testnet
• Smart contracts (contracts/) compiled/deployed via Hardhat
• Ethers.js in Next.js to submit and read transactions
f. Static & Cached Assets
• ML model weights (yolov8n.pt) in ml/models and python_backend
• Cached JSON files for Solidity ABI, dataset, placeholder images
Relationships and data flows
• User browser ⇄ Next.js front end (UI components)
• Next.js server actions ↔ SQLite for read/write operations
• Next.js ⇄ Python microservice
• Issue creation or image upload triggers child_process → Python script → returns analysis result
• Next.js ⇄ Blockchain node via Ethers.js
• Admin actions hashed → transaction → blockchain
• Frontend reads transaction history for audit log
• Static file store (public/) serves images, before/after comparisons
Architectural patterns & design principles
• Monolithic full-stack with integrated serverless functions (Next.js server actions)
• Microservice pattern for AI tasks (isolated Python services)
• Event sourcing / immutable log in blockchain (append-only)
• MVC-like separation: Next.js pages (V) ↔ server actions/controllers (C) ↔ SQLite models (M)
• Child-process integration for heterogeneous tech stacks