60+ API Endpoints

15 Data Models

40+ Vue Components

75 Passing Tests

5 RBAC Roles

50+ Permissions

---

Table of Contents

• Features
• Architecture
• Tech Stack
• Quick Start
• Project Structure
• API Overview
• Role-Based Access Control
• Screenshots
• License

---

Features

Backend Capabilities JWT Authentication with access + refresh tokens RBAC with 5 roles and 50+ granular permissions Deal Pipeline Engine with stage transitions, win/lose tracking Full-Text Search across contacts, companies, deals Analytics Dashboard — revenue forecasts, conversion rates, pipeline velocity Audit Logging for complete change tracking Webhook System with event subscriptions and retry logic Email Templates per user and organization API Key Management with expiration Celery Task Queue for async email and webhook dispatch WebSocket real-time notifications Multi-tenant organization isolation

Frontend Experience DataTable with sort, filter, paginate, bulk actions Kanban Board with drag-and-drop deal pipeline Contact & Deal Cards with inline editing Activity Timeline for tracking interactions Charts — revenue, pipeline, conversion via Chart.js Global Search with instant results (Alt+S) Form Builder for dynamic forms Tag Input, Date Range Picker, Rich Text Editor Notification Bell with real-time WebSocket updates Dark / Light Theme toggle Responsive Layout with sidebar navigation Keyboard Shortcuts for power users

---

Architecture

System Architecture Diagram

graph TB
    subgraph Frontend["Frontend — Vue 3 + TypeScript"]
        UI[Vue Components]
        Pinia[Pinia Stores]
        Router[Vue Router]
        WS_Client[WebSocket Client]
    end

    subgraph Backend["Backend — FastAPI"]
        API[REST API v1]
        Auth[JWT Auth + RBAC]
        Services[Business Logic]
        Pipeline[Deal Pipeline Engine]
        Search[Full-Text Search]
        Analytics[Analytics Engine]
        WS_Server[WebSocket Manager]
    end

    subgraph Workers["Async Workers"]
        Celery[Celery Workers]
        EmailTask[Email Tasks]
        WebhookTask[Webhook Dispatch]
    end

    subgraph Data["Data Layer"]
        PG[(PostgreSQL 16)]
        Redis[(Redis 7)]
    end

    UI --> Pinia
    Pinia --> API
    WS_Client --> WS_Server
    Router --> UI

    API --> Auth
    Auth --> Services
    Services --> Pipeline
    Services --> Search
    Services --> Analytics
    Services --> PG

    Celery --> EmailTask
    Celery --> WebhookTask
    Celery --> Redis
    Celery --> PG

    WS_Server --> Redis

    style Frontend fill:#42b883,color:#fff
    style Backend fill:#009688,color:#fff
    style Workers fill:#ff6f00,color:#fff
    style Data fill:#1565c0,color:#fff

Loading

---

Tech Stack

Backend

Frontend

Infrastructure

---

Quick Start

Docker (recommended)

git clone https://github.com/N3XT3R1337/nexus-crm.git && cd nexus-crm
cp .env.example .env
docker compose up -d

The app will be available at http://localhost:3000 with the API at http://localhost:8000.

Local Development

# Backend
cd backend && python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

# Frontend (in a new terminal)
cd frontend && npm install && npm run dev

Seed Data

make seed    # Generates 500 contacts, 200 companies, 100 deals

---

Project Structure

