Skip to content

README.md

Latest commit

 

History

History
206 lines (179 loc) · 9.57 KB

README.md

File metadata and controls

206 lines (179 loc) · 9.57 KB
Raw

ClientDesk

Multi-tenant CRM backend (ClientDesk) with a Next.js dashboard powered by Node.js, TypeScript, Express, Prisma, and Material UI.

Highlights

  • Multi-tenant CRM: companies isolate users, leads, and clients while preserving lead-to-client origins.
  • CRUD endpoints for companies, users, leads, and clients plus credential verification for login.
  • Request validation with Zod and typed ApplicationError responses for predictable HTTP status codes.
  • Password hashing with Argon2id and PostgreSQL persistence through Prisma.
  • OpenAPI 3.0 documentation generated by swagger-jsdoc and served at /api/docs.
  • Next.js dashboard with global search, charts, notifications, and lead-to-client conversion flows.

Tech Stack

Backend

  • Node.js and TypeScript with Express 5
  • Prisma ORM targeting PostgreSQL
  • Zod schema validation
  • Swagger JSDoc + Swagger UI Express
  • Argon2 for secure password hashing
  • dotenv + CORS configuration for environment and origin control

Frontend

  • Next.js 15 (App Router) with React 19 and TypeScript
  • Material UI 7 (Emotion) with light/dark theme toggling
  • Chart.js + react-chartjs-2 for dashboard visuals
  • Axios for HTTP requests
  • Zod for client-side validation
  • Lucide React icons and context-based state (auth, CRM data, notifications, search)

Getting Started

This repository hosts both the backend API (in the api/ folder) and the Next.js frontend (in the frontend/ folder). You can run them independently or in parallel.

Prerequisites

  • Node.js 18 or newer
  • npm
  • A PostgreSQL instance

Installation

  1. Clone the repository and install backend dependencies: 
    git clone https://github.com/JoaoArnaud/advanced-crm-api.git
cd advanced-crm-api/api
npm install
  2. Create an .env file inside api/ and configure your database and server: 
    DATABASE_URL="postgresql://postgres:postgres@localhost:5432/advanced_crm"
PORT=3333              # defaults to 3000 if unset; 3333 matches the Swagger server and frontend fallback
CORS_ORIGIN=http://localhost:3000
  3. Apply the Prisma schema and generate the client: 
    npm run prisma:migrate    # prisma migrate deploy over existing migrations
npm run prisma:generate
  4. Install frontend dependencies: 
    cd ../frontend
npm install

Running Locally

  • Start the backend (from api/): 
    npm run dev            # tsx watch on the API (PORT from .env or 3000)
npm run build
npm run start          # runs dist/index.js
  • Start the frontend (from frontend/): 
    npm run dev            # Next.js dev server on http://localhost:3000
npm run build
npm run start

Swagger UI becomes available at http://localhost:<PORT>/api/docs (spec at /api/docs.json). The dashboard consumes the API under <API_BASE>/api (falls back to http://localhost:3333/api when NEXT_PUBLIC_API_BASE_URL is unset).

Frontend (Next.js)

Folder Structure

frontend/
  src/
    app/                 # App Router routes (auth landing, dashboard, settings)
    components/          # Layout, dialogs, charts, dashboard widgets, UI helpers
    contexts/            # Auth, CRM data, notifications, and search providers
    hooks/               # Route protection and shared hooks
    services/            # Axios client and resource-specific wrappers
    types/               # Shared API/domain TypeScript definitions

Environment Variables

Create frontend/.env.local (or export the variable) to point the UI to the backend:

NEXT_PUBLIC_API_BASE_URL=http://localhost:3333

/api is appended automatically; if you leave it unset, the app falls back to http://localhost:3333/api.

Installation & Scripts

cd frontend
npm install          # install dependencies
npm run dev          # start Next.js dev server (http://localhost:3000)
npm run build        # production build
npm run start        # serve the production build
npm run lint         # lint TypeScript/React files

Core Pages & Features

  • Auth (/): register/login tabs with Zod validation, snackbars for feedback, and redirects after success; registration requires an existing company UUID.
  • Home (/home): protected dashboard with metric cards (totals, conversion rate, 30-day deltas), pipeline progress by lead status, recent activities, top clients, and charts (LeadStatusDonutChart, LeadClientMonthlyChart). Leads and clients tables support search, CRUD dialogs, and lead-to-client conversion (creates the client with leadOriginId and removes the lead).
  • Settings (/settings): protected page that loads the authenticated user, allows updating only the name, and shows e-mail/company ID as read-only fields.

