nexus-2/README.md

Nexus 2

A field service management and CRM platform built with Django REST Framework and SvelteKit. Designed for managing customers, accounts, service schedules, projects, invoices, and team coordination with integrated Google Workspace services.

Improvements Over Nexus 1

Nexus 2 is a complete rewrite that addresses limitations in the original Nexus platform:

Architecture

• Modern Frontend Stack: Migrated from React + Webpack to SvelteKit + Vite for faster builds, better developer experience, and SSR capabilities
• TypeScript Throughout: Full TypeScript support in the frontend with typed API interfaces
• Cleaner Project Structure: Separated backend and frontend into distinct directories for better organization
• Simplified Deployment: Removed Redis dependency - no longer required for basic operation

Data Model Enhancements

• Customer Entity: Added a Customer model to group related Accounts under a single business entity with centralized billing information
• Revenue Tracking: Track revenue per account with date ranges for historical billing data
• Labor Costs: Track labor costs on projects for profitability analysis
• Flexible Scheduling: New Schedule model defines weekly service patterns with exceptions, enabling automatic service generation

New Features

• Invoice Management: Full invoicing system with draft/sent/paid/overdue status tracking and payment recording
• Service Auto-Generation: Generate monthly service records automatically from defined schedules
• Role-Based Profiles: Team members have roles (Admin, Team Leader, Team Member) for access control
• Dashboard: Centralized overview of operations

API Improvements

• RESTful CRUD: Consistent REST API patterns for all entities (vs. custom action-based endpoints in Nexus 1)
• Pagination: Built-in pagination with configurable page sizes
• Better Filtering: Query parameters for filtering lists by related entities

Simplified Integrations

• Focused Google Integration: Calendar and Drive/Sheets only (removed Gmail dependency)
• Optional Google Features: Application works without Google integration configured

Features

• Customer Management: Track customers with contact and billing information
• Account Management: Manage service accounts with locations, contacts, and revenue tracking
• Service Scheduling: Define weekly service schedules with exceptions and auto-generate service records
• Service Tracking: Track service visits with status, team assignments, and notes
• Project Management: Plan and track projects with team assignments and labor costs
• Invoice Management: Generate and track invoices with payment status
• Team Profiles: Manage team members with roles (Admin, Team Leader, Team Member)
• Reports: Track team member activity across services and projects
• Punchlist API: Backend API for project punchlists with Google Sheets/PDF export (frontend UI requires customization)
• Google Calendar Integration: Create calendar events for services and projects
• JWT Authentication: Secure API access with token refresh

Tech Stack

Backend

• Python 3.12
• Django 5.x with Django REST Framework
• PostgreSQL
• Google APIs (Calendar, Drive, Sheets)
• JWT authentication via djangorestframework-simplejwt
• WhiteNoise for static file serving

Frontend

• SvelteKit with TypeScript
• Vite
• Axios for API calls
• SSR-ready

Prerequisites

• Python 3.12+
• Node.js 22+
• PostgreSQL
• Google Workspace account with domain-wide delegation (for calendar/drive features)

Google Workspace Setup

This application can integrate with Google Workspace for calendar events and punchlist exports:

1. Create a service account in Google Cloud Console
2. Enable the following APIs:
   • Google Calendar API
   • Google Drive API
   • Google Sheets API
3. For domain-wide delegation (calendar events on behalf of users):
   • Enable domain-wide delegation for the service account
   • Grant the following scopes in Google Workspace Admin:
     • https://www.googleapis.com/auth/calendar
     • https://www.googleapis.com/auth/drive
     • https://www.googleapis.com/auth/spreadsheets
4. Download the service account JSON key

Configuration

Backend

1. Copy the environment example:

cd backend
cp .env.example .env

2. Configure the required environment variables in .env:
   • SECRET_KEY: Django secret key
   • DB_*: PostgreSQL connection settings
   • GOOGLE_*: Google API configuration (optional)

Frontend

The frontend uses environment variables set in docker-compose or .env:

