# sanjaygoud009/pawmira architecture

> Architecture diagram of the GitHub repository sanjaygoud009/pawmira, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanjaygoud009/pawmira
- Repository: https://github.com/sanjaygoud009/pawmira

## Overview

#### Purpose and Entry Points
PawMira is a MERN rescue-operations system for reporting injured animals, triaging cases, and enabling NGO response. The browser application starts at `client/src/main.jsx` and composes UI/routing from `client/src/App.jsx`. The Express API starts at `server/server.js`, connects through `server/config/db.js`, and exposes domain route modules.

#### Client Application and User Flows
React provides public information, authentication, emergency reporting, rescue feed, lost/found, volunteer, and NGO/admin experiences. Key operational pages are `client/src/pages/ReportEmergency.jsx`, `client/src/pages/Dashboard.jsx`, and `client/src/pages/AdminDashboard.jsx`. Shared report UI covers photo intake, location selection, and report presentation in `client/src/components/report/ImageUpload.jsx`, `client/src/components/report/LocationPicker.jsx`, and `client/src/components/report/RescueCard.jsx`.

#### Identity and Authorization Boundary
Client auth state is centralized in `client/src/context/AuthContext.jsx`, with consumer access through `client/src/hooks/useAuth.js`. Backend JWT authentication and access control are enforced by `server/middleware/auth.js`; identity persistence is modeled in `server/models/User.js`. Auth lifecycle endpoints are defined by `server/routes/auth.js` and implemented in `server/controllers/authController.js`.

#### Rescue Report Lifecycle
Reports enter from the web reporting flow or WhatsApp integration, pass through route/controller handling, and persist as rescue records. The core API boundary is `server/routes/reports.js` → `server/controllers/reportController.js` → `server/models/Report.js`. The Report model supports soft deletion, priority/status history, and geospatial location queries; dashboard/feed consumers retrieve and act on this operational queue.

#### Media and Location Processing
Images are compressed before submission in `client/src/utils/imageCompressor.js`, then validated and accepted by upload middleware in `server/middleware/upload.js`. Cloudinary integration is configured in `server/config/cloudinary.js`; image validation resides in `server/utils/imageValidator.js`. Location selected client-side is stored in MongoDB report data, whose geospatial indexing supports proximity/filtering for responders.

#### Messaging, Notifications, and WhatsApp Intake
In-app rescue conversations use `server/routes/rescueMessageRoutes.js`, `server/controllers/rescueMessageController.js`, and `server/models/RescueMessage.js`; broader messaging has a separate `messagesRoutes` domain. Notifications are independently exposed through `server/routes/notifications.js` and persisted in `server/models/Notification.js`. Twilio WhatsApp webhook/chatbot flow is isolated in `server/routes/whatsapp.js` and `server/controllers/whatsappController.js`, with temporary conversational state in TTL-backed `server/models/WhatsAppSession.js`.

#### Supporting Operational Domains and Runtime
Lost/found animal records are a separate workflow from emergency reports, centered on `server/routes/lostFound.js`, `server/controllers/lostFoundController.js`, and `server/models/LostPet.js`/`server/models/FoundPet.js`. Admin operations, rankings/gamification, contact handling, escalations, cleanup, and email are backend service domains. Runtime infrastructure is Node/Express, MongoDB/Mongoose, Cloudinary, and Twilio; client deployment configuration is present at `client/vercel.json`, with PWA/offline assets in `client/public/sw.js`.

