# tashdik-29/shopninja-server architecture

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

- Interactive diagram: https://gitdiagram.com/tashdik-29/shopninja-server
- Repository: https://github.com/tashdik-29/shopninja-server

## Overview

1. **Repository shape**
   - This is a small Node.js backend service, not a multi-package or microservice system.
   - The top level contains only `index.js`, `package.json`, `package-lock.json`, `vercel.json`, and the README, which suggests a single deployable API entrypoint with minimal internal file structure exposed in this snapshot.

2. **Core runtime**
   - The application runs on **Node.js** with **Express.js** as the HTTP server layer.
   - `index.js` is the main bootstrap file and is likely responsible for creating the server, registering middleware, and wiring API routes.

3. **Primary domain**
   - The domain is a **delivery management system** called **ShopNinja**.
   - The system centers on parcel booking, approval, assignment, tracking, and delivery-status updates.

4. **User roles and boundaries**
   - There are three functional actors:
     - **User**: books parcels and tracks delivery progress.
     - **Admin**: approves bookings, views all parcels, and assigns parcels to delivery personnel.
     - **Deliveryman**: receives assigned parcels and updates delivery status.
   - These roles define the main authorization boundaries in the architecture.

5. **API security and identity**
   - The backend uses **JWT** to secure API access and enforce role-based behavior.
   - The README also states **Firebase** is used for authentication, so authentication appears split between Firebase sign-in/sign-up and JWT-based authorization for protected API operations.
   - In architecture terms, Firebase is the identity provider, while JWT is the session/access-control mechanism for the backend.

6. **Data layer**
   - **MongoDB** is the persistent datastore.
   - It likely stores user profiles, parcel bookings, approval state, assignment state, and delivery history.
   - The data model is probably centered on parcel lifecycle records rather than isolated feature-specific services.

7. **Parcel lifecycle flow**
   - The main business flow is:
     - User creates a parcel booking.
     - Booking enters a pending state.
     - Admin reviews and approves it.
     - Admin assigns it to a deliveryman.
     - Deliveryman updates delivery progress and final delivery status.
     - User can view status updates and history.
   - This is the central data flow for the whole system.

8. **Operational dashboards**
   - The README describes separate dashboards for admin, user, and deliveryman, which implies role-specific API endpoints and views on the client side.
   - The backend serves these dashboards by exposing different parcel queries and mutations depending on role and authorization level.

9. **Deployment / hosting**
   - `vercel.json` indicates the service is configured for **Vercel** deployment.
   - That suggests the backend may be deployed as a serverless/edge-friendly Node application or a Vercel-hosted API, rather than a traditional long-running VM service.

10. **External integrations**
   - The README mentions a **Stripe Secret Key** in environment setup, implying payment-related capabilities or future payment integration, even though payment flow is not described in detail.
   - The key external services affecting architecture are therefore:
     - **MongoDB** for persistence
     - **Firebase** for authentication
     - **JWT** for API authorization
     - **Stripe** for payment-related integration

11. **Architectural summary**
   - Overall, the repo appears to implement a **single-service monolithic API** with a simple server entrypoint, external auth, MongoDB persistence, and role-based parcel workflows.
   - The important diagram boundaries are: client dashboards on one side, the Express API in the middle, and MongoDB/Firebase/Stripe as external dependencies on the other side.

