# ankit-chauhan-nitdgp/bulk-parcel-pickup architecture

> Architecture diagram of the GitHub repository ankit-chauhan-nitdgp/bulk-parcel-pickup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ankit-chauhan-nitdgp/bulk-parcel-pickup
- Repository: https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup

## Overview

##### Project Type and Purpose
- This is a full-stack solution for “Bulk Garbage Pickup Scheduling” built as a modular monolith using Spring Boot.
- It exposes REST APIs to mobile clients and an admin dashboard, persists data in AWS RDS, and orchestrates third-party logistics and notification services.

##### File Structure
- Top-Level:
- pom.xml, mvnw – Maven build setup.
- src/main/java/com/demo/kasafaat – core application package.
- Modules under com/demo/kasafaat:
- commonModule – shared utilities, exceptions, API response wrapper.
- userModule – authentication, OTP, JWT, user profiles.
- addressModule – user addresses + geo utils.
- darkstoreModule – warehouse management, capacity, geolocation.
- orderModule – order creation, lifecycle, linking user, address, darkstore.
- logisticModule – integration with external courier APIs via REST/webhooks.
- notificationModule – push (FCM), SMS (DLT), email (SES).
- Deployment descriptors: .github/workflows/deploy.yml, Docker/maven wrapper, application.properties.

##### README Insights
- Architecture: Mobile + Admin UI → ALB → ECS Fargate container running Spring Boot → RDS
- External services: Secrets Manager, CodePipeline/CodeBuild, CloudWatch, logistics API, FCM/SMS/SES.

a. Main Components
- Clients: Mobile App (Customer), Admin Dashboard
- API Layer: AWS ALB
- Application: Spring Boot container on ECS Fargate
- Functional Modules (grouped):
· User Module
· Address Module
· Darkstore Module
· Order Module
· Logistics Module
· Notification Module
· Common Module
- Database: AWS RDS (Postgres/MySQL)
- Configuration: AWS Secrets Manager
- CI/CD: CodePipeline → CodeBuild → ECS deployment
- Monitoring: CloudWatch
- External Services:
- Logistics partners (Webhook/Polling)
- FCM, SMS gateway, SES for notifications

b. Relationships and Data Flow
1. Client → ALB: HTTP(S) requests
2. ALB → ECS Task: routes to Spring Boot service
3. Spring Boot Controller (per module) → Service Layer → Repository
4. Repository → RDS for CRUD operations
5. Order Module calls:
- Address Module to geocode & fetch user address
- Darkstore Module to get nearest warehouse
- Logistics Module to place shipment request
6. Logistics Module ↔ External Courier API (REST / Webhook)
7. Notification Module → FCM/SMS/SES to notify user
8. Secrets Manager supplies DB and API credentials at runtime
9. CI/CD pipeline builds, tests, and deploys Docker image
10. CloudWatch collects logs & metrics from ECS tasks

c. Architectural Patterns
- Modular Monolith: clear package-level separation by domain
- Layered Architecture: Controller → Service → DAO/Repository → Database
- Event/Callback: Webhook handling in logistics module
- Externalized Configuration and Secrets Injection

