Chapter 3: Architecture & Technical Stack

A comprehensive technical reference covering the full-stack architecture, database schema, state management patterns, component library, and directory structure of the NDSS CRM platform built by Newdawn Support Services.

3.1 System Architecture Overview

NDSS CRM follows a modern, layered full-stack architecture designed for performance, scalability, and maintainability. The platform is composed of four primary tiers: a Next.js frontend served via server-side rendering and static generation, a Supabase / Oracle backend-as-a-service layer providing authentication and real-time database access, Python microservices for data processing and analytics workloads, and PHP integration modules for legacy system compatibility with existing Newdawn Support Services infrastructure.

The architecture is designed to support the demanding requirements of NDIS disability care organisations, where data integrity, audit compliance, role-based security, and real-time collaboration are critical operational needs.

3.1.1 High-Level Architecture Diagram

The following wireframe diagram illustrates the four-tier architecture of the NDSS CRM platform and the data flow between each layer.

3.1.2 Architecture Summary Table

3.2 Frontend Architecture

The NDSS CRM frontend is built on Next.js 16 using the App Router paradigm introduced in Next.js 13 and matured through subsequent releases. The App Router provides file-system-based routing, React Server Components (RSC), streaming server-side rendering, and fine-grained layout nesting - all of which are leveraged extensively throughout the platform.

3.2.1 Next.js 16 App Router

The App Router organises routes as directories within the src/app/ folder. Each directory can contain a page.tsx file (the rendered page), a layout.tsx file (shared layout wrapper), a loading.tsx file (suspense fallback), and an error.tsx file (error boundary). This convention-based approach eliminates the need for manual route configuration.

3.2.2 React 19 Features Used

NDSS CRM leverages several React 19 features throughout the codebase:

• React Server Components (RSC): Data-fetching components that execute on the server, reducing client-side JavaScript bundle size. Used extensively for list pages, detail views, and report rendering.
• Server Actions: Server-side functions invoked directly from client components for form submissions (e.g., creating a new client, submitting a progress note, approving a timesheet).
• useOptimistic: Provides instant UI feedback for mutations before the server confirms the change. Used in shift status updates and message sending.
• useFormStatus: Tracks the pending state of form submissions to display loading indicators on submit buttons.
• Suspense Boundaries: Wrap async components to show loading skeletons while data streams from the server.

3.2.3 Component Hierarchy

The frontend component tree follows a strict hierarchy with clearly separated concerns:

3.2.4 Route Groups & Routing Structure

NDSS CRM uses Next.js route groups (parenthesised folders) to organise routes without affecting the URL path. The three primary route groups are:

3.3 Backend Architecture

The backend of NDSS CRM is built on a hybrid architecture combining Supabase / Oracle (PostgreSQL-based Backend-as-a-Service), Python microservices for data-intensive operations, and PHP integration modules for legacy system compatibility. This approach provides the rapid development benefits of a BaaS while retaining the flexibility to implement complex business logic in purpose-built services.

3.3.1 Supabase / Oracle (PostgreSQL)

Supabase / Oracle serves as the primary backend layer and provides the following capabilities:

• PostgreSQL 15 Database: All application data is stored in a managed PostgreSQL instance with full SQL support, including advanced features such as CTEs, window functions, JSONB columns, and full-text search.
• Row Level Security (RLS): Every table has RLS policies that enforce role-based data access at the database level. This means that even if application-level security is bypassed, the database itself prevents unauthorised data access.
• Supabase / Oracle Auth: Handles user authentication (email/password, OAuth), session management, password resets, and email verification. See Chapter 4 for detailed authentication documentation.
• Realtime: Supabase / Oracle Realtime enables WebSocket-based subscriptions to database changes. NDSS CRM uses this for live shift updates, message notifications, and dashboard data refreshes.
• Edge Functions: Deno-based serverless functions deployed at the edge for lightweight operations such as webhook handlers, email dispatch triggers, and NDIS price guide lookups.
• Storage: Supabase / Oracle Storage manages file uploads including client documents, staff qualification certificates, incident report attachments, and profile photos.

3.3.2 Python Microservices

Python 3.12 microservices handle data processing workloads that require computational libraries not available in the JavaScript/TypeScript ecosystem:

3.3.3 PHP Integration Modules

PHP 8.3 modules provide compatibility bridges with legacy systems and third-party services that use PHP-based APIs:

3.4 Database Schema

