Email Ecosystem Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Email Ecosystem Tracking is a core module within the NEXUS platform designed to manage and monitor a user's digital identities. Its primary purpose is to provide a centralized vault for various email addresses, categorizing them by purpose—such as personal use, professional work, or "throwaway" accounts for free trials—while monitoring their security status and primary designation.
This system ensures that users can track which email addresses are linked to specific Accounts and Free Trials. By providing metadata such as provider information, associated phone numbers, and security status indicators, the ecosystem acts as a security-first management layer for digital command centers.
Sources: backend/server.py:101-119, frontend/src/App.js:520-535, test_result.md:52-65
Data Architecture and Models
The backend utilizes Pydantic models to enforce strict data structures for email entities. The Email model serves as the primary data structure, while EmailCreate is used for handling incoming POST requests.
Email Data Schema
The system tracks several attributes to define an email's role and health within the ecosystem.
| Field | Type | Description |
|---|---|---|
id | String (UUID) | Unique identifier generated at creation. |
user_id | String | Reference to the owner of the email record. |
email_address | EmailStr | The actual email address (validated). |
provider | String | Service provider (e.g., Gmail, Outlook). |
purpose | Enum | Classification: Personal, Work, Trials, Shopping, Throwaway. |
is_primary | Boolean | Flags the main contact email for the user. |
security_status | Enum | Security health: Secure, Compromised, or Unknown. |
notes | String (Optional) | User-defined context or descriptions. |
Sources: backend/server.py:102-121, backend_test.py:125-132
Entity Relationships
The email entity sits at the center of the user's digital identity, serving as a foreign reference for both account registrations and trial signups.
The diagram shows the relationship where one user owns multiple emails, and those emails are subsequently used to register various accounts and trials.
Sources: backend/server.py:102, backend/server.py:141, backend/server.py:183
Backend API Implementation
The system implements a full CRUD (Create, Read, Update, Delete) suite via a FastAPI router. All routes are protected by JWT authentication, ensuring users can only access and modify their own email records.
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /api/emails | Create a new email record for the current user. |
GET | /api/emails | Retrieve all email records owned by the user. |
GET | /api/emails/{id} | Retrieve details for a specific email by ID. |
PUT | /api/emails/{id} | Update an existing email record. |
DELETE | /api/emails/{id} | Remove an email record from the ecosystem. |
Sources: backend/server.py:255-296, backend_test.py:122-192
Security Logic
Authorization is handled via the get_current_user dependency, which decodes the JWT and verifies the user's existence in the database before granting access to email resources.
Sources: backend/server.py:230-240
This sequence illustrates the authenticated flow for retrieving the user's email ecosystem.
Sources: backend/server.py:263-267, backend_test.py:146-155
Frontend Integration and UI
The frontend management interface is built using React and utilizes a "Glassmorphic" aesthetic with purpose-based color coding.
Management Components
The Emails component handles the high-level state, fetching data from the API and rendering EmailCard elements.
- Purpose Badges: The UI applies specific colors based on the email's purpose (e.g., Hot Pink for
TRIALS, Electric Blue forPERSONAL). - Security Indicators: Text colors change based on security status (Green for
SECURE, Red forCOMPROMISED). - Primary Tag: A distinct gradient badge is rendered if
is_primaryis true.
Sources: frontend/src/App.js:520-565, frontend/src/App.css:550-580
Styling Variables
The visual representation relies on CSS variables defined for the cyberpunk theme:
--electric-blue: #00D4FF; /* Personal */
--vibrant-purple: #9D4EDD; /* Work */
--hot-pink: #FF10F0; /* Trials */
--cyber-orange: #FF6B00; /* Shopping */
Sources: frontend/src/App.css:10-14, frontend/src/App.css:560-575
Summary of Operations
The Email Ecosystem Tracking module functions as the foundational layer of the NEXUS digital command center. By enforcing user isolation through JWT and providing categorized metadata for every email address, the system enables users to maintain a secure and organized digital footprint across various platforms.
Sources: backend/server.py:380-385, test_result.md:52-65