# meghnaroyal/fastcourier architecture

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

- Interactive diagram: https://gitdiagram.com/meghnaroyal/fastcourier
- Repository: https://github.com/meghnaroyal/fastcourier

## Overview

##### What this project is (from README + file tree)
**FastCourier** is a **web-based courier management system** covering the lifecycle from **package registration → dispatch → delivery tracking**, with **user** and **administrator** interfaces, plus:
- **Realtime tracking**
- **Automated notifications**
- **Analytics/reports**

From the repo layout, you clearly have:
- A **database schema** (`database/courierdb1.sql`)
- A **Node-based web deployment pipeline** (`.github/workflows/azure-webapps-node.yml`)
- A **frontend** directory (`frontend/…`) that includes an `.env` and even `dumpfile.js` (suggesting Node tooling/scripts)

- the backend exists but isn’t shown here,
- the backend is inside `frontend/` (e.g., Next.js API routes, or an Express server co-located),
- or the system is currently frontend + DB only (unlikely given “realtime tracking” + “notifications”).

##### System Context (1 page, high-level)
Actors and external dependencies:
- **End User (Customer)**: registers packages, views tracking
- **Admin/Operations**: manages couriers, dispatch, analytics
- **FastCourier System**: the product boundary
- Likely external services (based on features; include only if used/planned):
- **Maps/Geocoding** provider (for realtime location visualization)
- **SMS/Email/Push** provider (notifications)
- Possibly **Identity Provider** (if auth is external), otherwise “Auth in backend”

##### Web Client (Browser SPA or SSR Web App)
- Served from: Azure Web App (if combined) or static hosting (if separate)
- Reads configuration from `frontend/.env` (call out “build-time env” vs “runtime env”)

##### Backend API (Node.js)
- If present in repo: locate entrypoint (`server.js`, `app.js`, `api/`, `routes/`)
- Authentication/Authorization (user vs admin roles)
- Package Registration
- Dispatch/Assignment
- Tracking ingestion + querying
- Notification orchestration
- Analytics/report generation

##### Realtime Channel
- If implemented: WebSockets / Socket.IO / SSE
- part of Backend API (“Realtime Gateway inside API”), or
- separate service (“Realtime service”) if scaled independently

##### Database (SQL)
- From `database/courierdb1.sql`, label it explicitly:
- “CourierDB (SQL)”
- Main entity groupings (even if approximate):
- Users/Admins
- Packages/Shipments
- Tracking Events / Location updates
- Notifications log
- Reports/aggregations (or derived queries)

##### Notification Providers (External)
- Email/SMS gateways (e.g., SendGrid/Twilio) if used

##### Analytics/Reporting
- If it’s just SQL queries + backend endpoints: keep inside Backend API as a component
- If it’s heavy/batch: show a background worker or scheduled job

##### CI/CD + Hosting (Azure + GitHub Actions)
- A small “Deployment” area:
- GitHub Actions workflow (`azure-webapps-node.yml`) → Azure Web App

- Browser → Backend API: HTTPS/REST (label endpoints conceptually: `/packages`, `/tracking`, `/admin/reports`)
- Browser ↔ Realtime: WebSocket/SSE for live tracking updates
- Backend API → DB: SQL queries/transactions
- Backend API → Notification Provider: SMTP/HTTP API
- (Optional) Courier device/app → Backend API: tracking location updates (if couriers send GPS)

- **API Layer**
- Controllers/Routes (User, Admin, Tracking)
- **Domain/Service Layer**
- PackageService
- TrackingService
- NotificationService
- ReportingService
- AuthService
- **Infrastructure Layer**
- DB access/repositories
- Realtime adapter (Socket.IO)
- External notification adapters
- **Background Jobs**
- Notification retries
- Daily/weekly report generation
- Tracking cleanup/aggregation

Dependencies: Controllers → Services → Repositories/Adapters.

- `database/courierdb1.sql`

- `frontend/`
- “Azure Web App (Node) hosts both UI and API”
- If API is separate but missing here, keep API as its own container and annotate “backend repo/service not shown in this tree”.

- `.github/workflows/azure-webapps-node.yml`

- `frontend/.env`
- => indicate configuration for:
- API base URL
- keys (maps, notifications) *never drawn as raw secrets*, just “ENV config”

- `frontend/dumpfile.js`

Also, since `frontend/node_modules` is present (and should typically be gitignored), don’t model it; it’s not an architecture component.

##### Detail level guidance (don’t overthink, just decompose)
If a feature is called out in README, it should appear somewhere:
- “Realtime tracking” => realtime channel + tracking ingestion + tracking queries
- “Automated notifications” => notification service + provider(s) + templates/events
- “Analytics reports” => reporting module + DB queries/aggregations + admin UI pages

##### System Context
- Actors: User, Admin, (Courier if applicable)
- External: Maps, Notification provider
- System boundary: FastCourier

- Browser Web UI
- Node Backend API
- Realtime channel
- SQL DB
- Notification provider
- Azure Web App hosting
- GitHub Actions pipeline

