340 lines
14 KiB
Markdown
340 lines
14 KiB
Markdown
# Data Models Specification
|
|
|
|
## Entity Relationship Diagram
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ User │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ Role │ │ Setting │ │ Image │ │
|
|
│ │ • id │ │ • id │ │ • id │ │
|
|
│ │ • name │ │ • key │ │ • uuid │ │
|
|
│ │ • timestamps │ │ • value │ │ • path │ │
|
|
│ └─────────────────┘ │ • timestamps │ │ • is_temp │ │
|
|
│ │ 1 │ └─────────────────┘ │ • is_public │ │
|
|
│ ▼ │ │ 1 │ • timestamps │ │
|
|
│ ┌─────────────────┐ │ ▼ └─────────────────┘ │
|
|
│ │ • id │ │ ┌─────────────────┐ │
|
|
│ │ • name │ │ │ ApiProvider │ │
|
|
│ │ • email │ │ │ • id │ │
|
|
│ │ • password │ │ │ • name │ │
|
|
│ │ • role_id │ │ │ • api_url │ │
|
|
│ │ • timestamps │ │ │ • username │ │
|
|
│ │ • 2FA fields │ │ │ • password │ │
|
|
│ └─────────────────┘ │ │ • token │ │
|
|
│ │ │ │ • plugin │ │
|
|
│ ▼ │ │ • enabled │ │
|
|
│ ┌─────────────────┐ │ │ • timestamps │ │
|
|
│ │ Style │◄─┘ └─────────────────┘ │
|
|
│ │ • id │ │ 1 │
|
|
│ │ • title │ ▼ │
|
|
│ │ • prompt │ ┌─────────────────┐ │
|
|
│ │ • description │ │ AiModel │ │
|
|
│ │ • preview_img │ │ • id │ │
|
|
│ │ • parameters │ │ • name │ │
|
|
│ │ • ai_model_id │ │ • model_id │ │
|
|
│ │ • enabled │ │ • model_type │ │
|
|
│ │ • sort_order │ │ • api_provider │ │
|
|
│ │ • timestamps │ │ • parameters │ │
|
|
│ └─────────────────┘ │ • enabled │ │
|
|
│ │ │ • timestamps │ │
|
|
│ ▼ │ └─────────────────┘ │
|
|
│ ┌─────────────────┐ │ │
|
|
│ │ Original │◄┘ │
|
|
│ │ Image │ │
|
|
│ └─────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Model Specifications
|
|
|
|
### 1. User Model
|
|
|
|
**Purpose**: Represents authenticated users of the application
|
|
|
|
**Table**: `users`
|
|
|
|
**Attributes**:
|
|
```php
|
|
id: bigint unsigned auto_increment primary key
|
|
name: varchar(255) // User's display name
|
|
email: varchar(255) unique // Unique email address
|
|
password: varchar(255) // Hashed password
|
|
role_id: bigint unsigned nullable // Foreign key to roles table
|
|
email_notifications_enabled: tinyint(1) default(1) // Email notification preference
|
|
theme_preference: varchar(255) default('light') // UI theme preference
|
|
locale: varchar(255) default('en') // Language preference
|
|
two_factor_secret: text nullable // 2FA secret key
|
|
two_factor_recovery_codes: text nullable // 2FA backup codes
|
|
two_factor_confirmed_at: timestamp nullable // 2FA confirmation timestamp
|
|
created_at: timestamp nullable
|
|
updated_at: timestamp nullable
|
|
```
|
|
|
|
**Relationships**:
|
|
- **BelongsTo**: Role (one user has one role)
|
|
- **HasMany**: Images (one user can have many images)
|
|
|
|
**Business Rules**:
|
|
- Email must be unique across all users
|
|
- Password must be hashed using secure algorithm
|
|
- Role determines permissions and access levels
|
|
- 2FA fields are optional but provide enhanced security
|
|
|
|
---
|
|
|
|
### 2. Role Model
|
|
|
|
**Purpose**: Defines user roles for access control
|
|
|
|
**Table**: `roles`
|
|
|
|
**Attributes**:
|
|
```php
|
|
id: bigint unsigned auto_increment primary key
|
|
name: varchar(255) unique // Role name (e.g., 'admin', 'user')
|
|
created_at: timestamp nullable
|
|
updated_at: timestamp nullable
|
|
```
|
|
|
|
**Relationships**:
|
|
- **HasMany**: Users (one role can have many users)
|
|
|
|
**Business Rules**:
|
|
- Role names must be unique
|
|
- Predefined roles: 'admin', 'user'
|
|
- Used by Filament for access control
|
|
|
|
---
|
|
|
|
### 3. Image Model
|
|
|
|
**Purpose**: Stores metadata for uploaded and AI-generated images
|
|
|
|
**Table**: `images`
|
|
|
|
**Attributes**:
|
|
```php
|
|
id: bigint unsigned auto_increment primary key
|
|
uuid: char(36) unique nullable // Unique identifier for tracking
|
|
path: varchar(255) // File path relative to storage disk
|
|
original_image_id: bigint unsigned nullable // FK to original image (for styled images)
|
|
style_id: bigint unsigned nullable // FK to applied style
|
|
is_temp: tinyint(1) default(0) // True for temporary styled images
|
|
is_public: tinyint(1) default(1) // True for publicly visible images
|
|
comfyui_prompt_id: varchar(255) nullable // Tracking ID from ComfyUI
|
|
created_at: timestamp nullable
|
|
updated_at: timestamp nullable
|
|
```
|
|
|
|
**Relationships**:
|
|
- **BelongsTo**: Style (many images can use one style)
|
|
- **BelongsTo**: Original Image (self-referencing, styled images reference originals)
|
|
- **HasMany**: Styled Images (self-referencing, original images have many styled versions)
|
|
|
|
**Business Rules**:
|
|
- UUID is generated for tracking and external references
|
|
- Original images have `original_image_id` = null
|
|
- Styled images reference original via `original_image_id`
|
|
- Temporary images (`is_temp = true`) are pending user decision
|
|
- Public images (`is_public = true`) are visible to all users
|
|
- ComfyUI prompt ID tracks processing jobs
|
|
|
|
---
|
|
|
|
### 4. Style Model
|
|
|
|
**Purpose**: Defines AI artistic styles available for image transformation
|
|
|
|
**Table**: `styles`
|
|
|
|
**Attributes**:
|
|
```php
|
|
id: bigint unsigned auto_increment primary key
|
|
title: varchar(255) // Display name of the style
|
|
prompt: longtext // AI prompt describing the style
|
|
description: longtext // Human-readable description
|
|
preview_image: varchar(255) // Path to style preview image
|
|
parameters: json nullable // Additional AI parameters (cast to array)
|
|
ai_model_id: bigint unsigned // FK to associated AI model
|
|
enabled: tinyint(1) default(1) // Whether style is active
|
|
sort_order: integer default(0) // Display order in UI
|
|
created_at: timestamp nullable
|
|
updated_at: timestamp nullable
|
|
```
|
|
|
|
**Relationships**:
|
|
- **BelongsTo**: AiModel (many styles can use one AI model)
|
|
- **HasMany**: Images (one style can be applied to many images)
|
|
|
|
**Business Rules**:
|
|
- Only enabled styles are available to users
|
|
- Preview images help users choose appropriate styles
|
|
- Parameters are JSON and merged with AI model parameters
|
|
- Sort order controls display sequence in style selector
|
|
|
|
---
|
|
|
|
### 5. AiModel Model
|
|
|
|
**Purpose**: Represents specific AI models available through providers
|
|
|
|
**Table**: `ai_models`
|
|
|
|
**Attributes**:
|
|
```php
|
|
id: bigint unsigned auto_increment primary key
|
|
name: varchar(255) // Human-readable model name
|
|
model_id: varchar(255) // Identifier used by AI service
|
|
model_type: varchar(255) nullable // Type/category (e.g., 'Stable Diffusion')
|
|
parameters: json nullable // Default parameters (cast to array)
|
|
api_provider_id: bigint unsigned nullable // FK to primary API provider
|
|
enabled: tinyint(1) default(1) // Whether model is active
|
|
created_at: timestamp nullable
|
|
updated_at: timestamp nullable
|
|
```
|
|
|
|
**Relationships**:
|
|
- **BelongsTo**: ApiProvider (many models can use one provider)
|
|
- **HasMany**: Styles (one model can have many styles)
|
|
|
|
**Business Rules**:
|
|
- Model ID must match identifier expected by AI service
|
|
- Only enabled models are available for new styles
|
|
- Parameters provide defaults, merged with style parameters
|
|
- Primary API provider handles communication for this model
|
|
|
|
---
|
|
|
|
### 6. ApiProvider Model
|
|
|
|
**Purpose**: Configures connections to external AI services
|
|
|
|
**Table**: `api_providers`
|
|
|
|
**Attributes**:
|
|
```php
|
|
id: bigint unsigned auto_increment primary key
|
|
name: varchar(255) // Provider name (e.g., 'ComfyUI Production')
|
|
api_url: varchar(255) // Base URL of AI service
|
|
username: varchar(255) nullable // Authentication username
|
|
password: varchar(255) nullable // Authentication password
|
|
token: varchar(255) nullable // API token/key
|
|
plugin: varchar(255) // Plugin identifier (e.g., 'comfyui', 'runwareai')
|
|
enabled: tinyint(1) default(1) // Whether provider is active
|
|
created_at: timestamp nullable
|
|
updated_at: timestamp nullable
|
|
```
|
|
|
|
**Relationships**:
|
|
- **HasMany**: AiModels (one provider can serve many models)
|
|
- **HasMany**: Styles (indirectly through AI models)
|
|
|
|
**Business Rules**:
|
|
- Plugin field determines which adapter to use
|
|
- Only enabled providers are available for processing
|
|
- Authentication credentials are encrypted/stored securely
|
|
- API URL must be valid and accessible
|
|
|
|
---
|
|
|
|
### 7. Setting Model
|
|
|
|
**Purpose**: Stores application-wide configuration settings
|
|
|
|
**Table**: `settings`
|
|
|
|
**Attributes**:
|
|
```php
|
|
id: bigint unsigned auto_increment primary key
|
|
key: varchar(255) unique // Setting identifier
|
|
value: longtext nullable // Setting value (can be JSON)
|
|
created_at: timestamp nullable
|
|
updated_at: timestamp nullable
|
|
```
|
|
|
|
**Relationships**: None (standalone configuration storage)
|
|
|
|
**Business Rules**:
|
|
- Keys must be unique across application
|
|
- Values can be simple strings or complex JSON
|
|
- Used for various configuration needs throughout app
|
|
|
|
## Data Integrity Constraints
|
|
|
|
### Foreign Key Relationships
|
|
- `users.role_id` → `roles.id` (nullable, defaults to user role)
|
|
- `images.original_image_id` → `images.id` (nullable, self-referencing)
|
|
- `images.style_id` → `styles.id` (nullable)
|
|
- `styles.ai_model_id` → `ai_models.id` (required)
|
|
- `ai_models.api_provider_id` → `api_providers.id` (nullable)
|
|
|
|
### Unique Constraints
|
|
- `users.email` (unique)
|
|
- `roles.name` (unique)
|
|
- `images.uuid` (unique, nullable)
|
|
- `settings.key` (unique)
|
|
|
|
### Check Constraints
|
|
- `images.is_temp` ∈ {0, 1}
|
|
- `images.is_public` ∈ {0, 1}
|
|
- `styles.enabled` ∈ {0, 1}
|
|
- `ai_models.enabled` ∈ {0, 1}
|
|
- `api_providers.enabled` ∈ {0, 1}
|
|
|
|
## Data Types & Casting
|
|
|
|
### Automatic Casting
|
|
- **Boolean Fields**: `enabled`, `is_temp`, `is_public` → boolean
|
|
- **JSON Fields**: `parameters` (in styles, ai_models) → array
|
|
- **Timestamps**: `created_at`, `updated_at` → datetime
|
|
|
|
### File Paths
|
|
- All image paths are relative to storage disk
|
|
- Preview images stored in `storage/app/public/style_previews/`
|
|
- Uploaded images stored in `storage/app/public/uploads/`
|
|
|
|
## Business Logic Implementation
|
|
|
|
### Image Path Resolution
|
|
- **Storage Disk**: Uses 'public' disk configuration
|
|
- **URL Generation**: `asset('storage/' . $image->path)`
|
|
- **File Location**: `public_path('storage/' . $image->path)`
|
|
|
|
### Parameter Merging
|
|
- **Style Parameters**: Override AI model parameters
|
|
- **Merge Strategy**: `array_replace_recursive($modelParams, $styleParams)`
|
|
- **Placeholder Replacement**: `__PROMPT__`, `__FILENAME__`, `__MODEL_ID__`
|
|
|
|
### UUID Usage
|
|
- **Image Tracking**: Unique identifier for external references
|
|
- **Generation**: Laravel's `HasUuids` trait or manual generation
|
|
- **Uniqueness**: Enforced by unique database constraint
|
|
|
|
## Data Access Patterns
|
|
|
|
### Common Queries
|
|
- **User Images**: `$user->images()` - all images for a user
|
|
- **Public Images**: `Image::where('is_public', true)`
|
|
- **Active Styles**: `Style::where('enabled', true)->with('aiModel')`
|
|
- **Enabled Models**: `AiModel::where('enabled', true)->with('primaryApiProvider')`
|
|
|
|
### Query Optimization
|
|
- **Eager Loading**: Styles load AI models and providers
|
|
- **Soft Deletes**: Not implemented (permanent deletion)
|
|
- **Indexing**: Consider indexes on frequently queried fields
|
|
|
|
## Migration Strategy
|
|
|
|
### Future Enhancements
|
|
- **Image Metadata**: EXIF data, dimensions, file size
|
|
- **Processing History**: Track all transformations applied to images
|
|
- **User Preferences**: Default styles, notification settings
|
|
- **Batch Operations**: Multiple image processing, bulk style application
|
|
- **Tagging System**: Categorize images with custom tags
|
|
- **Sharing Features**: Public galleries, social features
|
|
|
|
### Schema Evolution
|
|
- **Version Control**: Each model change requires migration
|
|
- **Backward Compatibility**: Maintain existing data integrity
|
|
- **Testing**: Validate schema changes against business rules |