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

# 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

docker-compose up -d

Configuration

Required Environment Variables

# 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

# 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

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

Example Subscription

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

# 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.