NestJS CRM API

Table of Contents

• Introduction
• Features
• Technologies Used
• Getting Started
  • Prerequisites
  • Installation
  • Running the Application
• API Documentation (Swagger)
• Database Schema (ER Diagram Conceptual)
• Authentication
• Validation and Error Handling
• Running Tests
• Project Structure
• Contributing
• License

Introduction

This project is a robust Customer Relationship Management (CRM) API built with NestJS. It provides a comprehensive set of functionalities for managing users, customers, expenses, invoices, payments, and quotes. The API is designed to be scalable, maintainable, and secure, leveraging modern backend development practices.

Features

• User Management: Secure user registration, login, and authentication using JWT.
• Customer Management: CRUD operations for managing customer details. Each customer is associated with a user.
• Expense Tracking: Record and manage expenses, linked to specific users.
• Invoice Generation: Create, view, update, and delete invoices. Invoices can include multiple items and are linked to customers and users. PDF generation for invoices is also supported.
• Payment Processing: Track payments made against invoices.
• Quote Management: Generate, manage, and track quotes, similar to invoices, with multiple items and linked to customers and users.
• Data Validation: Robust input validation using class-validator and class-transformer.
• Centralized Error Handling: Consistent error responses for validation failures and resource not found scenarios.
• API Documentation: Interactive API documentation powered by Swagger UI.

Technologies Used

• Backend Framework: NestJS (Node.js)
• Database: TypeORM (ORM for PostgreSQL, MySQL, SQLite, etc. - configured via ormconfig.ts or environment variables)
• Authentication: JWT (JSON Web Tokens)
• Validation: Class-validator, Class-transformer
• API Documentation: Swagger (OpenAPI)
• PDF Generation: (Implicitly used by PdfService)
• Hashing: bcrypt

Getting Started

Prerequisites

• Node.js (LTS version recommended)
• npm or Yarn
• A running database instance (e.g., PostgreSQL, MySQL)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd nest-js-app

2. Install dependencies:

   npm install
   # or yarn install

3. Configure Environment Variables: Create a .env file in the project root based on .env.example (if available) or the expected environment variables. Example .env content (adjust as per your database and JWT secret):

   DATABASE_TYPE=postgres
   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   DATABASE_USERNAME=your_username
   DATABASE_PASSWORD=your_password
   DATABASE_NAME=your_database_name
   JWT_SECRET=your_jwt_secret_key
   PORT=3000
   

   Note: Ensure your database is running and accessible.

Running the Application

1. Run database migrations (if any): (This project uses TypeORM, so you might need to run migrations if you have entity changes or are setting up a new database. Check package.json for migration scripts, e.g., npm run typeorm migration:run)

   # Example: npm run typeorm migration:run

2. Start the application in development mode:

   npm run start:dev
   # or yarn start:dev

   The application will typically run on http://localhost:3000 (or the port specified in your .env file).

API Documentation (Swagger)

Once the application is running, you can access the interactive API documentation at: http://localhost:3000/api (adjust port if necessary)

This documentation provides detailed information about all available endpoints, including request/response schemas, parameters, and example values, making it easy to test and understand the API.

Database Schema (ER Diagram Conceptual)

The application's data model is designed around the following entities and their relationships:

• User: Represents an authenticated user of the system.

  • Fields: id (PK), email (Unique), password, firstName, lastName, createdAt, updatedAt.
  • Relationships: One User can manage many Customers, Expenses, Invoices, Payments, and Quotes.

• Customer: Stores information about a client.

  • Fields: id (PK), name, email (Unique), phone, address, createdAt, updatedAt, userId (FK to User).
  • Relationships: Many Customers belong to one User. One Customer can have many Invoices and Quotes.

• Expense: Records individual expenses.

  • Fields: id (PK), name, amount, date, createdAt, updatedAt, userId (FK to User).
  • Relationships: Many Expenses belong to one User.

• Invoice: Represents a bill issued to a customer.

  • Fields: id (PK), invoiceNumber (Unique), issueDate, dueDate, totalAmount, status (Enum: DRAFT, SENT, PAID, CANCELLED), createdAt, updatedAt, customerId (FK to Customer), userId (FK to User).
  • Relationships: Many Invoices belong to one Customer and one User. One Invoice can have many InvoiceItems and many Payments.

