semblance/mermaid-flow.md

Synthetic Society System Architecture

flowchart TB
    %% Define main components
    User([User/Researcher])
    Frontend[Frontend Application]
    Backend[Backend Flask API]
    LLM[LLM Service\nGoogle Gemini]
    MongoDB[(MongoDB Database)]
    
    %% Authentication flow
    subgraph Authentication
        Login[Login/Register]
        AuthContext[Auth Context]
        JWT[JWT Token]
        API_Auth[Auth Middleware]
    end
    
    %% Frontend components
    subgraph Frontend_Components
        SyntheticUsers[Synthetic Users Management]
        FocusGroups[Focus Groups Management]
        SessionView[Focus Group Session]
        Dashboard[Research Dashboard]
        AIRecruiter[AI Persona Recruiter]
    end
    
    %% Backend services
    subgraph Backend_Services
        PersonaService[AI Persona Service]
        FocusGroupService[Focus Group Service]
        ResponseService[Focus Group Response Service]
        LLMService[LLM Service]
    end
    
    %% Database models
    subgraph Database_Models
        UserModel[User Model]
        PersonaModel[Persona Model]
        FocusGroupModel[Focus Group Model]
    end
    
    %% Define relationships
    User --> Frontend
    Frontend --> Backend
    Backend --> MongoDB
    Backend --> LLM
    
    %% Authentication flow
    User --> Login
    Login --> JWT
    JWT --> AuthContext
    AuthContext --> Frontend
    JWT --> API_Auth
    API_Auth --> Backend
    
    %% Frontend component relationships
    Frontend --> Frontend_Components
    AIRecruiter --> SyntheticUsers
    SyntheticUsers --> FocusGroups
    FocusGroups --> SessionView
    SessionView --> Dashboard
    
    %% Backend service relationships
    Backend --> Backend_Services
    PersonaService --> LLMService
    FocusGroupService --> LLMService
    ResponseService --> LLMService
    
    %% Database model relationships
    MongoDB --> Database_Models
    PersonaService --> PersonaModel
    FocusGroupService --> FocusGroupModel
    ResponseService --> FocusGroupModel
    API_Auth --> UserModel
    
    %% Frontend to backend API
    SyntheticUsers -.-> |API Calls| personasApi[/Personas API/]
    personasApi -.-> PersonaService
    AIRecruiter -.-> |API Calls| aiPersonasApi[/AI Personas API/]
    aiPersonasApi -.-> PersonaService
    FocusGroups -.-> |API Calls| focusGroupsApi[/Focus Groups API/]
    focusGroupsApi -.-> FocusGroupService
    SessionView -.-> |API Calls| focusGroupAiApi[/Focus Group AI API/]
    focusGroupAiApi -.-> ResponseService
    
    %% Core user flows
    User -- 1. Create Personas --> SyntheticUsers
    User -- 2. Create Focus Group --> FocusGroups
    User -- 3. Run Discussion --> SessionView
    User -- 4. Analyze Results --> Dashboard
    
    %% API mode handling
    OfflineMode[Offline Mode\nLocal Storage Fallback]
    Frontend -- Check Backend --> OfflineMode
    OfflineMode -.-> Frontend
    
    %% Add classes and styles
    classDef primary fill:#f9f,stroke:#333,stroke-width:2px
    classDef secondary fill:#bbf,stroke:#333,stroke-width:1px
    classDef api fill:#bfb,stroke:#333,stroke-width:1px
    classDef db fill:#fbb,stroke:#333,stroke-width:1px
    
    class User,Frontend,Backend,LLM primary
    class Frontend_Components,Backend_Services,Authentication secondary
    class personasApi,aiPersonasApi,focusGroupsApi,focusGroupAiApi api
    class MongoDB,Database_Models db

Detailed Process Flow

