Encore OS Platform - Architecture Documentation

​

Overview

​

Structure

​

Platform Foundation (PF)

• PF-01: Organization & Site Management
• PF-02: Role-Based Access Control (RBAC)
• PF-06: User Profile Management

• PF-03: App Launcher & Module Switcher
• PF-04: Audit Logging System
• PF-07: Error Handling & Monitoring
• PF-08: Platform Forms Integration Layer

• PF-09: Form Analytics (pending)
• PF-10: Notifications System
• PF-11: Document Management System
• PF-12: Reporting Engine

​

Domain Cores

• Specifications: specs/README.md
• Per-core implementation notes: src/cores/{core}/AGENTS.md (e.g. src/cores/hr/AGENTS.md)
• User and operator guides: docs/index.md (Documentation by Category)

​

Key Principles

1. Bounded Contexts: Each core owns its domain, no cross-core dependencies
2. Platform Foundation Only: Cores depend only on PF, not each other
3. Explicit Integration Contracts: Cross-core communication via defined APIs/events
4. RLS-First Security: Multi-tenant isolation enforced at database level
5. Spec-First Delivery: No feature without written specification

​

Integration Patterns (Constitution Section 1.3)

​

Pattern 1: Platform Integration Layer

/src/platform/<capability>/
  ├── index.ts           # Public API exports
  ├── types.ts           # Type definitions
  ├── hooks/             # React Query hooks
  └── components/        # Reusable components

// Cores import from platform, NOT from fw
import { FormEmbed } from '@/platform/forms';

// In RH core
<FormEmbed formId="resident-intake" onSuccess={handleSubmit} />

​

Pattern 2: Event-Based Integration

-- Core publishes domain event
SELECT pg_notify('resident_admitted', json_build_object(
  'resident_id', NEW.id,
  'organization_id', NEW.organization_id
));

-- Other cores subscribe via triggers or edge functions

​

Pattern 3: API Contracts

// Define contract in spec
interface ResidentCensusRequest {
  organization_id: string;
  site_id: string;
  date: string;
}

// Implement as edge function
export async function getCensus(req: ResidentCensusRequest): Promise<CensusData>

​

Data Flow

​

Multi-Tenant Request Flow

User Request
  → Auth Middleware (Supabase Auth)
  → Organization Context (PF-01)
  → RLS Policies (PF-02 + per-table)
  → Core Business Logic
  → Audit Log (PF-04)
  → Response

​

Cross-Module Communication

Core A (e.g., RH)
  → Platform Integration Layer (e.g., PF-08 Forms)
  → FW Core (via abstraction)
  → Response back through Platform Layer
  → Core A continues processing

​

Security Model

​

Layers of Defense

1. Authentication: Supabase Auth (JWT tokens)
2. Organization Context: PF-01 sets current_organization_id
3. RLS Policies: Database-level enforcement
4. RBAC Functions: Security definer functions (PF-02)
5. Audit Logging: All actions logged (PF-04)

​

RLS Policy Template

-- Standard multi-tenant policy
CREATE POLICY "Users can only see own org data"
ON <table_name>
FOR SELECT
TO authenticated
USING (
  organization_id IN (
    SELECT organization_id 
    FROM pf_user_roles 
    WHERE user_id = auth.uid()
  )
);

-- Role-based policy
CREATE POLICY "Admins can update"
ON <table_name>
FOR UPDATE
TO authenticated
USING (
  has_role(auth.uid(), 'org_admin') OR
  has_role(auth.uid(), 'platform_admin')
)
WITH CHECK (same);

​

Testing Strategy

​

Test Pyramid

• Business logic functions
• Validation schemas
• Utility functions

• RLS policies (critical!)
• Database functions
• API endpoints
• Cross-module integrations

• Critical user journeys
• Auth flows
• Multi-tenant isolation
• Compliance workflows

​

RLS Testing Approach

// Test multi-tenant isolation
const { data: org1Data } = await client1
  .from('table')
  .select('*');

const { data: org2Data } = await client2
  .from('table')
  .select('*');

// Verify no cross-org data
expect(org1Data.some(row => row.organization_id === org2.id)).toBe(false);

​

Performance Targets (Constitution Section 5.6)

​

API Response Times (p95)

• Read operations: < 500ms
• Write operations: < 2s
• Report queries: < 30s (with timeout)
• Cached queries: < 1s

​

Page Load Times (p95)

• Initial load: < 3s
• Navigation: < 1s
• Form render: < 500ms

​

Database Performance

• All foreign keys indexed
• Full-text search with GIN indexes
• Query timeout: 30s max
• Connection pooling: 15-25 connections

​

Monitoring & Observability

​

Key Metrics

• API response times (p50, p95, p99)
• Error rates by endpoint
• Database query performance
• RLS policy execution time
• Audit log write latency

​

Logging Standards

// Structured logging
logger.info({
  module: 'rh',
  action: 'admit_resident',
  user_id: userId,
  org_id: orgId,
  correlation_id: requestId,
  duration_ms: elapsed
});

• Use structured JSON logs
• Include correlation IDs for tracing
• Do NOT log PHI, PII, or secrets
• Retention: 30 days (info), 90 days (errors), 1 year (audit)

​

Deployment Model

​

Environments

• Local: Developer machines (Docker + Supabase CLI)
• Dev: Shared development environment
• Staging: Pre-production testing
• Production: Live system with HA

​

Deployment Flow

