# alfishanshaikh/crowdlens-ai architecture

> Architecture diagram of the GitHub repository alfishanshaikh/crowdlens-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alfishanshaikh/crowdlens-ai
- Repository: https://github.com/alfishanshaikh/crowdlens-ai

## Overview

##### Project Type and Purpose
- This is a **prototype, single-page web application** (SPA) built in **React + TypeScript**, focused on AI-powered civic issue reporting.
- Although the README mentions a Node/Express backend and AI agents (qRaptor), the repository currently contains only the **frontend**. The frontend calls out to external services (AI orchestration, geolocation, municipal APIs).

##### File Structure
Top-level files & folders:
- package.json, tsconfig*.json, vite.config.ts → build & tooling (Vite + TS)
- public/ → static assets & index.html
- src/ → core React source code
‑ components/ → reusable UI pieces (Header, Footer, FAQ)
‑ pages/ → SPA routes (Home, ReportIssue, ViewReports, AdminDashboard, About)
‑ context/ → React Context providers (AuthContext, ReportsContext)
‑ App.tsx & main.tsx → entry points, router setup, context wrappers
‑ index.css, tailwind.config.js, postcss.config.js → styling

##### Key Insights from the README
- **User Flow**: Photo upload → AI Vision → Geo-context → Report drafting → Submission → Notifications → Status dashboard
- **External Services**:
- qRaptor Agentic AI (Vision, Geo, Drafting, Notification agents)
- GPS/location service (browser geolocation API)
- Municipal department endpoints (REST or webhook)
- **UI Features**: One-tap reporting, live status tracking, admin dashboard

##### Main Components
a. **User Client (Browser/Mobile Browser)**
– React SPA (Vite + TS)
– Pages & Components
– Context providers for Auth & Report state
b. **Frontend Service Layer**
– API module (e.g., src/services) to call:
- qRaptor AI orchestration endpoint
- Geolocation API (built-in browser)
- Municipal submission API
- Notification/WebSocket or polling endpoint
c. **AI Orchestration Layer (qRaptor)**
– Image Analysis Agent
– Geo-Context Agent
– Complaint Drafting Agent
– Notification Agent
– Central orchestrator that sequences agents
d. **Municipal Backend**
– Department-specific REST endpoint
– Acknowledgment & status callbacks (webhooks or polling)
e. **Data Store (Optional / Future)**
– User reports, status logs (could be Firebase, MongoDB, SQL)
f. **Admin Dashboard**
– Same SPA, different route with elevated privileges
– Fetches aggregate reports & status

##### Relationships & Data Flows
1. User snaps photo & clicks “Report Issue”
2. SPA uploads image + auto-captured GPS to **Frontend Service Layer**
3. Service Layer forwards payload to **qRaptor Orchestrator**
4. qRaptor invokes each AI Agent in sequence (Vision → Geo → Draft → Notify)
5. Orchestrator sends the formatted complaint to **Municipal Backend**
6. Municipal Backend returns acknowledgment
7. Notification Agent pushes status back to the SPA (via WebSocket or polling)
8. SPA updates **ReportsContext** → re-renders **ViewReports/AdminDashboard**

##### Architectural Patterns & Design Principles
- **Component-Based UI**: React + Tailwind CSS for modularity
- **Context API**: Global state for auth & reports, avoiding prop-drilling
- **Service Abstraction**: Encapsulate external calls in a services layer
- **Separation of Concerns**: UI vs. orchestration vs. persistence
- **Single Source of Truth**: ReportsContext holds live complaint data

##### Technologies & Frameworks to Annotate
- React.js, TypeScript, Vite (frontend)
- Tailwind CSS (styling)
- Browser Geolocation API
- qRaptor Agentic AI (external orchestration + agents)
- Node.js/Express (implied backend – could be stubbed or future)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% React SPA Layer
    subgraph "React SPA"
        direction TB
        Main["main.tsx"]:::frontend
        App["App.tsx"]:::frontend
        subgraph "Context Providers"
            AuthCtx["AuthContext"]:::frontend
            ReportsCtx["ReportsContext"]:::frontend
        end
        subgraph "UI Components"
            Header["Header"]:::frontend
            Footer["Footer"]:::frontend
            FAQ["FAQ"]:::frontend
        end
        subgraph "Pages / Routes"
            Home["Home Page"]:::frontend
            ReportIssue["ReportIssue Page"]:::frontend
            ViewReports["ViewReports Page"]:::frontend
            AdminDashboard["AdminDashboard Page"]:::frontend
            About["About Page"]:::frontend
        end
    end

    %% Frontend Service Layer
    subgraph "Frontend Service Layer"
        direction TB
        GeoAPI["Browser Geolocation API"]:::service
        QAAPI["qRaptor Orchestrator Endpoint"]:::service
        MunicipalAPI["Municipal Submission API"]:::service
        NotificationAPI["Notification Endpoint"]:::service
    end

    %% AI Orchestration Layer
    subgraph "qRaptor AI Platform"
        direction TB
        Orchestrator["Central Orchestrator"]:::ai
        VisionAgent["Vision Agent"]:::ai
        GeoAgent["Geo-Context Agent"]:::ai
        DraftAgent["Drafting Agent"]:::ai
        NotifyAgent["Notification Agent"]:::ai
    end

    %% Municipal Backend
    MunicipalBE["Municipal Backend"]:::external

    %% Future Data Store
    ExternalDB["(Future) Data Store"]:::datastore

    %% Data Flows
    Main --> App
    App --> AuthCtx
    App --> ReportsCtx
    App --> Home
    App --> ReportIssue
    App --> ViewReports
    App --> AdminDashboard
    App --> About

    ReportIssue -->|"get location"| GeoAPI
    ReportIssue -->|"submit report"| QAAPI
    GeoAPI -->|"location data"| QAAPI

    QAAPI --> Orchestrator
    Orchestrator --> VisionAgent
    VisionAgent --> GeoAgent
    GeoAgent --> DraftAgent
    DraftAgent --> NotifyAgent
    NotifyAgent -->|"send complaint"| MunicipalAPI

    MunicipalAPI --> MunicipalBE
    MunicipalBE -->|"acknowledgment & status"| NotifyAgent

    NotifyAgent -->|"push status"| NotificationAPI
    NotificationAPI --> ViewReports
    NotificationAPI --> AdminDashboard

    ViewReports --> ReportsCtx
    AdminDashboard --> ReportsCtx

    Orchestrator --> ExternalDB

    %% Click Events
    click Main "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/main.tsx"
    click App "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/App.tsx"
    click Header "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/components/Header.tsx"
    click Footer "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/components/Footer.tsx"
    click FAQ "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/components/FAQ.tsx"
    click Home "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/pages/Home.tsx"
    click ReportIssue "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/pages/ReportIssue.tsx"
    click ViewReports "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/pages/ViewReports.tsx"
    click AdminDashboard "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/pages/AdminDashboard.tsx"
    click About "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/pages/About.tsx"
    click AuthCtx "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/context/AuthContext.tsx"
    click ReportsCtx "https://github.com/alfishanshaikh/crowdlens-ai/blob/main/src/context/ReportsContext.tsx"

    %% Styling
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef service fill:#f0f0f0,stroke:#666666,color:#333333,stroke-width:1px;
    classDef ai fill:#e2ccff,stroke:#6600cc,color:#6600cc,stroke-width:1px;
    classDef external fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef datastore fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
```