sequenceDiagram
    actor User
    participant Frontend
    participant Backend
    participant LLM
    participant DB as Database
    
    %% Application startup
    User->>Frontend: Visit application
    Frontend->>Backend: Check availability
    alt Backend available
        Backend->>Frontend: Status OK
        Frontend->>Frontend: Disable offline mode
    else Backend unavailable
        Frontend->>Frontend: Enable offline mode
        Frontend->>Frontend: Load data from localStorage
    end
    
    %% Authentication
    User->>Frontend: Login/Register
    alt Backend available
        Frontend->>Backend: Auth request
        Backend->>DB: Verify credentials
        DB->>Backend: User data
        Backend->>Frontend: JWT token
        Frontend->>Frontend: Store token in localStorage
    else Offline mode
        Frontend->>Frontend: Create mock user session
    end
    
    %% Persona Creation Flow - Manual
    User->>Frontend: Create persona manually
    Frontend->>Frontend: Validate form inputs
    alt Backend available
        Frontend->>Backend: POST /personas
        Backend->>DB: Save persona
        DB->>Backend: Persona ID
        Backend->>Frontend: Saved persona data
    else Offline mode
        Frontend->>Frontend: Generate local ID
        Frontend->>Frontend: Save to localStorage
    end
    
    %% Persona Creation Flow - AI Generated
    User->>Frontend: Create AI-generated personas
    Frontend->>Frontend: Show recruiter form
    User->>Frontend: Submit research brief
    alt Backend available
        Frontend->>Backend: POST /ai-personas/batch-generate-with-stages
        
        %% Two-stage generation process
        Backend->>LLM: Generate basic profiles
        LLM->>Backend: Basic profiles
        
        loop For each basic profile
            Backend->>LLM: Complete persona details
            LLM->>Backend: Complete persona
            Backend->>DB: Save persona
        end
        
        Backend->>Frontend: Saved personas
    else Offline mode
        Frontend->>Frontend: Show error toast
    end
    
    %% Focus Group Creation
    User->>Frontend: Create focus group
    Frontend->>Frontend: Show creation form
    User->>Frontend: Add personas & discussion topics
    alt Backend available
        Frontend->>Backend: POST /focus-groups
        Backend->>DB: Save focus group
        Backend->>Frontend: Focus group data
    else Offline mode
        Frontend->>Frontend: Generate local ID
        Frontend->>Frontend: Save to localStorage
    end
    
    %% Focus Group Session Flow
    User->>Frontend: Open focus group session
    Frontend->>Backend: GET /focus-groups/:id
    Backend->>DB: Fetch session data
    DB->>Backend: Session details
    Backend->>Frontend: Session details
    
    %% Sending messages in session
    User->>Frontend: Send moderator message
    Frontend->>Backend: POST /focus-groups/:id/messages
    Backend->>DB: Save message
    
    %% Generating AI responses
    User->>Frontend: Request AI responses
    Frontend->>Backend: POST /focus-group-ai/generate-response
    Backend->>DB: Fetch conversation history
    DB->>Backend: Conversation context
    
    loop For each AI persona
        Backend->>LLM: Generate contextual response
        LLM->>Backend: AI response
        Backend->>DB: Save response
    end
    
    Backend->>Frontend: AI responses
    Frontend->>Frontend: Update discussion thread
    
    %% Theme analysis & dashboard
    User->>Frontend: View insights dashboard
    Frontend->>Frontend: Analyze message patterns
    Frontend->>Frontend: Display themes & stats

Data Model

erDiagram
    User ||--o{ Persona : creates
    User ||--o{ FocusGroup : manages
    Persona }o--o{ FocusGroup : participates
    FocusGroup ||--o{ Message : contains
    
    User {
        string _id
        string username
        string email
        string password_hash
        datetime created_at
        datetime last_login
    }
    
    Persona {
        string _id
        string name
        number age
        string gender
        string occupation
        string location
        string bio
        string personality
        json demographics
        json goals
        json frustrations
        json scenarios
        string creator_id
        datetime created_at
        boolean is_ai_generated
    }
    
    FocusGroup {
        string _id
        string name
        string description
        string topic
        string[] discussion_guide
        datetime created_at
        string creator_id
        string[] participant_ids
        string status
    }
    
    Message {
        string _id
        string focus_group_id
        string sender_id
        string sender_type
        string sender_name
        string content
        datetime timestamp
        boolean highlighted
        string[] themes
    }

Frontend State Management

stateDiagram-v2
    [*] --> Initializing
    
    Initializing --> CheckingBackend
    CheckingBackend --> Online: Backend available
    CheckingBackend --> Offline: Backend unavailable
    
    Online --> Authenticating: Check auth token
    Offline --> LoadingLocal: Use local data
    
    Authenticating --> LoggedIn: Valid token
    Authenticating --> LoggedOut: Invalid/no token
    
    LoggedIn --> FetchingData: Load data
    LoggedOut --> LoginPage: Redirect
    
    FetchingData --> ReadyState: Data loaded
    LoadingLocal --> ReadyState: Local data ready
    
    LoginPage --> Authenticating: Submit login
    
    state ReadyState {
        [*] --> BrowsingPersonas
        
        BrowsingPersonas --> CreatingPersona: New persona
        BrowsingPersonas --> EditingPersona: Edit persona
        BrowsingPersonas --> ViewingPersona: View persona
        BrowsingPersonas --> BrowsingFocusGroups: Navigate to focus groups
        
        CreatingPersona --> BrowsingPersonas: Save/Cancel
        EditingPersona --> BrowsingPersonas: Save/Cancel
        ViewingPersona --> BrowsingPersonas: Back
        
        BrowsingFocusGroups --> CreatingFocusGroup: New focus group
        BrowsingFocusGroups --> ViewingFocusGroup: View focus group
        
        CreatingFocusGroup --> BrowsingFocusGroups: Save/Cancel
        
        ViewingFocusGroup --> RunningSession: Start session
        ViewingFocusGroup --> BrowsingFocusGroups: Back
        
        RunningSession --> ViewingFocusGroup: End session
        RunningSession --> ViewingDashboard: View insights
        
        ViewingDashboard --> RunningSession: Back to session
    }
    
    note right of Offline
        All operations work with localStorage
        when backend is unavailable
    end note