# princeraj-in/city-helpline architecture

> Architecture diagram of the GitHub repository princeraj-in/city-helpline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/princeraj-in/city-helpline
- Repository: https://github.com/princeraj-in/city-helpline

## Overview

City Helpline is a student-focused local-services platform. The main journey is choosing or detecting a city, discovering and filtering housing and other student services, then viewing a listing; users can also sign in to save listings or contribute services. Separate capabilities include budget planning, peer-to-peer sales, roommate matching, emergency guidance, AI assistance, and role-based administration. The graph uses README descriptions for major capabilities and sampled code for location syncing, image uploads, and AI requests; unsampled feature wiring is not inferred.

Main entry points: [`src/App.tsx`](https://github.com/princeraj-in/city-helpline/blob/main/src/App.tsx) (App routing), [`src/pages/BudgetCalculator.tsx`](https://github.com/princeraj-in/city-helpline/blob/main/src/pages/BudgetCalculator.tsx) (Budget estimator), [`src/services/aiChatService.ts`](https://github.com/princeraj-in/city-helpline/blob/main/src/services/aiChatService.ts) (AI assistant), [`src/contexts/LocationContext.tsx`](https://github.com/princeraj-in/city-helpline/blob/main/src/contexts/LocationContext.tsx) (Location state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Student experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_discovery["Service discovery<br/>[Search.tsx]"]
  node_listing["Listing details<br/>[ListingDetails.tsx]"]
  node_authoring["Service listings<br/>[AddListing.tsx]"]
  node_budget["Budget estimator"]
  node_marketplace["Student marketplace<br/>[Marketplace.tsx]"]
  node_marketplacepost["Sell item<br/>[SellItem.tsx]"]
  node_roommates["Roommate finder<br/>[RoommatesPage.tsx]"]
  node_ai["AI assistant<br/>[aiChatService.ts]"]
  node_airesult["AI response"]
end

subgraph group_accounts["Identity and location"]
  node_auth["Authentication state<br/>[AuthContext.tsx]"]
  node_location["Location state"]
  node_locationservice["Geolocation tools<br/>[locationService.ts]"]
end

subgraph group_services["Student services"]
  node_roommateservice["Roommate data service<br/>[roommateService.ts]"]
  node_benchmarks["City benchmarks"]
end

subgraph group_operations["Platform operations"]
  node_upload["Image upload<br/>[storage.ts]"]
  node_admin["Admin console<br/>[AdminDashboard.tsx]"]
  node_server["Chat API<br/>[server.ts]"]
end

subgraph group_external["External services"]
  node_firebase["Firebase SDK<br/>[firebase.ts]"]
  node_firestore[("Firestore")]
  node_firebaseauth["Firebase Auth"]
  node_cloudinary["Cloudinary CDN"]
  node_gemini["Gemini AI"]
end

node_student(("Student"))

node_student -->|"opens"| node_app
node_app -->|"routes to"| node_discovery
node_app -->|"routes to"| node_listing
node_app -->|"routes to"| node_budget
node_app -->|"routes to"| node_marketplace
node_app -->|"routes to"| node_roommates
node_app -->|"routes to"| node_admin
node_student -->|"sets location"| node_location
node_location -->|"requests coordinates"| node_locationservice
node_location -->|"updates profile"| node_firebase
node_auth -->|"uses SDK"| node_firebase
node_firebase -->|"authenticates"| node_firebaseauth
node_discovery -->|"queries listings"| node_firestore
node_listing -->|"reads listing"| node_firestore
node_authoring -->|"writes listing"| node_firestore
node_marketplace -->|"reads items"| node_firestore
node_marketplacepost -->|"writes item"| node_firestore
node_budget -->|"uses costs"| node_benchmarks
node_budget -->|"loads services"| node_firestore
node_roommates -->|"requests profiles"| node_roommateservice
node_roommateservice -->|"reads and writes"| node_firestore
node_authoring -.->|"uploads images"| node_upload
node_marketplacepost -.->|"uploads images"| node_upload
node_upload -->|"uploads image"| node_cloudinary
node_student -->|"asks question"| node_ai
node_ai -->|"posts chat"| node_server
node_server -->|"requests generation"| node_gemini
node_ai -->|"renders reply"| node_airesult
node_admin -->|"manages records"| node_firestore

click node_app "https://github.com/princeraj-in/city-helpline/blob/main/src/App.tsx"
click node_discovery "https://github.com/princeraj-in/city-helpline/blob/main/src/pages/Search.tsx"
click node_listing "https://github.com/princeraj-in/city-helpline/blob/main/src/pages/ListingDetails.tsx"
click node_authoring "https://github.com/princeraj-in/city-helpline/blob/main/src/pages/AddListing.tsx"
click node_budget "https://github.com/princeraj-in/city-helpline/blob/main/src/pages/BudgetCalculator.tsx"
click node_marketplace "https://github.com/princeraj-in/city-helpline/blob/main/src/pages/Marketplace.tsx"
click node_marketplacepost "https://github.com/princeraj-in/city-helpline/blob/main/src/pages/SellItem.tsx"
click node_roommates "https://github.com/princeraj-in/city-helpline/blob/main/src/pages/RoommatesPage.tsx"
click node_ai "https://github.com/princeraj-in/city-helpline/blob/main/src/services/aiChatService.ts"
click node_auth "https://github.com/princeraj-in/city-helpline/blob/main/src/contexts/AuthContext.tsx"
click node_location "https://github.com/princeraj-in/city-helpline/blob/main/src/contexts/LocationContext.tsx"
click node_locationservice "https://github.com/princeraj-in/city-helpline/blob/main/src/lib/locationService.ts"
click node_firebase "https://github.com/princeraj-in/city-helpline/blob/main/src/lib/firebase.ts"
click node_roommateservice "https://github.com/princeraj-in/city-helpline/blob/main/src/lib/roommateService.ts"
click node_benchmarks "https://github.com/princeraj-in/city-helpline/blob/main/src/lib/budgetBenchmarks.ts"
click node_upload "https://github.com/princeraj-in/city-helpline/blob/main/src/lib/storage.ts"
click node_admin "https://github.com/princeraj-in/city-helpline/blob/main/src/pages/AdminDashboard.tsx"
click node_server "https://github.com/princeraj-in/city-helpline/blob/main/server.ts"
click node_airesult "https://github.com/princeraj-in/city-helpline/blob/main/src/components/ai/AiMessageRenderer.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_discovery,node_listing,node_authoring,node_budget,node_marketplace,node_marketplacepost,node_roommates,node_ai,node_airesult toneBlue
class node_auth,node_location,node_locationservice toneAmber
class node_roommateservice,node_benchmarks toneMint
class node_upload,node_admin,node_server toneRose
class node_firebase,node_firestore,node_firebaseauth,node_cloudinary,node_gemini,node_student toneIndigo
```

## Components

### Student experience

- [App routing](https://github.com/princeraj-in/city-helpline/blob/main/src/App.tsx): `src/App.tsx`
- [Service discovery](https://github.com/princeraj-in/city-helpline/blob/main/src/pages/Search.tsx): `src/pages/Search.tsx`
- [Listing details](https://github.com/princeraj-in/city-helpline/blob/main/src/pages/ListingDetails.tsx): `src/pages/ListingDetails.tsx`
- [Service listings](https://github.com/princeraj-in/city-helpline/blob/main/src/pages/AddListing.tsx): `src/pages/AddListing.tsx`
- [Budget estimator](https://github.com/princeraj-in/city-helpline/blob/main/src/pages/BudgetCalculator.tsx): `src/pages/BudgetCalculator.tsx`
- [Student marketplace](https://github.com/princeraj-in/city-helpline/blob/main/src/pages/Marketplace.tsx): `src/pages/Marketplace.tsx`
- [Sell item](https://github.com/princeraj-in/city-helpline/blob/main/src/pages/SellItem.tsx): `src/pages/SellItem.tsx`
- [Roommate finder](https://github.com/princeraj-in/city-helpline/blob/main/src/pages/RoommatesPage.tsx): `src/pages/RoommatesPage.tsx`
- [AI assistant](https://github.com/princeraj-in/city-helpline/blob/main/src/services/aiChatService.ts): `src/services/aiChatService.ts`
- [AI response](https://github.com/princeraj-in/city-helpline/blob/main/src/components/ai/AiMessageRenderer.tsx): `src/components/ai/AiMessageRenderer.tsx`

### Identity and location

- [Authentication state](https://github.com/princeraj-in/city-helpline/blob/main/src/contexts/AuthContext.tsx): `src/contexts/AuthContext.tsx`
- [Location state](https://github.com/princeraj-in/city-helpline/blob/main/src/contexts/LocationContext.tsx): `src/contexts/LocationContext.tsx`
- [Geolocation tools](https://github.com/princeraj-in/city-helpline/blob/main/src/lib/locationService.ts): `src/lib/locationService.ts`

### Student services

- [Roommate data service](https://github.com/princeraj-in/city-helpline/blob/main/src/lib/roommateService.ts): `src/lib/roommateService.ts`
- [City benchmarks](https://github.com/princeraj-in/city-helpline/blob/main/src/lib/budgetBenchmarks.ts): `src/lib/budgetBenchmarks.ts`

### Platform operations

- [Image upload](https://github.com/princeraj-in/city-helpline/blob/main/src/lib/storage.ts): `src/lib/storage.ts`
- [Admin console](https://github.com/princeraj-in/city-helpline/blob/main/src/pages/AdminDashboard.tsx): `src/pages/AdminDashboard.tsx`
- [Chat API](https://github.com/princeraj-in/city-helpline/blob/main/server.ts): `server.ts`

### External services

- [Firebase SDK](https://github.com/princeraj-in/city-helpline/blob/main/src/lib/firebase.ts): `src/lib/firebase.ts`
- **Firestore**
- **Firebase Auth**
- **Cloudinary CDN**
- **Gemini AI**

### Other components

- **Student**

## Connections

- Student → App routing: opens
- App routing → Service discovery: routes to
- App routing → Listing details: routes to
- App routing → Budget estimator: routes to
- App routing → Student marketplace: routes to
- App routing → Roommate finder: routes to
- App routing → Admin console: routes to
- Student → Location state: sets location
- Location state → Geolocation tools: requests coordinates
- Location state → Firebase SDK: updates profile
- Authentication state → Firebase SDK: uses SDK
- Firebase SDK → Firebase Auth: authenticates
- Service discovery → Firestore: queries listings
- Listing details → Firestore: reads listing
- Service listings → Firestore: writes listing
- Student marketplace → Firestore: reads items
- Sell item → Firestore: writes item
- Budget estimator → City benchmarks: uses costs
- Budget estimator → Firestore: loads services
- Roommate finder → Roommate data service: requests profiles
- Roommate data service → Firestore: reads and writes
- Service listings → Image upload: uploads images
- Sell item → Image upload: uploads images
- Image upload → Cloudinary CDN: uploads image
- Student → AI assistant: asks question
- AI assistant → Chat API: posts chat
- Chat API → Gemini AI: requests generation
- AI assistant → AI response: renders reply
- Admin console → Firestore: manages records