How d4nh-le/webmailer works
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.