Database Schema & Models
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The NEXUS system utilizes a NoSQL document-based architecture powered by MongoDB to manage digital accounts, email identities, and subscription trials. The schema is designed to support a multi-tenant environment where data is isolated per user through unique identifiers. The backend implementation uses Pydantic models to enforce data validation and structure before persisting information to the database via the Motor async driver.
The primary objective of the data models is to provide a "Digital Command Center" that tracks sensitive credentials, financial costs associated with subscriptions, and the lifecycle of free trials. The architecture emphasizes security through the inclusion of fields for two-factor authentication (2FA) status and encrypted password storage.
Sources: backend/server.py:1-40, test_result.md:52-58
Core Data Entities
The system is built around four primary data entities: Users, Emails, Accounts, and Trials. These entities are linked via foreign key relationships (UUID strings) to maintain relational integrity within the NoSQL environment.
Entity Relationship Overview
The following diagram illustrates the logical relationships between the core data models. Every entity except the User is owned by a user_id, ensuring strict user isolation.
Sources: backend/server.py:64-165
Detailed Model Specifications
User Management
The User model handles authentication and identity. It stores credentials using bcrypt hashing to ensure security.
| Field | Type | Description |
|---|---|---|
id | str (UUID) | Unique identifier for the user. |
username | str | Unique login name. |
email | EmailStr | Primary contact email. |
hashed_password | str | Bcrypt hashed password string. |
is_active | bool | Account status flag (default: true). |
Sources: backend/server.py:64-72
Account Vault
The Account model is the most comprehensive, tracking platform details, credentials, and financial metadata. It supports various categories and subscription types through Enums.
class Account(BaseModel):
id: str = Field(default_factory=lambda: str(uuid.uuid4()))
user_id: str
platform_name: str
username: str
email_used: str # Refers to Email address or ID
password: str
account_status: AccountStatus = AccountStatus.ACTIVE
subscription_type: SubscriptionType = SubscriptionType.FREE
monthly_cost: Optional[float] = 0.0
two_fa_enabled: bool = False
platform_category: PlatformCategory = PlatformCategory.OTHER
Sources: backend/server.py:101-127
Trial Tracking
The Trial model manages the lifecycle of limited-time subscriptions. It includes fields for tracking cancellation deadlines to prevent unwanted charges.
| Field | Type | Constraints |
|---|---|---|
platform | str | Reference to the service name/account. |
start_date | datetime | ISO format timestamp. |
end_date | datetime | ISO format timestamp. |
price_after_trial | float | Projected monthly cost if not cancelled. |
is_cancelled | bool | Current cancellation status. |
Sources: backend/server.py:151-165
Enumerated Types
NEXUS uses strict Enums to standardize data across the platform, improving query reliability and frontend consistency.
| Enum Name | Values |
|---|---|
PlatformCategory | Entertainment, Productivity, Social, Finance, Shopping, Gaming, Utilities, Other |
SubscriptionType | Free, Trial, Paid |
EmailPurpose | Personal, Work, Trials, Shopping, Throwaway |
SecurityStatus | Secure, Compromised, Unknown |
TwoFAType | None, SMS, App, Hardware |
Sources: backend/server.py:43-61
Data Flow & Persistence
Data is managed through a FastAPI backend that interfaces with MongoDB. The frontend (React) interacts with these models via a RESTful API, passing JSON payloads that are validated against the Pydantic schemas.
Summary
The Database Schema & Models in NEXUS provide a robust foundation for tracking digital assets. By utilizing Pydantic for validation and MongoDB for flexible storage, the system ensures that complex account data—including 2FA settings, subscription costs, and trial deadlines—is stored accurately and securely. The strict use of Enums and UUID-based linking facilitates a consistent data structure that supports the "Command Center" dashboard statistics.