# csye6225-neu/webapp architecture

> Architecture diagram of the GitHub repository csye6225-neu/webapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/csye6225-neu/webapp
- Repository: https://github.com/csye6225-neu/webapp

## Overview

##### Project Type and Purpose
- This is a backend-heavy, cloud-native NodeJS web application with:
- REST endpoints (file upload/download, health checks)
- AWS RDS for relational data
- AWS S3 for file storage
- AWS CloudWatch for logging and metrics
- CI/CD via GitHub Actions
- Packer-based AMI builds (infra/packer)

##### File Structure
- Top-level entry points:
- app.js / server.js – bootstraps Express server and middleware
- dist/webapp – compiled front-end assets (static UI)
- Core folders:
- controllers/ – request handlers
- routes/ – Express router definitions
- services/ – AWS integrations (s3service, cloudwatchService)
- models/ – ORM or schema definitions (RDS models)
- middleware/ – request/response processing (metrics, file upload, health check)
- config/ – database configuration
- infra/packer/ – AMI build scripts and configuration
- .github/actions & workflows – CI/CD pipelines

##### README and Docs
- README calls out architecture.md (docs/02-architecture.md) – likely describes functional components
- Docs outline CI/CD, CloudWatch, project structure, infra setup

##### Main Components
a. Client (Browser or API consumer)
b. CI/CD Pipeline (GitHub Actions)
– build-binary, setup-environment, cloud-credentials
– webapp-ci-pipeline
d. Infrastructure Provisioning (Packer → AMI)
e. AWS Compute (EC2 Auto Scaling Group or Container Service)
f. NodeJS Application
– Express framework (routes, controllers)
– Middleware chain (healthCheckMiddleware, metricsMiddleware, fileUploadMiddleware)
– Services layer (cloudwatchService, s3service)
– Models / ORM layer (RDS models via config/database.js, utils/dbInitializer.js)
g. AWS RDS (PostgreSQL/MySQL)
h. AWS S3 (file storage bucket)
i. AWS CloudWatch (logs, custom metrics)
j. (Optional) Load Balancer and VPC / Security Groups

##### Relationships and Data Flows
- Client → Load Balancer → EC2/ECS → NodeJS App
- NodeJS App ↔ AWS RDS (queries, transactions)
- NodeJS App → AWS S3 (upload/download via s3service)
- NodeJS App → AWS CloudWatch (logs & metrics via cloudwatchService + metricsMiddleware)
- GitHub Actions → build & test → push artifacts → trigger infra deployment (via packer scripts)
- Infra (packer) → produce AMI → deploy to AWS Compute

##### Architectural Patterns and Principles
- Layered architecture (route → controller → service → model)
- Separation of concerns (middleware handles cross-cutting aspects)
- Infrastructure as code (packer HCL, shell scripts, GitHub Actions)
- Cloud-native best practices (externalized config, managed services)

