# shubhan-12/civic-connect architecture

> Architecture diagram of the GitHub repository shubhan-12/civic-connect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubhan-12/civic-connect
- Repository: https://github.com/shubhan-12/civic-connect

## Overview

#### Purpose and deployable entry points
Civic Connect is a full-stack civic-complaint platform for citizens, municipal officers, and workers. The Android client starts at `android/app/src/main/java/com/civicconnect/app/MainActivity.kt`; the Spring Boot API starts at `backend/src/main/java/com/civicconnect/backend/BackendApplication.java`. The root `src/App.jsx` appears to be a separate/incomplete JavaScript entry point, not represented by the documented architecture.

#### Android client: Compose UI and session boundary
The Android app is Kotlin/Jetpack Compose. It presents complaint reporting, home, location selection, profile/history/details, and registration flows through screens such as `android/app/src/main/java/com/civicconnect/app/ReportIssueScreen.kt`, `android/app/src/main/java/com/civicconnect/app/ui/theme/MyComplaintsScreen.kt`, and `android/app/src/main/java/com/civicconnect/app/ui/theme/ComplaintDetailsScreen.kt`. Authentication/session state is persisted locally via `android/app/src/main/java/com/civicconnect/app/local/SessionManager.kt`.

#### Client API integration
Retrofit is the mobile-to-server boundary, centralized in `android/app/src/main/java/com/civicconnect/app/network/RetrofitClient.kt`. API contracts are divided by capability: authentication (`android/app/src/main/java/com/civicconnect/app/network/AuthApi.kt`), complaint lifecycle (`android/app/src/main/java/com/civicconnect/app/network/ComplaintApi.kt`), images and affected-user votes (`android/app/src/main/java/com/civicconnect/app/network/ComplaintImageApi.kt`, `android/app/src/main/java/com/civicconnect/app/network/ComplaintVoteApi.kt`). Kotlin request/response models mirror backend HTTP DTOs under `android/app/src/main/java/com/civicconnect/app/data/model/`.

#### API security and user roles
The Spring API exposes controllers for authentication/profile and role-oriented operations. JWT issuance/validation and request authentication are implemented by `backend/src/main/java/com/civicconnect/backend/security/JwtService.java`, `backend/src/main/java/com/civicconnect/backend/security/JwtAuthenticationFilter.java`, and `backend/src/main/java/com/civicconnect/backend/config/SecurityConfig.java`. User persistence and account workflows reside in `backend/src/main/java/com/civicconnect/backend/user/entity/User.java`, `backend/src/main/java/com/civicconnect/backend/user/service/UserService.java`, and `backend/src/main/java/com/civicconnect/backend/user/controller/AuthController.java`.

#### Complaint lifecycle orchestration
Complaint creation, retrieval, status updates, summaries, and history form the central domain flow: controller → service → JPA repositories/entities. Key paths are `backend/src/main/java/com/civicconnect/backend/complaint/controller/ComplaintController.java`, `backend/src/main/java/com/civicconnect/backend/complaint/service/ComplaintService.java`, and `backend/src/main/java/com/civicconnect/backend/complaint/entity/ComplaintStatusHistory.java`. Officers assign work through `backend/src/main/java/com/civicconnect/backend/admin/controller/AdminController.java`; worker assignment and worker-facing operations are modeled in `backend/src/main/java/com/civicconnect/backend/worker/service/WorkerService.java`.

#### Supporting complaint capabilities
Users can mark themselves affected through the vote domain (`backend/src/main/java/com/civicconnect/backend/complaintvote/service/ComplaintVoteService.java`). Complaint images are uploaded/served through `backend/src/main/java/com/civicconnect/backend/file/controller/ComplaintImageController.java` and stored behind `backend/src/main/java/com/civicconnect/backend/file/service/FileStorageService.java`. Location selection is backed by state/district/taluk APIs, notably `backend/src/main/java/com/civicconnect/backend/location/controller/DistrictController.java` and `backend/src/main/java/com/civicconnect/backend/location/controller/TalukController.java`.

#### Persistence and infrastructure
The backend is Maven/Spring Boot (`backend/pom.xml`) using PostgreSQL and JPA, with Flyway-style versioned schema/seed migrations under `backend/src/main/resources/db/migration/`. The schema covers users, geographic hierarchy, complaints, votes, status history, and workers; for example `backend/src/main/resources/db/migration/V40__create_complaints_table.sql`, `backend/src/main/resources/db/migration/V45__create_complaint_status_history.sql`, and `backend/src/main/resources/db/migration/V47/V47__create_workers_table.sql`. Runtime settings, database connectivity, JWT/security, and file storage are externalized in `backend/src/main/resources/application.properties` and `backend/src/main/resources/application.yaml`.

