nexus-5-frontend-3/README.md

# Nexus 5 Frontend 3 - Full Portal

Full-featured web portal for the Nexus 5 platform, combining public marketing pages, customer portal, team interface, and admin dashboard in a single unified application.

## Overview

This is the third and most complete iteration of the Nexus 5 frontend, designed as a comprehensive portal that serves all user types: public visitors, customers, team members, and administrators. It includes public-facing marketing pages alongside authenticated portals for different user roles.

## Tech Stack

- **SvelteKit 5** - Latest SvelteKit with Svelte 5 runes
- **Houdini** - Type-safe GraphQL client
- **Tailwind CSS v4** - Next-generation Tailwind with CSS variables
- **TypeScript** - Strict mode enabled
- **Node adapter** - Production deployment
- **Wave Integration** - Invoice management via Wave API

## Evolution

| Feature | Frontend 1 | Frontend 2 | Frontend 3 |
|---------|------------|------------|------------|
| **Purpose** | Admin only | Team only | All users |
| **Public Pages** | No | No | Yes |
| **Customer Portal** | No | No | Yes |
| **Team Portal** | No | Yes | Yes |
| **Admin Portal** | Yes | No | Yes |
| **Theming** | Basic dark mode | Theme toggle | Full CSS variables |
| **AI Chat** | No | No | Yes |
| **Invoice Integration** | No | No | Wave API |

## Features

### Public Pages
- **Home** - Landing page with service overview
- **Services** - Service offerings and descriptions
- **Pricing** - Pricing information
- **About** - Company information
- **Contact** - Contact form with email integration
- **Privacy/Terms** - Legal pages

### Customer Portal
- **Dashboard** - Overview of accounts and upcoming work
- **Accounts** - View service accounts and locations
- **Schedule** - Upcoming services and projects
- **History** - Completed work history
- **Invoices** - View and pay invoices
- **Profile** - Customer profile management

### Team Portal
- **Dashboard** - Today's assignments
- **Services** - Assigned services with session management
- **Projects** - Assigned projects
- **Reports** - Submit and view reports
- **Profile** - Team member profile

### Admin Portal
- **Dashboard** - Business overview
- **Customers** - Customer management
- **Accounts** - Account management
- **Services** - Service scheduling and assignment
- **Projects** - Project management
- **Scopes** - Scope template management
- **Reports** - Report management
- **Invoices** - Invoice creation and Wave integration
- **Calendar** - Event management
- **Profiles** - User profile management
- **Notifications** - Notification rule configuration
- **Event Log** - System event audit log

### Cross-cutting Features
- **AI Chat** - Claude-powered assistant for all users
- **Messages** - Inter-user messaging
- **Notifications** - Real-time notifications
- **Theme Toggle** - Light/dark mode support

## Getting Started

### Prerequisites

- Node.js 18+
- Access to Nexus 5 GraphQL API
- (Optional) Wave API credentials for invoicing

### Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Type checking
npm run check
```

### Docker Deployment

```bash
# Build and run
docker-compose up --build

# Production deployment
docker-compose -f docker-compose.prod.yml up -d
```

### Environment Variables

See `.env.example` for required configuration:

- `PUBLIC_GRAPHQL_URL` - Nexus 5 API endpoint
- `PUBLIC_KRATOS_URL` - Ory Kratos public URL
- `WAVE_ACCESS_TOKEN` - Wave API token (for invoicing)
- `WAVE_BUSINESS_ID` - Wave business ID

## Project Structure

```
src/
├── lib/
│   ├── components/
│   │   ├── admin/          # Admin-specific components
│   │   ├── chat/           # AI chat interface
│   │   ├── customer/       # Customer portal components
│   │   ├── entity/         # Shared entity components
│   │   ├── icons/          # SVG icon components
│   │   ├── layout/         # Layout components
│   │   ├── nav/            # Navigation (TopNav, AdminNav, etc.)
│   │   ├── session/        # Work session components
│   │   ├── shared/         # Shared UI components
│   │   └── team/           # Team portal components
│   ├── data/               # Static data (event types, etc.)
│   ├── graphql/
│   │   ├── mutations/      # GraphQL mutations
│   │   ├── queries/        # GraphQL queries
│   │   └── wave/           # Wave API integration
│   ├── server/             # Server-side utilities
│   ├── services/           # External service integrations
│   ├── stores/             # Svelte stores
│   └── utils/              # Utility functions
└── routes/
    ├── admin/              # Admin portal routes
    ├── customer/           # Customer portal routes
    ├── team/               # Team portal routes
    ├── messages/           # Messaging
    ├── notifications/      # Notifications
    ├── about/              # Public pages
    ├── contact/
    ├── pricing/
    ├── privacy/
    ├── services/
    ├── terms/
    └── login/logout/       # Auth flows
```

## Key Patterns

### CSS Variables for Theming

Uses CSS custom properties for comprehensive theming:

```css
:root {
  --color-primary-500: #3b82f6;
  --bg-primary: 255 255 255;
  --text-primary: 15 23 42;
}

.dark {
  --bg-primary: 15 23 42;
  --text-primary: 248 250 252;
}
```

### Role-Based Navigation

Navigation adapts based on user role:

```svelte
{#if isAdmin}
  <AdminNav />
{:else if isTeamMember}
  <TeamNav />
{:else if isCustomer}
  <CustomerNav />
{:else}
  <PublicNav />
{/if}
```

### Server-Side Data Loading

Uses SvelteKit's load functions for server-side data fetching:

```typescript
// +page.server.ts
export const load = async ({ locals }) => {
  const data = await fetchData(locals.user);
  return { data };
};
```

### Wave API Integration

Separate GraphQL client for Wave invoice management:

```typescript
import { waveClient } from '$lib/graphql/wave';

const invoices = await waveClient.query({
  query: ListInvoices,
  variables: { businessId }
});
```

## Related Repositories

- **nexus-5** - Django GraphQL API backend
- **nexus-5-auth** - Ory Kratos/Oathkeeper authentication
- **nexus-5-frontend-1** - Admin-only dashboard
- **nexus-5-frontend-2** - Team-only mobile app
- **nexus-5-emailer** - Email microservice
- **nexus-5-scheduler** - Calendar integration microservice

## License

MIT License - See LICENSE file for details.