# d4nh-le/webmailer architecture

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

- Interactive diagram: https://gitdiagram.com/d4nh-le/webmailer
- Repository: https://github.com/d4nh-le/webmailer

## Overview

##### Project Type and Purpose
- Webmailer is a full-stack analytic tool designed to notify developers via email when visitors enter their site. It acts as a middleware that captures web request details (page visited, timestamp, visitor location, referrer) and sends them to a central analytics service.
- The project features a NodeJS backend (handling API endpoints, middleware, database connection, and utilities) and a ReactJS frontend (registration and documentation website). PostgreSQL is used for data persistence.

##### Analyzing the File Structure
- At the root, files like app.js, various configuration files (dockerfile, eslint.config.mjs, etc.), and README indicate a NodeJS-based project.
- The “frontend” directory contains a standard React application structure (public assets, components, containers, etc.), reflecting the registration/documentation website.
- The “src” folder holds the backend code, including:
- “databases” for PostgreSQL connections and pooling.
- “services” for core logic like mailer and registration.
- “utilities” for various helper modules (encryption, sanitization, token handling).
- “tests” organized into unit-tests and integration-tests following TDD methodology.
- The presence of Docker and CI/CD (GitHub workflows) indicates an environment supporting containerization and continuous integration.

##### Key Components
a. Frontend (ReactJS):
- User Interface components (e.g., registration, navbar, instruction pages).
- Client-side routing (if used) and integration with backend API for registration and token management.

b. Backend (NodeJS Application):
- Core request handler (app.js) that wires up routes.
- Middleware layer: For example, the Webmailer middleware (*.middleware trigger as shown in the README sample), which intercepts requests, extracts parameters (key, page, ip, referer) and sends analytic data.
- Service layer: Contains modules like mailer.service.js and registration.service.js.
- Utility components: Modules for sanitization, validation (in Mailer and Registration utilities) and encryption.
- Test suites: Unit tests and integration tests that validate middleware and services.

c. Database (PostgreSQL):
- Connection pool management via src/databases/connection/connection_pool.database.js.
- Service-related database handlers in src/databases/service/.

