# anki-0015/issue-tracking architecture

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

- Interactive diagram: https://gitdiagram.com/anki-0015/issue-tracking
- Repository: https://github.com/anki-0015/issue-tracking

## Overview

CivicReport lets residents create accounts, report and locate civic issues, follow status and community activity, and lets administrators review reports and manage issue workflows. The main path runs from the protected Next.js interface through its API client to Express routes and controllers, which validate and persist data via Prisma/PostgreSQL. Authentication, uploads, notifications, summaries, and admin activity are separate capabilities around that path. Source excerpts establish some controller and client behavior; route-to-controller and UI details not shown are represented only where supported by the tree or README.

Main entry points: [`frontend/lib/api.ts`](https://github.com/anki-0015/issue-tracking/blob/main/frontend/lib/api.ts) (API client), [`backend/src/index.ts`](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/index.ts) (Express API), [`backend/src/routes/auth.ts`](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/routes/auth.ts) (Auth routes), [`backend/src/lib/prisma.ts`](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/lib/prisma.ts) (Prisma access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Citizen and Admin UI"]
  node_web_entry["Web entry<br/>[page.tsx]"]
  node_auth_pages["Sign in and signup<br/>[page.tsx]"]
  node_protected_shell["Protected workspace<br/>[layout.tsx]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_issue_browse["Issue listing<br/>[page.tsx]"]
  node_issue_report["Issue reporting<br/>[page.tsx]"]
  node_issue_detail["Issue detail and map<br/>[page.tsx]"]
  node_admin_ui["Admin console<br/>[page.tsx]"]
  node_profile_ui["Profile<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_proxy["Route gate<br/>[proxy.ts]"]
end

subgraph group_api["API and Routing"]
  node_api_app["Express API<br/>[index.ts]"]
  node_auth_routes["Auth routes<br/>[auth.ts]"]
  node_issue_routes["Issue routes<br/>[issues.ts]"]
  node_upload_routes["Upload routes<br/>[uploads.ts]"]
  node_notification_routes["Notification routes<br/>[notifications.ts]"]
end

subgraph group_domain["Issue and Account Services"]
  node_auth_controller["Account workflows<br/>[authController.ts]"]
  node_issue_controller["Issue workflows<br/>[issueController.ts]"]
  node_notification_controller["Notification workflows"]
  node_upload_controller["Image upload"]
  node_auth_middleware["Session verification<br/>[authMiddleware.ts]"]
end

subgraph group_state["Persistent State"]
  node_prisma["Prisma access<br/>[prisma.ts]"]
  node_postgres[("PostgreSQL")]
  node_local_uploads[("Uploaded files")]
end

subgraph group_integrations["External Services"]
  node_email["Email delivery<br/>[email.ts]"]
end

node_citizen(("Residents"))
node_administrator(("Administrators"))

node_citizen -->|"opens"| node_web_entry
node_administrator -->|"opens"| node_web_entry
node_web_entry -->|"redirects"| node_proxy
node_citizen -->|"registers or signs in"| node_auth_pages
node_auth_pages -->|"requests account actions"| node_api_client
node_protected_shell -->|"loads session and notifications"| node_api_client
node_protected_shell -->|"checks session"| node_auth_routes
node_protected_shell -->|"navigates"| node_issue_browse
node_citizen -->|"submits report"| node_issue_report
node_issue_report -->|"creates report and uploads image"| node_api_client
node_citizen -->|"browses reports"| node_issue_browse
node_issue_browse -->|"requests issues"| node_api_client
node_citizen -->|"views and engages"| node_issue_detail
node_issue_detail -->|"requests issue actions"| node_api_client
node_dashboard -->|"requests summary"| node_api_client
node_administrator -->|"manages workflow"| node_admin_ui
node_admin_ui -->|"requests admin actions"| node_api_client
node_profile_ui -->|"requests account data"| node_api_client
node_api_client -->|"sends HTTP requests"| node_api_app
node_api_app -->|"mounts"| node_auth_routes
node_api_app -->|"mounts"| node_issue_routes
node_api_app -->|"mounts"| node_upload_routes
node_api_app -->|"mounts"| node_notification_routes
node_auth_routes -->|"verifies protected requests"| node_auth_middleware
node_auth_routes -->|"dispatches"| node_auth_controller
node_issue_routes -->|"verifies protected requests"| node_auth_middleware
node_issue_routes -->|"dispatches"| node_issue_controller
node_upload_routes -->|"dispatches"| node_upload_controller
node_notification_routes -->|"verifies requests"| node_auth_middleware
node_notification_routes -->|"dispatches"| node_notification_controller
node_auth_controller -->|"reads and writes accounts"| node_prisma
node_auth_controller -.->|"sends reset email"| node_email
node_issue_controller -->|"reads and writes issues"| node_prisma
node_notification_controller -->|"reads and updates notifications"| node_prisma
node_upload_controller -->|"returns stored file URL"| node_local_uploads
node_api_app -->|"serves uploaded files"| node_local_uploads
node_prisma -->|"queries"| node_postgres

click node_web_entry "https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/page.tsx"
click node_auth_pages "https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(auth)/login/page.tsx"
click node_protected_shell "https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/layout.tsx"
click node_dashboard "https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/dashboard/page.tsx"
click node_issue_browse "https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/issues/page.tsx"
click node_issue_report "https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/issues/report/page.tsx"
click node_issue_detail "https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/issues/%5Bid%5D/page.tsx"
click node_admin_ui "https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/admin/page.tsx"
click node_profile_ui "https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/profile/page.tsx"
click node_api_client "https://github.com/anki-0015/issue-tracking/blob/main/frontend/lib/api.ts"
click node_proxy "https://github.com/anki-0015/issue-tracking/blob/main/frontend/proxy.ts"
click node_api_app "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/index.ts"
click node_auth_routes "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/routes/auth.ts"
click node_issue_routes "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/routes/issues.ts"
click node_upload_routes "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/routes/uploads.ts"
click node_notification_routes "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/routes/notifications.ts"
click node_auth_controller "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/controllers/authController.ts"
click node_issue_controller "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/controllers/issueController.ts"
click node_notification_controller "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/controllers/notificationController.ts"
click node_upload_controller "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/controllers/uploadController.ts"
click node_auth_middleware "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/middleware/authMiddleware.ts"
click node_prisma "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/lib/prisma.ts"
click node_email "https://github.com/anki-0015/issue-tracking/blob/main/backend/src/lib/email.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_web_entry,node_auth_pages,node_protected_shell,node_dashboard,node_issue_browse,node_issue_report,node_issue_detail,node_admin_ui,node_profile_ui,node_api_client,node_proxy toneBlue
class node_api_app,node_auth_routes,node_issue_routes,node_upload_routes,node_notification_routes toneAmber
class node_auth_controller,node_issue_controller,node_notification_controller,node_upload_controller,node_auth_middleware toneMint
class node_prisma,node_postgres,node_local_uploads toneRose
class node_email,node_citizen,node_administrator toneIndigo
```

## Components

### Citizen and Admin UI

- [Web entry](https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Sign in and signup](https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(auth)/login/page.tsx): `frontend/app/(auth)/login/page.tsx`
- [Protected workspace](https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/layout.tsx): `frontend/app/(protected)/layout.tsx`
- [Dashboard](https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/dashboard/page.tsx): `frontend/app/(protected)/dashboard/page.tsx`
- [Issue listing](https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/issues/page.tsx): `frontend/app/(protected)/issues/page.tsx`
- [Issue reporting](https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/issues/report/page.tsx): `frontend/app/(protected)/issues/report/page.tsx`
- [Issue detail and map](https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/issues/%5Bid%5D/page.tsx): `frontend/app/(protected)/issues/[id]/page.tsx`
- [Admin console](https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/admin/page.tsx): `frontend/app/(protected)/admin/page.tsx`
- [Profile](https://github.com/anki-0015/issue-tracking/blob/main/frontend/app/(protected)/profile/page.tsx): `frontend/app/(protected)/profile/page.tsx`
- [API client](https://github.com/anki-0015/issue-tracking/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Route gate](https://github.com/anki-0015/issue-tracking/blob/main/frontend/proxy.ts): `frontend/proxy.ts`

### API and Routing

- [Express API](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Auth routes](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Issue routes](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/routes/issues.ts): `backend/src/routes/issues.ts`
- [Upload routes](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/routes/uploads.ts): `backend/src/routes/uploads.ts`
- [Notification routes](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/routes/notifications.ts): `backend/src/routes/notifications.ts`

### Issue and Account Services

- [Account workflows](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/controllers/authController.ts): `backend/src/controllers/authController.ts`
- [Issue workflows](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/controllers/issueController.ts): `backend/src/controllers/issueController.ts`
- [Notification workflows](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/controllers/notificationController.ts): `backend/src/controllers/notificationController.ts`
- [Image upload](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/controllers/uploadController.ts): `backend/src/controllers/uploadController.ts`
- [Session verification](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/middleware/authMiddleware.ts): `backend/src/middleware/authMiddleware.ts`

### Persistent State

- [Prisma access](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/lib/prisma.ts): `backend/src/lib/prisma.ts`
- **PostgreSQL**
- **Uploaded files**

### External Services

- [Email delivery](https://github.com/anki-0015/issue-tracking/blob/main/backend/src/lib/email.ts): `backend/src/lib/email.ts`

### Other components

- **Residents**
- **Administrators**

## Connections

- Residents → Web entry: opens
- Administrators → Web entry: opens
- Web entry → Route gate: redirects
- Residents → Sign in and signup: registers or signs in
- Sign in and signup → API client: requests account actions
- Protected workspace → API client: loads session and notifications
- Protected workspace → Auth routes: checks session
- Protected workspace → Issue listing: navigates
- Residents → Issue reporting: submits report
- Issue reporting → API client: creates report and uploads image
- Residents → Issue listing: browses reports
- Issue listing → API client: requests issues
- Residents → Issue detail and map: views and engages
- Issue detail and map → API client: requests issue actions
- Dashboard → API client: requests summary
- Administrators → Admin console: manages workflow
- Admin console → API client: requests admin actions
- Profile → API client: requests account data
- API client → Express API: sends HTTP requests
- Express API → Auth routes: mounts
- Express API → Issue routes: mounts
- Express API → Upload routes: mounts
- Express API → Notification routes: mounts
- Auth routes → Session verification: verifies protected requests
- Auth routes → Account workflows: dispatches
- Issue routes → Session verification: verifies protected requests
- Issue routes → Issue workflows: dispatches
- Upload routes → Image upload: dispatches
- Notification routes → Session verification: verifies requests
- Notification routes → Notification workflows: dispatches
- Account workflows → Prisma access: reads and writes accounts
- Account workflows → Email delivery: sends reset email
- Issue workflows → Prisma access: reads and writes issues
- Notification workflows → Prisma access: reads and updates notifications
- Image upload → Uploaded files: returns stored file URL
- Express API → Uploaded files: serves uploaded files
- Prisma access → PostgreSQL: queries