Shared System Design

SYNDI Shared Infrastructure - Common patterns, authentication, and infrastructure components used across SAM and CLAIRE.

Technology Stack

Component

Technology

Frontend Framework

React + Vite

UI Components

shadcn/ui + Radix

Form Management

react-hook-form + Zod

State Management

@tanstack/react-query

YAML Processing

js-yaml

File Storage

AWS S3 (pre-signed URLs)

Authentication

AWS Cognito

Infrastructure

CloudFormation

Deployment

S3 + CloudFront

Frontend Organization

Service Separation

SYNDI follows a clean service separation pattern in the frontend:

  • frontend/src/sam/ - SAM-specific implementation (SOP creation and validation)

  • frontend/src/claire/ - CLAIRE-specific implementation (ELN data capture) [Future]

  • frontend/src/paul/ - PAUL-specific implementation (Protocol analysis) [Future]

  • frontend/src/shared/ - Shared components, hooks, and utilities across all services

Shared Infrastructure

The shared directory contains reusable components and utilities:

  • shared/components/ui/ - shadcn/ui components (Button, Card, Form, etc.)

  • shared/components/ - Custom shared components (Layout, Autosave, etc.)

  • shared/hooks/ - Shared React hooks (useAutosave, useToast)

  • shared/lib/ - Shared utilities and business logic

  • shared/schemas/ - Schema definitions used across services

  • shared/views/ - Shared page components (Login, etc.)

Component Naming Conventions

  • React Components: PascalCase (e.g., AutosaveBrowser.tsx)

  • React Hooks: camelCase with use prefix (e.g., useAutosave.ts)

  • Utility Libraries: kebab-case (e.g., config-loader.ts)

  • Types/Interfaces: PascalCase matching component names

Benefits of This Structure

  • Clean Service Boundaries: Each service has its own implementation space

  • Reusable Shared Components: Common UI patterns shared across services

  • Consistent Naming: Clear conventions for easy navigation

  • Scalable Architecture: Easy to add new services (CLAIRE, PAUL) without conflicts

  • Type Safety: TypeScript throughout with proper interfaces

Authentication System

AWS Cognito Integration

  • JWT Token Management: Frontend manages authentication tokens for both SOP and ELN workflows

  • Token Validation: Backend services validate tokens using Cognito’s JWT verification

  • Role-based Access: Admin vs user authorization for different workflows

  • Local Development: Simulated tokens for development and testing

Authentication Flow

User Login → Cognito Validation → JWT Token → API Requests → Backend Validation

Token Usage

  • SOP Templates: Admin-level access required for template creation

  • ELN Submissions: User-level access for data capture

  • API Endpoints: All requests include authentication tokens

Infrastructure Architecture

AWS Services

  • S3 Buckets:

    • webapp/ - Frontend static files

    • forms/ - SOP templates storage

    • eln/ - ELN submission storage

  • CloudFront: Frontend distribution and caching

  • Lambda: Backend API endpoints

  • Cognito: User management and authentication

Environment Configuration

Configuration loaded from infra/config/[service]/[env].json:

interface ServiceConfig {
  apiEndpoint: string;
  authRequired: boolean;
  storageType: 'local' | 'remote';
  retryConfig: {
    maxRetries: number;
    backoffMultiplier: number;
  };
}

Environment Mapping