Main entry points: [`index.js`](https://github.com/tashdik-29/shopninja-server/blob/main/index.js) (index.js), [`vercel.json`](https://github.com/tashdik-29/shopninja-server/blob/main/vercel.json) (Vercel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["API Service"]
  node_n_index["index.js<br/>bootstrap entrypoint<br/>[index.js]"]
  node_n_express["Express API<br/>http server"]
  node_n_auth{{"JWT Guard<br/>auth middleware"}}
  node_n_routes["Role Routes<br/>api routes"]
end

subgraph group_grp_domain["Parcel Domain"]
  node_n_user_api["User API<br/>client-facing endpoints"]
  node_n_admin_api["Admin API<br/>approval workflow"]
  node_n_delivery_api["Delivery API<br/>status workflow"]
  node_n_parcels(("Parcel Flow<br/>business model"))
  node_n_history["Tracking Data<br/>read model"]
end

subgraph group_grp_external["External Systems"]
  node_n_db[("MongoDB<br/>persistent store")]
  node_n_firebase{{"Firebase<br/>identity provider"}}
  node_n_stripe["Stripe<br/>payment integration"]
  node_n_vercel["Vercel<br/>deployment target<br/>[vercel.json]"]
end

node_n_clients["Dashboards<br/>frontend consumers"]

node_n_index -->|"boots"| node_n_express
node_n_index -->|"registers"| node_n_auth
node_n_index -->|"mounts"| node_n_routes
node_n_express -->|"deploys on"| node_n_vercel
node_n_clients -->|"calls"| node_n_routes
node_n_routes -->|"exposes"| node_n_user_api
node_n_routes -->|"exposes"| node_n_admin_api
node_n_routes -->|"exposes"| node_n_delivery_api
node_n_auth -->|"verifies identity"| node_n_firebase
node_n_auth -->|"authorizes"| node_n_routes
node_n_user_api -->|"creates"| node_n_parcels
node_n_admin_api -->|"approves/assigns"| node_n_parcels
node_n_delivery_api -->|"updates"| node_n_parcels
node_n_parcels -->|"records"| node_n_history
node_n_user_api -->|"reads/writes"| node_n_db
node_n_admin_api -->|"reads/writes"| node_n_db
node_n_delivery_api -->|"reads/writes"| node_n_db
node_n_routes -.->|"integrates"| node_n_stripe

click node_n_index "https://github.com/tashdik-29/shopninja-server/blob/main/index.js"
click node_n_vercel "https://github.com/tashdik-29/shopninja-server/blob/main/vercel.json"

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_n_index,node_n_express,node_n_auth,node_n_routes toneBlue
class node_n_user_api,node_n_admin_api,node_n_delivery_api,node_n_parcels,node_n_history toneAmber
class node_n_db,node_n_firebase,node_n_stripe,node_n_vercel toneMint
class node_n_clients toneNeutral
```

## Components

### API Service

Single Node.js backend entrypoint and request handling layer

- [index.js](https://github.com/tashdik-29/shopninja-server/blob/main/index.js): bootstrap entrypoint · Main server bootstrap and wiring file · `index.js`
- **Express API**: http server · HTTP application layer and route registration
- **JWT Guard**: auth middleware · Protects API access and enforces session-based authorization
- **Role Routes**: api routes · Separates user, admin, and deliveryman operations

### Parcel Domain

Role-based delivery workflow and business operations

- **User API**: client-facing endpoints · Booking and tracking actions for parcel owners
- **Admin API**: approval workflow · Reviews bookings, assigns parcels, and oversees all parcels
- **Delivery API**: status workflow · Updates delivery progress and completion status
- **Parcel Flow**: business model · Core booking-to-delivery lifecycle state machine
- **Tracking Data**: read model · Parcel status history and user-visible progress views

### External Systems

Identity, persistence, payment, and hosting dependencies

- **MongoDB**: persistent store · Stores users, parcels, assignments, and delivery records
- **Firebase**: identity provider · Authentication source for sign-in and sign-up
- **Stripe**: payment integration · Payment-related external service referenced by environment setup
- [Vercel](https://github.com/tashdik-29/shopninja-server/blob/main/vercel.json): deployment target · Serverless hosting and deployment configuration target · `vercel.json`

### Other components

- **Dashboards**: frontend consumers · User, admin, and deliveryman dashboard clients that consume the API

## Connections

- index.js → Express API: boots · Creates and configures the HTTP app
- index.js → JWT Guard: registers · Adds authorization layer to protected routes
- index.js → Role Routes: mounts · Attaches API route groups
- Express API → Vercel: deploys on · Runs as a Vercel-hosted Node service
- Dashboards → Role Routes: calls · Dashboard clients invoke the role-specific API
- Role Routes → User API: exposes · User-facing booking and tracking endpoints
- Role Routes → Admin API: exposes · Admin approval and assignment endpoints
- Role Routes → Delivery API: exposes · Delivery status update endpoints
- JWT Guard → Firebase: verifies identity · Authentication begins with Firebase-backed identity
- JWT Guard → Role Routes: authorizes · Checks JWT claims and role access
- User API → Parcel Flow: creates · User booking initiates parcel lifecycle
- Admin API → Parcel Flow: approves/assigns · Admin advances parcels through workflow
- Delivery API → Parcel Flow: updates · Deliveryman changes parcel delivery state
- Parcel Flow → Tracking Data: records · Lifecycle changes feed tracking history
- User API → MongoDB: reads/writes · Persists bookings and retrieves status
- Admin API → MongoDB: reads/writes · Stores approvals, assignments, and parcel views
- Delivery API → MongoDB: reads/writes · Stores delivery progress and completion updates
- Role Routes → Stripe: integrates · Potential payment integration point