Main entry points: [`backend/src/main/java/com/civicconnect/backend/complaint/entity/ComplaintStatusHistory.java`](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaint/entity/ComplaintStatusHistory.java) (JPA domain data), [`backend/src/main/java/com/civicconnect/backend/complaint/service/ComplaintService.java`](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaint/service/ComplaintService.java) (Complaint lifecycle), [`android/app/src/main/java/com/civicconnect/app/ReportIssueScreen.kt`](https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/ReportIssueScreen.kt) (Citizen screens), [`backend/src/main/java/com/civicconnect/backend/BackendApplication.java`](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/BackendApplication.java) (API application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android client"]
  node_android_entry["Compose app<br/>Android entry<br/>[MainActivity.kt]"]
  node_android_screens["Citizen screens<br/>Compose UI"]
  node_session["Session storage<br/>local auth state<br/>[SessionManager.kt]"]
  node_retrofit["Retrofit client<br/>HTTP client<br/>[RetrofitClient.kt]"]
  node_mobile_apis["Mobile API contracts<br/>Retrofit interfaces<br/>[ComplaintApi.kt]"]
end

subgraph group_backend["Spring Boot API"]
  node_backend_entry["API application<br/>Spring Boot entry"]
  node_security["JWT security<br/>auth filter"]
  node_auth_users["Accounts and auth<br/>controller/service"]
  node_complaint_controller["Complaint API<br/>controller"]
  node_complaint_service["Complaint lifecycle<br/>domain service"]
  node_admin_worker["Assignment operations<br/>admin and worker services<br/>[WorkerService.java]"]
  node_votes["Affected-user votes<br/>domain service"]
  node_images["Complaint images<br/>upload controller"]
  node_file_storage["File storage<br/>storage service"]
  node_locations["Location API<br/>geography controllers"]
end

subgraph group_persistence["Persistence"]
  node_jpa_domain["JPA domain data<br/>entities and repositories"]
  node_postgres[("PostgreSQL<br/>relational database")]
  node_migrations["Schema migrations<br/>Flyway SQL"]
end

node_android_entry -->|"hosts"| node_android_screens
node_android_screens -->|"reads session"| node_session
node_android_screens -->|"uses"| node_mobile_apis
node_mobile_apis -->|"executed by"| node_retrofit
node_retrofit -->|"HTTPS API"| node_backend_entry
node_backend_entry -->|"secures requests"| node_security
node_security -->|"authenticates access"| node_auth_users
node_security -->|"authorizes"| node_complaint_controller
node_backend_entry -->|"serves"| node_locations
node_complaint_controller -->|"orchestrates"| node_complaint_service
node_complaint_service -->|"assignment lifecycle"| node_admin_worker
node_complaint_service -->|"vote context"| node_votes
node_complaint_service -->|"persists"| node_jpa_domain
node_auth_users -->|"accounts"| node_jpa_domain
node_admin_worker -->|"assignments"| node_jpa_domain
node_votes -->|"votes"| node_jpa_domain
node_images -->|"stores files"| node_file_storage
node_images -->|"links images"| node_jpa_domain
node_locations -->|"queries geography"| node_jpa_domain
node_jpa_domain -->|"JPA"| node_postgres
node_migrations -->|"provisions"| node_postgres

click node_android_entry "https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/MainActivity.kt"
click node_android_screens "https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/ReportIssueScreen.kt"
click node_session "https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/local/SessionManager.kt"
click node_retrofit "https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/network/RetrofitClient.kt"
click node_mobile_apis "https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/network/ComplaintApi.kt"
click node_backend_entry "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/BackendApplication.java"
click node_security "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/security/JwtAuthenticationFilter.java"
click node_auth_users "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/user/controller/AuthController.java"
click node_complaint_controller "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaint/controller/ComplaintController.java"
click node_complaint_service "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaint/service/ComplaintService.java"
click node_admin_worker "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/worker/service/WorkerService.java"
click node_votes "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaintvote/service/ComplaintVoteService.java"
click node_images "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/file/controller/ComplaintImageController.java"
click node_file_storage "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/file/service/FileStorageService.java"
click node_locations "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/location/controller/DistrictController.java"
click node_jpa_domain "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaint/entity/ComplaintStatusHistory.java"
click node_migrations "https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/resources/db/migration/V40__create_complaints_table.sql"

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_android_entry,node_android_screens,node_session,node_retrofit,node_mobile_apis toneBlue
class node_backend_entry,node_security,node_auth_users,node_complaint_controller,node_complaint_service,node_admin_worker,node_votes,node_images,node_file_storage,node_locations toneAmber
class node_jpa_domain,node_postgres,node_migrations toneMint
```

## Components

### Android client

- [Compose app](https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/MainActivity.kt): Android entry · `android/app/src/main/java/com/civicconnect/app/MainActivity.kt`
- [Citizen screens](https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/ReportIssueScreen.kt): Compose UI · Reporting, history, details, profile, and location flows. · `android/app/src/main/java/com/civicconnect/app/ReportIssueScreen.kt`
- [Session storage](https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/local/SessionManager.kt): local auth state · `android/app/src/main/java/com/civicconnect/app/local/SessionManager.kt`
- [Retrofit client](https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/network/RetrofitClient.kt): HTTP client · `android/app/src/main/java/com/civicconnect/app/network/RetrofitClient.kt`
- [Mobile API contracts](https://github.com/shubhan-12/civic-connect/blob/main/android/app/src/main/java/com/civicconnect/app/network/ComplaintApi.kt): Retrofit interfaces · Authentication, complaints, images, and affected-user votes. · `android/app/src/main/java/com/civicconnect/app/network/ComplaintApi.kt`

### Spring Boot API

- [API application](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/BackendApplication.java): Spring Boot entry · `backend/src/main/java/com/civicconnect/backend/BackendApplication.java`
- [JWT security](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/security/JwtAuthenticationFilter.java): auth filter · Validates bearer tokens and enforces role access. · `backend/src/main/java/com/civicconnect/backend/security/JwtAuthenticationFilter.java`
- [Accounts and auth](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/user/controller/AuthController.java): controller/service · `backend/src/main/java/com/civicconnect/backend/user/controller/AuthController.java`
- [Complaint API](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaint/controller/ComplaintController.java): controller · Creation, retrieval, status, summaries, and history endpoints. · `backend/src/main/java/com/civicconnect/backend/complaint/controller/ComplaintController.java`
- [Complaint lifecycle](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaint/service/ComplaintService.java): domain service · `backend/src/main/java/com/civicconnect/backend/complaint/service/ComplaintService.java`
- [Assignment operations](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/worker/service/WorkerService.java): admin and worker services · Officers assign work; workers handle assigned complaints. · `backend/src/main/java/com/civicconnect/backend/worker/service/WorkerService.java`
- [Affected-user votes](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaintvote/service/ComplaintVoteService.java): domain service · `backend/src/main/java/com/civicconnect/backend/complaintvote/service/ComplaintVoteService.java`
- [Complaint images](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/file/controller/ComplaintImageController.java): upload controller · Uploads and serves complaint images. · `backend/src/main/java/com/civicconnect/backend/file/controller/ComplaintImageController.java`
- [File storage](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/file/service/FileStorageService.java): storage service · `backend/src/main/java/com/civicconnect/backend/file/service/FileStorageService.java`
- [Location API](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/location/controller/DistrictController.java): geography controllers · Supplies state, district, and taluk selections. · `backend/src/main/java/com/civicconnect/backend/location/controller/DistrictController.java`

### Persistence

- [JPA domain data](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/java/com/civicconnect/backend/complaint/entity/ComplaintStatusHistory.java): entities and repositories · Users, complaints, workers, votes, geography, and status history. · `backend/src/main/java/com/civicconnect/backend/complaint/entity/ComplaintStatusHistory.java`
- **PostgreSQL**: relational database
- [Schema migrations](https://github.com/shubhan-12/civic-connect/blob/main/backend/src/main/resources/db/migration/V40__create_complaints_table.sql): Flyway SQL · Versioned schema and seed migrations. · `backend/src/main/resources/db/migration/V40__create_complaints_table.sql`

## Connections

- Compose app → Citizen screens: hosts
- Citizen screens → Session storage: reads session
- Citizen screens → Mobile API contracts: uses
- Mobile API contracts → Retrofit client: executed by
- Retrofit client → API application: HTTPS API
- API application → JWT security: secures requests
- JWT security → Accounts and auth: authenticates access
- JWT security → Complaint API: authorizes
- API application → Location API: serves
- Complaint API → Complaint lifecycle: orchestrates
- Complaint lifecycle → Assignment operations: assignment lifecycle
- Complaint lifecycle → Affected-user votes: vote context
- Complaint lifecycle → JPA domain data: persists
- Accounts and auth → JPA domain data: accounts
- Assignment operations → JPA domain data: assignments
- Affected-user votes → JPA domain data: votes
- Complaint images → File storage: stores files
- Complaint images → JPA domain data: links images
- Location API → JPA domain data: queries geography
- JPA domain data → PostgreSQL: JPA
- Schema migrations → PostgreSQL: provisions