Production:  infra/config/*/prod.json → S3 buckets
Staging:     infra/config/*/stage.json → staging environment  
Development: infra/config/*/dev.json → local servers
Testing:     tests/fixtures/s3-simulation → Playwright fixtures

Schema System Foundation

Dynamic Schema Architecture

  • Zod Validation: Real-time schema validation with TypeScript integration

  • Relationship Discovery: Automatic parent-child relationship detection

  • Property Introspection: Dynamic field definitions from schema metadata

  • UI Generation: Component types derived from schema configurations

Schema Registry Pattern

interface SchemaDefinition {
  name: string;
  schema: z.ZodSchema;
  uiMetadata: Record<string, any>;
  relationships: SchemaRelationship[];
}

Core Registry Functions

  • getPropertyDefinitions() - Extract field definitions

  • getRelationships() - Discover schema relationships

  • getAddableChildren() - Determine valid child types

  • validateField() - Real-time field validation

Configuration Management

Multi-Environment Support

class ConfigLoader {
  async loadConfig(environment?: string): Promise<EnvironmentConfig>
  private detectEnvironment(): string // Maps Vite modes to env names
  private fetchConfigForEnvironment(env: string): Promise<EnvironmentConfig>
  private getFallbackConfig(service: string, env: string): ServiceConfig
}

Configuration Loading Strategy

  • Production: Configs served from S3 via CloudFront

  • Development: Configs served by Vite proxy from infra/config

  • Testing: Configs served from Playwright fixtures

  • Fallback: Built-in defaults for each environment

Error Handling & Validation

Multi-Level Validation

  • Schema Validation: Zod schemas with real-time feedback

  • Form Validation: react-hook-form integration

  • Network Retry: Exponential backoff via React Query

  • Storage Fallback: localStorage → sessionStorage degradation

Error Recovery Patterns

  • Optimistic Updates: Immediate UI feedback with rollback

  • Conflict Resolution: User-controlled recovery prompts

  • Circuit Breaker: Prevent cascade failures

  • Graceful Degradation: Progressive feature reduction

Security & Compliance

Data Protection

  • Transit Security: HTTPS for all communications

  • At-rest Security: S3 encryption for stored data

  • Client-side Storage: Encrypted localStorage for drafts

  • Token Security: Secure JWT handling and refresh

Access Control

  • Authentication: Cognito-based user validation

  • Authorization: Role-based access control

  • API Security: Token validation on all endpoints

  • Audit Trail: Request logging and provenance tracking

Development Guidelines

Component Patterns

  • Single Responsibility: Each component handles one concern

  • TypeScript Interfaces: Clear prop and state definitions

  • Error Boundaries: Graceful error handling

  • Performance: Lazy loading and memoization

Code Organization

  • Feature-based Structure: Co-locate related components

  • Shared Utilities: Common functions in dedicated modules

  • Type Definitions: Shared types across components

  • Import Hierarchy: Clear dependency structure

Testing Strategy

  • Unit Tests: Component and utility testing

  • Integration Tests: Component interaction patterns

  • E2E Tests: Complete user workflows via Playwright

  • Visual Regression: UI consistency validation

File Structure

project/
├── infra/
│   └── config/                # Environment configurations
│       ├── eln/[env].json     # ELN service configs
│       ├── forms/[env].json   # Forms service configs
│       └── webapp/[env].json  # Webapp configs
├── frontend/
│   ├── src/
│   │   ├── sam/                      # SAM-specific implementation
│   │   │   ├── components/          # SAM UI components
│   │   │   ├── hooks/               # SAM-specific hooks
│   │   │   ├── lib/                 # SAM business logic
│   │   │   │   ├── schema-registry.ts    # Schema management
│   │   │   │   └── schema-introspector.ts # Schema analysis
│   │   │   ├── types/               # SAM TypeScript types
│   │   │   └── views/               # SAM pages/views
│   │   ├── shared/                  # Shared across services
│   │   │   ├── components/          # Shared UI components
│   │   │   │   ├── ui/             # shadcn/ui components
│   │   │   │   │   ├── button.tsx  # Button component
│   │   │   │   │   ├── card.tsx    # Card component
│   │   │   │   │   ├── form.tsx    # Form components
│   │   │   │   │   ├── toast.tsx   # Toast notifications
│   │   │   │   │   └── ...         # Other UI components
│   │   │   │   ├── ActionButtonGroup.tsx # Reusable action buttons
│   │   │   │   ├── AutosaveBrowser.tsx   # Autosave version browser
│   │   │   │   ├── AutosaveStatus.tsx    # Autosave status indicator
│   │   │   │   ├── Layout.tsx            # Application layout
│   │   │   │   └── ThemeProvider.tsx     # Theme context provider
│   │   │   ├── hooks/               # Shared hooks
│   │   │   │   ├── useAutosave.ts   # Autosave management
│   │   │   │   └── useToast.ts      # Notification system
│   │   │   ├── lib/                 # Shared utilities
│   │   │   │   ├── auth.tsx         # Authentication logic
│   │   │   │   ├── autosave-storage.ts   # Autosave storage
│   │   │   │   ├── config-loader.ts      # Configuration management
│   │   │   │   └── utils.ts         # Utility functions
│   │   │   ├── schemas/             # Schema definitions
│   │   │   │   └── SOPTemplateSchema.yaml # SOP template schema
│   │   │   └── views/               # Shared views
│   │   │       └── LoginPage.tsx    # Login page
│   │   └── main.tsx                 # Application entry point
│   ├── tools/                       # Build tools
│   │   └── generateSOPTemplateSchema.ts # Schema generation
│   └── public/                      # Static assets
└── tests/
    ├── fixtures/s3-simulation/       # Test data
    └── e2e/                          # Playwright tests

Deployment Pipeline

Build Process

  1. Configuration Copy: Environment configs copied to dist/

  2. Schema Generation: YAML schemas compiled to TypeScript

  3. Asset Optimization: Static asset bundling and compression

  4. CloudFormation: Infrastructure provisioning

Environment Promotion

Development → Testing → Staging → Production
    ↓            ↓         ↓          ↓
Local Dev → Playwright → AWS Stage → AWS Prod

Monitoring & Observability

  • Application Metrics: Performance and usage tracking

  • Error Tracking: Centralized error logging

  • User Analytics: Usage pattern analysis

  • Health Checks: Service availability monitoring

Autosave Infrastructure ✅

Reusable Autosave System

Status: Implemented for SAM, ready for CLAIRE integration

The autosave system provides a complete, reusable solution for client-side draft management across all SYNDI applications.

Key Components

  • useAutosave Hook: Environment-aware, configurable autosave with React Query integration

  • Storage Abstraction: Pluggable storage (localStorage, sessionStorage, future IndexedDB)

  • Configuration Management: Environment-specific settings via JSON config files

  • Version Management: LRU cache with automatic cleanup and version browsing

  • Recovery Workflows: VS Code-style recovery prompts and anti-overwrite protection

Cross-Application Benefits

  • Zero Schema Dependencies: Works with any schema-driven form

  • Environment Flexibility: Different behaviors for dev/test/stage/prod

  • Minimal Integration: 2-3 lines of code to add to existing forms

  • Extensible Design: Ready for ELN forms, protocol builders, data entry workflows

Future Considerations

Scalability

  • Caching Strategy: Template and schema caching

  • Performance: Virtual scrolling for large datasets

  • Load Balancing: Multi-region deployment

  • Database: Consider transition from S3 to RDS for complex queries

Extensibility

  • Plugin Architecture: Custom field types and validators

  • API Integration: External system connections

  • Mobile Support: Progressive Web App capabilities

  • Offline Mode: Service worker implementation

  • CLAIRE Integration: Extend autosave to ELN data capture forms