# towhidcse4/testsafezone-api architecture

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

- Interactive diagram: https://gitdiagram.com/towhidcse4/testsafezone-api
- Repository: https://github.com/towhidcse4/testsafezone-api

## Overview

##### Project Type and Purpose
- This is a Serverless backend application written in Node.js and TypeScript, using the Serverless Framework to deploy a set of AWS Lambda functions behind API Gateway.
- It serves as a domain-driven REST API for user management, subscriptions, notifications, safe zones, and other family-safety features, persisting data in MongoDB Atlas and integrating with AWS services (Cognito, S3, SQS, VPC) plus Firebase Cloud Messaging.

##### Key Structural Observations
- Top-level “serverless.yml” plus per-handler YAML files define each Lambda function, triggers (HTTP, scheduled), and AWS resources (API Gateway authorizer, Cognito User Pool, S3 bucket, SQS queue, VPC).
- `src/handlers/...` is organized by domain: auth, cron_jobs, notification_mobile, orders, safezone, subscribe, subscriptions, users, zvelo.
- Layered code:
· **actions/**: orchestrate high-level operations
· **handlers/**: function entry points
· **models/**: database schema/ORM definitions
· **modules/**: AWS and core utilities (Cognito, S3, SQS, Mongoose bootstrap, request/response)
· **service/firebase/**: FCM integration
· **utils/**: JWT, auth helpers, string utilities
- Infrastructure config under `config/` defines CloudFormation snippets (VPC, S3, SQS, Cognito, API Gateway Authorizer).
- Data directory holds seed data for subscription plans, user groups, web categories.

a. Main Components
- **Clients**: Mobile/web frontends consuming the API
- **API Gateway**:
- Public HTTP endpoints per domain.
- Authorizer integrated with Cognito User Pool.
- **AWS Lambdas**: grouped by domain (auth, users, subscriptions, cron jobs, notifications, etc.)
- **MongoDB Atlas**: primary document database, accessed via Mongoose in the VPC
- **Cognito User Pool**: user authentication & JWT issuance
- **S3 Bucket**: file storage (configured via `config/s3-bucket.yml`)
- **SQS Queue**: message queue for asynchronous tasks
- **Firebase Cloud Messaging**: push notifications from Lambda → FCM
- **CloudWatch Events / Scheduled Cron**: triggers for cron_jobs Lambdas
- **VPC**: secures Lambdas and network access to MongoDB Atlas
- **CloudWatch Logs**: all Lambdas stream logs here

b. Relationships & Data Flow
1. Client request → API Gateway → Lambda (auth & domain handlers)
2. Authorized Lambda uses `modules/cognito` to validate token or call Cognito (login/register).
3. Business Lambdas invoke `modules/core/mongoose` to read/write MongoDB Atlas.
4. Some flows enqueue messages to SQS (`modules/sqs`) or read from it.
5. Notification-related Lambdas send messages to FCM via `service/firebase`.
6. Scheduled CloudWatch Events trigger cron_jobs Lambdas on a schedule.
7. Lambdas that need file storage call `modules/s3` to read/write S3.

c. Architectural Patterns & Principles
- **Domain-Driven Design**: each domain’s handlers/models/actions form a bounded context.
- **Micro-function / Serverless**: each handler is a single-purpose Lambda.
- **Layered Modularization**: shared code in modules/core, modules/s3, modules/sqs, service, utils.
- **Event-Driven**: scheduled jobs and SQS for asynchronous processing.
- **Infrastructure as Code**: Serverless Framework YAML + config snippets.

d. Key Technologies & Frameworks
- Node.js, TypeScript, Serverless Framework
- AWS Lambda, API Gateway, Cognito, S3, SQS, VPC
- MongoDB Atlas with Mongoose
- Firebase Cloud Messaging SDK

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients and Front Door
    Clients["Clients (Mobile/Web)"]:::external
    APIGW["API Gateway"]:::compute
    Authorizer["API Gateway Authorizer"]:::identity

    %% VPC Boundary
    subgraph "VPC Boundary"
      direction TB

      %% Domain Lambdas
      subgraph "Auth Lambdas" 
        Auth["Auth Lambdas (src/handlers/auth/)"]:::lambda
      end
      subgraph "Cron Job Lambdas"
        Cron["Cron Job Lambdas (src/handlers/cron_jobs/)"]:::lambda
      end
      subgraph "Notification Mobile Lambdas"
        NotifMobile["Notification Mobile Lambdas (src/handlers/notification_mobile/)"]:::lambda
      end
      subgraph "Orders Lambdas"
        Orders["Orders Lambdas (src/handlers/orders/)"]:::lambda
      end
      subgraph "SafeZone Lambdas"
        SafeZone["SafeZone Lambdas (src/handlers/safezone/)"]:::lambda
      end
      subgraph "Payment Subscribe Lambdas"
        Subscribe["Subscribe Lambdas (src/handlers/subscribe/)"]:::lambda
      end
      subgraph "Subscription Plan Lambdas"
        Subscriptions["Subscription Lambdas (src/handlers/subscriptions/)"]:::lambda
      end
      subgraph "User Management Lambdas"
        Users["Users Lambdas (src/handlers/users/)"]:::lambda
      end
      subgraph "Zvelo Integration Lambdas"
        Zvelo["Zvelo Lambdas (src/handlers/zvelo/)"]:::lambda
      end

      %% Shared Modules and Libraries
      subgraph "Shared Modules / Libraries"
        direction TB
        MongooseMod["Mongoose Bootstrap\n(src/modules/core/mongoose.ts)"]:::storage
        CoreUtils["Core Utilities\n(src/modules/core/)"]:::compute
        S3Mod["S3 Module\n(src/modules/s3/index.ts)"]:::storage
        SQSMod["SQS Module\n(src/modules/sqs/index.ts)"]:::messaging
        CognitoMod["Cognito Module\n(src/modules/cognito/index.ts)"]:::identity
        FirebaseMod["FCM Integration\n(src/service/firebase/index.ts)"]:::external
      end

      %% Data Store
      MongoDBAtlas["MongoDB Atlas"]:::storage

    end

    %% External Infra Components
    CognitoUP["Cognito User Pool"]:::identity
    S3Bucket["S3 Bucket"]:::storage
    SQSQueue["SQS Queue"]:::messaging
    VPCInfra["VPC"]:::compute
    CronEvent["CloudWatch Events\n(Scheduled)"]:::messaging

    %% Flows
    Clients -->|HTTP| APIGW
    APIGW -->|Authorize via JWT| Authorizer
    APIGW -->|Invoke| Auth
    APIGW -->|Invoke| Users
    APIGW -->|Invoke| Subscriptions
    APIGW -->|Invoke| Subscribe
    APIGW -->|Invoke| SafeZone
    APIGW -->|Invoke| Orders
    APIGW -->|Invoke| NotifMobile
    APIGW -->|Invoke| Zvelo

    Auth -->|Validate/Register| CognitoMod
    CognitoMod -->|Calls| CognitoUP
    Authorizer -->|Verifies| CognitoUP

    Auth -->|Reads/Writes| MongooseMod
    Users -->|Reads/Writes| MongooseMod
    Subscriptions -->|Reads/Writes| MongooseMod
    Subscribe -->|Reads/Writes| MongooseMod
    SafeZone -->|Reads/Writes| MongooseMod
    Orders -->|Reads/Writes| MongooseMod
    Zvelo -->|Reads/Writes| MongooseMod

    MongooseMod -->|Connect| MongoDBAtlas

    Auth -->|S3 API| S3Mod
    SafeZone -->|S3 API| S3Mod
    S3Mod -->|Access| S3Bucket

    Users -->|SQS Message| SQSMod
    Cron -->|SQS Message| SQSMod
    SQSMod -->|Queue| SQSQueue

    CronEvent -->|Trigger| Cron

    NotifMobile -->|Push via FCM| FirebaseMod
    FirebaseMod -->|Deliver| FCMService["Firebase Cloud Messaging"]:::external

    %% Click Events
    click APIGW "https://github.com/towhidcse4/testsafezone-api/blob/main/serverless.yml"
    click Authorizer "https://github.com/towhidcse4/testsafezone-api/blob/main/config/apigateway-authorizer.yml"
    click CognitoUP "https://github.com/towhidcse4/testsafezone-api/blob/main/config/cognito.yml"
    click CognitoMod "https://github.com/towhidcse4/testsafezone-api/blob/main/src/modules/cognito/index.ts"
    click S3Bucket "https://github.com/towhidcse4/testsafezone-api/blob/main/config/s3-bucket.yml"
    click S3Mod "https://github.com/towhidcse4/testsafezone-api/blob/main/src/modules/s3/index.ts"
    click SQSQueue "https://github.com/towhidcse4/testsafezone-api/blob/main/config/sqs.yml"
    click SQSMod "https://github.com/towhidcse4/testsafezone-api/blob/main/src/modules/sqs/index.ts"
    click VPCInfra "https://github.com/towhidcse4/testsafezone-api/blob/main/config/vpc.yml"
    click Auth "https://github.com/towhidcse4/testsafezone-api/tree/main/src/handlers/auth/"
    click Cron "https://github.com/towhidcse4/testsafezone-api/tree/main/src/handlers/cron_jobs/"
    click NotifMobile "https://github.com/towhidcse4/testsafezone-api/tree/main/src/handlers/notification_mobile/"
    click Orders "https://github.com/towhidcse4/testsafezone-api/tree/main/src/handlers/orders/"
    click SafeZone "https://github.com/towhidcse4/testsafezone-api/tree/main/src/handlers/safezone/"
    click Subscribe "https://github.com/towhidcse4/testsafezone-api/tree/main/src/handlers/subscribe/"
    click Subscriptions "https://github.com/towhidcse4/testsafezone-api/tree/main/src/handlers/subscriptions/"
    click Users "https://github.com/towhidcse4/testsafezone-api/tree/main/src/handlers/users/"
    click Zvelo "https://github.com/towhidcse4/testsafezone-api/tree/main/src/handlers/zvelo/"
    click MongooseMod "https://github.com/towhidcse4/testsafezone-api/blob/main/src/modules/core/mongoose.ts"
    click CoreUtils "https://github.com/towhidcse4/testsafezone-api/tree/main/src/modules/core/"
    click FirebaseMod "https://github.com/towhidcse4/testsafezone-api/blob/main/src/service/firebase/index.ts"
    click FCMService "https://github.com/towhidcse4/testsafezone-api/blob/main/src/service/firebase/fcm_key/safezone-a0eec-firebase-adminsdk-mo3o5-365fe6f0a4.json"

    %% Styles
    classDef lambda fill:#e0f2e9,stroke:#27ae60,stroke-width:2px;
    classDef compute fill:#e8f4fc,stroke:#2980b9,stroke-width:2px;
    classDef storage fill:#e8f0fd,stroke:#2471a3,stroke-width:2px;
    classDef messaging fill:#fff4e5,stroke:#e67e22,stroke-width:2px;
    classDef identity fill:#f5e8fc,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#ecedef,stroke:#7f8c8d,stroke-width:2px;
```
