nexus-3/README.md

Nexus 3

A modern business management platform built with Django GraphQL and SvelteKit. Nexus 3 represents a significant architectural evolution from its predecessors, featuring a GraphQL API, modular backend architecture, and enhanced frontend state management.

Improvements Over Nexus 1 and Nexus 2

Architectural Improvements Over Nexus 1

Feature	Nexus 1	Nexus 3
API Architecture	REST API	GraphQL API
Frontend Framework	React (JSX)	SvelteKit with TypeScript
Backend Structure	Monolithic (single models.py, views.py)	Modular (separate directories per domain)
State Management	Prop drilling	Svelte stores with typed operations
Authentication	JWT with DRF	JWT with graphql-jwt
Type Safety	None	Full TypeScript support
Code Organization	Flat structure	Domain-driven design

Architectural Improvements Over Nexus 2

Feature	Nexus 2	Nexus 3
API Architecture	REST API (DRF ViewSets)	GraphQL API (Graphene)
Data Fetching	Multiple REST endpoints	Single GraphQL endpoint with precise queries
Backend Patterns	MVC with serializers	Repository + Command pattern
Settings Management	Single settings.py	Split settings (base/dev/prod)
Frontend Data Layer	Direct API calls	Typed GraphQL operations with URQL
Caching	None	URQL exchange-based caching
Error Handling	HTTP status codes	GraphQL error extensions

Key Improvements in Nexus 3

1. GraphQL API: Clients request exactly the data they need, reducing over-fetching and under-fetching
2. Repository Pattern: Data access is abstracted through repositories, making testing and maintenance easier
3. Command Pattern: Business logic is encapsulated in commands, promoting single responsibility
4. Factory Pattern: Object creation is standardized through factories
5. Split Settings: Environment-specific configuration (development, production)
6. Typed Frontend: Full TypeScript support with generated types for GraphQL operations
7. URQL Client: Modern GraphQL client with built-in caching and auth exchange
8. Modular Structure: Each domain (accounts, customers, services, etc.) has its own:
   • Models
   • Repositories
   • Commands
   • GraphQL types, inputs, queries, and mutations
   • Frontend stores and components

Tech Stack

Backend

• Python 3.11+
• Django 4.2+
• Graphene-Django (GraphQL)
• graphql-jwt (Authentication)
• PostgreSQL
• Redis (caching)

Frontend

• SvelteKit
• TypeScript
• URQL (GraphQL client)
• TailwindCSS

Project Structure

nexus-3/
├── backend/
│   ├── config/
│   │   └── settings/
│   │       ├── base.py
│   │       ├── development.py
│   │       └── production.py
│   ├── core/
│   │   ├── models/          # Domain models
│   │   ├── repositories/    # Data access layer
│   │   ├── commands/        # Business logic
│   │   ├── factories/       # Object creation
│   │   ├── services/        # Service layer
│   │   └── utils/           # Utilities
│   └── graphql_api/
│       ├── types/           # GraphQL types
│       ├── inputs/          # GraphQL input types
│       ├── queries/         # GraphQL queries
│       └── mutations/       # GraphQL mutations
├── frontend/
│   └── src/
│       ├── lib/
│       │   ├── components/  # UI components by domain
│       │   ├── graphql/     # GraphQL client & operations
│       │   └── stores/      # Svelte stores by domain
│       └── routes/          # SvelteKit routes
└── docker-compose.yml

Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+ (or use Docker)
• Redis (optional, for caching)

Using Docker (Recommended)

# Clone the repository
git clone <repository-url>
cd nexus-3

# Copy environment file
cp backend/.env.example backend/.env
# Edit backend/.env with your settings

# Start all services
docker-compose up -d

# Run migrations
docker-compose exec backend python manage.py migrate

# Create a superuser
docker-compose exec backend python manage.py createsuperuser

Manual Setup

Backend

cd backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment file
cp .env.example .env
# Edit .env with your settings

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Start development server
python manage.py runserver

Frontend

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

Configuration

Backend Environment Variables

Variable	Description	Default
DJANGO_SETTINGS_MODULE	Settings module to use	config.settings.development
DJANGO_SECRET_KEY	Django secret key (production)	-
DEV_SECRET_KEY	Django secret key (development)	-
DB_NAME	Database name	nexus
DB_USER	Database user	postgres
DB_PASSWORD	Database password	-
DB_HOST	Database host	localhost
DB_PORT	Database port	5432
REDIS_URL	Redis connection URL	redis://localhost:6379/1
SENTRY_DSN	Sentry DSN for error tracking	-

Frontend Environment Variables

Variable	Description	Default
PUBLIC_GRAPHQL_URL	GraphQL API endpoint	http://localhost:8000/graphql/

GraphQL API

The GraphQL API is available at /graphql/. In development, you can use the GraphiQL interface to explore the schema.

Example Query

query GetAccounts {
  accounts {
    id
    name
    customer {
      id
      name
    }
    services {
      id
      status
      scheduledDate
    }
  }
}

Example Mutation

mutation CreateAccount($input: AccountCreateInput!) {
  createAccount(input: $input) {
    account {
      id
      name
    }
    errors
  }
}

Core Entities

• Customers: Client organizations
• Accounts: Individual locations/sites belonging to customers
• Services: Scheduled service visits
• Projects: Multi-service projects
• Invoices: Billing records
• Labor: Labor tracking records
• Revenue: Revenue tracking
• Schedules: Employee schedules
• Reports: Generated reports
• Punchlists: Customizable service checklists

Customizing the Punchlist Feature

The Punchlist model is designed to be customizable for your specific service workflow. The default fields provide a generic structure with sections for:

• Front area (customer-facing)
• Main work area
• Equipment
• Back area
• End of visit checklist

To customize:

1. Edit backend/core/models/punchlists/punchlists.py to add/remove/rename fields
2. Update backend/graphql_api/types/punchlists.py to expose the new fields
3. Update backend/graphql_api/inputs/punchlists/punchlists.py for create/update inputs
4. Run python manage.py makemigrations and python manage.py migrate
5. Update the frontend components accordingly

Development

Running Tests

# Backend tests
cd backend
python manage.py test

# Frontend tests
cd frontend
npm run test

Code Style

# Backend (using black and isort)
cd backend
black .
isort .

# Frontend (using prettier and eslint)
cd frontend
npm run lint
npm run format

Deployment

Production Checklist

1. Set DJANGO_SETTINGS_MODULE=config.settings.production
2. Generate a strong DJANGO_SECRET_KEY
3. Configure PostgreSQL with proper credentials
4. Set up Redis for caching
5. Configure ALLOWED_HOSTS and CORS settings
6. Set up SSL/TLS
7. Configure email settings
8. (Optional) Set up Sentry for error tracking

License

MIT License - See LICENSE file for details.