Architecture

System Architecture

LeadSmart API follows a layered architecture pattern with clear separation of concerns:

┌─────────────────┐
│    API Layer    │ Routes, Request Validation
├─────────────────┤
│ Controller Layer│ Business Logic Coordination
├─────────────────┤
│  Service Layer  │ Core Business Logic
├─────────────────┤
│    Data Layer   │ Database Access, Models
└─────────────────┘

Layers

API Layer: Routes and request validation using Zod schemas

Controller Layer: Coordinates business logic and handles HTTP responses

Service Layer: Core business logic implementation

Data Layer: Database models and data access using Sequelize

Project Structure

src/
├── configs/        # Application configuration
├── controllers/    # Request handlers
├── database/       # Database models and migrations
├── exceptions/     # Custom error classes
├── integrations/   # External service integrations
├── jobs/           # Scheduled tasks and cron jobs
├── messaging/      # Messaging service implementations
├── middlewares/    # Express middlewares
├── responses/      # Standardized response formatters
├── routes/         # API route definitions
├── schemas/        # Request validation schemas
├── services/       # Business logic services
├── types/          # TypeScript type definitions
└── utils/          # Utility functions

Key Components

Express Application

The main Express application is configured in src/configs/app.ts with middleware setup and security configurations.

Database

The application uses PostgreSQL with Sequelize ORM. The database models are defined in src/database/models/ and represent the application's data entities.

Authentication

User authentication is handled using JWT (JSON Web Tokens) with refresh token functionality for extended sessions.

Job Scheduling

Scheduled tasks are managed using node-cron, including:

Google Calendar webhook renewal

WhatsApp connection health checks

Database connection health checks

Messaging

The application integrates with WhatsApp for messaging capabilities, managed through the @whiskeysockets/baileys library.

Error Handling

A centralized error handling middleware (errorHandler.middleware.ts) processes all application errors and returns standardized error responses.

Request Flow

Request Received: Express route handles incoming request

Middleware Processing: Authentication, rate limiting, etc.

Request Validation: Zod schemas validate request data

Controller Processing: Controller method orchestrates business logic

Service Execution: Service methods perform core business operations

Database Interaction: Sequelize models handle data persistence

Response Formatting: Standardized response is returned to client

System Architecture#

Layers#

Project Structure#

Key Components#

Express Application#

Database#

Authentication#

Job Scheduling#

Messaging#

Error Handling#

Request Flow#