# suneetbafna83-ship-it/civicresolver architecture

> Architecture diagram of the GitHub repository suneetbafna83-ship-it/civicresolver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suneetbafna83-ship-it/civicresolver
- Repository: https://github.com/suneetbafna83-ship-it/civicresolver

## Overview

CivicResolve supports citizen issue reporting and tracking alongside municipal, department-scoped dispatch. The main flow runs from the portal and report UI through server-side triage, then persists issues for citizen and admin workflows. The README also documents maps, authentication, resilient local storage, exports, localization, and repair-proof handling. Some UI and service links rely on README descriptions or SOURCE INDEX references rather than inspected call sites; unsampled internals are represented cautiously.

Main entry points: [`src/App.tsx`](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/App.tsx) (Workspace Shell), [`api/_lib/triage/triageService.ts`](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/_lib/triage/triageService.ts) (Triage Orchestrator), [`src/lib/repositories/issueRepository.ts`](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/repositories/issueRepository.ts) (Repository Facade), [`src/components/report/ReportIssueView.tsx`](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/report/ReportIssueView.tsx) (Issue Reporting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Civic Workspaces"]
  node_app["Workspace Shell<br/>[App.tsx]"]
  node_report["Issue Reporting"]
  node_triagepreview["Triage Preview"]
  node_tracking["Issue Tracking"]
  node_command["Admin Command Desk"]
  node_map["Civic Map<br/>[CivicMap.tsx]"]
end

subgraph group_triage["Issue Triage"]
  node_triageclient["Triage Client<br/>[triageClient.ts]"]
  node_triageapi["Triage Endpoint<br/>[triage.ts]"]
  node_triageservice["Triage Orchestrator<br/>[triageService.ts]"]
  node_gemini["Gemini Classifier<br/>[geminiTriage.ts]"]
  node_heuristic["Heuristic Fallback<br/>[heuristicTriage.ts]"]
  node_cache["Triage Cache<br/>[triageCache.ts]"]
end

subgraph group_operations["Issue Operations"]
  node_issuecontract["Issue Validation<br/>[issue.ts]"]
  node_repository["Repository Facade<br/>[issueRepository.ts]"]
  node_hybrid["Hybrid Storage"]
  node_firestore[("Firestore Issues")]
  node_local[("Local Issues")]
end

subgraph group_platform["Identity and Platform"]
  node_auth["Authentication Service<br/>[authService.ts]"]
  node_export["Receipts and Proof<br/>[civicExport.ts]"]
  node_localization["Localization<br/>[translations.ts]"]
end

node_citizen(("Citizen"))
node_admin(("Municipal Staff"))
node_geminiservice{{"Google Gemini"}}
node_firebase[("Firebase")]

node_citizen -->|"opens workspace"| node_app
node_admin -->|"opens workspace"| node_app
node_app -->|"presents reporting"| node_report
node_report -->|"selects location"| node_map
node_report -->|"requests triage"| node_triageclient
node_triageclient -.->|"sends request"| node_triageapi
node_triageapi -->|"dispatches triage"| node_triageservice
node_triageservice -->|"runs classification"| node_gemini
node_triageservice -->|"falls back"| node_heuristic
node_triageservice -->|"checks cache"| node_cache
node_gemini -->|"calls model"| node_geminiservice
node_triageservice -.->|"returns result"| node_triagepreview
node_report -.->|"submits issue"| node_repository
node_repository -.->|"delegates storage"| node_hybrid
node_hybrid -->|"uses cloud store"| node_firestore
node_hybrid -->|"falls back locally"| node_local
node_repository -->|"validates issues"| node_issuecontract
node_firestore -.->|"reads and writes"| node_firebase
node_app -->|"manages sessions"| node_auth
node_auth -.->|"authenticates users"| node_firebase
node_app -->|"shows citizen status"| node_tracking
node_tracking -.->|"loads issues"| node_repository
node_app -->|"shows operations desk"| node_command
node_command -.->|"updates issues"| node_repository
node_command -->|"exports records"| node_export
node_app -->|"loads repair proofs"| node_export
node_app -->|"switches language"| node_localization

click node_app "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/App.tsx"
click node_report "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/report/ReportIssueView.tsx"
click node_triagepreview "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/report/TriagePreviewPanel.tsx"
click node_tracking "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/dashboard/TrackIssuesView.tsx"
click node_command "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/admin/AdminDashboardView.tsx"
click node_map "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/map/CivicMap.tsx"
click node_triageclient "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/api/triageClient.ts"
click node_triageapi "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/triage.ts"
click node_triageservice "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/_lib/triage/triageService.ts"
click node_gemini "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/_lib/triage/geminiTriage.ts"
click node_heuristic "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/_lib/triage/heuristicTriage.ts"
click node_cache "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/_lib/triage/triageCache.ts"
click node_issuecontract "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/shared/schemas/issue.ts"
click node_repository "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/repositories/issueRepository.ts"
click node_hybrid "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/repositories/hybridIssueRepository.ts"
click node_firestore "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/repositories/firestoreIssueRepository.ts"
click node_local "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/repositories/localIssueRepository.ts"
click node_auth "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/auth/authService.ts"
click node_export "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/export/civicExport.ts"
click node_localization "https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/i18n/translations.ts"

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_report,node_triagepreview,node_tracking,node_command,node_map toneBlue
class node_triageclient,node_triageapi,node_triageservice,node_gemini,node_heuristic,node_cache,node_firebase toneAmber
class node_issuecontract,node_repository,node_hybrid,node_firestore,node_local toneMint
class node_auth,node_export,node_localization toneRose
class node_citizen,node_admin,node_geminiservice toneIndigo
```

## Components

### Civic Workspaces

- [Workspace Shell](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/App.tsx): `src/App.tsx`
- [Issue Reporting](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/report/ReportIssueView.tsx): `src/components/report/ReportIssueView.tsx`
- [Triage Preview](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/report/TriagePreviewPanel.tsx): `src/components/report/TriagePreviewPanel.tsx`
- [Issue Tracking](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/dashboard/TrackIssuesView.tsx): `src/components/dashboard/TrackIssuesView.tsx`
- [Admin Command Desk](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/admin/AdminDashboardView.tsx): `src/components/admin/AdminDashboardView.tsx`
- [Civic Map](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/components/map/CivicMap.tsx): `src/components/map/CivicMap.tsx`

### Issue Triage

- [Triage Client](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/api/triageClient.ts): `src/lib/api/triageClient.ts`
- [Triage Endpoint](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/triage.ts): `api/triage.ts`
- [Triage Orchestrator](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/_lib/triage/triageService.ts): `api/_lib/triage/triageService.ts`
- [Gemini Classifier](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/_lib/triage/geminiTriage.ts): `api/_lib/triage/geminiTriage.ts`
- [Heuristic Fallback](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/_lib/triage/heuristicTriage.ts): `api/_lib/triage/heuristicTriage.ts`
- [Triage Cache](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/api/_lib/triage/triageCache.ts): `api/_lib/triage/triageCache.ts`

### Issue Operations

- [Issue Validation](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/shared/schemas/issue.ts): `shared/schemas/issue.ts`
- [Repository Facade](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/repositories/issueRepository.ts): `src/lib/repositories/issueRepository.ts`
- [Hybrid Storage](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/repositories/hybridIssueRepository.ts): `src/lib/repositories/hybridIssueRepository.ts`
- [Firestore Issues](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/repositories/firestoreIssueRepository.ts): `src/lib/repositories/firestoreIssueRepository.ts`
- [Local Issues](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/repositories/localIssueRepository.ts): `src/lib/repositories/localIssueRepository.ts`

### Identity and Platform

- [Authentication Service](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/auth/authService.ts): `src/lib/auth/authService.ts`
- [Receipts and Proof](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/export/civicExport.ts): `src/lib/export/civicExport.ts`
- [Localization](https://github.com/suneetbafna83-ship-it/civicresolver/blob/main/src/lib/i18n/translations.ts): `src/lib/i18n/translations.ts`

### Other components

- **Citizen**
- **Municipal Staff**
- **Google Gemini**
- **Firebase**

## Connections

- Citizen → Workspace Shell: opens workspace (evidence: `README.md`)
- Municipal Staff → Workspace Shell: opens workspace (evidence: `README.md`)
- Workspace Shell → Issue Reporting: presents reporting (evidence: `README.md`)
- Issue Reporting → Civic Map: selects location (evidence: `README.md`)
- Issue Reporting → Triage Client: requests triage (evidence: `README.md`)
- Triage Client → Triage Endpoint: sends request (evidence: `README.md`)
- Triage Endpoint → Triage Orchestrator: dispatches triage (evidence: `api/triage.ts`)
- Triage Orchestrator → Gemini Classifier: runs classification (evidence: `api/_lib/triage/triageService.ts`)
- Triage Orchestrator → Heuristic Fallback: falls back (evidence: `api/_lib/triage/triageService.ts`)
- Triage Orchestrator → Triage Cache: checks cache (evidence: `api/_lib/triage/triageService.ts`)
- Gemini Classifier → Google Gemini: calls model (evidence: `README.md`)
- Triage Orchestrator → Triage Preview: returns result
- Issue Reporting → Repository Facade: submits issue (evidence: `README.md`)
- Repository Facade → Hybrid Storage: delegates storage (evidence: `src/lib/repositories/hybridIssueRepository.ts`)
- Hybrid Storage → Firestore Issues: uses cloud store (evidence: `src/lib/repositories/hybridIssueRepository.ts`)
- Hybrid Storage → Local Issues: falls back locally (evidence: `src/lib/repositories/hybridIssueRepository.ts`)
- Repository Facade → Issue Validation: validates issues (evidence: `src/lib/repositories/issueRepository.ts`)
- Firestore Issues → Firebase: reads and writes (evidence: `README.md`)
- Workspace Shell → Authentication Service: manages sessions (evidence: `src/App.tsx`)
- Authentication Service → Firebase: authenticates users (evidence: `README.md`)
- Workspace Shell → Issue Tracking: shows citizen status (evidence: `README.md`)
- Issue Tracking → Repository Facade: loads issues
- Workspace Shell → Admin Command Desk: shows operations desk (evidence: `README.md`)
- Admin Command Desk → Repository Facade: updates issues (evidence: `README.md`)
- Admin Command Desk → Receipts and Proof: exports records (evidence: `README.md`)
- Workspace Shell → Receipts and Proof: loads repair proofs (evidence: `src/App.tsx`)
- Workspace Shell → Localization: switches language (evidence: `src/App.tsx`)
