BackendDatabase
Data Model
Complete entity-relationship overview of all Django models.
Entity Relationships
User
├── owns → Workspace (via owner FK)
├── member of → Workspace (via WorkspaceMembership M2M)
├── has one → StripeUser → Subscription → SubscriptionItem → Price → Product
├── has one → UserCost (legacy, unused for limits)
└── has many → AIUsage (per-call cost logs)
Workspace
├── has many → ChatSession
├── has many → KnowledgeBase
├── has many → Document
├── has many → Team → TeamMembership
├── has many → Invitation
├── has many → Folder
├── has one → Subscription (FK) → its plan
└── has many → AIUsage (counted against its credit), WorkspaceCost (legacy)
ChatSession
├── has many → Message → MessageFeedback
├── has many → ChatSessionShare
└── attached to → KnowledgeBase (via ChatSessionKnowledgeBase M2M)
KnowledgeBase
├── has many → Document (via KnowledgeBaseDocument M2M)
└── has many → KnowledgeBaseTeamAccess
Document
├── has many → DocumentChunk (text + embedding vector)
└── has many → DocumentProcessingTaskModel Summary
| App | Model | Primary Key | Key Relationships |
|---|---|---|---|
| users | User | BigAutoField | email (unique, ignoring case), USERNAME_FIELD |
| users | UserCost | BigAutoField | OneToOne → User (legacy) |
| workspaces | Workspace | UUID | owner → User, subscription → Subscription |
| workspaces | WorkspaceMembership | BigAutoField | workspace + user (unique together) |
| workspaces | Team | BigAutoField | workspace → Workspace, owner → User |
| workspaces | TeamMembership | BigAutoField | team + user (unique together) |
| workspaces | Invitation | BigAutoField | workspace/team → inviter → invitee |
| workspaces | Folder | BigAutoField | workspace → Workspace, user → User |
| workspaces | AIUsage | UUID | workspace + user + chat_session, purpose |
| workspaces | WorkspaceCost | BigAutoField | workspace → Workspace (legacy) |
| chat | ChatSession | UUID | workspace → Workspace, user → User |
| chat | Message | UUID | session → ChatSession, sequence_number |
| chat | ChatSessionShare | UUID | chat_session + shared_with_user |
| chat | MessageFeedback | UUID | message + user (one rating each) |
| documents | KnowledgeBase | UUID | workspace → Workspace |
| documents | Document | UUID | workspace → Workspace |
| documents | DocumentChunk | UUID | document → Document, embedding (1536d vector) |
| documents | KnowledgeBaseDocument | BigAutoField | knowledge_base + document |
| documents | ChatSessionKnowledgeBase | BigAutoField | chat_session + knowledge_base |
| documents | DocumentProcessingTask | BigAutoField | document → Document, task_id (Celery) |
| subscriptions | StripeUser | User PK | OneToOne → User |
| subscriptions | Product | product_id (str) | Stripe product ID, plan key |
| subscriptions | Price | price_id (str) | product → Product |
| subscriptions | Subscription | subscription_id (str) | stripe_user → StripeUser |
| subscriptions | SubscriptionItem | sub_item_id (str) | subscription + price |
| subscriptions | Feature | feature_id (str) | Stripe feature |
| subscriptions | ProductFeature | BigAutoField | product + feature |
Multi-Tenancy Model
HyperSaaS uses workspace-based multi-tenancy:
- Every resource (chat, document, knowledge base) belongs to a
Workspace - Users access workspaces through
WorkspaceMembership - The
WorkspaceAwareModelabstract mixin provides aworkspaceFK for any model that needs scoping - Every workspace-scoped endpoint checks membership of the workspace in the URL, and refuses non-members with
403 - A workspace's plan sets its limits, and its AI usage is counted against its own credit
class WorkspaceAwareModel(models.Model):
workspace = models.ForeignKey(Workspace, on_delete=models.CASCADE)
class Meta:
abstract = True