340 lines
No EOL
9.9 KiB
Markdown
Executable file
340 lines
No EOL
9.9 KiB
Markdown
Executable file
## Synthetic Society System Architecture
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
``` |