SAM Developer Documentation

SAM (SOP Automation to Models) is the validation and authoring service for Standard Operating Procedures in the SYNDI ecosystem. This documentation covers the technical implementation, architecture, and development guidelines for the SAM frontend.

Frontend Architecture

Technology Stack

  • React 18 with TypeScript

  • Vite for build tooling and development server

  • shadcn/ui + Radix UI for component library

  • React Hook Form + Zod for form validation

  • TanStack Query for state management and caching

  • Tailwind CSS for styling

Directory Structure

frontend/src/
├── sam/                           # SAM-specific implementation
│   ├── components/                # SAM UI components
│   │   ├── SOPCreator.tsx        # Main SOP creation interface
│   │   ├── SOPActionButtons.tsx  # Action buttons for SOP operations
│   │   ├── ArrayPropertyHandler.tsx  # Array property management
│   │   ├── CollapsibleProperties.tsx # Property grouping UI
│   │   ├── CollapsableSchema.tsx     # Schema container component
│   │   ├── DynamicFormField.tsx      # Dynamic form field renderer
│   │   ├── DynamicSchemaCard.tsx     # Schema card component
│   │   └── TagInput.tsx              # Tag input component
│   ├── hooks/                     # SAM-specific hooks
│   │   └── useSOPTemplates.ts    # SOP template management
│   ├── lib/                       # SAM business logic
│   │   ├── schema-registry.ts    # Schema management and validation
│   │   └── schema-introspector.ts # Schema analysis utilities
│   ├── types/                     # SAM TypeScript types
│   │   └── index.ts              # Type definitions
│   └── views/                     # SAM pages/views
│       ├── SOPCreatorPage.tsx    # SOP creation page
│       └── UserForm.tsx          # User form interface
└── shared/                        # Shared across services
    ├── components/                # Shared UI components
    │   ├── ui/                   # shadcn/ui components
    │   │   ├── button.tsx        # Button component
    │   │   ├── card.tsx          # Card component
    │   │   ├── form.tsx          # Form components
    │   │   ├── input.tsx         # Input components
    │   │   ├── toast.tsx         # Toast notifications
    │   │   └── ...               # Other UI components
    │   ├── ActionButtonGroup.tsx # Reusable action button group
    │   ├── 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 functionality
    │   └── useToast.ts           # Toast notifications
    ├── lib/                       # Shared utilities
    │   ├── auth.tsx              # Authentication logic
    │   ├── autosave-storage.ts   # Autosave storage abstraction
    │   ├── config-loader.ts      # Configuration management
    │   └── utils.ts              # Utility functions
    ├── schemas/                   # Schema definitions
    │   └── SOPTemplateSchema.yaml # SOP template schema
    └── views/                     # Shared views
        └── LoginPage.tsx         # Login page

Key Components

SOPCreator.tsx

The main interface for creating and editing Standard Operating Procedures.

Features:

  • Dynamic form generation from YAML schemas

  • Real-time validation with Zod

  • Autosave integration with version management

  • Test data generation

  • Export to YAML format

  • Import from JSON/YAML files

Usage:

<SOPCreator 
  mainSchema="sopTemplate" 
  uiConfig="sopTemplateUI" 
/>

Schema Registry System

Central system for managing schema definitions and relationships.

Core Functions:

  • getPropertyDefinitions() - Extract field definitions from schemas

  • getRelationships() - Discover parent-child relationships

  • getAddableChildren() - Determine valid child schema types

  • validateField() - Real-time field validation

Autosave Integration

SAM integrates with the shared autosave system to provide:

  • Automatic draft saving every 5 seconds

  • Version browsing and recovery

  • Loss prevention with recovery prompts

  • Environment-specific configuration

Development Guidelines

Component Naming

  • Components: PascalCase (e.g., SOPCreator.tsx)

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

  • Utilities: kebab-case (e.g., schema-registry.ts)

Code Organization

  • Single Responsibility: Each component handles one specific concern

  • TypeScript First: All components use TypeScript with proper interfaces

  • Error Boundaries: Graceful error handling throughout

  • Performance: Lazy loading and memoization where appropriate

Schema-Driven Development

SAM follows a schema-driven approach where:

  1. Schemas define structure - YAML schemas describe data models

  2. UI generates dynamically - Components adapt to schema changes

  3. Validation follows schema - Zod validators match schema definitions

  4. Relationships are discovered - Parent-child connections auto-detected

Testing Strategy

  • Unit Tests: Component and utility testing

  • Integration Tests: Schema registry and form interaction

  • E2E Tests: Complete SOP creation workflows

  • Schema Validation: YAML schema compliance testing

API Integration

Configuration Management

SAM uses environment-aware configuration loading:

// Development: loads from infra/config/webapp/dev.json
// Production: loads from S3 via CloudFront
const config = await configLoader.loadConfig();

Authentication

  • JWT Tokens: AWS Cognito integration for authentication

  • Role-based Access: Admin access required for SOP template creation

  • Token Validation: Automatic token refresh and validation

Build and Deployment

Development

cd frontend
npm install
npm run dev

Schema Generation

npm run generate:schemas

Build

npm run build

Testing

npm run test        # Unit tests
npm run test:e2e    # End-to-end tests
npm run test:schema # Schema validation tests

Future Enhancements

Planned Features

  • Collaborative Editing: Real-time multi-user SOP editing

  • Version Control: Git-like versioning for SOP templates

  • Template Library: Shareable SOP template

  • Advanced Validation: Custom validation rules and constraints

  • Export Formats: Additional export formats (PDF, Word, etc.)

Architecture Improvements

  • Micro-frontends: Split SAM into smaller, focused applications

  • Offline Support: Service worker for offline SOP creation

  • Performance: Virtual scrolling for large schema forms

  • Accessibility: Enhanced ARIA support and keyboard navigation