Trial Countdown & Tracking

Relevant source files

The following files were used as context for generating this wiki page:

• backend/server.py
• frontend/src/App.js
• frontend/src/App.css
• backend_test.py
• test_result.md

The Trial Countdown & Tracking system is a core module of the NEXUS digital command center designed to manage the lifecycle of software and service trials. It allows users to monitor start and end dates, calculate trial durations, and track cancellation deadlines to avoid unwanted subscription charges. This system integrates directly with the NEXUS Account Vault and dashboard statistics to provide a centralized view of all active financial commitments.

The module consists of a FastAPI-based backend using MongoDB for persistence and a React-based frontend that provides a glassmorphic interface for data entry and visualization. It specifically tracks metadata such as the platform, associated email, trial type, and the potential cost if the trial converts to a paid subscription.
Sources: backend/server.py:27-30, frontend/src/App.js:770-785, test_result.md:95-103

Data Architecture & Models

The tracking system relies on a structured Pydantic data model in the backend and a corresponding state management system in the frontend. Each trial is uniquely identified and linked to a specific user through a user_id.

Trial Data Schema

The Trial model includes critical temporal fields for tracking, specifically start_date and end_date.

Field	Type	Description
id	str	Unique UUID for the trial record
user_id	str	Reference to the owner of the trial
platform	str	The service platform (e.g., "Spotify Premium")
email_used	str	The email address used for the registration
trial_type	str	Description of the trial (e.g., "7-day Pro")
start_date	datetime	The official commencement date
end_date	datetime	The expiration date of the trial
trial_length_days	int	Duration of the trial period
price_after_trial	float	Predicted monthly cost after expiration
is_cancelled	bool	Current status of the trial subscription

Sources: backend/server.py:164-178, backend_test.py:286-296

System Data Flow

The following diagram illustrates the lifecycle of a trial record from creation to dashboard visualization.

The diagram shows the end-to-end flow of trial data through the system.
Sources: backend/server.py:321-344, frontend/src/App.js:847-862

Backend Implementation

The backend provides a RESTful interface for Trial CRUD operations. All endpoints are protected by JWT authentication, ensuring users only access trials associated with their own accounts.

Key API Endpoints

The system uses an api_router with the /api prefix to manage trial resources.

• POST /api/trials: Creates a new trial record. It automatically injects the current_user.id into the record before saving to MongoDB.
• GET /api/trials: Retrieves a list of all trials owned by the authenticated user.
• PUT /api/trials/{trial_id}: Updates an existing trial, commonly used to toggle the is_cancelled flag.
• DELETE /api/trials/{trial_id}: Removes the trial record from the database.

Sources: backend/server.py:291-325

Implementation Example (Creation)

@api_router.post("/trials", response_model=Trial)
async def create_trial(trial: TrialCreate, current_user: User = Depends(get_current_user)):
    trial_dict = trial.dict()
    trial_dict['user_id'] = current_user.id
    new_trial = Trial(**trial_dict)
    await db.trials.insert_one(new_trial.dict())
    return new_trial

Sources: backend/server.py:291-297

Frontend Interface & Interaction

The frontend uses a grid-based layout to display trials as "Glassmorphic Cards." Each card visually distinguishes between "Active" and "Cancelled" trials through color-coded status badges.

Countdown Logic and UI

While the backend stores the raw dates, the frontend TrialForm component manages the date inputs and converts them to ISO strings for API compatibility.

This sequence shows the interaction between the UI and backend during trial creation.
Sources: frontend/src/App.js:847-865, backend_test.py:300-313

Visual Styling

The visual representation of trials is defined in App.css, utilizing cyberpunk aesthetics such as neon greens for active statuses and hot pink or red for cancelled or urgent deadlines.

.trial-status.active {
  background: rgba(0, 255, 136, 0.2);
  color: var(--neon-green);
  border: 1px solid var(--neon-green);
}

.trial-status.cancelled {
  background: rgba(255, 71, 87, 0.2);
  color: #FF4757;
  border: 1px solid #FF4757;
}

Sources: frontend/src/App.css:577-588

Dashboard Integration

The Trial tracking system contributes to the global "Command Center" dashboard. The get_dashboard_stats endpoint specifically queries the trials collection to provide a count of active trials.

• Logic: The system counts documents where user_id matches the current user and is_cancelled is False.
• Visual: This number is displayed in a stat-card with an animated pulse effect.

Sources: backend/server.py:338-340, frontend/src/App.js:237-243

Summary

The Trial Countdown & Tracking system provides a vital financial oversight tool within NEXUS. By combining a rigid MongoDB schema for date tracking with a responsive React UI, the system ensures users stay informed about upcoming subscription transitions. The integration of JWT security ensures that sensitive trial data, including associated email addresses and partial card information, remains private and isolated per user.