Hybrid Architecture: Static Frontend + Dynamic Database

System Overview

The Strategic Intelligence Onboarding system uses a hybrid architecture that combines static frontend configurations with dynamic database storage to optimize both performance and flexibility.

🏗️ Architecture Pattern

The system splits responsibilities between two complementary data layers:

mermaid

graph TB
    subgraph "Frontend Layer (Static)"
        A[Industry Configurations] --> B[Business Types]
        A --> C[Revenue Streams]
        A --> D[Supplier Categories]
        A --> E[Competitive Factors]
    end
    
    subgraph "Database Layer (Dynamic)"
        F[Industries Table] --> G[Client Profiles]
        G --> H[Client Responses]
        G --> I[Onboarding Flows]
        G --> J[Orchestrator Submissions]
    end
    
    K[User Selection] --> A
    A --> L[Onboarding Process]
    L --> F
    
    style A fill:#e1f5fe
    style F fill:#f3e5f5

💡 Why This Hybrid Approach?

🚀 Performance Benefits

Instant Industry Selection

Zero database queries for the critical first step
No loading states or network latency
Immediate user feedback and validation
Better perceived performance

Frontend Optimization

Static assets cached by CDN
Offline capability for industry selection
Reduced server load and bandwidth
Better SEO and crawlability

🛡️ Resilience & Reliability

Graceful Degradation

Industry selection works during database outages
Reduced single points of failure
Better error handling and recovery
Improved overall system availability

Development Flexibility

Frontend can be developed/tested without database
Independent deployment cycles
Version-controlled configurations
Type-safe development with TypeScript

📊 Data Flow Architecture

Static Configuration Layer

typescript

// Frontend: Type-safe industry configurations
export const realEstateProfessionalsConfig: IndustryConfig = {
  id: 'real-estate-professionals',
  name: 'Real Estate Professionals',
  icon: '🏠',
  description: 'Territory & market optimization',
  businessTypes: [...],
  revenueStreamTypes: [...],
  supplierCategories: [...],
  competitiveFactors: [...]
}

Responsibilities:

Industry selection UI/UX
Business logic validation
Rich configuration metadata
Type safety and IDE support
Fast user interactions

Dynamic Database Layer

sql

-- Database: Persistent storage schema
CREATE TABLE industries (
    id TEXT PRIMARY KEY,
    name TEXT UNIQUE,
    slug TEXT UNIQUE,
    description TEXT,
    active INTEGER,
    created_at DATETIME,
    updated_at DATETIME
);

CREATE TABLE client_profiles (
    id TEXT PRIMARY KEY,
    industry_id TEXT REFERENCES industries(id),
    company_name TEXT,
    onboarding_status TEXT,
    -- ... additional fields
);

Responsibilities:

User data persistence
Analytics and reporting
Admin configuration
Integration with backend services
Audit trails and compliance

🔄 Integration Points

1. Industry Registration Sync

Both layers must maintain consistent industry IDs:

typescript

// Frontend configuration ID
id: 'real-estate-professionals'

sql

-- Database record ID  
INSERT INTO industries (id, name, ...) 
VALUES ('real-estate-professionals', 'Real Estate Professionals', ...);

2. User Journey Flow

mermaid

sequenceDiagram
    participant U as User
    participant F as Frontend (Static)
    participant D as Database (Dynamic)
    participant A as AI Orchestrator
    
    U->>F: View industry options
    Note over F: Instant response from static configs
    
    U->>F: Select industry
    F->>F: Validate selection (static)
    
    U->>F: Complete onboarding
    F->>D: Store user profile
    D->>D: Persist onboarding data
    
    D->>A: Submit to orchestrator
    A->>D: Update processing status

3. Configuration Management

Frontend Changes (Industry configs, UI/UX)

Modified via code deployment
Version controlled in Git
Type-safe compilation
Instant user experience updates

Backend Changes (User data, flows, analytics)

Modified via database updates
Admin interfaces and APIs
Runtime configuration changes
Persistent data management

