# syntaxraw/civic-forge-miniproject architecture

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

- Interactive diagram: https://gitdiagram.com/syntaxraw/civic-forge-miniproject
- Repository: https://github.com/syntaxraw/civic-forge-miniproject

## Overview

CivicForge lets residents report and corroborate civic issues, while staff track progress and hand issues off to departments. The main flow runs from report submission through duplicate detection, trust/spam checks, priority scoring and in-memory storage; browsing, maps, leaderboard and staff actions are distinct product branches. The README documents live updates and optional translation. Sampled source supports the issue-route integrations; unsampled routes are represented at their exact paths, with uncertain internal links omitted.

Main entry points: [`server/src/routes/issues.js`](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/routes/issues.js) (Issue routes), [`client/src/App.jsx`](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/App.jsx) (Page routing), [`client/src/api.js`](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/api.js) (HTTP client), [`client/src/pages/IssueDetail.jsx`](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/IssueDetail.jsx) (Issue detail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Page routing<br/>[App.jsx]"]
  node_authpages["Sign in and register<br/>[AuthPages.jsx]"]
  node_authstate["Browser auth state<br/>[auth.jsx]"]
  node_home["Issue feed<br/>[Home.jsx]"]
  node_report["Issue reporting<br/>[Report.jsx]"]
  node_detail["Issue detail<br/>[IssueDetail.jsx]"]
  node_prioritypage["Priority view<br/>[Priority.jsx]"]
  node_mappage["Issue map<br/>[MapPage.jsx]"]
  node_leaderboard["Leaderboard<br/>[Leaderboard.jsx]"]
  node_issuecard["Issue card<br/>[IssueCard.jsx]"]
  node_mapview["Map renderer<br/>[MapView.jsx]"]
  node_status["Status display<br/>[StatusBadge.jsx]"]
end

subgraph group_api["API and access"]
  node_api_client["HTTP client<br/>[api.js]"]
  node_realtime_client["Live event listener<br/>[useRealtime.js]"]
  node_server["Express entry<br/>[index.js]"]
  node_authroutes["Auth routes<br/>[auth.js]"]
  node_authmw["Session middleware<br/>[auth.js]"]
end

subgraph group_issues["Issue lifecycle"]
  node_issueroutes["Issue routes<br/>[issues.js]"]
  node_store[("In-memory state<br/>[store.js]")]
  node_dedupe["Duplicate matching<br/>[dedupe.js]"]
  node_priority["Priority scoring<br/>[priority.js]"]
  node_trust["Trust and spam<br/>[trust.js]"]
  node_upload["Photo upload<br/>[upload.js]"]
  node_realtime["WebSocket broadcasts<br/>[realtime.js]"]
  node_translate["Optional translation<br/>[translate.js]"]
end

subgraph group_community["Community features"]
  node_misc["Stats and misc routes<br/>[misc.js]"]
end

node_resident(("Resident or staff"))

node_resident -->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_report
node_app -->|"routes to"| node_detail
node_app -->|"routes to"| node_prioritypage
node_app -->|"routes to"| node_mappage
node_app -->|"routes to"| node_leaderboard
node_app -->|"routes to"| node_authpages
node_authpages -->|"uses"| node_authstate
node_authstate -->|"calls"| node_api_client
node_home -->|"loads issues"| node_api_client
node_home -->|"renders"| node_issuecard
node_home -->|"subscribes"| node_realtime_client
node_report -->|"submits report"| node_api_client
node_report -->|"selects location"| node_mapview
node_detail -->|"loads and acts"| node_api_client
node_detail -->|"subscribes"| node_realtime_client
node_detail -->|"renders location"| node_mapview
node_detail -->|"renders progress"| node_status
node_prioritypage -->|"loads ranking"| node_api_client
node_prioritypage -->|"renders"| node_issuecard
node_mappage -->|"loads map issues"| node_api_client
node_mappage -->|"renders"| node_mapview
node_mappage -->|"subscribes"| node_realtime_client
node_leaderboard -->|"loads standings"| node_api_client
node_issuecard -->|"sends upvote"| node_api_client
node_issuecard -->|"renders status"| node_status
node_api_client -->|"calls API"| node_server
node_server -->|"mounts routes"| node_authroutes
node_server -->|"mounts routes"| node_issueroutes
node_server -->|"mounts routes"| node_misc
node_server -->|"starts service"| node_realtime
node_authroutes -->|"reads and writes"| node_store
node_authroutes -->|"sets sessions"| node_authmw
node_authmw -->|"loads users"| node_store
node_issueroutes -->|"reads and writes"| node_store
node_issueroutes -->|"checks access"| node_authmw
node_issueroutes -->|"accepts photos"| node_upload
node_issueroutes -->|"checks duplicates"| node_dedupe
node_issueroutes -->|"scores issues"| node_priority
node_issueroutes -->|"checks trust"| node_trust
node_issueroutes -->|"broadcasts updates"| node_realtime
node_issueroutes -->|"translates detail"| node_translate
node_misc -->|"reads state"| node_store
node_misc -->|"uses translation"| node_translate
node_realtime_client -->|"receives updates"| node_realtime

click node_app "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/App.jsx"
click node_authpages "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/AuthPages.jsx"
click node_authstate "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/auth.jsx"
click node_home "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/Home.jsx"
click node_report "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/Report.jsx"
click node_detail "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/IssueDetail.jsx"
click node_prioritypage "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/Priority.jsx"
click node_mappage "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/MapPage.jsx"
click node_leaderboard "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/Leaderboard.jsx"
click node_issuecard "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/components/IssueCard.jsx"
click node_mapview "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/components/MapView.jsx"
click node_status "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/components/StatusBadge.jsx"
click node_api_client "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/api.js"
click node_realtime_client "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/useRealtime.js"
click node_server "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/index.js"
click node_authroutes "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/routes/auth.js"
click node_authmw "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/middleware/auth.js"
click node_issueroutes "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/routes/issues.js"
click node_store "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/store.js"
click node_dedupe "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/dedupe.js"
click node_priority "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/priority.js"
click node_trust "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/trust.js"
click node_upload "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/middleware/upload.js"
click node_realtime "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/realtime.js"
click node_translate "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/translate.js"
click node_misc "https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/routes/misc.js"

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_authpages,node_authstate,node_home,node_report,node_detail,node_prioritypage,node_mappage,node_leaderboard,node_issuecard,node_mapview,node_status toneBlue
class node_api_client,node_realtime_client,node_server,node_authroutes,node_authmw toneAmber
class node_issueroutes,node_store,node_dedupe,node_priority,node_trust,node_upload,node_realtime,node_translate toneMint
class node_misc toneRose
class node_resident toneIndigo
```

## Components

### Web experience

- [Page routing](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Sign in and register](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/AuthPages.jsx): `client/src/pages/AuthPages.jsx`
- [Browser auth state](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/auth.jsx): `client/src/auth.jsx`
- [Issue feed](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/Home.jsx): `client/src/pages/Home.jsx`
- [Issue reporting](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/Report.jsx): `client/src/pages/Report.jsx`
- [Issue detail](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/IssueDetail.jsx): `client/src/pages/IssueDetail.jsx`
- [Priority view](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/Priority.jsx): `client/src/pages/Priority.jsx`
- [Issue map](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/MapPage.jsx): `client/src/pages/MapPage.jsx`
- [Leaderboard](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/pages/Leaderboard.jsx): `client/src/pages/Leaderboard.jsx`
- [Issue card](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/components/IssueCard.jsx): `client/src/components/IssueCard.jsx`
- [Map renderer](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/components/MapView.jsx): `client/src/components/MapView.jsx`
- [Status display](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/components/StatusBadge.jsx): `client/src/components/StatusBadge.jsx`

### API and access

- [HTTP client](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/api.js): `client/src/api.js`
- [Live event listener](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/client/src/useRealtime.js): `client/src/useRealtime.js`
- [Express entry](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/index.js): `server/src/index.js`
- [Auth routes](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/routes/auth.js): `server/src/routes/auth.js`
- [Session middleware](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/middleware/auth.js): `server/src/middleware/auth.js`

### Issue lifecycle

- [Issue routes](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/routes/issues.js): `server/src/routes/issues.js`
- [In-memory state](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/store.js): `server/src/store.js`
- [Duplicate matching](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/dedupe.js): `server/src/services/dedupe.js`
- [Priority scoring](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/priority.js): `server/src/services/priority.js`
- [Trust and spam](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/trust.js): `server/src/services/trust.js`
- [Photo upload](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/middleware/upload.js): `server/src/middleware/upload.js`
- [WebSocket broadcasts](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/realtime.js): `server/src/services/realtime.js`
- [Optional translation](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/services/translate.js): `server/src/services/translate.js`

### Community features

- [Stats and misc routes](https://github.com/syntaxraw/civic-forge-miniproject/blob/main/server/src/routes/misc.js): `server/src/routes/misc.js`

### Other components

- **Resident or staff**

## Connections

- Resident or staff → Page routing: uses (evidence: `client/src/App.jsx`)
- Page routing → Issue feed: routes to (evidence: `client/src/App.jsx`)
- Page routing → Issue reporting: routes to (evidence: `client/src/App.jsx`)
- Page routing → Issue detail: routes to (evidence: `client/src/App.jsx`)
- Page routing → Priority view: routes to (evidence: `client/src/App.jsx`)
- Page routing → Issue map: routes to (evidence: `client/src/App.jsx`)
- Page routing → Leaderboard: routes to (evidence: `client/src/App.jsx`)
- Page routing → Sign in and register: routes to (evidence: `client/src/App.jsx`)
- Sign in and register → Browser auth state: uses (evidence: `client/src/pages/AuthPages.jsx`)
- Browser auth state → HTTP client: calls (evidence: `client/src/auth.jsx`)
- Issue feed → HTTP client: loads issues (evidence: `client/src/pages/Home.jsx`)
- Issue feed → Issue card: renders (evidence: `client/src/pages/Home.jsx`)
- Issue feed → Live event listener: subscribes (evidence: `client/src/pages/Home.jsx`)
- Issue reporting → HTTP client: submits report (evidence: `client/src/pages/Report.jsx`)
- Issue reporting → Map renderer: selects location (evidence: `client/src/pages/Report.jsx`)
- Issue detail → HTTP client: loads and acts (evidence: `client/src/pages/IssueDetail.jsx`)
- Issue detail → Live event listener: subscribes (evidence: `client/src/pages/IssueDetail.jsx`)
- Issue detail → Map renderer: renders location (evidence: `client/src/pages/IssueDetail.jsx`)
- Issue detail → Status display: renders progress (evidence: `client/src/pages/IssueDetail.jsx`)
- Priority view → HTTP client: loads ranking (evidence: `client/src/pages/Priority.jsx`)
- Priority view → Issue card: renders (evidence: `client/src/pages/Priority.jsx`)
- Issue map → HTTP client: loads map issues (evidence: `client/src/pages/MapPage.jsx`)
- Issue map → Map renderer: renders (evidence: `client/src/pages/MapPage.jsx`)
- Issue map → Live event listener: subscribes (evidence: `client/src/pages/MapPage.jsx`)
- Leaderboard → HTTP client: loads standings (evidence: `client/src/pages/Leaderboard.jsx`)
- Issue card → HTTP client: sends upvote (evidence: `client/src/components/IssueCard.jsx`)
- Issue card → Status display: renders status (evidence: `client/src/components/IssueCard.jsx`)
- HTTP client → Express entry: calls API (evidence: `README.md`)
- Express entry → Auth routes: mounts routes (evidence: `server/src/index.js`)
- Express entry → Issue routes: mounts routes (evidence: `server/src/index.js`)
- Express entry → Stats and misc routes: mounts routes (evidence: `server/src/index.js`)
- Express entry → WebSocket broadcasts: starts service (evidence: `server/src/index.js`)
- Auth routes → In-memory state: reads and writes (evidence: `server/src/routes/auth.js`)
- Auth routes → Session middleware: sets sessions (evidence: `server/src/routes/auth.js`)
- Session middleware → In-memory state: loads users (evidence: `server/src/middleware/auth.js`)
- Issue routes → In-memory state: reads and writes (evidence: `server/src/routes/issues.js`)
- Issue routes → Session middleware: checks access (evidence: `server/src/routes/issues.js`)
- Issue routes → Photo upload: accepts photos (evidence: `server/src/routes/issues.js`)
- Issue routes → Duplicate matching: checks duplicates (evidence: `server/src/routes/issues.js`)
- Issue routes → Priority scoring: scores issues (evidence: `server/src/routes/issues.js`)
- Issue routes → Trust and spam: checks trust (evidence: `server/src/routes/issues.js`)
- Issue routes → WebSocket broadcasts: broadcasts updates (evidence: `server/src/routes/issues.js`)
- Issue routes → Optional translation: translates detail (evidence: `server/src/routes/issues.js`)
- Stats and misc routes → In-memory state: reads state (evidence: `server/src/routes/misc.js`)
- Stats and misc routes → Optional translation: uses translation (evidence: `server/src/routes/misc.js`)
- Live event listener → WebSocket broadcasts: receives updates (evidence: `client/src/useRealtime.js`)
