224 lines
10 KiB
Markdown
224 lines
10 KiB
Markdown
# Integration Settings Workflow & Data Flow
|
|
|
|
## Part 1: How Global Settings Load on Frontend
|
|
|
|
### Admin Configures Global Settings
|
|
**URL**: `https://api.igny8.com/admin/system/globalintegrationsettings/1/change/`
|
|
|
|
**What's Stored**:
|
|
- Platform-wide API keys (OpenAI, DALL-E, Runware)
|
|
- Default model selections (gpt-4o-mini, dall-e-3, runware:97@1)
|
|
- Default parameters (temperature: 0.7, max_tokens: 8192)
|
|
- Default image settings (size, quality, style)
|
|
|
|
**Who Can Access**: Only platform administrators
|
|
|
|
### Normal User Opens Integration Page
|
|
**URL**: `https://app.igny8.com/settings/integration`
|
|
|
|
**What Happens**:
|
|
|
|
1. **Frontend Request**:
|
|
- User browser requests: `GET /api/v1/system/settings/integrations/openai/`
|
|
- User browser requests: `GET /api/v1/system/settings/integrations/image_generation/`
|
|
|
|
2. **Backend Processing** (`integration_views.py` - `get_settings()` method):
|
|
- Checks if user's account has custom overrides in `IntegrationSettings` table
|
|
- Gets global defaults from `GlobalIntegrationSettings` singleton
|
|
- Merges data with this priority:
|
|
- If account has overrides → use account settings
|
|
- If no overrides → use global defaults
|
|
- **NEVER returns API keys** (security)
|
|
|
|
3. **Response to Frontend**:
|
|
```
|
|
{
|
|
"id": "openai",
|
|
"enabled": true,
|
|
"model": "gpt-4o-mini", // From global OR account override
|
|
"temperature": 0.7, // From global OR account override
|
|
"max_tokens": 8192, // From global OR account override
|
|
"using_global": true // Flag: true if using defaults
|
|
}
|
|
```
|
|
|
|
4. **Frontend Display**:
|
|
- Shows current model selection
|
|
- Shows "Using platform defaults" badge if `using_global: true`
|
|
- Shows "Custom settings" badge if `using_global: false`
|
|
- User can change model, temperature, etc.
|
|
- **API key status is NOT shown** (user cannot see/change platform keys)
|
|
|
|
---
|
|
|
|
## Part 2: How User Changes Are Saved
|
|
|
|
### User Changes Settings on Frontend
|
|
|
|
1. **User Actions**:
|
|
- Opens settings modal
|
|
- Changes model from `gpt-4o-mini` to `gpt-4o`
|
|
- Changes temperature from `0.7` to `0.8`
|
|
- Clicks "Save"
|
|
|
|
2. **Frontend Request**:
|
|
- Sends: `PUT /api/v1/system/settings/integrations/openai/`
|
|
- Body: `{"model": "gpt-4o", "temperature": 0.8, "max_tokens": 8192}`
|
|
|
|
3. **Backend Processing** (`integration_views.py` - `save_settings()` method):
|
|
- **CRITICAL SECURITY**: Strips ANY API keys from request (apiKey, api_key, openai_api_key, etc.)
|
|
- Validates account exists
|
|
- Builds clean config with ONLY allowed overrides:
|
|
- For OpenAI: model, temperature, max_tokens
|
|
- For Image: service, model, image_quality, image_style, sizes
|
|
- Saves to `IntegrationSettings` table:
|
|
```
|
|
account_id: 123
|
|
integration_type: "openai"
|
|
config: {"model": "gpt-4o", "temperature": 0.8, "max_tokens": 8192}
|
|
is_active: true
|
|
```
|
|
|
|
4. **Database Structure**:
|
|
- **GlobalIntegrationSettings** (1 row, pk=1):
|
|
- Contains: API keys + default settings
|
|
- Used by: ALL accounts for API keys
|
|
|
|
- **IntegrationSettings** (multiple rows):
|
|
- Row per account per integration type
|
|
- Contains: ONLY overrides (no API keys)
|
|
- Example:
|
|
```
|
|
id | account_id | integration_type | config
|
|
100 | 123 | openai | {"model": "gpt-4o", "temperature": 0.8}
|
|
101 | 456 | openai | {"model": "gpt-4.1", "max_tokens": 4000}
|
|
102 | 123 | image_generation| {"service": "runware", "model": "runware:100@1"}
|
|
```
|
|
|
|
5. **Next Request from User**:
|
|
- Frontend requests: `GET /api/v1/system/settings/integrations/openai/`
|
|
- Backend finds IntegrationSettings row for account 123
|
|
- Returns: `{"model": "gpt-4o", "temperature": 0.8, "using_global": false}`
|
|
- User sees their custom settings
|
|
|
|
---
|
|
|
|
## Data Flow Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ ADMIN SIDE │
|
|
│ https://api.igny8.com/admin/ │
|
|
│ │
|
|
│ GlobalIntegrationSettings (pk=1) │
|
|
│ ├── openai_api_key: "sk-xxx" ← Platform-wide │
|
|
│ ├── openai_model: "gpt-4o-mini" ← Default │
|
|
│ ├── openai_temperature: 0.7 ← Default │
|
|
│ ├── dalle_api_key: "sk-xxx" ← Platform-wide │
|
|
│ ├── runware_api_key: "xxx" ← Platform-wide │
|
|
│ └── image_quality: "standard" ← Default │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ Backend reads from
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ BACKEND API LAYER │
|
|
│ integration_views.py │
|
|
│ │
|
|
│ get_settings(): │
|
|
│ 1. Load GlobalIntegrationSettings (for defaults) │
|
|
│ 2. Check IntegrationSettings (for account overrides) │
|
|
│ 3. Merge: account overrides > global defaults │
|
|
│ 4. Return to frontend (NO API keys) │
|
|
│ │
|
|
│ save_settings(): │
|
|
│ 1. Receive request from frontend │
|
|
│ 2. Strip ALL API keys (security) │
|
|
│ 3. Save ONLY overrides to IntegrationSettings │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ API sends data
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ FRONTEND - USER SIDE │
|
|
│ https://app.igny8.com/settings/integration │
|
|
│ │
|
|
│ User sees: │
|
|
│ ├── Model: gpt-4o-mini (dropdown) │
|
|
│ ├── Temperature: 0.7 (slider) │
|
|
│ ├── Status: ✓ Connected (test connection works) │
|
|
│ └── Badge: "Using platform defaults" │
|
|
│ │
|
|
│ User CANNOT see: │
|
|
│ ✗ API keys (security) │
|
|
│ ✗ Platform configuration │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ User changes settings
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ IntegrationSettings Table │
|
|
│ (Per-account overrides - NO API KEYS) │
|
|
│ │
|
|
│ Account 123: │
|
|
│ ├── openai: {"model": "gpt-4o", "temperature": 0.8} │
|
|
│ └── image_generation: {"service": "runware"} │
|
|
│ │
|
|
│ Account 456: │
|
|
│ ├── openai: {"model": "gpt-4.1"} │
|
|
│ └── image_generation: (no row = uses global defaults) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Important Security Rules
|
|
|
|
1. **API Keys Flow**:
|
|
- Admin sets → GlobalIntegrationSettings
|
|
- Backend uses → For ALL accounts
|
|
- Frontend NEVER sees → Security
|
|
- Users NEVER save → Stripped by backend
|
|
|
|
2. **Settings Flow**:
|
|
- Admin sets defaults → GlobalIntegrationSettings
|
|
- Users customize → IntegrationSettings (overrides only)
|
|
- Backend merges → Global defaults + account overrides
|
|
- Frontend displays → Merged result (no keys)
|
|
|
|
3. **Free Plan Restriction**:
|
|
- Cannot create IntegrationSettings rows
|
|
- Must use global defaults only
|
|
- Enforced at frontend (UI disabled)
|
|
- TODO: Add backend validation
|
|
|
|
---
|
|
|
|
## Example Scenarios
|
|
|
|
### Scenario 1: New User First Visit
|
|
- User has NO IntegrationSettings row
|
|
- Backend returns global defaults
|
|
- `using_global: true`
|
|
- User sees platform defaults
|
|
- API operations use platform API key
|
|
|
|
### Scenario 2: User Customizes Model
|
|
- User changes model to "gpt-4o"
|
|
- Frontend sends: `{"model": "gpt-4o"}`
|
|
- Backend creates IntegrationSettings row
|
|
- Next visit: `using_global: false`
|
|
- API operations use platform API key + user's model choice
|
|
|
|
### Scenario 3: User Resets to Default
|
|
- Frontend sends: `{"model": "gpt-4o-mini"}` (same as global)
|
|
- Backend still saves override row
|
|
- Alternative: Delete row to truly use global
|
|
- TODO: Add "Reset to defaults" button
|
|
|
|
### Scenario 4: Admin Changes Global Default
|
|
- Admin changes global model to "gpt-4.1"
|
|
- Users WITH overrides: See their custom model
|
|
- Users WITHOUT overrides: See new "gpt-4.1" default
|
|
- All users: Use platform API key
|