📁 File Structure & Organization

strategic-intelligence-onboarding/
├── src/
│   ├── types/
│   │   └── index.ts                    # Industry type definitions
│   ├── features/onboarding/
│   │   └── industry-configs/
│   │       ├── index.ts                # Industry registry
│   │       ├── real-estate-professionals.ts
│   │       ├── automotive-services-expansion.ts
│   │       └── ... (14 total industries)
│   └── features/onboarding/screens/
│       └── IndustrySelectionScreen.tsx # Static UI component

Database Schema:
├── industries                 # Core industry definitions
├── onboarding_flows          # Dynamic workflow configuration  
├── client_profiles           # User onboarding data
├── client_responses          # Form submissions
└── orchestrator_submissions  # AI processing queue

⚙️ Implementation Details

Static Configuration Example

typescript

// Complete industry configuration
export const aviationAerospaceConfig: IndustryConfig = {
  id: 'aviation-aerospace',
  name: 'Aviation & Aerospace',
  icon: '✈️',
  description: 'Certification and market opportunities',
  
  businessTypes: [
    {
      id: 'aircraft-maintenance',
      name: 'Aircraft Maintenance & Repair',
      description: 'MRO services for commercial and private aircraft'
    }
    // ... 3 more types
  ],
  
  revenueStreamTypes: [
    {
      id: 'certification-services',
      name: 'Certification Services',
      description: 'Aircraft certification and compliance services',
      intelligenceValue: "Monitor regulatory changes and certification requirements..."
    }
    // ... 3 more revenue streams
  ],
  
  supplierCategories: [
    {
      id: 'parts-materials',
      name: 'Parts & Materials',
      suppliers: ['Boeing', 'Airbus', 'Rolls-Royce', 'GE Aviation'],
      spendRanges: ['Under $25K', '$25K-$100K', '$100K-$500K', 'Over $500K']
    }
    // ... 3 more categories
  ],
  
  competitiveFactors: [
    'Regulatory compliance record',
    'Certification capabilities',
    'Technical expertise'
    // ... 7 more factors
  ]
}

Database Integration Pattern

sql

-- Seeding script for new industries
INSERT INTO industries (id, name, slug, description, active, created_at, updated_at)
VALUES 
  ('aviation-aerospace', 'Aviation & Aerospace', 'aviation-aerospace', 
   'Certification and market opportunities', 1, datetime('now'), datetime('now')),
  -- ... additional industries

-- Create corresponding onboarding flows
INSERT INTO onboarding_flows (id, industry_id, name, description, version, active, flow_config)
VALUES 
  ('flow-aviation-aerospace', 'aviation-aerospace', 
   'Aviation & Aerospace Onboarding', 'Strategic intelligence onboarding flow', 
   1, 1, '{"steps": ["industry-selection", "business-profile", ...]}');

🔧 Maintenance & Operations

Adding New Industries

Step 1: Frontend Configuration

typescript

// 1. Create industry config file
// 2. Add to IndustryType union
// 3. Register in industry configs index
// 4. Test UI functionality

Step 2: Database Integration

sql

-- 1. Insert industry record
-- 2. Create onboarding flow
-- 3. Verify foreign key relationships
-- 4. Test end-to-end data flow

Synchronization Requirements

Consistency Critical

Frontend and database industry IDs must match exactly for proper data flow:

Frontend: 'real-estate-professionals'
Database: 'real-estate-professionals'

📊 Performance Characteristics

Frontend (Static Layer)

Load Time: ~50ms (cached assets)
Industry Selection: Instant (0 network requests)
Validation: Client-side, immediate feedback
Offline Support: Full functionality available

Database (Dynamic Layer)

User Profile Storage: ~200ms (single write)
Analytics Queries: Variable (optimized with indexes)
Admin Operations: Real-time updates
Integration APIs: Background processing

🎯 Best Practices

Configuration Management

typescript

