# rudracoderr/feel_backend architecture

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

- Interactive diagram: https://gitdiagram.com/rudracoderr/feel_backend
- Repository: https://github.com/rudracoderr/feel_backend

## Overview

1. **Overall shape**
   - This is a **Node.js + Express REST API** for the FEEL platform.
   - The app is split into a classic three-layer backend shape: **routes** for HTTP handling, **middleware** for request gating, **models** for MongoDB persistence, and a small **service** layer for notifications.

2. **Runtime and deployment boundary**
   - The API starts from **`server.js`** and listens on **port 5000**.
   - It is intended for **Railway** deployment.
   - Configuration is driven by environment variables, especially **`MONGO_URI`** and Firebase Admin credentials.

3. **Persistence layer**
   - Data is stored in **MongoDB Atlas** through **Mongoose**.
   - The main domain collections are represented by:
     - `usermodel.js`
     - `report-model.js`
     - `adoption-listing-model.js`
     - `abuse-report-model.js`
     - `notification-model.js`
     - `audit-log-model.js`
     - `ngo-model.js`
   - These models define the data boundary for users, rescue reports, adoption listings, abuse/moderation records, notifications, audit history, and NGO metadata.

4. **External identity and messaging**
   - **Firebase Admin SDK** is the main external integration.
   - It is used for:
     - **verifying Firebase ID tokens** on protected routes
     - supporting **push/messaging workflows** via the notification service
   - The repo includes Firebase initialization/config files in `Config/` and a root-level `firebase-admin.js`, which together indicate a centralized Firebase bootstrap path.

5. **Security and access control**
   - Authentication is enforced by middleware in `middleware/requireAuth.js`.
   - Authorization is split into:
     - `requireAdmin.js` for admin-only operations
     - `requireActiveUser.js` for blocking suspended/inactive users from sensitive actions
   - This creates a clear security boundary between:
     - public reads
     - authenticated user actions
     - privileged moderation/admin actions

6. **HTTP API surface**
   - Routes are organized by domain:
     - `Routes/users-routes.js`
     - `Routes/report-routes.js`
     - `Routes/adoption-routes.js`
     - `Routes/notification-routes.js`
     - `Routes/admin-routes.js`
   - The API is mounted under **`/api`**, with public health/test endpoints outside or adjacent to the main API namespace.

7. **Core user workflow: rescue reports**
   - The rescue-report subsystem is one of the main business flows.
   - It supports:
     - creating reports
     - listing reports with optional radius filtering
     - volunteers claiming/accepting reports
     - updating progress and resolving/canceling work
     - deleting reports
     - filing abuse reports against a report
   - This flow crosses multiple layers: user auth, report persistence, notification dispatch, and admin moderation.

8. **Adoption workflow**
   - Adoption listings are handled as a separate domain from rescue reports.
   - Users can create adoption listings, while the public can browse approved listings.
   - Admin routes can approve, reject, or mark adoption listings as adopted, which suggests a moderation gate before listings become public.

9. **User and volunteer administration**
   - User profiles are stored in MongoDB and managed through `/api/users`.
   - A user’s **device token** can be updated, which is important for push notification delivery.
   - Admin routes manage:
     - user suspension/unsuspension
     - volunteer approval/rejection/suspension
     - viewing user-associated reports
   - This makes user state central to both access control and workflow eligibility.

10. **Moderation and audit trail**
   - The admin subsystem is broader than simple CRUD.
   - It includes:
     - report moderation states such as resolved/fake/pending
     - NGO management
     - adoption moderation
     - audit log retrieval
   - `audit-log-model.js` indicates that important admin actions are recorded for traceability, which is a separate concern from the operational data models.

11. **Notification subsystem**
   - `Services/notification-service.js` sits between domain events and outbound messaging/storage.
   - The presence of both a notification model and Firebase Admin messaging support suggests a dual notification path:
     - persist notifications in MongoDB
     - optionally send push notifications using device tokens/Firebase
   - This service likely reacts to state changes in reports, adoptions, or admin actions.

12. **Architectural boundaries to show in a diagram**
   - **Client/API consumers** call Express routes.
   - **Middleware** enforces auth, admin role, and active-user checks before domain logic runs.
   - **Route handlers** coordinate the request.
   - **Mongoose models** persist to MongoDB Atlas.
   - **Firebase Admin** is used for identity verification and messaging.
   - **Notification service** bridges domain events to stored notifications and push delivery.
   - The main business domains are **users**, **rescue reports**, **adoptions**, **moderation/admin**, and **notifications**.

