# mrtimonm/amar-shohor- architecture

> Architecture diagram of the GitHub repository mrtimonm/amar-shohor-, 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/mrtimonm/amar-shohor-
- Repository: https://github.com/mrtimonm/amar-shohor-

## Overview

Amar Shohor is a civic issue-reporting and municipal response application. Citizens browse a public map, submit geolocated, photo-backed reports, and follow their history; city staff review, verify, assign, and resolve issues, while administrators manage access and monitor operations. The web client communicates through a shared API layer with an Express API and MongoDB-backed domain models; shared definitions cover issue categories, roles, and lifecycle rules. The repository also includes a separate AI service. Edges reflect shown imports, route declarations, or calls; API route registration and several endpoint internals were not sampled, so those links are omitted or marked unverified.

Main entry points: [`amar-shohor/apps/web/src/App.tsx`](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/App.tsx) (Route shell), [`amar-shohor/apps/web/src/lib/api.ts`](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/lib/api.ts) (HTTP client), [`amar-shohor/apps/web/src/pages/ReportPage.tsx`](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/ReportPage.tsx) (Report submission), [`amar-shohor/apps/api/src/dedup.ts`](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/dedup.ts) (Report deduplication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Route shell<br/>[App.tsx]"]
  node_report_ui["Report submission<br/>[ReportPage.tsx]"]
  node_issue_ui["Issue details<br/>[IssuePage.tsx]"]
  node_home_ui["Public browse<br/>[HomePage.tsx]"]
  node_review_ui["Staff review<br/>[ReviewPage.tsx]"]
  node_admin_ui["Administration<br/>[AdminPage.tsx]"]
  node_other_ui["Maps, queue, stats"]
  node_api_client["HTTP client<br/>[api.ts]"]
  node_offline["Offline reports<br/>[offline.ts]"]
  node_auth_ui["Session context<br/>[auth-context.tsx]"]
end

subgraph group_api["API and domain"]
  node_api_routes["Issue and report endpoints"]
  node_authority["Authority workflow<br/>[authority.ts]"]
  node_auth_routes["Sign-in endpoints<br/>[auth.ts]"]
  node_admin_routes["Admin endpoints<br/>[admin.ts]"]
  node_auth_core["Authentication<br/>[auth.ts]"]
  node_dedup["Report deduplication<br/>[dedup.ts]"]
  node_models[("Domain models<br/>[models.ts]")]
  node_storage["Photo storage<br/>[storage.ts]"]
  node_api_core["HTTP and validation<br/>[http.ts]"]
end

subgraph group_shared["Shared domain"]
  node_domain["Categories and lifecycle<br/>[domain.ts]"]
end

subgraph group_ai["AI service"]
  node_ai_main["AI service API<br/>[main.py]"]
  node_vision["Vision analysis<br/>[vision.py]"]
  node_registry["Model registry<br/>[registry.py]"]
end

node_citizen(("Citizen / staff"))

node_citizen -.->|"uses"| node_app
node_app -->|"routes to"| node_report_ui
node_app -->|"routes to"| node_issue_ui
node_app -->|"routes to"| node_home_ui
node_app -->|"routes to"| node_review_ui
node_app -->|"routes to"| node_admin_ui
node_app -->|"routes to"| node_other_ui
node_report_ui -->|"calls"| node_api_client
node_issue_ui -->|"calls"| node_api_client
node_home_ui -->|"calls"| node_api_client
node_review_ui -->|"calls"| node_api_client
node_admin_ui -->|"calls"| node_api_client
node_api_client -.->|"HTTP requests"| node_api_routes
node_report_ui -->|"queues offline"| node_offline
node_auth_ui -->|"fetches session"| node_api_client
node_auth_routes -->|"uses"| node_auth_core
node_authority -->|"uses"| node_auth_core
node_authority -->|"invokes"| node_dedup
node_auth_core -->|"loads user"| node_models
node_api_routes -.->|"uses"| node_models
node_dedup -->|"uses"| node_models
node_dedup -.->|"requests analysis"| node_ai_main
node_ai_main -->|"calls"| node_vision
node_ai_main -->|"uses"| node_registry
node_vision -->|"uses"| node_registry

click node_app "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/App.tsx"
click node_report_ui "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/ReportPage.tsx"
click node_issue_ui "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/IssuePage.tsx"
click node_home_ui "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/HomePage.tsx"
click node_review_ui "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/ReviewPage.tsx"
click node_admin_ui "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/AdminPage.tsx"
click node_other_ui "https://github.com/mrtimonm/amar-shohor-/tree/main/amar-shohor/apps/web/src/pages"
click node_api_client "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/lib/api.ts"
click node_offline "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/lib/offline.ts"
click node_auth_ui "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/lib/auth-context.tsx"
click node_api_routes "https://github.com/mrtimonm/amar-shohor-/tree/main/amar-shohor/apps/api/src/routes"
click node_authority "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/routes/authority.ts"
click node_auth_routes "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/routes/auth.ts"
click node_admin_routes "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/routes/admin.ts"
click node_auth_core "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/auth.ts"
click node_dedup "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/dedup.ts"
click node_models "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/models.ts"
click node_storage "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/storage.ts"
click node_api_core "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/http.ts"
click node_domain "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/packages/shared/src/domain.ts"
click node_ai_main "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/services/ai/app/main.py"
click node_vision "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/services/ai/app/vision.py"
click node_registry "https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/services/ai/app/registry.py"

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_ui,node_issue_ui,node_home_ui,node_review_ui,node_admin_ui,node_other_ui,node_api_client,node_offline,node_auth_ui toneBlue
class node_api_routes,node_authority,node_auth_routes,node_admin_routes,node_auth_core,node_dedup,node_models,node_storage,node_api_core toneAmber
class node_domain toneMint
class node_ai_main,node_vision,node_registry toneRose
class node_citizen toneIndigo
```

## Components

### Web client

- [Route shell](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/App.tsx): `amar-shohor/apps/web/src/App.tsx`
- [Report submission](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/ReportPage.tsx): `amar-shohor/apps/web/src/pages/ReportPage.tsx`
- [Issue details](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/IssuePage.tsx): `amar-shohor/apps/web/src/pages/IssuePage.tsx`
- [Public browse](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/HomePage.tsx): `amar-shohor/apps/web/src/pages/HomePage.tsx`
- [Staff review](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/ReviewPage.tsx): `amar-shohor/apps/web/src/pages/ReviewPage.tsx`
- [Administration](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/pages/AdminPage.tsx): `amar-shohor/apps/web/src/pages/AdminPage.tsx`
- [Maps, queue, stats](https://github.com/mrtimonm/amar-shohor-/tree/main/amar-shohor/apps/web/src/pages): `amar-shohor/apps/web/src/pages`
- [HTTP client](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/lib/api.ts): `amar-shohor/apps/web/src/lib/api.ts`
- [Offline reports](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/lib/offline.ts): `amar-shohor/apps/web/src/lib/offline.ts`
- [Session context](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/web/src/lib/auth-context.tsx): `amar-shohor/apps/web/src/lib/auth-context.tsx`

### API and domain

- [Issue and report endpoints](https://github.com/mrtimonm/amar-shohor-/tree/main/amar-shohor/apps/api/src/routes): `amar-shohor/apps/api/src/routes`
- [Authority workflow](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/routes/authority.ts): `amar-shohor/apps/api/src/routes/authority.ts`
- [Sign-in endpoints](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/routes/auth.ts): `amar-shohor/apps/api/src/routes/auth.ts`
- [Admin endpoints](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/routes/admin.ts): `amar-shohor/apps/api/src/routes/admin.ts`
- [Authentication](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/auth.ts): `amar-shohor/apps/api/src/auth.ts`
- [Report deduplication](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/dedup.ts): `amar-shohor/apps/api/src/dedup.ts`
- [Domain models](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/models.ts): `amar-shohor/apps/api/src/models.ts`
- [Photo storage](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/storage.ts): `amar-shohor/apps/api/src/storage.ts`
- [HTTP and validation](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/apps/api/src/http.ts): `amar-shohor/apps/api/src/http.ts`

### Shared domain

- [Categories and lifecycle](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/packages/shared/src/domain.ts): `amar-shohor/packages/shared/src/domain.ts`

### AI service

- [AI service API](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/services/ai/app/main.py): `amar-shohor/services/ai/app/main.py`
- [Vision analysis](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/services/ai/app/vision.py): `amar-shohor/services/ai/app/vision.py`
- [Model registry](https://github.com/mrtimonm/amar-shohor-/blob/main/amar-shohor/services/ai/app/registry.py): `amar-shohor/services/ai/app/registry.py`

### Other components

- **Citizen / staff**

## Connections

- Citizen / staff → Route shell: uses
- Route shell → Report submission: routes to (evidence: `amar-shohor/apps/web/src/App.tsx`)
- Route shell → Issue details: routes to (evidence: `amar-shohor/apps/web/src/App.tsx`)
- Route shell → Public browse: routes to (evidence: `amar-shohor/apps/web/src/App.tsx`)
- Route shell → Staff review: routes to (evidence: `amar-shohor/apps/web/src/App.tsx`)
- Route shell → Administration: routes to (evidence: `amar-shohor/apps/web/src/App.tsx`)
- Route shell → Maps, queue, stats: routes to (evidence: `amar-shohor/apps/web/src/App.tsx`)
- Report submission → HTTP client: calls (evidence: `amar-shohor/apps/web/src/pages/ReportPage.tsx`)
- Issue details → HTTP client: calls (evidence: `amar-shohor/apps/web/src/pages/IssuePage.tsx`)
- Public browse → HTTP client: calls (evidence: `amar-shohor/apps/web/src/pages/HomePage.tsx`)
- Staff review → HTTP client: calls (evidence: `amar-shohor/apps/web/src/pages/ReviewPage.tsx`)
- Administration → HTTP client: calls (evidence: `amar-shohor/apps/web/src/pages/AdminPage.tsx`)
- HTTP client → Issue and report endpoints: HTTP requests
- Report submission → Offline reports: queues offline (evidence: `amar-shohor/apps/web/src/pages/ReportPage.tsx`)
- Session context → HTTP client: fetches session (evidence: `amar-shohor/apps/web/src/lib/auth-context.tsx`)
- Sign-in endpoints → Authentication: uses (evidence: `amar-shohor/apps/api/src/routes/auth.ts`)
- Authority workflow → Authentication: uses (evidence: `amar-shohor/apps/api/src/routes/authority.ts`)
- Authority workflow → Report deduplication: invokes (evidence: `amar-shohor/apps/api/src/routes/authority.ts`)
- Authentication → Domain models: loads user (evidence: `amar-shohor/apps/api/src/auth.ts`)
- Issue and report endpoints → Domain models: uses (evidence: `amar-shohor/apps/api/src/routes/authority.ts`)
- Report deduplication → Domain models: uses (evidence: `amar-shohor/apps/api/src/dedup.ts`)
- Report deduplication → AI service API: requests analysis
- AI service API → Vision analysis: calls (evidence: `amar-shohor/services/ai/app/main.py`)
- AI service API → Model registry: uses (evidence: `amar-shohor/services/ai/app/main.py`)
- Vision analysis → Model registry: uses (evidence: `amar-shohor/services/ai/app/vision.py`)