// ✅ Good: Comprehensive configuration
const industryConfig = {
  id: 'consistent-kebab-case',
  name: 'Human Readable Name', 
  description: 'Clear business focus',
  businessTypes: [...], // Always 4 types
  revenueStreamTypes: [...], // Always 4 streams  
  supplierCategories: [...], // Always 4 categories
  competitiveFactors: [...] // Always 10 factors
}

// ❌ Avoid: Incomplete or inconsistent configs
const badConfig = {
  id: 'inconsistent_naming',
  name: 'Vague Industry',
  businessTypes: [...] // Only 2 types - inconsistent
}

Database Operations

sql

-- ✅ Good: Consistent with frontend
INSERT INTO industries (id, name, slug, description, active)
VALUES ('real-estate-professionals', 'Real Estate Professionals', 
        'real-estate-professionals', 'Territory & market optimization', 1);

-- ❌ Avoid: Mismatched IDs or missing fields  
INSERT INTO industries (id, name) 
VALUES ('realestate', 'Real Estate'); -- ID mismatch!

🔍 Troubleshooting

Common Issues

Industry Not Appearing in UI

✅ Check frontend configuration is registered
✅ Verify IndustryType union includes new type
✅ Ensure getAllIndustries() returns new config
✅ Clear browser cache and rebuild

Onboarding Data Not Saving

✅ Verify database industry record exists
✅ Check industry ID matches exactly
✅ Confirm onboarding_flows record created
✅ Test database connectivity and permissions

Frontend/Database Sync Issues

✅ Compare industry IDs between layers
✅ Verify database foreign key constraints
✅ Check for typos in industry identifiers
✅ Run end-to-end integration tests

🚀 Future Enhancements

Potential Improvements

Configuration Validation

Automated sync verification between frontend/database
Schema validation for industry configurations
Integration tests for data flow consistency

Dynamic Configuration

Runtime industry configuration updates
Admin interface for industry management
A/B testing for different industry configurations

Performance Optimizations

Progressive loading for large industry catalogs
Intelligent caching strategies
Background sync processes

Architecture Summary

This hybrid approach optimizes for user experience (fast, reliable industry selection) while maintaining business requirements (persistent data, analytics, integration). The separation of concerns allows each layer to excel at its strengths while working together seamlessly.

Hybrid Architecture: Static Frontend + Dynamic Database ​

🏗️ Architecture Pattern ​

💡 Why This Hybrid Approach? ​

🚀 Performance Benefits ​

🛡️ Resilience & Reliability ​

📊 Data Flow Architecture ​

Static Configuration Layer ​

Dynamic Database Layer ​

🔄 Integration Points ​

1. Industry Registration Sync ​

2. User Journey Flow ​

3. Configuration Management ​

📁 File Structure & Organization ​

⚙️ Implementation Details ​

Static Configuration Example ​

Database Integration Pattern ​

🔧 Maintenance & Operations ​

Adding New Industries ​

Synchronization Requirements ​

📊 Performance Characteristics ​

Frontend (Static Layer) ​

Database (Dynamic Layer) ​

🎯 Best Practices ​

Configuration Management ​

Database Operations ​

🔍 Troubleshooting ​

Common Issues ​

🚀 Future Enhancements ​

Potential Improvements ​

Hybrid Architecture: Static Frontend + Dynamic Database

🏗️ Architecture Pattern

💡 Why This Hybrid Approach?

🚀 Performance Benefits

🛡️ Resilience & Reliability

📊 Data Flow Architecture

Static Configuration Layer

Dynamic Database Layer

🔄 Integration Points

1. Industry Registration Sync

2. User Journey Flow

3. Configuration Management

📁 File Structure & Organization

⚙️ Implementation Details

Static Configuration Example

Database Integration Pattern

🔧 Maintenance & Operations

Adding New Industries

Synchronization Requirements

📊 Performance Characteristics

Frontend (Static Layer)

Database (Dynamic Layer)

🎯 Best Practices

Configuration Management

Database Operations

🔍 Troubleshooting

Common Issues

🚀 Future Enhancements

Potential Improvements