Main entry points: [`server/server.js`](https://github.com/sanjaygoud009/pawmira/blob/main/server/server.js) (API server), [`server/routes/reports.js`](https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/reports.js) (Rescue reports API), [`client/src/App.jsx`](https://github.com/sanjaygoud009/pawmira/blob/main/client/src/App.jsx) (App routing), [`server/routes/auth.js`](https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/auth.js) (Auth lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_main(("Browser entry<br/>React bootstrap<br/>[main.jsx]"))
  node_client_app["App routing<br/>React app<br/>[App.jsx]"]
  node_auth_context["Auth state<br/>React context<br/>[AuthContext.jsx]"]
  node_report_ui["Emergency reporting<br/>React pages"]
  node_report_components["Report intake UI<br/>React components<br/>[ImageUpload.jsx]"]
  node_image_compressor["Image compression<br/>client utility<br/>[imageCompressor.js]"]
end

subgraph group_api["Express API"]
  node_express_server{{"API server<br/>Node/Express<br/>[server.js]"}}
  node_auth_api["Auth lifecycle<br/>route/controller<br/>[auth.js]"]
  node_auth_guard["JWT access control<br/>Express middleware<br/>[auth.js]"]
  node_reports_api["Rescue reports API<br/>route/controller<br/>[reports.js]"]
  node_upload_pipeline["Upload validation<br/>middleware<br/>[upload.js]"]
  node_rescue_messages["Rescue conversations<br/>route/controller"]
  node_notifications_api["Notifications<br/>route domain<br/>[notifications.js]"]
  node_whatsapp_api["WhatsApp intake<br/>webhook/controller<br/>[whatsapp.js]"]
  node_lost_found_api["Lost and found<br/>route/controller<br/>[lostFound.js]"]
end

subgraph group_data["Data and integrations"]
  node_mongodb[("MongoDB connection<br/>Mongoose datastore<br/>[db.js]")]
  node_user_model["Users<br/>Mongoose model<br/>[User.js]"]
  node_report_model[("Rescue records<br/>Mongoose model<br/>[Report.js]")]
  node_messaging_models["Conversation state<br/>Mongoose models<br/>[RescueMessage.js]"]
  node_notification_model["Notification records<br/>Mongoose model<br/>[Notification.js]"]
  node_cloudinary{{"Cloudinary<br/>media service<br/>[cloudinary.js]"}}
  node_twilio{{"Twilio WhatsApp<br/>messaging service"}}
end

node_client_main -->|"renders"| node_client_app
node_client_app -->|"provides auth"| node_auth_context
node_client_app -->|"routes to"| node_report_ui
node_report_ui -->|"uses"| node_report_components
node_report_components -->|"compresses images"| node_image_compressor
node_client_app -->|"auth requests"| node_auth_api
node_report_ui -->|"submits and queries"| node_reports_api
node_express_server -->|"mounts"| node_auth_api
node_express_server -->|"mounts"| node_reports_api
node_express_server -->|"mounts"| node_rescue_messages
node_express_server -->|"mounts"| node_notifications_api
node_express_server -->|"mounts"| node_whatsapp_api
node_express_server -->|"mounts"| node_lost_found_api
node_auth_api -->|"protects access"| node_auth_guard
node_auth_api -->|"manages"| node_user_model
node_reports_api -->|"enforces roles"| node_auth_guard
node_reports_api -->|"processes uploads"| node_upload_pipeline
node_upload_pipeline -->|"stores images"| node_cloudinary
node_reports_api -->|"persists queue"| node_report_model
node_rescue_messages -->|"persists"| node_messaging_models
node_notifications_api -->|"persists"| node_notification_model
node_whatsapp_api -->|"webhook/chatbot"| node_twilio
node_whatsapp_api -->|"creates reports"| node_report_model
node_express_server -->|"connects"| node_mongodb

click node_client_main "https://github.com/sanjaygoud009/pawmira/blob/main/client/src/main.jsx"
click node_client_app "https://github.com/sanjaygoud009/pawmira/blob/main/client/src/App.jsx"
click node_auth_context "https://github.com/sanjaygoud009/pawmira/blob/main/client/src/context/AuthContext.jsx"
click node_report_ui "https://github.com/sanjaygoud009/pawmira/blob/main/client/src/pages/ReportEmergency.jsx"
click node_report_components "https://github.com/sanjaygoud009/pawmira/blob/main/client/src/components/report/ImageUpload.jsx"
click node_image_compressor "https://github.com/sanjaygoud009/pawmira/blob/main/client/src/utils/imageCompressor.js"
click node_express_server "https://github.com/sanjaygoud009/pawmira/blob/main/server/server.js"
click node_auth_api "https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/auth.js"
click node_auth_guard "https://github.com/sanjaygoud009/pawmira/blob/main/server/middleware/auth.js"
click node_reports_api "https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/reports.js"
click node_upload_pipeline "https://github.com/sanjaygoud009/pawmira/blob/main/server/middleware/upload.js"
click node_rescue_messages "https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/rescueMessageRoutes.js"
click node_notifications_api "https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/notifications.js"
click node_whatsapp_api "https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/whatsapp.js"
click node_lost_found_api "https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/lostFound.js"
click node_mongodb "https://github.com/sanjaygoud009/pawmira/blob/main/server/config/db.js"
click node_user_model "https://github.com/sanjaygoud009/pawmira/blob/main/server/models/User.js"
click node_report_model "https://github.com/sanjaygoud009/pawmira/blob/main/server/models/Report.js"
click node_messaging_models "https://github.com/sanjaygoud009/pawmira/blob/main/server/models/RescueMessage.js"
click node_notification_model "https://github.com/sanjaygoud009/pawmira/blob/main/server/models/Notification.js"
click node_cloudinary "https://github.com/sanjaygoud009/pawmira/blob/main/server/config/cloudinary.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_client_main,node_client_app,node_auth_context,node_report_ui,node_report_components,node_image_compressor toneBlue
class node_express_server,node_auth_api,node_auth_guard,node_reports_api,node_upload_pipeline,node_rescue_messages,node_notifications_api,node_whatsapp_api,node_lost_found_api toneAmber
class node_mongodb,node_user_model,node_report_model,node_messaging_models,node_notification_model,node_cloudinary,node_twilio toneMint
```

## Components

### React client

- [Browser entry](https://github.com/sanjaygoud009/pawmira/blob/main/client/src/main.jsx): React bootstrap · `client/src/main.jsx`
- [App routing](https://github.com/sanjaygoud009/pawmira/blob/main/client/src/App.jsx): React app · `client/src/App.jsx`
- [Auth state](https://github.com/sanjaygoud009/pawmira/blob/main/client/src/context/AuthContext.jsx): React context · Provides identity state through useAuth. · `client/src/context/AuthContext.jsx`
- [Emergency reporting](https://github.com/sanjaygoud009/pawmira/blob/main/client/src/pages/ReportEmergency.jsx): React pages · Report, responder dashboard, and admin dashboard flows. · `client/src/pages/ReportEmergency.jsx`
- [Report intake UI](https://github.com/sanjaygoud009/pawmira/blob/main/client/src/components/report/ImageUpload.jsx): React components · Photo intake, location selection, and rescue cards. · `client/src/components/report/ImageUpload.jsx`
- [Image compression](https://github.com/sanjaygoud009/pawmira/blob/main/client/src/utils/imageCompressor.js): client utility · `client/src/utils/imageCompressor.js`

### Express API

- [API server](https://github.com/sanjaygoud009/pawmira/blob/main/server/server.js): Node/Express · Mounts domain routes and initializes the API. · `server/server.js`
- [Auth lifecycle](https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/auth.js): route/controller · `server/routes/auth.js`
- [JWT access control](https://github.com/sanjaygoud009/pawmira/blob/main/server/middleware/auth.js): Express middleware · `server/middleware/auth.js`
- [Rescue reports API](https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/reports.js): route/controller · Receives, updates, and retrieves the operational rescue queue. · `server/routes/reports.js`
- [Upload validation](https://github.com/sanjaygoud009/pawmira/blob/main/server/middleware/upload.js): middleware · Accepts validated report image uploads. · `server/middleware/upload.js`
- [Rescue conversations](https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/rescueMessageRoutes.js): route/controller · `server/routes/rescueMessageRoutes.js`
- [Notifications](https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/notifications.js): route domain · `server/routes/notifications.js`
- [WhatsApp intake](https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/whatsapp.js): webhook/controller · Twilio chatbot intake for rescue reports. · `server/routes/whatsapp.js`
- [Lost and found](https://github.com/sanjaygoud009/pawmira/blob/main/server/routes/lostFound.js): route/controller · Separate workflow for lost and found animals. · `server/routes/lostFound.js`

### Data and integrations

- [MongoDB connection](https://github.com/sanjaygoud009/pawmira/blob/main/server/config/db.js): Mongoose datastore · `server/config/db.js`
- [Users](https://github.com/sanjaygoud009/pawmira/blob/main/server/models/User.js): Mongoose model · `server/models/User.js`
- [Rescue records](https://github.com/sanjaygoud009/pawmira/blob/main/server/models/Report.js): Mongoose model · Tracks status and priority history, soft deletion, and geospatial locations. · `server/models/Report.js`
- [Conversation state](https://github.com/sanjaygoud009/pawmira/blob/main/server/models/RescueMessage.js): Mongoose models · Rescue messages plus TTL-backed WhatsApp sessions. · `server/models/RescueMessage.js`
- [Notification records](https://github.com/sanjaygoud009/pawmira/blob/main/server/models/Notification.js): Mongoose model · `server/models/Notification.js`
- [Cloudinary](https://github.com/sanjaygoud009/pawmira/blob/main/server/config/cloudinary.js): media service · `server/config/cloudinary.js`
- **Twilio WhatsApp**: messaging service

## Connections

- Browser entry → App routing: renders
- App routing → Auth state: provides auth
- App routing → Emergency reporting: routes to
- Emergency reporting → Report intake UI: uses
- Report intake UI → Image compression: compresses images
- App routing → Auth lifecycle: auth requests
- Emergency reporting → Rescue reports API: submits and queries
- API server → Auth lifecycle: mounts
- API server → Rescue reports API: mounts
- API server → Rescue conversations: mounts
- API server → Notifications: mounts
- API server → WhatsApp intake: mounts
- API server → Lost and found: mounts
- Auth lifecycle → JWT access control: protects access
- Auth lifecycle → Users: manages
- Rescue reports API → JWT access control: enforces roles
- Rescue reports API → Upload validation: processes uploads
- Upload validation → Cloudinary: stores images
- Rescue reports API → Rescue records: persists queue
- Rescue conversations → Conversation state: persists
- Notifications → Notification records: persists
- WhatsApp intake → Twilio WhatsApp: webhook/chatbot
- WhatsApp intake → Rescue records: creates reports
- API server → MongoDB connection: connects