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:

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

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

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