State & Data Flow

  • AuthContext: persists the authenticated user in localStorage, exposes register/login/logout/refresh/update helpers, and hydrates the session on load.
  • CRMDataContext: fetches leads/clients for the user’s company and provides create/update/delete plus conversion helpers with inline error surfacing.
  • NotificationContext: stores recent lead/client events and unread counts; rendered by NotificationMenu.
  • SearchContext: keeps a shared search query (used by SearchBar) to filter leads and clients.
  • Route Protection: useProtectedRoute redirects anonymous visitors back to /.
  • Services: axios instance resolves the API base URL and centralizes calls under src/services/.

UI Notes

  • LayoutProviders applies MUI theming, responsive typography, and a persistent light/dark toggle stored in localStorage.
  • DashboardLayout offers a responsive sidebar, global search, notifications, and user menu across protected pages.
  • Dialog components (LeadDialog, ClientDialog, ConfirmDialog) encapsulate form validation, and charts use Chart.js wrappers.
  • Global tokens in globals.css keep colors consistent between light and dark modes.

Database & Prisma

  • Prisma models live in api/prisma/schema.prisma and target a PostgreSQL datasource configured via DATABASE_URL.
  • Entities:
    • Company: parent record for the multi-tenant structure.
    • User: belongs to a company, stores passwordHash, and defaults to role USER.
    • Leads: prospects tied to a company with LeadStatus (HOT, WARM, COLD), plus optional cnpj/cpf.
    • Clients: customers tied to a company, optionally linked to a lead origin (leadOriginId).
  • Run Prisma tooling from api/: 
    npm run prisma:generate
npm run prisma:migrate    # applies existing migrations
npm run prisma:studio
  • src/scripts/seedAll.ts exists as a stub; no seed data is applied by default.

API Overview

Every route is prefixed with /api (see api/src/index.ts). The key resources are:

Resource Base Path Notes
Users /users Includes authentication via /users/login (returns the user without tokens).
Companies /companies Full CRUD with UUID identifiers.
Leads /companies/{companyId}/leads Scoped to a company; uses integer lead IDs.
Clients /companies/{companyId}/clients Scoped to a company; can be linked to a lead origin.

Detailed request/response shapes and status codes are documented in Swagger UI and enforced via Zod validators under api/src/validators.

Error Handling & Validation

  • Zod schemas guard bodies and params; failures raise ValidationError with 400 responses.
  • Domain errors (ConflictError, NotFoundError, AuthenticationError) extend ApplicationError to keep status codes consistent.
  • Unknown exceptions are logged and returned as 500 errors.

Project Structure

api/
  src/
    controllers/     # Express route handlers coordinating validation and services
    services/        # Business logic layers integrating with Prisma
    routes/          # Resource routing mounted under /api
    validators/      # Zod schemas for bodies and params
    errors/          # Custom error hierarchy for predictable HTTP responses
    docs/            # Swagger specification builder
    db/              # Prisma client bootstrap
    security/        # Password hashing helpers
    scripts/         # Seed stub for deployment environments
  prisma/
    schema.prisma    # Database schema and generator configuration
frontend/
  src/
    app/             # Next.js routes (App Router)
    components/      # Shared UI components, dialogs, layout, charts
    contexts/        # React context providers (auth, CRM data, notifications, search)
    hooks/           # Custom hooks (route protection, etc.)
    services/        # Axios instances and resource-specific calls
    types/           # Shared data contracts between frontend modules

Available npm Scripts

  • api/npm run dev: start the API with tsx watch.
  • api/npm run build: compile TypeScript sources to dist/.
  • api/npm run start: run the compiled API with Node.js.
  • api/npm run prisma:generate: generate the Prisma client.
  • api/npm run prisma:migrate: apply migrations with prisma migrate deploy.
  • api/npm run prisma:studio: open Prisma Studio.
  • api/npm run seed: run the seed stub (no-op by default).
  • api/npm run render:build: install, generate Prisma client, and build (Render deployment helper).
  • frontend/npm run dev: start the Next.js dev server.
  • frontend/npm run build: create a production build.
  • frontend/npm run start: serve the production build.
  • frontend/npm run lint: lint TypeScript/React files.

Contributing

  1. Fork the repository and create a feature branch.
  2. Keep commits focused and document any behavioral changes.
  3. Open a pull request describing the motivation and how you validated the change.