- Routes/Controllers
- Services: Package, Tracking, Notification, Reporting, Auth
- Repos/DB layer
- Realtime adapter
- Job scheduler/worker (if used)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Actors
    %% =========================
    subgraph "Actors"
        U["End User (Customer)"]:::actor
        A["Admin / Operations"]:::actor
        C["Courier (Mobile/Device)"]:::actor
    end

    %% =========================
    %% FastCourier System Boundary
    %% =========================
    subgraph "FastCourier System"
        direction TB

        subgraph "Client Layer"
            direction TB
            WEB["Web Client (Browser)"]:::client
            UI["Web UI (User + Admin interface)"]:::frontend
            ENV["Frontend Env Config (.env)"]:::config
            UTIL["Utility / Ops Script (dump/export/import)"]:::ops
        end

        subgraph "Hosting / Runtime (Azure)"
            direction TB
            AZ["Azure Web App (Node hosting)"]:::hosting
        end

        subgraph "Application Layer"
            direction TB

            API["Backend API (Node.js)"]:::service
            RT["Realtime Gateway (WebSocket/SSE)"]:::service

            subgraph "Backend Components"
                direction TB
                AUTH["Auth Service (roles: user/admin)"]:::component
                PKG["Package Registration Service"]:::component
                DSP["Dispatch / Assignment Service"]:::component
                TRK["Tracking Service (ingest + query)"]:::component
                NOTIF["Notification Orchestrator"]:::component
                RPT["Analytics / Reporting Service"]:::component
                JOBS["Background Jobs / Scheduler"]:::component
                REPO["DB Access Layer (Repositories/DAO)"]:::component
                RTAD["Realtime Adapter"]:::component
                EXTAD["External Provider Adapters"]:::component
            end
        end

        subgraph "Data Layer"
            direction TB
            DB[("CourierDB (SQL)")]:::db
            SCHEMA["DB Schema (SQL script in repo)"]:::artifact
        end
    end

    %% =========================
    %% External Integrations
    %% =========================
    subgraph "External Services (3rd-party)"
        direction TB
        MAPS["Maps / Geocoding Provider (TBD)"]:::external
        MSG["SMS/Email/Push Provider (TBD)"]:::external
    end

    %% =========================
    %% CI/CD
    %% =========================
    subgraph "Delivery Pipeline"
        direction TB
        DOC["Project Docs / README"]:::artifact
        GHA["GitHub Actions (CI/CD)"]:::cicd
    end

    %% =========================
    %% Relationships (vertical oriented)
    %% =========================
    U -->|"uses"| WEB
    A -->|"uses"| WEB
    C -->|"sends_location_updates"| API

    WEB -->|"renders"| UI
    UI -->|"reads_build_or_runtime_config"| ENV
    UTIL -->|"imports/exports_seed_ops_data"| DB

    WEB -->|"HTTPS_REST (/packages,/tracking,/admin/reports)"| API
    WEB <-->|"WebSocket_or_SSE (realtime_tracking)"| RT

    RT -->|"subscribes/publishes"| RTAD
    RTAD -->|"uses"| TRK

    API -->|"calls"| AUTH
    API -->|"calls"| PKG
    API -->|"calls"| DSP
    API -->|"calls"| TRK
    API -->|"calls"| NOTIF
    API -->|"calls"| RPT

    AUTH -->|"reads/writes"| REPO
    PKG -->|"reads/writes"| REPO
    DSP -->|"reads/writes"| REPO
    TRK -->|"reads/writes"| REPO
    RPT -->|"reads"| REPO
    JOBS -->|"runs_scheduled_tasks"| RPT
    JOBS -->|"retries_sends"| NOTIF

    REPO -->|"SQL_read_write"| DB
    SCHEMA -->|"defines"| DB

    NOTIF -->|"uses"| EXTAD
    EXTAD -->|"HTTP_API (send_notifications)"| MSG

    TRK -->|"optional_geocoding"| EXTAD
    EXTAD -->|"HTTP_API (maps/geocode)"| MAPS

    %% Hosting and deployment linkage
    UI -->|"served_by"| AZ
    API -->|"hosted_by"| AZ
    RT -->|"hosted_by"| AZ

    DOC -->|"documents_features_architecture"| GHA
    GHA -->|"deploys"| AZ

    %% =========================
    %% Click events (from component_mapping)
    %% =========================
    click DB "https://github.com/meghnaroyal/fastcourier/blob/master/database/courierdb1.sql"
    click SCHEMA "https://github.com/meghnaroyal/fastcourier/blob/master/database/courierdb1.sql"
    click UI "https://github.com/meghnaroyal/fastcourier/tree/master/frontend/"
    click ENV "https://github.com/meghnaroyal/fastcourier/blob/master/frontend/.env"
    click UTIL "https://github.com/meghnaroyal/fastcourier/blob/master/frontend/dumpfile.js"
    click GHA "https://github.com/meghnaroyal/fastcourier/blob/master/.github/workflows/azure-webapps-node.yml"
    click DOC "https://github.com/meghnaroyal/fastcourier/blob/master/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
    classDef client fill:#DBEAFE,stroke:#1D4ED8,color:#0B1B3A,stroke-width:1px
    classDef frontend fill:#93C5FD,stroke:#1D4ED8,color:#0B1B3A,stroke-width:1px
    classDef config fill:#E0E7FF,stroke:#4338CA,color:#111827,stroke-width:1px
    classDef ops fill:#FEF3C7,stroke:#B45309,color:#111827,stroke-width:1px
    classDef hosting fill:#CFFAFE,stroke:#0891B2,color:#083344,stroke-width:1px
    classDef service fill:#BFDBFE,stroke:#2563EB,color:#0B1B3A,stroke-width:1px
    classDef component fill:#A7F3D0,stroke:#047857,color:#064E3B,stroke-width:1px
    classDef db fill:#FDE68A,stroke:#B45309,color:#111827,stroke-width:1px
    classDef external fill:#FED7AA,stroke:#C2410C,color:#7C2D12,stroke-width:2px,stroke-dasharray: 5 3
    classDef cicd fill:#E9D5FF,stroke:#7C3AED,color:#2E1065,stroke-width:1px
    classDef artifact fill:#F3F4F6,stroke:#4B5563,color:#111827,stroke-width:1px
```