d. External Integrations:
- Email service: The middleware sends requests (using axios) to Webmailer’s server endpoint (https://w3bmailer.site/trigger) for email notifications.
- Docker container orchestration represented in dockerfile.

##### Determining Relationships and Interactions
- Frontend interacts with the backend via HTTP/REST API calls (e.g., during registration or when configuring the middleware).
- The backend handles incoming requests by applying middleware. The middleware extracts the necessary web visit data and uses an HTTP client (axios) to notify the Webmailer server.
- Service components invoke utility functions (for sanitization, validation, encryption) and connect with PostgreSQL through the connection pool.
- Testing components simulate requests to ensure that middleware and utilities work as expected.

##### Architectural Patterns and Design Principles
- Component-Based Architecture: Both React and NodeJS portions are organized into modular components/services to provide separation of concerns, scalability, and reusability.
- Middleware Pattern: The design leverages middleware for intercepting requests, enriching them with analytics data, and securely sending notifications.
- Test-Driven Development (TDD): The project enforces unit and integration testing for reliability.
- Microservice/MVC-Like Separation: Although not fully microservices (everything is within one repository), there is a clear separation between frontend presentation, backend business logic, and data persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        FE["ReactJS Frontend"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        NS["NodeJS API Server (app.js)"]:::backend
        MW["Webmailer Middleware"]:::backend
        MS["Mailer Service"]:::backend
        RS["Registration Service"]:::backend
        subgraph "Utilities"
            ENC["Encryption Utility"]:::utility
            GEO["GeoIP Utility"]:::utility
            TOK["Token Utility"]:::utility
            MSAN["Mailer Sanitization"]:::utility
            MVAL["Mailer Validation"]:::utility
            RSAN["Registration Sanitization"]:::utility
            RVAL["Registration Validation"]:::utility
            VSAN["Verify Sanitization"]:::utility
            VVAL["Verify Validation"]:::utility
        end
    end

    %% Persistence Layer
    subgraph "Persistence"
        CP["Connection Pool"]:::database
        DBH["Service Database Handlers"]:::database
    end

    %% External Integrations
    subgraph "External Integrations"
        ES["External Email Service"]:::external
    end

    %% Infrastructure and Testing
    subgraph "Infrastructure"
        DCK["Docker Containerization"]:::infrastructure
        CICD["CI/CD Integration"]:::infrastructure
        TST["Testing Suite"]:::testing
    end

    %% Data Flow connections
    FE -->|"HTTPRequest"| NS
    NS -->|"InvokeMiddleware"| MW
    MW -->|"NotifyEmail"| ES
    NS -->|"CallMailer"| MS
    NS -->|"CallRegistration"| RS
    NS -->|"Utilize"| ENC
    NS -->|"Utilize"| GEO
    NS -->|"Utilize"| TOK
    MS -->|"Uses"| MSAN
    MS -->|"Uses"| MVAL
    RS -->|"Uses"| RSAN
    RS -->|"Uses"| RVAL
    MS -->|"DBCall"| CP
    RS -->|"DBCall"| CP
    CP -->|"ManageConnections"| DBH
    TST -->|"Tests"| NS
    TST -->|"Tests"| MS
    TST -->|"Tests"| RS
    TST -->|"Tests"| ENC
    TST -->|"Tests"| GEO
    TST -->|"Tests"| TOK
    TST -->|"Tests"| MSAN
    TST -->|"Tests"| MVAL
    TST -->|"Tests"| RSAN
    TST -->|"Tests"| RVAL
    TST -->|"Tests"| VSAN
    TST -->|"Tests"| VVAL

    %% Optional connections for infrastructure context
    DCK --- NS
    CICD --- NS

    %% Click Events
    click FE "https://github.com/d4nh-le/webmailer/tree/main/frontend/"
    click NS "https://github.com/d4nh-le/webmailer/blob/main/app.js"
    click MS "https://github.com/d4nh-le/webmailer/blob/main/src/services/mailer.service.js"
    click RS "https://github.com/d4nh-le/webmailer/blob/main/src/services/registration.service.js"
    click ENC "https://github.com/d4nh-le/webmailer/blob/main/src/utilities/encryption.utility.js"
    click GEO "https://github.com/d4nh-le/webmailer/blob/main/src/utilities/geoip.utility.js"
    click TOK "https://github.com/d4nh-le/webmailer/blob/main/src/utilities/token.utility.js"
    click MSAN "https://github.com/d4nh-le/webmailer/blob/main/src/utilities/mailer_utilities/Mailer_sanitize.utility.js"
    click MVAL "https://github.com/d4nh-le/webmailer/blob/main/src/utilities/mailer_utilities/Mailer_validation.utility.js"
    click RSAN "https://github.com/d4nh-le/webmailer/blob/main/src/utilities/registration_utilities/Registration_sanitize.utility.js"
    click RVAL "https://github.com/d4nh-le/webmailer/blob/main/src/utilities/registration_utilities/Registration_validation.utility.js"
    click VSAN "https://github.com/d4nh-le/webmailer/blob/main/src/utilities/verify_utilities/Verify_sanitize.utility.js"
    click VVAL "https://github.com/d4nh-le/webmailer/blob/main/src/utilities/verify_utilities/Verify_validation.utility.js"
    click CP "https://github.com/d4nh-le/webmailer/blob/main/src/databases/connection/connection_pool.database.js"
    click DBH "https://github.com/d4nh-le/webmailer/blob/main/src/databases/service/services.database.js"
    click TST "https://github.com/d4nh-le/webmailer/tree/main/src/tests/"
    click DCK "https://github.com/d4nh-le/webmailer/tree/main/dockerfile"
    click CICD "https://github.com/d4nh-le/webmailer/blob/main/.github/workflows/main.yml"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef utility fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef testing fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef infrastructure fill:#D5DBDB,stroke:#566573,stroke-width:2px;
```
