# freefiremax/paithan-digital-platform architecture

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

- Interactive diagram: https://gitdiagram.com/freefiremax/paithan-digital-platform
- Repository: https://github.com/freefiremax/paithan-digital-platform

## Overview

Paithan Digital Platform combines municipal information and administration, citizen services, heritage and tourism content, and a bilingual AI assistant. A principal citizen workflow is submitting a grievance, which the API validates, verifies, stores with a tracking number, and makes available for later tracking. Administrators manage civic content through protected APIs. Relationships below are grounded in the README or shown source references and excerpts; unsampled feature implementations are represented at their existing route directories, and their internal wiring is not inferred.

Main entry points: [`lib/auth/guard.ts`](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/auth/guard.ts) (Role and access checks), [`lib/db.ts`](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/db.ts) (Prisma data store), [`app/api/grievances/route.ts`](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/grievances/route.ts) (Grievance intake), [`app/api/chatbot/route.ts`](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/chatbot/route.ts) (Chatbot API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public information"]
  node_public_portal["Public portal<br/>[page.tsx]"]
  node_civic_info["Council information"]
  node_heritage["Heritage exhibits"]
  node_tourism["Tourism guides"]
  node_ward_map["Ward map<br/>[PaithanWardMap.tsx]"]
  node_search_ui["Search interface<br/>[SearchClient.tsx]"]
  node_search_api["Search API<br/>[route.ts]"]
end

subgraph group_civic["Civic services"]
  node_grievance_form["Grievance submission<br/>[GrievanceForm.tsx]"]
  node_grievance_api["Grievance intake<br/>[route.ts]"]
  node_grievance_track["Ticket tracking<br/>[route.ts]"]
  node_contact_api["Contact intake<br/>[route.ts]"]
end

subgraph group_governance["Admin governance"]
  node_admin_ui["Governance CMS"]
  node_admin_api["Civic management API"]
  node_sector_api["Sector management<br/>[route.ts]"]
  node_upload_api["Authenticated uploads<br/>[route.ts]"]
end

subgraph group_assistant["AI assistant"]
  node_rag["Local knowledge base<br/>[rag.ts]"]
  node_chat_api["Chatbot API<br/>[route.ts]"]
  node_chat_ui["Chat interface<br/>[ChatInterface.tsx]"]
end

subgraph group_core["Platform foundations"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_auth_guard["Role and access checks<br/>[guard.ts]"]
  node_permissions["Role permissions<br/>[permissions.ts]"]
  node_database[("Prisma data store<br/>[db.ts]")]
  node_audit["Audit logging<br/>[audit.ts]"]
  node_rate_limit["Rate limiting<br/>[rate-limit.ts]"]
  node_turnstile["Turnstile verification<br/>[turnstile.ts]"]
  node_cloudflare_gate["Security gate"]
  node_client_providers["Client providers"]
  node_cloudinary["Media storage integration<br/>[cloudinary.ts]"]
end

node_visitor(("Citizen or visitor"))
node_gemini{{"Google Gemini"}}

node_visitor -->|"visits"| node_public_portal
node_public_portal -->|"renders"| node_ward_map
node_visitor -->|"explores"| node_civic_info
node_visitor -->|"explores"| node_heritage
node_visitor -->|"explores"| node_tourism
node_visitor -.->|"searches"| node_search_ui
node_search_ui -.->|"requests results"| node_search_api
node_search_api -->|"queries"| node_database
node_visitor -.->|"submits issue"| node_grievance_form
node_grievance_form -.->|"posts details"| node_grievance_api
node_grievance_api -->|"verifies token"| node_turnstile
node_grievance_api -->|"stores ticket"| node_database
node_visitor -.->|"tracks ticket"| node_grievance_track
node_visitor -.->|"sends message"| node_contact_api
node_admin_ui -.->|"manages records"| node_admin_api
node_admin_api -->|"checks access"| node_auth_guard
node_sector_api -->|"checks access"| node_auth_guard
node_auth_guard -->|"reads session"| node_auth
node_auth_guard -->|"checks roles"| node_permissions
node_auth_guard -->|"loads user"| node_database
node_auth -->|"uses adapter"| node_database
node_sector_api -->|"reads and updates"| node_database
node_sector_api -->|"records change"| node_audit
node_audit -->|"writes log"| node_database
node_chat_ui -.->|"sends query"| node_chat_api
node_chat_api -->|"retrieves context"| node_rag
node_chat_api -->|"requests generation"| node_gemini
node_chat_api -->|"checks quota"| node_rate_limit
node_grievance_api -->|"checks quota"| node_rate_limit
node_client_providers -->|"renders"| node_cloudflare_gate
node_upload_api -->|"requires login"| node_auth_guard
node_upload_api -->|"uploads media"| node_cloudinary
node_upload_api -->|"checks quota"| node_rate_limit

click node_public_portal "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/%5Blocale%5D/(public)/page.tsx"
click node_civic_info "https://github.com/freefiremax/paithan-digital-platform/tree/main/app/%5Blocale%5D/(public)/nagar-parishad"
click node_heritage "https://github.com/freefiremax/paithan-digital-platform/tree/main/app/%5Blocale%5D/(public)/heritage"
click node_tourism "https://github.com/freefiremax/paithan-digital-platform/tree/main/app/%5Blocale%5D/(public)/tourism"
click node_ward_map "https://github.com/freefiremax/paithan-digital-platform/blob/main/components/home/PaithanWardMap.tsx"
click node_search_ui "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/%5Blocale%5D/search/SearchClient.tsx"
click node_search_api "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/search/route.ts"
click node_grievance_form "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/%5Blocale%5D/grievances/new/GrievanceForm.tsx"
click node_grievance_api "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/grievances/route.ts"
click node_grievance_track "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/grievances/track/route.ts"
click node_contact_api "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/contact/route.ts"
click node_admin_ui "https://github.com/freefiremax/paithan-digital-platform/tree/main/app/%5Blocale%5D/admin"
click node_admin_api "https://github.com/freefiremax/paithan-digital-platform/tree/main/app/api/admin"
click node_sector_api "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/sectors/%5Bsector%5D/route.ts"
click node_auth "https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/auth/auth.ts"
click node_auth_guard "https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/auth/guard.ts"
click node_permissions "https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/auth/permissions.ts"
click node_database "https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/db.ts"
click node_audit "https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/audit.ts"
click node_rag "https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/rag.ts"
click node_chat_api "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/chatbot/route.ts"
click node_chat_ui "https://github.com/freefiremax/paithan-digital-platform/blob/main/components/chatbot/ChatInterface.tsx"
click node_rate_limit "https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/rate-limit.ts"
click node_turnstile "https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/turnstile.ts"
click node_cloudflare_gate "https://github.com/freefiremax/paithan-digital-platform/blob/main/components/security/CloudflareSecurityGate.tsx"
click node_client_providers "https://github.com/freefiremax/paithan-digital-platform/blob/main/components/providers/ClientProviders.tsx"
click node_cloudinary "https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/cloudinary.ts"
click node_upload_api "https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/upload/route.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_public_portal,node_civic_info,node_heritage,node_tourism,node_ward_map,node_search_ui,node_search_api toneBlue
class node_grievance_form,node_grievance_api,node_grievance_track,node_contact_api toneAmber
class node_admin_ui,node_admin_api,node_sector_api,node_upload_api toneMint
class node_rag,node_chat_api,node_chat_ui toneRose
class node_auth,node_auth_guard,node_permissions,node_database,node_audit,node_rate_limit,node_turnstile,node_cloudflare_gate,node_client_providers,node_cloudinary,node_visitor,node_gemini toneIndigo
```

## Components

### Public information

- [Public portal](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/%5Blocale%5D/(public)/page.tsx): `app/[locale]/(public)/page.tsx`
- [Council information](https://github.com/freefiremax/paithan-digital-platform/tree/main/app/%5Blocale%5D/(public)/nagar-parishad): `app/[locale]/(public)/nagar-parishad`
- [Heritage exhibits](https://github.com/freefiremax/paithan-digital-platform/tree/main/app/%5Blocale%5D/(public)/heritage): `app/[locale]/(public)/heritage`
- [Tourism guides](https://github.com/freefiremax/paithan-digital-platform/tree/main/app/%5Blocale%5D/(public)/tourism): `app/[locale]/(public)/tourism`
- [Ward map](https://github.com/freefiremax/paithan-digital-platform/blob/main/components/home/PaithanWardMap.tsx): `components/home/PaithanWardMap.tsx`
- [Search interface](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/%5Blocale%5D/search/SearchClient.tsx): `app/[locale]/search/SearchClient.tsx`
- [Search API](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/search/route.ts): `app/api/search/route.ts`

### Civic services

- [Grievance submission](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/%5Blocale%5D/grievances/new/GrievanceForm.tsx): `app/[locale]/grievances/new/GrievanceForm.tsx`
- [Grievance intake](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/grievances/route.ts): `app/api/grievances/route.ts`
- [Ticket tracking](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/grievances/track/route.ts): `app/api/grievances/track/route.ts`
- [Contact intake](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/contact/route.ts): `app/api/contact/route.ts`

### Admin governance

- [Governance CMS](https://github.com/freefiremax/paithan-digital-platform/tree/main/app/%5Blocale%5D/admin): `app/[locale]/admin`
- [Civic management API](https://github.com/freefiremax/paithan-digital-platform/tree/main/app/api/admin): `app/api/admin`
- [Sector management](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/sectors/%5Bsector%5D/route.ts): `app/api/sectors/[sector]/route.ts`
- [Authenticated uploads](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/upload/route.ts): `app/api/upload/route.ts`

### AI assistant

- [Local knowledge base](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/rag.ts): `lib/rag.ts`
- [Chatbot API](https://github.com/freefiremax/paithan-digital-platform/blob/main/app/api/chatbot/route.ts): `app/api/chatbot/route.ts`
- [Chat interface](https://github.com/freefiremax/paithan-digital-platform/blob/main/components/chatbot/ChatInterface.tsx): `components/chatbot/ChatInterface.tsx`

### Platform foundations

- [Authentication](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/auth/auth.ts): `lib/auth/auth.ts`
- [Role and access checks](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/auth/guard.ts): `lib/auth/guard.ts`
- [Role permissions](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/auth/permissions.ts): `lib/auth/permissions.ts`
- [Prisma data store](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/db.ts): `lib/db.ts`
- [Audit logging](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/audit.ts): `lib/audit.ts`
- [Rate limiting](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/rate-limit.ts): `lib/rate-limit.ts`
- [Turnstile verification](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/turnstile.ts): `lib/turnstile.ts`
- [Security gate](https://github.com/freefiremax/paithan-digital-platform/blob/main/components/security/CloudflareSecurityGate.tsx): `components/security/CloudflareSecurityGate.tsx`
- [Client providers](https://github.com/freefiremax/paithan-digital-platform/blob/main/components/providers/ClientProviders.tsx): `components/providers/ClientProviders.tsx`
- [Media storage integration](https://github.com/freefiremax/paithan-digital-platform/blob/main/lib/cloudinary.ts): `lib/cloudinary.ts`

### Other components

- **Citizen or visitor**
- **Google Gemini**

## Connections

- Citizen or visitor → Public portal: visits
- Public portal → Ward map: renders (evidence: `app/[locale]/(public)/page.tsx`)
- Citizen or visitor → Council information: explores
- Citizen or visitor → Heritage exhibits: explores
- Citizen or visitor → Tourism guides: explores
- Citizen or visitor → Search interface: searches
- Search interface → Search API: requests results
- Search API → Prisma data store: queries (evidence: `app/api/search/route.ts`)
- Citizen or visitor → Grievance submission: submits issue
- Grievance submission → Grievance intake: posts details
- Grievance intake → Turnstile verification: verifies token (evidence: `app/api/grievances/route.ts`)
- Grievance intake → Prisma data store: stores ticket (evidence: `app/api/grievances/route.ts`)
- Citizen or visitor → Ticket tracking: tracks ticket
- Citizen or visitor → Contact intake: sends message
- Governance CMS → Civic management API: manages records
- Civic management API → Role and access checks: checks access (evidence: `app/api/admin/facilities/route.ts`)
- Sector management → Role and access checks: checks access (evidence: `app/api/sectors/[sector]/route.ts`)
- Role and access checks → Authentication: reads session (evidence: `lib/auth/guard.ts`)
- Role and access checks → Role permissions: checks roles (evidence: `lib/auth/guard.ts`)
- Role and access checks → Prisma data store: loads user (evidence: `lib/auth/guard.ts`)
- Authentication → Prisma data store: uses adapter (evidence: `lib/auth/auth.ts`)
- Sector management → Prisma data store: reads and updates (evidence: `app/api/sectors/[sector]/route.ts`)
- Sector management → Audit logging: records change (evidence: `app/api/sectors/[sector]/route.ts`)
- Audit logging → Prisma data store: writes log (evidence: `lib/audit.ts`)
- Chat interface → Chatbot API: sends query
- Chatbot API → Local knowledge base: retrieves context (evidence: `app/api/chatbot/route.ts`)
- Chatbot API → Google Gemini: requests generation (evidence: `app/api/chatbot/route.ts`)
- Chatbot API → Rate limiting: checks quota (evidence: `app/api/chatbot/route.ts`)
- Grievance intake → Rate limiting: checks quota (evidence: `app/api/grievances/route.ts`)
- Client providers → Security gate: renders (evidence: `components/providers/ClientProviders.tsx`)
- Authenticated uploads → Role and access checks: requires login (evidence: `app/api/upload/route.ts`)
- Authenticated uploads → Media storage integration: uploads media (evidence: `app/api/upload/route.ts`)
- Authenticated uploads → Rate limiting: checks quota (evidence: `app/api/upload/route.ts`)
