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)

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

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

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

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

### Example Mutation

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

```bash
# Backend tests
cd backend
python manage.py test

# Frontend tests
cd frontend
npm run test
```

### Code Style

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