d. Key Technologies & Frameworks
- Java 17 (or 11) + Spring Boot
- Spring Data JPA, Hibernate
- Maven build / Docker containerization
- AWS: ECS Fargate, ALB, RDS, Secrets Manager, CloudWatch, CodePipeline/CodeBuild
- JWT, DLT OTP for authentication
- FCM, SES, SMS gateway

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    ClientMobile["Mobile App"]:::client
    AdminUI["Admin Dashboard"]:::client

    %% AWS Infrastructure
    ALB["AWS ALB"]:::aws
    ECS["ECS Fargate Task"]:::aws
    Secrets["AWS Secrets Manager"]:::aws
    RDS["AWS RDS<br/>(Postgres/MySQL)"]:::db
    CloudWatch["CloudWatch"]:::aws

    %% Application Container
    subgraph "Container: Spring Boot Application"
        direction TB
        AppEntry["KasafaatApplication"]:::app
        subgraph "Common Module"
            CommonMod["commonModule"]:::module
        end
        subgraph "User Module"
            UserMod["userModule"]:::module
        end
        subgraph "Address Module"
            AddrMod["addressModule"]:::module
        end
        subgraph "Darkstore Module"
            DarkMod["darkstoreModule"]:::module
        end
        subgraph "Order Module"
            OrderMod["orderModule"]:::module
        end
        subgraph "Logistics Module"
            LogisticMod["logisticModule"]:::module
        end
        subgraph "Notification Module"
            NotifyMod["notificationModule"]:::module
        end
        Config["application.properties"]:::config
    end

    %% CI/CD Pipeline
    GitRepo["Code Repository"]:::cicd
    CodePipeline["CodePipeline"]:::cicd
    CodeBuild["CodeBuild"]:::cicd
    DeployWF["deploy.yml"]:::cicd

    %% External Services
    Courier["Courier API (REST/Webhook)"]:::external
    FCM["FCM"]:::external
    SMS["SMS Gateway (DLT)"]:::external
    SES["SES"]:::external

    %% Connections: Clients to ALB to Container
    ClientMobile -->|HTTPS| ALB
    AdminUI -->|HTTPS| ALB
    ALB --> ECS
    ECS --> AppEntry

    %% Application to AWS services
    AppEntry --> CommonMod
    AppEntry --> UserMod
    AppEntry --> AddrMod
    AppEntry --> DarkMod
    AppEntry --> OrderMod
    AppEntry --> LogisticMod
    AppEntry --> NotifyMod
    AppEntry --> Config
    AppEntry --> RDS
    AppEntry --> Secrets
    ECS --> CloudWatch

    %% Module interactions
    OrderMod -->|uses| AddrMod
    OrderMod -->|uses| DarkMod
    OrderMod -->|uses| LogisticMod
    LogisticMod -->|calls| Courier
    NotifyMod -->|push| FCM
    NotifyMod -->|SMS| SMS
    NotifyMod -->|email| SES

    %% CI/CD Flow
    GitRepo --> CodePipeline
    CodePipeline --> CodeBuild
    CodeBuild -->|deploy| ECS
    CodeBuild --> DeployWF

    %% Click Events
    click AppEntry "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/blob/main/src/main/java/com/demo/kasafaat/KasafaatApplication.java"
    click CommonMod "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/tree/main/src/main/java/com/demo/kasafaat/commonModule"
    click UserMod "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/tree/main/src/main/java/com/demo/kasafaat/userModule"
    click AddrMod "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/tree/main/src/main/java/com/demo/kasafaat/addressModule"
    click DarkMod "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/tree/main/src/main/java/com/demo/kasafaat/darkstoreModule"
    click OrderMod "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/tree/main/src/main/java/com/demo/kasafaat/orderModule"
    click LogisticMod "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/tree/main/src/main/java/com/demo/kasafaat/logisticModule"
    click NotifyMod "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/tree/main/src/main/java/com/demo/kasafaat/notificationModule"
    click Config "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/blob/main/src/main/resources/application.properties"
    click Pom "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/blob/main/pom.xml"
    click DeployWF "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/blob/main/.github/workflows/deploy.yml"
    click Tests "https://github.com/ankit-chauhan-nitdgp/bulk-parcel-pickup/blob/main/src/test/java/com/demo/kasafaat/KasafaatApplicationTests.java"

    %% Styles
    classDef client fill:#e8e8e8,stroke:#333,stroke-width:1px
    classDef aws fill:#a2f5a1,stroke:#333,stroke-width:1px
    classDef db fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef module fill:#a0d8ef,stroke:#333,stroke-width:1px
    classDef external fill:#f5b57a,stroke:#333,stroke-width:1px
    classDef cicd fill:#d4a1f9,stroke:#333,stroke-width:1px
    classDef config fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef app fill:#b0c4de,stroke:#333,stroke-width:1px
    class Pom,DeployWF,Tests cicd
```
