nexus-5/README.md

# Nexus 5

A modern, production-ready field service management API built with Django, Strawberry GraphQL, and Django Channels. Nexus 5 represents the culmination of lessons learned from previous iterations, combining the developer productivity of Django with enterprise-grade features.

## Improvements Over Previous Versions

### Evolution from Nexus 1-4

| Feature | Nexus 1-2 | Nexus 3 | Nexus 4 (Rust) | Nexus 5 |
|---------|-----------|---------|----------------|---------|
| **API** | REST (DRF) | GraphQL (Graphene) | GraphQL (async-graphql) | GraphQL (Strawberry) |
| **Real-time** | None | None | None | WebSocket subscriptions |
| **Auth** | JWT (DRF) | JWT (graphql-jwt) | JWT (jsonwebtoken) | Ory Kratos + Oathkeeper |
| **Background Tasks** | None | None | None | Celery + Redis |
| **File Storage** | Local | Local | None | S3-compatible (Garage) |
| **Caching** | None | None | None | Valkey/Redis with Sentinel HA |
| **Database Credentials** | Static .env | Static .env | Static .env | HashiCorp Vault (dynamic) |
| **Chat/AI** | None | None | None | Claude AI integration |
| **Email** | Django SMTP | Django SMTP | None | Rust microservice |

### Key Improvements in Nexus 5

1. **Strawberry GraphQL**: Modern, type-safe GraphQL with native Python type hints
2. **Real-time Subscriptions**: WebSocket-based subscriptions for live updates via Django Channels
3. **Ory Authentication Stack**: Enterprise-grade auth with Kratos (identity) + Oathkeeper (API gateway)
4. **High-Availability Caching**: Valkey/Redis with Sentinel support for automatic failover
5. **Dynamic Database Credentials**: HashiCorp Vault integration for rotating DB credentials
6. **S3-Compatible Storage**: Garage cluster for distributed file storage
7. **AI Chat Integration**: Claude-powered assistant for the application
8. **MCP Server**: Model Context Protocol server for AI tool integration
9. **Celery Beat Scheduling**: Automated monitoring and notification tasks
10. **Session Tracking**: Detailed work sessions with images, videos, and notes

## Tech Stack

### Backend
- Python 3.11+
- Django 5.x
- Strawberry GraphQL
- Django Channels (WebSocket)
- Celery + Redis/Valkey
- PostgreSQL
- S3 Storage (Garage/MinIO compatible)
- HashiCorp Vault (optional)

### External Services
- Ory Kratos (Identity Management)
- Ory Oathkeeper (API Gateway)
- Valkey/Redis (Caching & Pub/Sub)
- Anthropic Claude (AI Chat)

## Project Structure

```
nexus-5/
├── config/
│   ├── settings.py       # Django settings with env vars
│   ├── celery.py         # Celery configuration
│   ├── asgi.py           # ASGI with Channels
│   ├── storage.py        # S3 storage backend
│   └── db_backend/       # Custom DB backend for Vault
├── core/
│   ├── models/           # Domain models
│   ├── graphql/
│   │   ├── types/        # Strawberry types
│   │   ├── inputs/       # Input types
│   │   ├── filters/      # Filter types
│   │   ├── queries/      # Query resolvers
│   │   ├── mutations/    # Mutation resolvers
│   │   └── subscriptions/# WebSocket subscriptions
│   ├── chat/             # AI chat with Channels
│   ├── mcp/              # MCP server for AI tools
│   ├── services/         # Business logic services
│   ├── tasks/            # Celery tasks
│   └── templates/        # Email templates
├── vault/                # Vault configuration templates
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml        # Poetry dependencies
```

## Quick Start

### Prerequisites
- Python 3.11+
- PostgreSQL 15+
- Redis/Valkey
- Docker (recommended)

### Development Setup

```bash
# Clone repository
git clone <repository-url>
cd nexus-5

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies with Poetry
pip install poetry
poetry install

# Create .env file
cp .env.example .env
# Edit .env with your configuration

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Start development server
python manage.py runserver
```

### With Docker

```bash
docker-compose up -d
```

## Configuration

### Required Environment Variables

```bash
# Django
SECRET_KEY=your-secret-key
DEBUG=False

# Database
DB_NAME=nexus
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=password

# Redis/Valkey
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=password

# Ory (if using)
OATHKEEPER_SECRET=your-oathkeeper-secret
```

### Optional Environment Variables

```bash
# High Availability
REDIS_SENTINEL_HOSTS=host1:26379,host2:26379,host3:26379
REDIS_SENTINEL_MASTER=valkey-ha
REDIS_CLUSTER_MODE=False

# S3 Storage
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_STORAGE_BUCKET_NAME=nexus-media
AWS_S3_ENDPOINT_URL=http://localhost:3900

# AI Chat
ANTHROPIC_API_KEY=your-api-key
ANTHROPIC_MODEL=claude-sonnet-4-20250514

# Emailer Microservice
EMAILER_BASE_URL=https://email.example.com
EMAILER_API_KEY=your-api-key

# Dispatch Profile (for labor calculations)
DISPATCH_TEAM_PROFILE_ID=uuid-here
```

## GraphQL API

The GraphQL endpoint is available at `/graphql/` with the GraphiQL playground.

### Example Query

```graphql
query GetServices($filter: ServiceFilter) {
  services(filter: $filter) {
    id
    date
    status
    account {
      name
    }
    teamMembers {
      firstName
      lastName
    }
  }
}
```

### Example Subscription

```graphql
subscription OnServiceUpdated {
  serviceUpdated {
    id
    status
    date
  }
}
```

## Core Features

### Work Session Tracking
- Start/stop time tracking for services and projects
- Photo and video documentation
- Internal and customer-visible notes
- Task completion tracking with scopes

### Scope Management
- Reusable scope templates
- Area-based task organization
- Frequency-based task scheduling (daily, weekly, monthly)
- Completion tracking per service

### Real-time Messaging
- Internal team conversations
- Customer communication threads
- Unread counts and read receipts
- WebSocket-based live updates

### AI Chat Assistant
- Claude-powered contextual help
- MCP server for tool integration
- Conversation history per user

## Deployment

### Production Checklist

1. Set `DEBUG=False`
2. Configure strong `SECRET_KEY`
3. Set up PostgreSQL with proper credentials
4. Configure Valkey/Redis (consider Sentinel for HA)
5. Set up Ory Kratos and Oathkeeper
6. Configure S3 storage
7. Set up Celery workers and beat scheduler
8. Configure nginx reverse proxy
9. Enable HTTPS

### Running Celery

```bash
# Worker
celery -A config worker -l INFO

# Beat scheduler
celery -A config beat -l INFO
```

## Related Services

- **nexus-5-auth**: Ory Kratos/Oathkeeper configuration and auth frontend
- **nexus-5-emailer**: Rust-based email microservice
- **nexus-5-scheduler**: Calendar integration service
- **nexus-5-frontend-***: SvelteKit frontend applications

## License

MIT License - See LICENSE file for details.