Main entry points: [`Routes/admin-routes.js`](https://github.com/rudracoderr/feel_backend/blob/main/Routes/admin-routes.js) (Admin), [`server.js`](https://github.com/rudracoderr/feel_backend/blob/main/server.js) (server.js), [`Routes/report-routes.js`](https://github.com/rudracoderr/feel_backend/blob/main/Routes/report-routes.js) (Reports), [`middleware/requireAuth.js`](https://github.com/rudracoderr/feel_backend/blob/main/middleware/requireAuth.js) (Auth Gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server["server.js<br/>entrypoint<br/>[server.js]"]
  node_api_consumers(("API Clients<br/>consumer"))
end

subgraph group_api["API Layer"]
  node_users_routes["Users<br/>route<br/>[users-routes.js]"]
  node_report_routes["Reports<br/>route<br/>[report-routes.js]"]
  node_adoption_routes["Adoptions<br/>route<br/>[adoption-routes.js]"]
  node_notification_routes["Notifications<br/>route"]
  node_admin_routes["Admin<br/>route<br/>[admin-routes.js]"]
end

subgraph group_security["Security"]
  node_require_auth{{"Auth Gate<br/>middleware<br/>[requireAuth.js]"}}
  node_require_active{{"Active User<br/>middleware"}}
  node_require_admin{{"Admin Gate<br/>middleware<br/>[requireAdmin.js]"}}
end

subgraph group_domain["Domain"]
  node_notification_service["Notify Service"]
end

subgraph group_data["Data Models"]
  node_user_model[("Users<br/>mongoose model<br/>[usermodel.js]")]
  node_report_model[("Reports<br/>mongoose model<br/>[report-model.js]")]
  node_adoption_model[("Listings<br/>mongoose model")]
  node_abuse_model[("Abuse Reports<br/>mongoose model")]
  node_notification_model[("Notifications<br/>mongoose model")]
  node_audit_model[("Audit Logs<br/>mongoose model<br/>[audit-log-model.js]")]
  node_ngo_model[("NGOs<br/>mongoose model<br/>[ngo-model.js]")]
end

subgraph group_integrations["Integrations"]
  node_firebase_config["Firebase Config<br/>[firebase.js]"]
  node_firebase_admin["Firebase Admin<br/>bootstrap<br/>[firebase-admin.js]"]
  node_firebase_sdk["Firebase Admin SDK<br/>external service"]
  node_mongo_atlas[("MongoDB Atlas<br/>external database")]
end

node_api_consumers -->|"HTTP requests"| node_server
node_server -->|"mounts"| node_users_routes
node_server -->|"mounts"| node_report_routes
node_server -->|"mounts"| node_adoption_routes
node_server -->|"mounts"| node_notification_routes
node_server -->|"mounts"| node_admin_routes
node_users_routes -->|"guards"| node_require_auth
node_report_routes -->|"guards"| node_require_auth
node_report_routes -->|"guards"| node_require_active
node_adoption_routes -->|"guards"| node_require_auth
node_admin_routes -->|"guards"| node_require_auth
node_admin_routes -->|"guards"| node_require_admin
node_admin_routes -->|"guards"| node_require_active
node_users_routes -->|"reads/writes"| node_user_model
node_report_routes -->|"reads/writes"| node_report_model
node_report_routes -->|"writes"| node_abuse_model
node_report_routes -->|"events"| node_notification_service
node_adoption_routes -->|"reads/writes"| node_adoption_model
node_notification_routes -->|"reads/writes"| node_notification_model
node_admin_routes -->|"reads/writes"| node_audit_model
node_admin_routes -->|"reads/writes"| node_ngo_model
node_admin_routes -->|"moderates"| node_user_model
node_notification_service -->|"persists"| node_notification_model
node_notification_service -->|"pushes"| node_firebase_sdk
node_firebase_admin -->|"initializes"| node_firebase_sdk
node_firebase_config -->|"configures"| node_firebase_admin
node_require_auth -->|"verifies tokens"| node_firebase_sdk
node_user_model -->|"persists to"| node_mongo_atlas
node_report_model -->|"persists to"| node_mongo_atlas
node_adoption_model -->|"persists to"| node_mongo_atlas
node_abuse_model -->|"persists to"| node_mongo_atlas
node_notification_model -->|"persists to"| node_mongo_atlas
node_audit_model -->|"persists to"| node_mongo_atlas
node_ngo_model -->|"persists to"| node_mongo_atlas

click node_server "https://github.com/rudracoderr/feel_backend/blob/main/server.js"
click node_users_routes "https://github.com/rudracoderr/feel_backend/blob/main/Routes/users-routes.js"
click node_report_routes "https://github.com/rudracoderr/feel_backend/blob/main/Routes/report-routes.js"
click node_adoption_routes "https://github.com/rudracoderr/feel_backend/blob/main/Routes/adoption-routes.js"
click node_notification_routes "https://github.com/rudracoderr/feel_backend/blob/main/Routes/notification-routes.js"
click node_admin_routes "https://github.com/rudracoderr/feel_backend/blob/main/Routes/admin-routes.js"
click node_require_auth "https://github.com/rudracoderr/feel_backend/blob/main/middleware/requireAuth.js"
click node_require_active "https://github.com/rudracoderr/feel_backend/blob/main/middleware/requireActiveUser.js"
click node_require_admin "https://github.com/rudracoderr/feel_backend/blob/main/middleware/requireAdmin.js"
click node_notification_service "https://github.com/rudracoderr/feel_backend/blob/main/Services/notification-service.js"
click node_user_model "https://github.com/rudracoderr/feel_backend/blob/main/Models/usermodel.js"
click node_report_model "https://github.com/rudracoderr/feel_backend/blob/main/Models/report-model.js"
click node_adoption_model "https://github.com/rudracoderr/feel_backend/blob/main/Models/adoption-listing-model.js"
click node_abuse_model "https://github.com/rudracoderr/feel_backend/blob/main/Models/abuse-report-model.js"
click node_notification_model "https://github.com/rudracoderr/feel_backend/blob/main/Models/notification-model.js"
click node_audit_model "https://github.com/rudracoderr/feel_backend/blob/main/Models/audit-log-model.js"
click node_ngo_model "https://github.com/rudracoderr/feel_backend/blob/main/Models/ngo-model.js"
click node_firebase_config "https://github.com/rudracoderr/feel_backend/blob/main/Config/firebase.js"
click node_firebase_admin "https://github.com/rudracoderr/feel_backend/blob/main/firebase-admin.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_server,node_api_consumers toneBlue
class node_users_routes,node_report_routes,node_adoption_routes,node_notification_routes,node_admin_routes toneAmber
class node_require_auth,node_require_active,node_require_admin toneMint
class node_notification_service toneRose
class node_user_model,node_report_model,node_adoption_model,node_abuse_model,node_notification_model,node_audit_model,node_ngo_model toneIndigo
class node_firebase_config,node_firebase_admin,node_firebase_sdk,node_mongo_atlas toneTeal
```

## Components

### Runtime

Process entrypoint and deployment boundary

- [server.js](https://github.com/rudracoderr/feel_backend/blob/main/server.js): entrypoint · Starts the Express app and listens on port 5000 · `server.js`
- **API Clients**: consumer · Mobile or frontend clients calling the REST API

### API Layer

Express routes and request handling

- [Users](https://github.com/rudracoderr/feel_backend/blob/main/Routes/users-routes.js): route · User profile, device token, and volunteer-facing operations · `Routes/users-routes.js`
- [Reports](https://github.com/rudracoderr/feel_backend/blob/main/Routes/report-routes.js): route · Rescue report workflow endpoints · `Routes/report-routes.js`
- [Adoptions](https://github.com/rudracoderr/feel_backend/blob/main/Routes/adoption-routes.js): route · Adoption listing endpoints and public browsing · `Routes/adoption-routes.js`
- [Notifications](https://github.com/rudracoderr/feel_backend/blob/main/Routes/notification-routes.js): route · Notification read and delivery endpoints · `Routes/notification-routes.js`
- [Admin](https://github.com/rudracoderr/feel_backend/blob/main/Routes/admin-routes.js): route · Moderation, approval, suspension, and audit endpoints · `Routes/admin-routes.js`

### Security

Authentication and access control middleware

- [Auth Gate](https://github.com/rudracoderr/feel_backend/blob/main/middleware/requireAuth.js): middleware · Verifies Firebase ID tokens for protected routes · `middleware/requireAuth.js`
- [Active User](https://github.com/rudracoderr/feel_backend/blob/main/middleware/requireActiveUser.js): middleware · Blocks suspended or inactive users from sensitive actions · `middleware/requireActiveUser.js`
- [Admin Gate](https://github.com/rudracoderr/feel_backend/blob/main/middleware/requireAdmin.js): middleware · Restricts privileged operations to admins · `middleware/requireAdmin.js`

### Domain

Core business subsystems

- [Notify Service](https://github.com/rudracoderr/feel_backend/blob/main/Services/notification-service.js): service · Bridges domain events to stored notifications and push delivery · `Services/notification-service.js`

### Data Models

MongoDB/Mongoose persistence boundary

- [Users](https://github.com/rudracoderr/feel_backend/blob/main/Models/usermodel.js): mongoose model · User accounts, roles, status, and device tokens · `Models/usermodel.js`
- [Reports](https://github.com/rudracoderr/feel_backend/blob/main/Models/report-model.js): mongoose model · Rescue reports and status lifecycle · `Models/report-model.js`
- [Listings](https://github.com/rudracoderr/feel_backend/blob/main/Models/adoption-listing-model.js): mongoose model · Adoption listings and approval state · `Models/adoption-listing-model.js`
- [Abuse Reports](https://github.com/rudracoderr/feel_backend/blob/main/Models/abuse-report-model.js): mongoose model · Moderation reports filed against rescue reports · `Models/abuse-report-model.js`
- [Notifications](https://github.com/rudracoderr/feel_backend/blob/main/Models/notification-model.js): mongoose model · Persisted user notifications · `Models/notification-model.js`
- [Audit Logs](https://github.com/rudracoderr/feel_backend/blob/main/Models/audit-log-model.js): mongoose model · Admin action history for traceability · `Models/audit-log-model.js`
- [NGOs](https://github.com/rudracoderr/feel_backend/blob/main/Models/ngo-model.js): mongoose model · NGO metadata and management records · `Models/ngo-model.js`

### Integrations

External identity and messaging services

- [Firebase Config](https://github.com/rudracoderr/feel_backend/blob/main/Config/firebase.js): config · Firebase bootstrap and initialization settings · `Config/firebase.js`
- [Firebase Admin](https://github.com/rudracoderr/feel_backend/blob/main/firebase-admin.js): bootstrap · Central Firebase Admin initialization entry · `firebase-admin.js`
- **Firebase Admin SDK**: external service · Token verification and push messaging backend
- **MongoDB Atlas**: external database · Primary persistence backend accessed through Mongoose

## Connections

- API Clients → server.js: HTTP requests · Clients call the Express API
- server.js → Users: mounts · Registers user routes
- server.js → Reports: mounts · Registers report routes
- server.js → Adoptions: mounts · Registers adoption routes
- server.js → Notifications: mounts · Registers notification routes
- server.js → Admin: mounts · Registers admin routes
- Users → Auth Gate: guards · Protects authenticated user actions
- Reports → Auth Gate: guards · Protects report operations
- Reports → Active User: guards · Blocks inactive users from sensitive report actions
- Adoptions → Auth Gate: guards · Protects listing creation and owner actions
- Admin → Auth Gate: guards · Requires authenticated admin caller
- Admin → Admin Gate: guards · Enforces admin-only access
- Admin → Active User: guards · Ensures active account status for privileged actions
- Users → Users: reads/writes · Manages user profiles and device tokens
- Reports → Reports: reads/writes · Creates and updates rescue reports
- Reports → Abuse Reports: writes · Stores abuse reports against incidents
- Reports → Notify Service: events · Triggers notifications on workflow changes
- Adoptions → Listings: reads/writes · Creates, lists, and moderates adoption listings
- Notifications → Notifications: reads/writes · Exposes persisted notifications to users
- Admin → Audit Logs: reads/writes · Records and retrieves admin audit history
- Admin → NGOs: reads/writes · Manages NGO metadata
- Admin → Users: moderates · Suspends, approves, or rejects users and volunteers
- Notify Service → Notifications: persists · Stores notification records in MongoDB
- Notify Service → Firebase Admin SDK: pushes · Sends push messages through Firebase
- Firebase Admin → Firebase Admin SDK: initializes · Central Firebase Admin bootstrap
- Firebase Config → Firebase Admin: configures · Provides Firebase initialization settings
- Auth Gate → Firebase Admin SDK: verifies tokens · Uses Firebase Admin to validate ID tokens
- Users → MongoDB Atlas: persists to · Mongoose-backed MongoDB storage
- Reports → MongoDB Atlas: persists to · Mongoose-backed MongoDB storage
- Listings → MongoDB Atlas: persists to · Mongoose-backed MongoDB storage
- Abuse Reports → MongoDB Atlas: persists to · Mongoose-backed MongoDB storage
- Notifications → MongoDB Atlas: persists to · Mongoose-backed MongoDB storage
- Audit Logs → MongoDB Atlas: persists to · Mongoose-backed MongoDB storage
- NGOs → MongoDB Atlas: persists to · Mongoose-backed MongoDB storage
