Big-Link-Man/docs/architecture/data-models.md

Data Models

The following data models will be implemented using SQLAlchemy.

1. User

Purpose: Stores user credentials and role information.

Key Attributes:

• id: Integer, Primary Key
• username: String, Unique, Not Null
• hashed_password: String, Not Null
• role: String, Not Null ("Admin" or "User")

Relationships: A User can have many Projects.

2. Project

Purpose: Represents a single content generation job initiated from a CORA report.

Key Attributes:

• id: Integer, Primary Key
• user_id: Integer, Foreign Key to User
• project_name: String, Not Null
• cora_data: JSON (stores extracted keywords, entities, etc.)
• status: String (e.g., "Pending", "Generating", "Complete")

Relationships: A Project belongs to one User and has many GeneratedContents.

3. GeneratedContent

Purpose: Stores the AI-generated content from the three-stage pipeline.

Key Attributes:

• id: Integer, Primary Key, Auto-increment
• project_id: Integer, Foreign Key to Project, Indexed
• tier: String(20), Not Null, Indexed (tier1, tier2, tier3)
• keyword: String(255), Not Null, Indexed
• title: Text, Not Null (Generated in stage 1)
• outline: JSON, Not Null (Generated in stage 2)
• content: Text, Not Null (HTML fragment from stage 3)
• word_count: Integer, Not Null (Validated word count)
• status: String(20), Not Null (generated, augmented, failed)
• created_at: DateTime, Not Null
• updated_at: DateTime, Not Null

Relationships: Belongs to one Project.

Status Values:

• generated: Content was successfully generated within word count range
• augmented: Content was below minimum and was augmented
• failed: Generation failed (error details in outline JSON)

4. FqdnMapping

Purpose: Maps cloud storage buckets to fully qualified domain names for URL generation.

Key Attributes:

• id: Integer, Primary Key
• bucket_name: String, Not Null
• provider: String, Not Null (e.g., "aws", "bunny", "azure")
• fqdn: String, Not Null

Relationships: None.