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

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Type checking
npm run check

Docker Deployment

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

: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:

{#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:

// +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:

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.