• InvoiceItem: Details individual line items within an Invoice.

  • Fields: id (PK), description, quantity, unitPrice, total, invoiceId (FK to Invoice).
  • Relationships: Many InvoiceItems belong to one Invoice.

• Payment: Tracks payments received.

  • Fields: id (PK), amount, paymentDate, paymentType (Enum: EFT, CASH, CREDIT_CARD), createdAt, updatedAt, invoiceId (FK to Invoice), userId (FK to User).
  • Relationships: Many Payments belong to one Invoice and one User.

• Quote: Represents a formal offer to a customer.

  • Fields: id (PK), quoteNumber (Unique), issueDate, expiryDate, totalAmount, status (Enum: DRAFT, SENT, ACCEPTED, REJECTED), createdAt, updatedAt, customerId (FK to Customer), userId (FK to User).
  • Relationships: Many Quotes belong to one Customer and one User. One Quote can have many QuoteItems.

• QuoteItem: Details individual line items within a Quote.

  • Fields: id (PK), description, quantity, unitPrice, total, quoteId (FK to Quote).
  • Relationships: Many QuoteItems belong to one Quote.

Authentication

The API uses JSON Web Tokens (JWT) for authentication.

• Sign Up: New users can register via the /auth/signup endpoint.
• Sign In: Existing users can obtain a JWT by signing in via the /auth/signin endpoint.
• Protected Routes: Most API endpoints require a valid JWT provided in the Authorization header as a Bearer token.

Validation and Error Handling

• DTO Validation: All incoming request payloads are automatically validated against their respective Data Transfer Objects (DTOs) using class-validator and class-transformer. Invalid data will result in a 400 Bad Request response with detailed error messages.
• Resource Not Found: Attempts to access or manipulate resources that do not exist will result in a 404 Not Found response.
• Unauthorized Access: Attempts to access protected resources without a valid token or with insufficient permissions will result in a 401 Unauthorized response.

Running Tests

To run the automated tests for the project:

npm run test
# or yarn test

For end-to-end tests:

npm run test:e2e
# or yarn test:e2e

Project Structure

The project follows a modular structure, with each major feature (e.g., auth, users, customers) residing in its own directory.

src/
├── app.controller.ts
├── app.module.ts
├── app.service.ts
├── auth/
│   ├── auth.controller.ts
│   ├── auth.module.ts
│   ├── auth.service.ts
│   └── dto/
│       └── sign-in.dto.ts
│   └── strategies/
│       └── jwt.strategy.ts
├── common/
│   └── guards/
│       └── jwt-auth.guard.ts
├── customers/
│   ├── customer.entity.ts
│   ├── customers.controller.ts
│   ├── customers.module.ts
│   ├── customers.service.ts
│   └── dto/
│       └── create-customer.dto.ts
├── expenses/
│   ├── expense.entity.ts
│   ├── expenses.controller.ts
│   ├── expenses.module.ts
│   ├── expenses.service.ts
│   └── dto/
│       └── create-expense.dto.ts
├── invoices/
│   ├── invoice-item.entity.ts
│   ├── invoice.entity.ts
│   ├── invoices.controller.ts
│   ├── invoices.module.ts
│   ├── invoices.service.ts
│   └── dto/
│       ├── create-invoice-item.dto.ts
│       └── create-invoice.dto.ts
├── payments/
│   ├── payment.entity.ts
│   ├── payments.controller.ts
│   ├── payments.module.ts
│   ├── payments.service.ts
│   └── dto/
│       └── create-payment.dto.ts
├── pdf/
│   ├── pdf.module.ts
│   └── pdf.service.ts
├── quotes/
│   ├── quote-item.entity.ts
│   ├── quote.entity.ts
│   ├── quotes.controller.ts
│   ├── quotes.module.ts
│   ├── quotes.service.ts
│   └── dto/
│       ├── create-quote-item.dto.ts
│       └── create-quote.dto.ts
└── users/
    ├── user.entity.ts
    ├── users.controller.ts
    ├── users.module.ts
    ├── users.service.ts
    └── dto/
        └── create-user.dto.ts

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature-name).
3. Make your changes.
4. Commit your changes (git commit -m 'feat: Add new feature').
5. Push to the branch (git push origin feature/your-feature-name).
6. Open a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.