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:
```bash
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

```bash
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

```bash
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:
```bash
BACKEND_PORT=8443
FRONTEND_PORT=443
FRONTEND_ORIGIN=https://your-domain.com
PUBLIC_API_URL=https://api.your-domain.com/api
```

### Build and Run

```bash
# 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