# joyslin-2006/civic-shield architecture

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

- Interactive diagram: https://gitdiagram.com/joyslin-2006/civic-shield
- Repository: https://github.com/joyslin-2006/civic-shield

## Overview

Civic Shield is a civic-issue reporting and response application: users register or log in, submit issues, and view workers and assignments. The React UI calls separate authentication, issue, and worker services; the issue and worker service trees also expose event, file, and assignment subsystems. UI routing and API calls are shown in excerpts. Backend internals and cross-service event wiring are represented only where the tree supports a meaningful component; unverified connections are dashed.

Main entry points: [`civic-shield-ui/src/services/api.js`](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/services/api.js) (API clients), [`civic-shield-ui/src/App.jsx`](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/App.jsx) (App routes), [`worker-service/src/main/java/com/example/worker_service/service/AssignmentService.java`](https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/service/AssignmentService.java) (Assignment logic), [`auth-service/src/main/java/com/example/auth_service/service/AuthServiceImpl.java`](https://github.com/joyslin-2006/civic-shield/blob/main/auth-service/src/main/java/com/example/auth_service/service/AuthServiceImpl.java) (Auth logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Civic Shield UI"]
  node_app["App routes<br/>[App.jsx]"]
  node_login["Login<br/>[Login.jsx]"]
  node_register["Registration<br/>[Register.jsx]"]
  node_raise["Raise issue<br/>[RaiseIssue.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_workerspage["Workers view<br/>[Workers.jsx]"]
  node_assignmentsview["Assignments view<br/>[Assignments.jsx]"]
  node_api["API clients<br/>[api.js]"]
end

subgraph group_auth["Authentication"]
  node_authcontroller["Auth endpoints"]
  node_authservice["Auth logic"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_users[("User repository")]
end

subgraph group_issues["Issue management"]
  node_issuecontroller["Issue endpoints"]
  node_issueservice["Issue logic"]
  node_issuerepo[("Issue repository")]
  node_filecontroller["File endpoints"]
  node_fileservice["File service<br/>[FileService.java]"]
  node_producer["Issue event producer"]
end

subgraph group_response["Worker response"]
  node_workercontrollers["Worker endpoints"]
  node_assignmentcontroller["Assignment endpoints"]
  node_assignmentservice["Assignment logic"]
  node_assignments[("Assignment repository")]
  node_workerrepo[("Worker repository")]
  node_consumer["Issue event consumer"]
end

node_citizen(("User"))
node_kafka["Kafka"]
node_minio[("MinIO")]

node_citizen -->|"uses"| node_app
node_app -->|"routes"| node_login
node_app -->|"routes"| node_register
node_app -->|"routes"| node_dashboard
node_app -->|"routes"| node_raise
node_app -->|"routes"| node_workerspage
node_app -->|"routes"| node_assignmentsview
node_login -->|"calls"| node_api
node_register -->|"posts registration"| node_authcontroller
node_api -->|"targets auth"| node_authcontroller
node_raise -->|"calls"| node_api
node_api -->|"targets issues"| node_issuecontroller
node_workerspage -->|"calls"| node_api
node_assignmentsview -->|"calls"| node_api
node_api -->|"targets workers"| node_workercontrollers
node_api -->|"targets assignments"| node_assignmentcontroller
node_authcontroller -.->|"delegates"| node_authservice
node_authservice -.->|"uses token service"| node_jwt
node_authservice -.->|"accesses users"| node_users
node_issuecontroller -.->|"delegates"| node_issueservice
node_issueservice -.->|"persists issues"| node_issuerepo
node_filecontroller -.->|"delegates"| node_fileservice
node_fileservice -.->|"stores files"| node_minio
node_issueservice -.->|"publishes event"| node_producer
node_producer -.->|"publishes"| node_kafka
node_kafka -.->|"delivers event"| node_consumer
node_consumer -.->|"triggers assignment"| node_assignmentservice
node_workercontrollers -.->|"reads workers"| node_workerrepo
node_assignmentcontroller -.->|"delegates"| node_assignmentservice
node_assignmentservice -.->|"stores assignments"| node_assignments
node_assignmentservice -.->|"uses workers"| node_workerrepo

click node_app "https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/App.jsx"
click node_login "https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Login.jsx"
click node_register "https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Register.jsx"
click node_raise "https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/RaiseIssue.jsx"
click node_dashboard "https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Dashboard.jsx"
click node_workerspage "https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Workers.jsx"
click node_assignmentsview "https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Assignments.jsx"
click node_api "https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/services/api.js"
click node_authcontroller "https://github.com/joyslin-2006/civic-shield/blob/main/auth-service/src/main/java/com/example/auth_service/controller/AuthController.java"
click node_authservice "https://github.com/joyslin-2006/civic-shield/blob/main/auth-service/src/main/java/com/example/auth_service/service/AuthServiceImpl.java"
click node_jwt "https://github.com/joyslin-2006/civic-shield/blob/main/auth-service/src/main/java/com/example/auth_service/security/JwtService.java"
click node_users "https://github.com/joyslin-2006/civic-shield/blob/main/auth-service/src/main/java/com/example/auth_service/repository/UserRepository.java"
click node_issuecontroller "https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/controller/IssueController.java"
click node_issueservice "https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/service/IssueServiceImpl.java"
click node_issuerepo "https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/repository/IssueRepository.java"
click node_filecontroller "https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/controller/FileController.java"
click node_fileservice "https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/service/FileService.java"
click node_producer "https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/kafka/KafkaProducerService.java"
click node_workercontrollers "https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/controller/WorkerController.java"
click node_assignmentcontroller "https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/controller/AssignmentController.java"
click node_assignmentservice "https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/service/AssignmentService.java"
click node_assignments "https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/repository/AssignmentRepository.java"
click node_workerrepo "https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/repository/WorkerRepository.java"
click node_consumer "https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/kafka/IssueCreatedConsumer.java"

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_login,node_register,node_raise,node_dashboard,node_workerspage,node_assignmentsview,node_api,node_citizen toneBlue
class node_authcontroller,node_authservice,node_jwt,node_users,node_minio toneAmber
class node_issuecontroller,node_issueservice,node_issuerepo,node_filecontroller,node_fileservice,node_producer toneMint
class node_workercontrollers,node_assignmentcontroller,node_assignmentservice,node_assignments,node_workerrepo,node_consumer toneRose
class node_kafka toneIndigo
```

## Components

### Civic Shield UI

- [App routes](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/App.jsx): `civic-shield-ui/src/App.jsx`
- [Login](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Login.jsx): `civic-shield-ui/src/pages/Login.jsx`
- [Registration](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Register.jsx): `civic-shield-ui/src/pages/Register.jsx`
- [Raise issue](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/RaiseIssue.jsx): `civic-shield-ui/src/pages/RaiseIssue.jsx`
- [Dashboard](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Dashboard.jsx): `civic-shield-ui/src/pages/Dashboard.jsx`
- [Workers view](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Workers.jsx): `civic-shield-ui/src/pages/Workers.jsx`
- [Assignments view](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/pages/Assignments.jsx): `civic-shield-ui/src/pages/Assignments.jsx`
- [API clients](https://github.com/joyslin-2006/civic-shield/blob/main/civic-shield-ui/src/services/api.js): `civic-shield-ui/src/services/api.js`

### Authentication

- [Auth endpoints](https://github.com/joyslin-2006/civic-shield/blob/main/auth-service/src/main/java/com/example/auth_service/controller/AuthController.java): `auth-service/src/main/java/com/example/auth_service/controller/AuthController.java`
- [Auth logic](https://github.com/joyslin-2006/civic-shield/blob/main/auth-service/src/main/java/com/example/auth_service/service/AuthServiceImpl.java): `auth-service/src/main/java/com/example/auth_service/service/AuthServiceImpl.java`
- [JWT service](https://github.com/joyslin-2006/civic-shield/blob/main/auth-service/src/main/java/com/example/auth_service/security/JwtService.java): `auth-service/src/main/java/com/example/auth_service/security/JwtService.java`
- [User repository](https://github.com/joyslin-2006/civic-shield/blob/main/auth-service/src/main/java/com/example/auth_service/repository/UserRepository.java): `auth-service/src/main/java/com/example/auth_service/repository/UserRepository.java`

### Issue management

- [Issue endpoints](https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/controller/IssueController.java): `issue-service/src/main/java/com/example/issue_service/controller/IssueController.java`
- [Issue logic](https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/service/IssueServiceImpl.java): `issue-service/src/main/java/com/example/issue_service/service/IssueServiceImpl.java`
- [Issue repository](https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/repository/IssueRepository.java): `issue-service/src/main/java/com/example/issue_service/repository/IssueRepository.java`
- [File endpoints](https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/controller/FileController.java): `issue-service/src/main/java/com/example/issue_service/controller/FileController.java`
- [File service](https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/service/FileService.java): `issue-service/src/main/java/com/example/issue_service/service/FileService.java`
- [Issue event producer](https://github.com/joyslin-2006/civic-shield/blob/main/issue-service/src/main/java/com/example/issue_service/kafka/KafkaProducerService.java): `issue-service/src/main/java/com/example/issue_service/kafka/KafkaProducerService.java`

### Worker response

- [Worker endpoints](https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/controller/WorkerController.java): `worker-service/src/main/java/com/example/worker_service/controller/WorkerController.java`
- [Assignment endpoints](https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/controller/AssignmentController.java): `worker-service/src/main/java/com/example/worker_service/controller/AssignmentController.java`
- [Assignment logic](https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/service/AssignmentService.java): `worker-service/src/main/java/com/example/worker_service/service/AssignmentService.java`
- [Assignment repository](https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/repository/AssignmentRepository.java): `worker-service/src/main/java/com/example/worker_service/repository/AssignmentRepository.java`
- [Worker repository](https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/repository/WorkerRepository.java): `worker-service/src/main/java/com/example/worker_service/repository/WorkerRepository.java`
- [Issue event consumer](https://github.com/joyslin-2006/civic-shield/blob/main/worker-service/src/main/java/com/example/worker_service/kafka/IssueCreatedConsumer.java): `worker-service/src/main/java/com/example/worker_service/kafka/IssueCreatedConsumer.java`

### Other components

- **User**
- **Kafka**
- **MinIO**

## Connections

- User → App routes: uses (evidence: `civic-shield-ui/src/App.jsx`)
- App routes → Login: routes (evidence: `civic-shield-ui/src/App.jsx`)
- App routes → Registration: routes (evidence: `civic-shield-ui/src/App.jsx`)
- App routes → Dashboard: routes (evidence: `civic-shield-ui/src/App.jsx`)
- App routes → Raise issue: routes (evidence: `civic-shield-ui/src/App.jsx`)
- App routes → Workers view: routes (evidence: `civic-shield-ui/src/App.jsx`)
- App routes → Assignments view: routes (evidence: `civic-shield-ui/src/App.jsx`)
- Login → API clients: calls (evidence: `civic-shield-ui/src/pages/Login.jsx`)
- Registration → Auth endpoints: posts registration (evidence: `civic-shield-ui/src/pages/Register.jsx`)
- API clients → Auth endpoints: targets auth (evidence: `civic-shield-ui/src/services/api.js`)
- Raise issue → API clients: calls (evidence: `civic-shield-ui/src/pages/RaiseIssue.jsx`)
- API clients → Issue endpoints: targets issues (evidence: `civic-shield-ui/src/services/api.js`)
- Workers view → API clients: calls (evidence: `civic-shield-ui/src/pages/Workers.jsx`)
- Assignments view → API clients: calls (evidence: `civic-shield-ui/src/pages/Assignments.jsx`)
- API clients → Worker endpoints: targets workers (evidence: `civic-shield-ui/src/services/api.js`)
- API clients → Assignment endpoints: targets assignments (evidence: `civic-shield-ui/src/services/api.js`)
- Auth endpoints → Auth logic: delegates
- Auth logic → JWT service: uses token service
- Auth logic → User repository: accesses users
- Issue endpoints → Issue logic: delegates
- Issue logic → Issue repository: persists issues
- File endpoints → File service: delegates
- File service → MinIO: stores files
- Issue logic → Issue event producer: publishes event
- Issue event producer → Kafka: publishes
- Kafka → Issue event consumer: delivers event
- Issue event consumer → Assignment logic: triggers assignment
- Worker endpoints → Worker repository: reads workers
- Assignment endpoints → Assignment logic: delegates
- Assignment logic → Assignment repository: stores assignments
- Assignment logic → Worker repository: uses workers
