Platform Overview

​

How the platform is layered

​

Explore the platform foundation

​

📚 Table of Contents

• Architecture Overview
• Multi-Tenancy Model
• Authentication & Authorization
• Module Registry
• User Guides

​

Architecture Overview

​

Core Responsibilities

1. Multi-Tenant Infrastructure
   • Organization and site management
   • Tenant isolation via RLS
   • Cross-tenant security enforcement
2. Authentication & Authorization
   • User authentication via Supabase Auth
   • Role-Based Access Control (RBAC)
   • Permission enforcement at data and UI levels
3. Shared Services
   • Notifications (in-app, email, SMS)
   • Document management
   • Reporting engine
   • Audit logging
   • Form analytics
4. Developer Infrastructure
   • Module registry for dynamic navigation
   • Error handling and monitoring
   • Testing utilities
   • Shared UI components

​

Module Architecture

Platform Foundation (PF) - Core Services
├── RH (Recovery Housing)
├── FA (Finance & Accounting)
├── HR (Workforce Management)
├── GR (Governance & Compliance)
├── FW (Forms & Workflow)
└── FM (Facilities Management)

​

Multi-Tenancy Model

​

Organization Hierarchy

Platform
└── Organizations (pf_organizations)
    └── Sites (pf_sites)
        └── Sub-sites (hierarchical)

​

Tenant Isolation

• organization_id - Required, references pf_organizations
• site_id - Optional, references pf_sites

CREATE POLICY "tenant_isolation" ON table_name
  FOR SELECT USING (
    has_org_access(auth.uid(), organization_id)
  );

​

Security Functions

• SECURITY DEFINER function (bypasses RLS recursion)
• Checks if user has ANY role in the organization
• Used by all RLS policies for tenant isolation

• Verifies user has required role level or higher
• Respects role hierarchy (platform_admin > org_admin > site_admin > manager > staff)

​

Authentication & Authorization

​

Authentication Flow

1. User signs in via email/password or OAuth
2. Supabase Auth creates session with JWT
3. JWT contains auth.uid() used by RLS policies
4. User’s roles and permissions fetched from pf_user_role_assignments (V2 permissions system)

​

Role Hierarchy

​

Permission Checks

CREATE POLICY "policy_name" ON table_name
  FOR operation USING (
    has_role(auth.uid(), 'required_role', organization_id, site_id)
  );

import { useRole } from '@/shared/lib/hooks/use-role';

const { hasRole } = useRole();

if (hasRole('org_admin')) {
  // Show admin features
}

​

Module Registry

​

Dynamic Module Loading

// src/cores/rh/index.ts
import { registerModule } from '@/platform/registry';

registerModule({
  id: 'rh',
  name: 'Recovery Housing',
  icon: Home,
  description: 'Census and bed management',
  route: '/rh',
  requiredRole: 'staff',
  component: lazy(() => import('./RHDashboard'))
});

​

Benefits

• ✅ No hardcoded module lists
• ✅ Role-based visibility
• ✅ Lazy loading (performance)
• ✅ Easy to add/remove modules

​

App Launcher

1. User’s role
2. Module’s requiredRole
3. Module enablement in org settings

​

User Guides

​

For End Users

• Notifications Guide - Managing notifications and preferences
• Document Management Guide - Uploading and organizing documents
• Reporting Guide - Creating and running reports

​

For Administrators

• Organization Setup - Configuring organizations and sites
• User Management - Adding users and assigning roles
• Module Configuration - Enabling/disabling modules per org

​

For Developers

• Testing Guide - Writing RLS security tests
• Integration Documentation - Cross-module communication
• Constitution - Architecture guardrails

​

Database Naming Conventions

​

Key Technologies

• Backend: Supabase (PostgreSQL + Auth + Storage)
• Frontend: React + TypeScript + Tailwind CSS
• State Management: TanStack Query (React Query)
• Routing: React Router v6
• Forms: React Hook Form + Zod
• Testing: Vitest + Testing Library

​

Support & Resources

• Internal Documentation: /docs/
• Specifications: /specs/pf/
• Implementation Logs: /specs/pf/IMPLEMENTATION_LOG.md
• Test Coverage: /tests/README.md

​

Security Best Practices

1. Always use RLS policies - Never trust client-side checks alone
2. Use SECURITY DEFINER functions - Avoid RLS recursion issues
3. Validate all inputs - Use Zod schemas for API inputs
4. Test multi-tenant isolation - Every table needs RLS tests
5. Scrub PII/PHI from logs - No sensitive data in error messages
6. Audit critical actions - All data changes logged in pf_audit_logs