The NDSS CRM database is a relational PostgreSQL schema containing over 40 tables. This section documents the 10 primary entities that form the core of the data model. Every table uses UUID primary keys, includes created_at and updated_at timestamp columns, and is protected by Row Level Security policies.

3.4.1 Profile (User Accounts)

The profiles table extends the Supabase / Oracle auth.users table with application-specific user data. Every authenticated user has exactly one profile record.

3.4.2 Client (NDIS Participants)

The clients table stores all NDIS participant records, including personal details, NDIS identifiers, and service status information.

3.4.3 Goal (Client Goals)

The goals table tracks NDIS participant goals as defined in their NDIS plan and service agreements.

3.4.4 ProgressNote

The progress_notes table stores shift-level notes recorded by support workers after each service delivery session.

3.4.5 ClientFunding

The client_funding table tracks NDIS plan funding allocations and budget utilisation for each participant.

3.4.6 StaffProfile

The staff_profiles table extends the profiles table with employment-specific fields for all staff members.

3.4.7 Qualification

The qualifications table records certifications, qualifications, and training completions for staff members.

3.4.8 Shift

The shifts table is the core scheduling entity, representing individual service delivery appointments between staff and clients.

3.4.9 Invoice

The invoices table tracks all financial documents generated for NDIS claims and client billing.

3.4.10 Incident

The incidents table records all safety incidents, near-misses, and complaints as required by NDIS Practice Standards.

3.4.11 Entity Relationship Overview

The following diagram summarises the primary relationships between core database entities:

3.5 Authentication Flow

NDSS CRM uses Supabase / Oracle Auth for all authentication operations. The authentication flow is protected by Next.js middleware that intercepts every request and verifies the user session before allowing access to protected routes. For a complete guide to authentication features and user management, refer to Chapter 4.

3.5.1 Authentication Sequence

The following describes the step-by-step authentication flow when a user accesses NDSS CRM:

1. Request Interception: Next.js middleware (src/middleware.ts) intercepts all incoming HTTP requests.
2. Session Check: The middleware calls supabase.auth.getSession() to check for a valid session cookie.
3. Unauthenticated Redirect: If no valid session exists and the requested route is protected, the user is redirected to /login.
4. Credential Submission: The user submits their email and password via the login form.
5. Supabase / Oracle Verification: Supabase / Oracle Auth verifies the credentials against the auth.users table and returns a JWT access token and refresh token.
6. Session Cookie: The tokens are stored in an HTTP-only, secure, SameSite cookie managed by the Supabase / Oracle SSR helper library.
7. Profile Fetch: The application fetches the user profile from the profiles table to determine the user role.
8. Role-Based Redirect: The user is redirected to their role-specific dashboard (e.g., /dashboard for admins, /portal for clients).

3.5.2 Middleware Protection

The middleware configuration defines which routes are public (accessible without authentication) and which are protected:

// src/middleware.ts - Route Protection Configuration

const publicRoutes = [
  '/login',
  '/register',
  '/forgot-password',
  '/reset-password',
  '/verify-email',
  '/terms',
  '/privacy',
  '/demo'
];

const protectedRouteGroups = [
  '/(dashboard)',    // All internal platform pages
  '/(client-portal)' // Client self-service portal
];

// Middleware function
export async function middleware(request: NextRequest) {
  const session = await getSession(request);

  if (!session && isProtectedRoute(request.pathname)) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  if (session && isPublicOnlyRoute(request.pathname)) {
    return NextResponse.redirect(new URL('/dashboard', request.url));
  }

  return NextResponse.next();
}

3.5.3 Session Management

Sessions are managed using Supabase / Oracle's cookie-based approach with the @supabase/ssr library:

3.6 State Management

NDSS CRM employs a deliberate separation between server state (data from the database) and client state (UI state, form state, user preferences). This separation prevents the common pitfalls of mixing remote data with local UI state and ensures predictable data flow throughout the application.

3.6.1 React Query (TanStack Query) - Server State

React Query manages all data fetching, caching, synchronisation, and background updates for data originating from the Supabase / Oracle database or microservice APIs:

• Automatic Caching: Query results are cached by unique keys and served from cache on subsequent requests until the cache expires or is invalidated.
• Background Refetching: Stale data is automatically refetched in the background when the user refocuses the browser tab or reconnects to the network.
• Optimistic Updates: Mutations (create, update, delete) immediately update the UI cache before the server confirms the change, providing instant feedback.
• Query Invalidation: After a successful mutation, related queries are invalidated to trigger a refetch with the latest data.

