How alfishanshaikh/crowdlens-ai works
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)