Code Push
  → CI/CD Pipeline (GitHub Actions)
  → Run Tests (unit + integration + RLS)
  → Build Frontend
  → Deploy Database Migrations
  → Deploy Edge Functions
  → Deploy Frontend
  → Smoke Tests
  → Rollback if Failed

​

Technology Stack

​

Frontend

• React 18 + TypeScript
• Vite (build tool)
• TailwindCSS + shadcn/ui
• TanStack Query (data fetching)
• React Router (navigation)

​

Backend

• Supabase (Postgres + Auth + Storage + Realtime)
• Edge Functions (Deno runtime)
• Row-Level Security (RLS)
• pg_cron (scheduled jobs)

​

DevOps

• GitHub Actions (CI/CD)
• Vitest (testing framework)
• Docker (local development)

​

Directory Structure

• patterns/ - Reusable architecture patterns (custom fields, data flow, etc.)
• standards/ - Architecture standards and conventions (navigation, terminology)
• analysis/ - Analysis and recommendation documents
• integrations/ - Cross-core integration contracts
• decisions/ - Architecture Decision Records (ADRs)
• deprecation/ - Deprecation notices
• archive/ - Historical architecture documentation

​

Documentation Files

​

Core Architecture

• README.md (this file) - Architecture overview
• standards/CORE_DEPENDENCIES.md - Module dependency structure
• patterns/DATA_FLOW.md - Detailed request flows and integration patterns
• patterns/ORGANIZATIONAL_DATA.md - Organizational entity structure
• standards/TERMINOLOGY.md - Unified glossary of platform terms

​

Integration Documentation

• integrations/README.md - Integration documentation overview and single source of truth (see Integration Documentation)
  • Note: Replaces the previous INTEGRATION_CONTRACTS.md (archived 2025-01-22)
• integrations/PLATFORM_INTEGRATION_LAYERS.md - Platform integration layers (Pattern 1)
• integrations/EVENT_CONTRACTS.md - Event-based integration contracts (Pattern 2)
• integrations/API_CONTRACTS.md - API-based integration contracts (Pattern 3)
• integrations/CROSS_CORE_INTEGRATIONS.md - Integration matrix
• integrations/DATA_MODELS.md - Core data models
• patterns/INTEGRATION_EXAMPLES.md - Integration pattern examples

​

Design Decisions & Analysis

• integrations/PF-60-rag-infrastructure-INTEGRATION.md - Current platform AI/RAG integration strategy reference
• Clarity Analysis - Forms vs Data Manager overlap analysis (includes wizards and templates)
• analysis/IT_MODULE_RECOMMENDATION.md - IT module recommendation
• Permissions System: See Permissions System Guide and Quick Reference
• decisions/ADR-001-form-analytics-architecture.md - Architecture Decision Record

​

Navigation & UX Standards

• standards/NAVIGATION_STANDARD.md - Complete navigation standards, policies, and implementation guidelines
• standards/navigation-quick-reference.md - Quick reference for navigation implementation tasks
• reviews/NAVIGATION_AUDIT.md - Navigation and routing audit checklist (routes, sidebar, mobile nav, breadcrumbs)
• Mobile Navigation Guide: See docs/development/mobile-navigation-guide.md - Mobile navigation patterns
• Breadcrumb Guide: See docs/development/breadcrumb-implementation-guide.md - Breadcrumb implementation
• UI/UX Standards: See docs/development/UI_UX_STANDARDS.md - Complete UI/UX standards
• Spacing & UX Standards: See docs/development/SPACING_AND_UX_STANDARDS.md - Spacing patterns and responsive design

​

Customization

• patterns/CUSTOM_FIELDS_GUIDE.md - Custom fields implementation guide

​

Deprecation

• deprecation/pf_user_roles.md - Deprecation notice for pf_user_roles

​

Related Documentation

• constitution.md (current: see docs/VERSIONS.md) - Full architectural guardrails
• AI_GUIDE.md (current: see docs/VERSIONS.md) - AI contribution guidelines (for AI agents writing code)
• /specs/ - Feature specifications
• /tests/README.md - Testing documentation
• /docs/guides/use-cases/ - Practical use case guides

​

See Also

​

Integration Documentation

• Integration Documentation (v2.1.0) - Single source of truth for all cross-core integrations
• Platform Integration Layers - Pattern 1: Shared utilities
• Event Contracts - Pattern 2: Event-based integration
• API Contracts - Pattern 3: Synchronous APIs
• Cross-Core Integrations - Integration matrix
• IT Integration Contracts - IT module integration documentation
• Integration Examples - Code examples for all patterns

​

Design Decisions

• PF-60 RAG Infrastructure Integration - Current platform AI/RAG integration strategy reference
• Design Decisions - Architecture Decision Records (ADRs)

​

Data & Flow

• Data Flow - Detailed request flows and integration patterns
• Organizational Data - Organizational entity structure
• Core Dependencies - Module dependency structure
• Data Models - Core data models and relationships

​

Standards & Guidelines

• Navigation Standard (v1.0.0) - Navigation patterns and policies
• Terminology - Unified glossary of platform terms
• Custom Fields Guide - Custom fields implementation guide
• Spacing & UX Standards (v1.0.0) - Spacing and UX patterns

​

Documentation Management

• Documentation inventory (archived) — historical architecture file list (2025-01-22)
• Consolidation recommendations (archived) — historical consolidation notes
• Documentation Standards — standards, maintenance, and high-traffic paths

​

References

• /constitution.md - Full architectural guardrails
• /AI_GUIDE.md - AI contribution guidelines
• /specs/ - Feature specifications
• /tests/README.md - Testing documentation
• Supabase RLS Documentation