// Example: Fetching client list with React Query
const { data: clients, isLoading, error } = useQuery({
  queryKey: ['clients', { status: 'active', page: 1 }],
  queryFn: () => supabase
    .from('clients')
    .select('*')
    .eq('status', 'active')
    .range(0, 24)
    .order('last_name', { ascending: true }),
  staleTime: 5 * 60 * 1000, // 5 minutes
});

3.6.2 Zustand - Client State

Zustand manages lightweight client-side state that does not originate from the database:

• Sidebar State: Whether the sidebar is collapsed or expanded, and on mobile, whether it is open or closed.
• Theme Preferences: Light mode, dark mode, or system preference.
• Filter Selections: Active filter chips, search queries, and sort preferences for data tables.
• Modal State: Which dialogs are currently open and their associated context data.
• Notification Queue: Toast notifications waiting to be displayed.

// Example: Zustand store for sidebar state
import { create } from 'zustand';

interface SidebarStore {
  isCollapsed: boolean;
  isMobileOpen: boolean;
  toggleCollapse: () => void;
  setMobileOpen: (open: boolean) => void;
}

export const useSidebarStore = create<SidebarStore>((set) => ({
  isCollapsed: false,
  isMobileOpen: false,
  toggleCollapse: () => set((s) => ({ isCollapsed: !s.isCollapsed })),
  setMobileOpen: (open) => set({ isMobileOpen: open }),
}));

3.6.3 React Hook Form - Form State

All forms across the platform use React Hook Form with Zod schema validation:

// Example: Client creation form with Zod validation
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const clientSchema = z.object({
  ndis_number: z.string().regex(/^\d{9}$/, 'Must be 9 digits'),
  first_name: z.string().min(1, 'Required'),
  last_name: z.string().min(1, 'Required'),
  date_of_birth: z.string().min(1, 'Required'),
  status: z.enum(['active', 'inactive', 'waitlist']),
  email: z.string().email().optional().or(z.literal('')),
  phone: z.string().optional(),
});

type ClientFormData = z.infer<typeof clientSchema>;

const { register, handleSubmit, formState: { errors } } = useForm<ClientFormData>({
  resolver: zodResolver(clientSchema),
});

3.7 API Layer

The NDSS CRM API layer consists of three complementary interfaces: Supabase / Oracle Client SDK for direct database operations, Next.js API Routes for custom server-side logic, and Supabase / Oracle Realtime for live data subscriptions.

3.7.1 RESTful Endpoints (Next.js API Routes)

Custom API routes are defined in src/app/api/ and handle operations that require server-side processing beyond simple CRUD:

3.7.2 Supabase / Oracle Client SDK

The majority of CRUD operations are performed directly via the Supabase / Oracle JavaScript client, which translates method calls into PostgREST API requests:

// Direct Supabase / Oracle client operations
// SELECT
const { data } = await supabase.from('clients').select('*').eq('status', 'active');

// INSERT
const { data } = await supabase.from('clients').insert({ ... }).select().single();

// UPDATE
const { data } = await supabase.from('clients').update({ status: 'inactive' }).eq('id', clientId);

// DELETE
const { error } = await supabase.from('incidents').delete().eq('id', incidentId);

3.7.3 Supabase / Oracle Realtime Subscriptions

Real-time subscriptions are used for features that require live data updates without page refresh:

3.8 Component Library

NDSS CRM uses a custom component library built on top of Radix UI unstyled primitives, styled with TailwindCSS utility classes. This approach provides accessible, keyboard-navigable UI components with full design control.

3.8.1 Radix UI Primitives

The following Radix UI primitives are used across the platform:

3.8.2 Custom Components

The src/components/ directory contains custom components built on top of Radix primitives:

3.8.3 TailwindCSS Configuration

TailwindCSS is configured with a custom design system that includes NDSS CRM brand colours, spacing scale, and responsive breakpoints:

// tailwind.config.ts - Key customisations
export default {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f0f7ff',
          100: '#e0effe',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
          900: '#1e3a5f',
        },
        success: '#22c55e',
        warning: '#f59e0b',
        danger: '#ef4444',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
  ],
};

3.9 Directory Structure

The following is the complete project directory tree for the NDSS CRM codebase, showing all major directories and their purposes:

ndss-crm/
+-- src/
|   +-- app/
|   |   +-- (auth)/
|   |   |   +-- login/page.tsx
|   |   |   +-- register/page.tsx
|   |   |   +-- forgot-password/page.tsx
|   |   |   +-- reset-password/page.tsx
|   |   |   +-- verify-email/page.tsx
|   |   |   +-- layout.tsx
|   |   +-- (dashboard)/
|   |   |   +-- dashboard/page.tsx
|   |   |   +-- clients/
|   |   |   |   +-- page.tsx
|   |   |   |   +-- [id]/page.tsx
|   |   |   |   +-- new/page.tsx
|   |   |   +-- staff/
|   |   |   |   +-- page.tsx
|   |   |   |   +-- [id]/page.tsx
|   |   |   +-- rostering/
|   |   |   |   +-- page.tsx
|   |   |   |   +-- calendar/page.tsx
|   |   |   +-- finance/
|   |   |   |   +-- page.tsx
|   |   |   |   +-- invoices/page.tsx
|   |   |   +-- compliance/
|   |   |   |   +-- page.tsx
|   |   |   |   +-- incidents/page.tsx
|   |   |   +-- intake/page.tsx
|   |   |   +-- clinical/page.tsx
|   |   |   +-- learning/page.tsx
|   |   |   +-- messaging/page.tsx
|   |   |   +-- reports/page.tsx
|   |   |   +-- admin/
|   |   |   |   +-- page.tsx
|   |   |   |   +-- settings/page.tsx
|   |   |   |   +-- users/page.tsx
|   |   |   +-- sil/page.tsx
|   |   |   +-- layout.tsx
|   |   +-- (client-portal)/
|   |   |   +-- portal/page.tsx
|   |   |   +-- my-services/page.tsx
|   |   |   +-- my-plan/page.tsx
|   |   |   +-- layout.tsx
|   |   +-- (public)/
|   |   |   +-- page.tsx
|   |   |   +-- terms/page.tsx
|   |   |   +-- privacy/page.tsx
|   |   +-- api/
|   |   |   +-- claims/route.ts
|   |   |   +-- reports/route.ts
|   |   |   +-- payroll/route.ts
|   |   |   +-- dashboard/route.ts
|   |   |   +-- shifts/route.ts
|   |   |   +-- documents/route.ts
|   |   |   +-- notifications/route.ts
|   |   +-- globals.css
|   |   +-- layout.tsx
|   +-- components/
|   |   +-- layout/
|   |   |   +-- sidebar.tsx
|   |   |   +-- topbar.tsx
|   |   |   +-- breadcrumb.tsx
|   |   |   +-- footer.tsx
|   |   +-- ui/
|   |   |   +-- button.tsx
|   |   |   +-- input.tsx
|   |   |   +-- select.tsx
|   |   |   +-- data-table.tsx
|   |   |   +-- stat-card.tsx
|   |   |   +-- filter-bar.tsx
|   |   |   +-- status-badge.tsx
|   |   |   +-- form-field.tsx
|   |   |   +-- confirm-dialog.tsx
|   |   |   +-- file-uploader.tsx
|   |   |   +-- empty-state.tsx
|   |   |   +-- toast.tsx
|   |   +-- clients/
|   |   |   +-- client-form.tsx
|   |   |   +-- client-table.tsx
|   |   |   +-- client-profile.tsx
|   |   +-- staff/
|   |   |   +-- staff-form.tsx
|   |   |   +-- staff-table.tsx
|   |   +-- rostering/
|   |   |   +-- shift-form.tsx
|   |   |   +-- shift-calendar.tsx
|   |   |   +-- shift-table.tsx
|   |   +-- finance/
|   |   |   +-- invoice-form.tsx
|   |   |   +-- invoice-table.tsx
|   +-- lib/
|   |   +-- supabase/
|   |   |   +-- client.ts
|   |   |   +-- server.ts
|   |   |   +-- middleware.ts
|   |   +-- utils.ts
|   |   +-- constants.ts
|   |   +-- roles.ts
|   +-- providers/
|   |   +-- query-provider.tsx
|   |   +-- theme-provider.tsx
|   |   +-- auth-provider.tsx
|   +-- types/
|   |   +-- database.ts
|   |   +-- roles.ts
|   |   +-- forms.ts
|   +-- middleware.ts
+-- supabase/
|   +-- migrations/
|   |   +-- 001_create_profiles.sql
|   |   +-- 002_create_clients.sql
|   |   +-- 003_create_goals.sql
|   |   +-- 004_create_shifts.sql
|   |   +-- 005_create_invoices.sql
|   |   +-- 006_create_incidents.sql
|   +-- seed.sql
|   +-- config.toml
+-- services/
|   +-- python/
|   |   +-- report-engine/
|   |   +-- claim-processor/
|   |   +-- data-pipeline/
|   |   +-- notification-worker/
|   +-- php/
|       +-- payroll-bridge/
|       +-- legacy-api/
|       +-- doc-converter/
+-- public/
|   +-- ndss-crm-logo.svg
|   +-- favicon.ico
+-- package.json
+-- tsconfig.json
+-- tailwind.config.ts
+-- next.config.ts
+-- .env.local

