pal-e-docs

Data Flow: intelligentstaffingsystems

arch-dataflow-iss Architecture

architecture active
Project

Data Flow: intelligentstaffingsystems

Diagram

Flow 1: Authentication (OIDC)




          
  
Flow 2: Lead ↔ Keycloak Account Linking



          
  



          
  
Flow 3: Message Broadcasting



          
  



          
  
Components



          
  

    

        
          

              Component
              Purpose
              Notes
          

        
      
          

              Rails App
              Full-stack application server
              Server-rendered HTML with Hotwire; no API mode
          

          

              Keycloak
              SSO/OIDC provider
              Realm: iss. Roles: lead, client, admin. PKCE enforced.
          

          

              PostgreSQL
              Primary data store
              CNPG-managed on k3s
          

          

              Turbo Streams
              Real-time UI updates
              WebSocket via Action Cable; message broadcasting
          

          

              Postmark
              Transactional email
              Appointment confirmations, password resets
          

      
    

  



          
  
Key Decisions



          
  
    
      
  • Keycloak roles are authoritative — access control reads realm roles from the ID token, never Lead.role. Lead.role is a display mirror synced on each login.
    • 
      
  • Three-step lead resolution — by sub (fast path), by email (first login after form), walk-in fallback (new Lead from token). Handles the gap between form registration and Keycloak account creation.
    • 
      
  • Turbo Streams for messaging — broadcasts_to :lead gives real-time message delivery without polling. One broadcast channel per lead thread.
    • 



          
  


          
  
    
      
  • arch-domain-iss — entity relationships
    • 
      
  • arch-deployment-iss — where services run
    • 
      
  • project-iss — project page
    •