• PUBLIC_API_URL: Backend API URL (e.g., http://localhost:8000/api)

Development Setup

Backend

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Start development server
python manage.py runserver

Frontend

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Docker Deployment

SSL Certificates

Place your SSL certificates in the certs/ directory:

• frontend-cert.pem and frontend-key.pem for the frontend
• backend-cert.pem and backend-key.pem for the backend (if using HTTPS)

Environment Variables

Create a .env file in the root directory for docker-compose:

BACKEND_PORT=8443
FRONTEND_PORT=443
FRONTEND_ORIGIN=https://your-domain.com
PUBLIC_API_URL=https://api.your-domain.com/api

Build and Run

# Build and start containers
docker-compose up -d --build

# View logs
docker-compose logs -f

Project Structure

nexus-2/
├── backend/                    # Django backend
│   ├── api/                    # Main Django app
│   │   ├── models.py          # Database models
│   │   ├── views.py           # API views
│   │   ├── serializers.py     # DRF serializers
│   │   ├── urls.py            # URL routing
│   │   ├── google.py          # Google API integrations
│   │   └── migrations/        # Database migrations
│   ├── config/                # Django project settings
│   │   ├── settings.py        # Django configuration
│   │   └── urls.py            # Root URL routing
│   ├── manage.py
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/                   # SvelteKit frontend
│   ├── src/
│   │   ├── lib/               # Shared utilities
│   │   │   ├── api.ts         # API client with types
│   │   │   ├── auth.ts        # Authentication helpers
│   │   │   └── components/    # Reusable components
│   │   └── routes/            # SvelteKit routes
│   │       ├── accounts/      # Account management
│   │       ├── customers/     # Customer management
│   │       ├── services/      # Service tracking
│   │       ├── projects/      # Project management
│   │       ├── invoices/      # Invoice management
│   │       ├── schedules/     # Schedule management
│   │       ├── dashboard/     # Dashboard
│   │       ├── profile/       # User profile
│   │       ├── admin/         # Admin features
│   │       ├── calendar/      # Calendar integration
│   │       └── login/         # Authentication
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml
└── README.md

API Endpoints

Authentication

• POST /api/token/ - Obtain JWT tokens
• POST /api/token/refresh/ - Refresh access token

Profiles

• GET/POST /api/profiles/ - List/create profiles
• GET/PUT/PATCH/DELETE /api/profiles/{id}/ - Profile detail
• POST /api/auth/change-password/ - Change password
• POST /api/auth/reset-password/ - Reset password (admin)

Customers

• GET/POST /api/customers/ - List/create customers
• GET/PUT/PATCH/DELETE /api/customers/{id}/ - Customer detail

Accounts

• GET/POST /api/accounts/ - List/create accounts
• GET/PUT/PATCH/DELETE /api/accounts/{id}/ - Account detail

Revenues

• GET/POST /api/revenues/ - List/create revenues
• GET/PUT/DELETE /api/revenues/{id}/ - Revenue detail

Schedules

• GET/POST /api/schedules/ - List/create schedules
• GET/PUT/PATCH/DELETE /api/schedules/{id}/ - Schedule detail
• POST /api/generate-services/ - Generate services from schedules

Services

• GET/POST /api/services/ - List/create services
• GET/PUT/PATCH/DELETE /api/services/{id}/ - Service detail

Projects

• GET/POST /api/projects/ - List/create projects
• GET/PUT/PATCH/DELETE /api/projects/{id}/ - Project detail

Invoices

• GET/POST /api/invoices/ - List/create invoices
• GET/PUT/PATCH/DELETE /api/invoices/{id}/ - Invoice detail
• POST /api/invoices/{id}/mark_as_paid/ - Mark invoice as paid

Reports

• GET/POST /api/reports/ - List/create reports
• GET/PUT/PATCH/DELETE /api/reports/{id}/ - Report detail

Punchlists

• GET/POST /api/punchlists/ - List/create punchlists
• GET/PUT/PATCH/DELETE /api/punchlists/{id}/ - Punchlist detail
• POST /api/export/punchlist/ - Export punchlist to Google Sheets/PDF

Customizing the Punchlist Feature

The Punchlist model is designed as a customizable checklist for service projects. The backend includes a generic punchlist structure with sections for:

• Front area: ceiling, vents, fixtures, counter
• Main work area: equipment, walls, ceiling, vents, floors
• Equipment stations: 7 configurable stations plus sinks, dispensers, other
• Back area: ceiling, vents
• End of visit: trash, cleanup, security check

To customize for your use case:

1. Modify the model (backend/api/models.py): Update the Punchlist model fields to match your specific checklist requirements

2. Update the field mapping (backend/api/google.py): Modify PUNCHLIST_FIELD_MAPPING to map your model fields to cells in your Google Sheets template

3. Create a Google Sheets template: Design a template that matches your punchlist layout and configure PUNCHLIST_TEMPLATE_ID in your environment

4. Build frontend UI: The frontend punchlist routes were removed as they were specific to a previous implementation. Create new SvelteKit routes under frontend/src/routes/projects/punchlist/ with forms matching your model fields

The punchlist API endpoints are fully functional - only the frontend UI needs to be built for your specific workflow.

License

MIT