nexus-crm/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   ├── deps.py              # Auth dependencies & permission checks
│   │   │   └── v1/                   # API v1 endpoints
│   │   │       ├── auth.py           #   Registration, login, token refresh
│   │   │       ├── contacts.py       #   Contact CRUD + bulk actions
│   │   │       ├── companies.py      #   Company management
│   │   │       ├── deals.py          #   Deal pipeline & transitions
│   │   │       ├── activities.py     #   Activity tracking
│   │   │       ├── notes.py          #   Notes on contacts/deals
│   │   │       ├── tags.py           #   Tag management
│   │   │       ├── users.py          #   User administration
│   │   │       ├── email_templates.py#   Email template CRUD
│   │   │       ├── notifications.py  #   Notification management
│   │   │       ├── webhooks.py       #   Webhook subscriptions
│   │   │       ├── reports.py        #   Analytics & reports
│   │   │       ├── search.py         #   Full-text search
│   │   │       └── dashboard.py      #   Dashboard statistics
│   │   ├── core/
│   │   │   ├── security.py           # JWT, password hashing
│   │   │   ├── rbac.py               # Role-based access control
│   │   │   └── websocket.py          # WebSocket connection manager
│   │   ├── models/                   # 15 SQLAlchemy models
│   │   ├── schemas/                  # Pydantic request/response schemas
│   │   ├── services/                 # Business logic layer
│   │   │   ├── auth.py               #   Authentication service
│   │   │   ├── analytics.py          #   Dashboard & reporting
│   │   │   ├── deal_pipeline.py      #   Pipeline stage transitions
│   │   │   ├── search.py             #   Full-text search service
│   │   │   ├── notification.py       #   Notification dispatch
│   │   │   └── webhook.py            #   Webhook event handling
│   │   ├── tasks/                    # Celery async tasks
│   │   ├── config.py                 # Application settings
│   │   ├── database.py               # SQLAlchemy engine & session
│   │   ├── main.py                   # FastAPI application entry
│   │   └── seed.py                   # Sample data generator
│   ├── tests/                        # 75 pytest tests
│   ├── alembic/                      # Database migrations
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── api/client.ts             # Axios instance with interceptors
│   │   ├── components/               # 40+ Vue components
│   │   │   ├── common/               #   DataTable, Modal, SearchBar, etc.
│   │   │   ├── dashboard/            #   StatsCard, Charts
│   │   │   ├── deals/                #   KanbanBoard, DealCard
│   │   │   ├── contacts/             #   ContactCard
│   │   │   ├── activities/           #   ActivityTimeline
│   │   │   ├── layout/               #   Sidebar, TopBar
│   │   │   └── notifications/        #   NotificationBell
│   │   ├── views/                    # 15+ page views
│   │   ├── stores/                   # 5 Pinia stores
│   │   ├── composables/              # useTheme, useKeyboardShortcuts, useWebSocket
│   │   ├── types/                    # TypeScript interfaces
│   │   ├── router/                   # Vue Router configuration
│   │   └── main.ts
│   ├── Dockerfile
│   ├── vite.config.ts
│   └── package.json
├── docker-compose.yml                # PostgreSQL + Redis + Backend + Celery + Frontend
├── Makefile                          # Development commands
├── .env.example
├── .editorconfig
├── .gitignore
└── LICENSE

---

API Overview

Module	Endpoints	Description
Auth	POST /register POST /login POST /refresh GET /me PUT /me POST /change-password	Authentication & profile
Contacts	GET POST PUT DELETE + /bulk /activities /deals /notes	Contact management with relationships
Companies	GET POST PUT DELETE + /contacts /deals	Company management
Deals	GET POST PUT DELETE + /stages /transition /win /lose /pipeline	Deal pipeline engine
Activities	GET POST PUT DELETE + /complete	Activity tracking (calls, emails, meetings)
Notes	GET POST PUT DELETE	Notes on contacts, deals, companies
Tags	GET POST PUT DELETE	Color-coded tag system
Users	GET POST PUT DELETE	User administration
Email Templates	GET POST PUT DELETE	Reusable email templates
Notifications	GET PUT /read PUT /read-all DELETE	Notification management
Webhooks	GET POST PUT DELETE	Event-driven webhook subscriptions
Reports	GET /revenue-forecast /pipeline-velocity /conversion-rates	Analytics & reporting
Search	GET /search?q=	Cross-entity full-text search
Dashboard	GET /stats /pipeline-summary /deal-value-by-month /contacts-by-source	Dashboard analytics

Interactive API docs available at http://localhost:8000/docs (Swagger UI).

---

Role-Based Access Control

Permission	Viewer	Sales Rep	Manager	Admin	Super Admin
View contacts/deals	✅	✅	✅	✅	✅
Create/edit contacts	❌	✅	✅	✅	✅
Delete contacts	❌	❌	✅	✅	✅
Transition deal stages	❌	✅	✅	✅	✅
Manage users	❌	❌	👀	✅	✅
Delete users	❌	❌	❌	❌	✅
System settings	❌	❌	❌	✅	✅
Audit logs	❌	❌	❌	✅	✅

---

Screenshots

Dashboard	Pipeline
Revenue charts, stats cards, activity feed	Kanban board with drag-and-drop stages

Contacts	Deal Detail
DataTable with filters, search, bulk actions	Timeline, notes, stage history

---

Built with ❤️ by panaceya | github.com/N3XT3R1337