##### Essential Details to Capture
- Labels for all npm scripts, action names (setup-environment, build-binary) and packer scripts (machine-image.pkr.hcl)
- Environment configuration loading (config/database.js)
- Middleware chain and service dependencies (services/cloudwatchService.js, services/s3service.js)
- Call out test coverage for middleware (middleware/__tests__)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Plane
    subgraph "CI/CD Plane"
        direction TB
        gha1["setup-environment"]:::infra
        gha2["build-binary"]:::infra
        gha3["cloud-credentials"]:::infra
        wf1["webapp-ci-pipeline"]:::infra
        wf2["image-build-and-distribution"]:::infra
    end

    gha1 --> wf1
    gha2 --> wf1
    gha3 --> wf1
    wf1 --> wf2

    %% Infra Provisioning Plane
    subgraph "Infra Provisioning Plane"
        direction TB
        packer["machine-image.pkr.hcl"]:::infra
        cw_conf["amazon-cloudwatch-config.json"]:::infra
        setup_sh["setup.sh"]:::infra
        cw_setup["cloudwatch-setup.sh"]:::infra
        ami_mig["ami_migration.sh"]:::infra
        gcp_mig["gcp_migration.sh"]:::infra
        service_unit["webapp.service"]:::infra
    end

    wf2 --> packer
    packer --> setup_sh
    setup_sh --> service_unit

    %% Runtime Plane
    subgraph "Runtime Plane"
        direction TB
        Client["Client (Browser/API)"]:::external
        LB["Load Balancer"]:::compute
        ECS["EC2 Auto Scaling Group"]:::compute

        subgraph "NodeJS Application"
            direction TB
            entry["app.js / server.js"]:::compute

            subgraph "Routing Layer"
                fileRoutes["fileRoutes.js"]:::compute
                healthRoutes["healthCheckRoutes.js"]:::compute
            end

            subgraph "Controller Layer"
                fileCtrl["fileController.js"]:::compute
                healthCtrl["healthCheckController.js"]:::compute
            end

            subgraph "Middleware"
                uploadMw["fileUploadMiddleware.js"]:::compute
                healthMw["healthCheckMiddleware.js"]:::compute
                metricsMw["metricsMiddleware.js"]:::compute
            end

            subgraph "Service Layer"
                s3Svc["s3service.js"]:::compute
                cwSvc["cloudwatchService.js"]:::compute
            end

            subgraph "Data Model / ORM"
                fileModel["File.js"]:::datastore
                healthModel["HealthCheck.js"]:::datastore
                dbConfig["database.js"]:::infra
                dbInit["dbInitializer.js"]:::compute
            end
        end

        S3[(AWS S3)]:::datastore
        RDS[(AWS RDS)]:::datastore
        CW[(AWS CloudWatch)]:::observable

        Client -->|API call| LB
        LB --> ECS
        ECS --> entry

        entry --> fileRoutes
        entry --> healthRoutes

        fileRoutes --> fileCtrl
        healthRoutes --> healthCtrl

        entry --> uploadMw
        entry --> healthMw
        entry --> metricsMw

        uploadMw --> s3Svc
        s3Svc --> S3

        fileCtrl --> dbInit
        healthCtrl --> dbInit
        dbInit --> RDS

        metricsMw --> cwSvc
        cwSvc --> CW
    end

    %% Click Events
    click Client "https://github.com/csye6225-neu/webapp/tree/main/dist/webapp"
    click gha1 "https://github.com/csye6225-neu/webapp/blob/main/.github/actions/setup-environment/action.yml"
    click gha2 "https://github.com/csye6225-neu/webapp/blob/main/.github/actions/build-binary/action.yml"
    click gha3 "https://github.com/csye6225-neu/webapp/blob/main/.github/actions/cloud-credentials/action.yml"
    click wf1 "https://github.com/csye6225-neu/webapp/blob/main/.github/workflows/webapp-ci-pipeline.yml"
    click wf2 "https://github.com/csye6225-neu/webapp/blob/main/.github/workflows/image-build-and-distribution.yml"
    click packer "https://github.com/csye6225-neu/webapp/blob/main/infra/packer/machine-image.pkr.hcl"
    click cw_conf "https://github.com/csye6225-neu/webapp/blob/main/infra/packer/amazon-cloudwatch-config.json"
    click setup_sh "https://github.com/csye6225-neu/webapp/blob/main/infra/packer/setup.sh"
    click cw_setup "https://github.com/csye6225-neu/webapp/blob/main/infra/packer/cloudwatch-setup.sh"
    click ami_mig "https://github.com/csye6225-neu/webapp/blob/main/infra/packer/ami_migration.sh"
    click gcp_mig "https://github.com/csye6225-neu/webapp/blob/main/infra/packer/gcp_migration.sh"
    click service_unit "https://github.com/csye6225-neu/webapp/blob/main/infra/packer/webapp.service"
    click entry "https://github.com/csye6225-neu/webapp/blob/main/app.js"
    click entry "https://github.com/csye6225-neu/webapp/blob/main/server.js"
    click fileRoutes "https://github.com/csye6225-neu/webapp/blob/main/routes/fileRoutes.js"
    click healthRoutes "https://github.com/csye6225-neu/webapp/blob/main/routes/healthCheckRoutes.js"
    click fileCtrl "https://github.com/csye6225-neu/webapp/blob/main/controllers/fileController.js"
    click healthCtrl "https://github.com/csye6225-neu/webapp/blob/main/controllers/healthCheckController.js"
    click uploadMw "https://github.com/csye6225-neu/webapp/blob/main/middleware/fileUploadMiddleware.js"
    click healthMw "https://github.com/csye6225-neu/webapp/blob/main/middleware/healthCheckMiddleware.js"
    click metricsMw "https://github.com/csye6225-neu/webapp/blob/main/middleware/metricsMiddleware.js"
    click s3Svc "https://github.com/csye6225-neu/webapp/blob/main/services/s3service.js"
    click cwSvc "https://github.com/csye6225-neu/webapp/blob/main/services/cloudwatchService.js"
    click fileModel "https://github.com/csye6225-neu/webapp/blob/main/models/File.js"
    click healthModel "https://github.com/csye6225-neu/webapp/blob/main/models/HealthCheck.js"
    click dbConfig "https://github.com/csye6225-neu/webapp/blob/main/config/database.js"
    click dbInit "https://github.com/csye6225-neu/webapp/blob/main/utils/dbInitializer.js"

    %% Styles
    classDef compute fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef datastore fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef observable fill:#c8e6c9,stroke:#43a047,stroke-width:1px
    classDef infra fill:#eeeeee,stroke:#757575,stroke-width:1px
    classDef external fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px,stroke-dasharray: 5 5
```
