# ritabrata777/civiclens architecture

> Architecture diagram of the GitHub repository ritabrata777/civiclens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ritabrata777/civiclens
- Repository: https://github.com/ritabrata777/civiclens

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        Browser["User Browser"]:::external
        Pages["Pages & Layout"]:::frontend
        Components["Shared Components"]:::frontend
    end
    Browser -->|"HTTP/HTTPS"| Pages
    Pages -->|"renders"| Components
    click Pages "https://github.com/ritabrata777/civiclens/tree/main/src/app/"
    click Components "https://github.com/ritabrata777/civiclens/tree/main/src/components/"

    subgraph "Application Layer"
        Server["Next.js Server Actions & Controllers"]:::backend
        API["API Route: /api/verify-voter"]:::backend
        ChildProc["child_process"]:::backend
    end
    Pages -->|"Server Actions"| Server
    Server -->|"CRUD & Auth"| API
    Server -->|"spawns"| ChildProc
    click Server "https://github.com/ritabrata777/civiclens/blob/main/src/server/actions.ts"
    click API "https://github.com/ritabrata777/civiclens/blob/main/src/app/api/verify-voter/route.ts"

    subgraph "AI Microservices"
        direction TB
        Duplicate["Duplicate Detection"]:::ai
        Violation["Violation Detection"]:::ai
        OCR["Voter-ID OCR"]:::ai
        AIMS["Python Microservice Entry"]:::ai
    end
    ChildProc -->|"detect"| Duplicate
    ChildProc -->|"detect"| Violation
    ChildProc -->|"verify"| OCR
    AIMS --> Duplicate
    AIMS --> Violation
    AIMS --> OCR
    click AIMS "https://github.com/ritabrata777/civiclens/blob/main/python_backend/app.py"
    click Duplicate "https://github.com/ritabrata777/civiclens/blob/main/python_backend/detect_duplicates_logic.py"
    click Violation "https://github.com/ritabrata777/civiclens/blob/main/python_backend/detect_violation_logic.py"
    click OCR "https://github.com/ritabrata777/civiclens/blob/main/python_backend/verify_voter_logic.py"

    subgraph "Data & Persistence Layer"
        DB["SQLite Database"]:::db
    end
    Server -->|"SQL Read/Write"| DB
    click DB "https://github.com/ritabrata777/civiclens/blob/main/src/lib/db.ts"

    subgraph "Blockchain & Smart Contracts"
        Contracts["Solidity Contracts"]:::blockchain
        Hardhat["Hardhat Config & Deploy"]:::blockchain
        Web3["Ethers.js Integration"]:::blockchain
        Node["Blockchain Node"]:::blockchain
    end
    Server -->|"Ethers.js RPC"| Web3
    Web3 -->|"JSON-RPC"| Node
    Hardhat -->|"deploys"| Node
    click Contracts "https://github.com/ritabrata777/civiclens/tree/main/contracts/"
    click Hardhat "https://github.com/ritabrata777/civiclens/blob/main/hardhat.config.cjs"
    click Web3 "https://github.com/ritabrata777/civiclens/blob/main/src/lib/web3.ts"

    subgraph "Static & Cached Assets"
        Models["ML Model Weights"]:::static
        Cache["Solidity ABI Cache"]:::static
        Public["Public Assets"]:::static
    end
    AIMS --> Models
    Server --> Public
    click Models "https://github.com/ritabrata777/civiclens/blob/main/ml/models/yolov8n.pt"
    click Cache "https://github.com/ritabrata777/civiclens/blob/main/cache/solidity-files-cache.json"
    click Public "https://github.com/ritabrata777/civiclens/tree/main/public/"

    classDef frontend fill:#cce5ff,stroke:#66b2ff;
    classDef backend fill:#d4edda,stroke:#28a745;
    classDef ai fill:#e2d6f5,stroke:#7d3cff,shape:hexagon;
    classDef db fill:#fff3cd,stroke:#ffecb5,shape:cylinder;
    classDef blockchain fill:#fff0b3,stroke:#ffcc00,shape:cylinder;
    classDef static fill:#e2e3e5,stroke:#d6d8db;
    classDef external fill:#f8f9fa,stroke:#ced4da;
```
