nexus-1/README.md

Nexus

A field service management platform built with Django REST Framework and React. Designed for managing accounts, service visits, projects, and team coordination with integrated Google Workspace services.

Features

• Account Management: Track client accounts with service schedules and contact information
• Service Visits: Create, track, and close daily service visits with notes
• Project Management: Schedule and manage multi-store projects with punchlists
• Reports: Generate monthly reports with visit tracking and rate calculations
• Supply Requests: Submit supply requests from the field
• Google Integration: Calendar invites, email notifications, and Drive-based punchlist PDFs
• JWT Authentication: Secure team member login with token refresh

Tech Stack

Backend

• Python 3.12
• Django 5.1.3 with Django REST Framework
• PostgreSQL with psycopg2-binary
• Redis for caching
• Google APIs (Calendar, Gmail, Drive, Sheets)
• JWT authentication via djangorestframework-simplejwt

Frontend

• React 18
• React Router 7
• Bootstrap 5
• Webpack 5
• Axios for API calls

Prerequisites

• Python 3.12+
• Node.js 22+
• PostgreSQL
• Redis (optional, for caching)
• Google Workspace account with domain-wide delegation configured

Google Workspace Setup

This application requires a Google Service Account with domain-wide delegation:

1. Create a service account in Google Cloud Console
2. Enable domain-wide delegation for the service account
3. Grant the following scopes in Google Workspace Admin:
   • https://www.googleapis.com/auth/calendar
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/drive
   • https://www.googleapis.com/auth/spreadsheets
4. Download the service account JSON key

Configuration

1. Copy .env.example to .env and configure:

cp .env.example .env

2. Required environment variables:
   • SECRET_KEY: Django secret key
   • PSQL: PostgreSQL connection string
   • SERVICE_ACCOUNT_KEY: Google service account JSON (as string)
   • DISPATCH_EMAIL: Email address for the service account to impersonate
   • TEAM_EMAILS: Comma-separated list of team member emails
   • PUNCHLIST_FOLDER_ID: Google Drive folder ID for punchlists
   • PUNCHLIST_TEMPLATE_ID: Google Sheets template ID for punchlists

Development Setup

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

# Install dependencies
npm install

# Start development server
npm start

# 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 nginx
• backend-cert.pem and backend-key.pem for gunicorn

Build and Run

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

# View logs
docker-compose logs -f

The frontend will be available on port 443, and the backend API on port 8443.

Project Structure

nexus/
├── api/                    # Django app with models, views, serializers
│   ├── models.py          # Database models
│   ├── views.py           # API endpoints
│   ├── serializers.py     # DRF serializers
│   ├── gcalendar.py       # Google Calendar integration
│   ├── gmail.py           # Gmail integration
│   ├── gdrive.py          # Google Drive integration
│   ├── gsheets.py         # Google Sheets integration
│   └── redis_client.py    # Redis caching
├── nexus/                  # Django project settings
│   ├── settings.py        # Django configuration
│   └── urls.py            # URL routing
├── frontend/               # React application
│   ├── components/        # Reusable React components
│   ├── modules/           # Page-level React components
│   ├── api.js             # Axios API client
│   ├── constants.js       # Frontend constants
│   ├── App.jsx            # Main React app
│   └── main.jsx           # React entry point
├── templates/              # HTML templates
├── static/                 # Static files
├── docker-compose.yml      # Docker composition
├── Dockerfile.backend      # Backend container
├── Dockerfile.frontend     # Frontend container
└── nginx.conf             # Nginx configuration

API Endpoints

• POST /token/ - Obtain JWT tokens
• POST /token/refresh/ - Refresh JWT token
• GET /accounts/ - List all accounts
• GET /accounts/status/ - Get account status
• POST /accounts/supplies/ - Submit supply request
• GET /stores/ - List all stores
• GET /projects/ - List all projects
• POST /projects/close/ - Close a project
• POST /projects/punch/ - Submit punchlist
• POST /visits/ - Get visits for date
• POST /visits/close/ - Close a visit
• GET /days/:account/ - Get service days for account
• POST /calendar/ - Create calendar event
• GET /team/ - List team members
• POST /user/password/change/ - Change user password

License

MIT