3.10 Design Patterns

NDSS CRM employs several design patterns consistently across the codebase to ensure maintainability, reusability, and developer productivity.

3.10.1 Composable Components

Components are designed to be composable rather than monolithic. Instead of building a single large "ClientPage" component, the page is composed of smaller, focused components that can be reused independently:

// Composable page structure example
export default function ClientsPage() {
  return (
    <PageShell title="Clients" subtitle="Manage NDIS participants">
      <PageHeader>
        <FilterBar
          searchPlaceholder="Search clients..."
          filters={[
            { key: 'status', label: 'Status', options: statusOptions },
            { key: 'coordinator', label: 'Coordinator', options: staffOptions },
          ]}
        />
        <Button onClick={openCreateModal}>+ New Client</Button>
      </PageHeader>

      <DataTable
        columns={clientColumns}
        data={clients}
        pagination={pagination}
        onRowClick={navigateToClient}
      />

      <CreateClientDialog open={isCreateOpen} onClose={closeCreateModal} />
    </PageShell>
  );
}

3.10.2 Role-Based Rendering

A custom <RoleGate> component conditionally renders UI elements based on the current user role. This pattern is used throughout the platform to show or hide features, navigation items, action buttons, and data columns:

// Role-based rendering pattern
import { RoleGate } from '@/components/auth/role-gate';

// Only visible to admin roles
<RoleGate allowedRoles={['master_admin', 'administrator']}>
  <Button variant="danger" onClick={deleteClient}>
    Delete Client
  </Button>
</RoleGate>

// Visible to coordinators and above
<RoleGate allowedRoles={['master_admin', 'administrator', 'service_coordinator']}>
  <Tabs.Tab value="funding">Funding</Tabs.Tab>
</RoleGate>

// Visible to everyone except clients
<RoleGate excludeRoles={['client', 'family_member']}>
  <DataTable.Column header="Internal Notes" />
</RoleGate>

3.10.3 Server-First Data Fetching

Data fetching follows a "server-first" pattern where React Server Components fetch data on the server whenever possible, reducing client-side JavaScript and eliminating loading spinners for initial page loads:

// Server Component - data fetched on server, no client JS needed
export default async function ClientDetailPage({ params }: { params: { id: string } }) {
  const supabase = createServerClient();
  const { data: client } = await supabase
    .from('clients')
    .select('*, goals(*), client_funding(*)')
    .eq('id', params.id)
    .single();

  return <ClientProfile client={client} />;
}

3.10.4 Error Boundary Pattern

Every route segment includes an error.tsx file that catches runtime errors and provides a user-friendly error recovery experience:

// src/app/(dashboard)/clients/error.tsx
'use client';

export default function ClientsError({ error, reset }: {
  error: Error;
  reset: () => void;
}) {
  return (
    <ErrorState
      title="Failed to load clients"
      message={error.message}
      onRetry={reset}
    />
  );
}

3.10.5 Type Safety Throughout

TypeScript is enforced across the entire codebase with strict mode enabled. Database types are auto-generated from the Supabase / Oracle schema using supabase gen types typescript, ensuring that all database queries and responses are type-checked at compile time:

// Auto-generated database types
export type Database = {
  public: {
    Tables: {
      clients: {
        Row: {
          id: string;
          ndis_number: string;
          first_name: string;
          last_name: string;
          date_of_birth: string;
          status: 'active' | 'inactive' | 'waitlist' | 'exited';
          // ... all other fields
        };
        Insert: { /* ... */ };
        Update: { /* ... */ };
      };
      // ... all other tables
    };
  };
};