Trial Tracking API Endpoints

Relevant source files

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

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

The Trial Tracking API is a core module of the NEXUS system designed to manage the lifecycle of digital service trials. It allows users to log subscription trials, monitor their duration, track associated payment methods, and manage cancellation statuses to prevent unwanted charges. This system integrates with the broader Account Management and Email Management systems by linking trials to specific platforms and email addresses used for registration.

The module provides full CRUD (Create, Read, Update, Delete) functionality through a secured RESTful interface. Every request requires JWT-based authentication to ensure data isolation between users. The backend utilizes FastAPI and Motor (Async MongoDB driver) to handle trial data persists, while the frontend provides a glassmorphic interface for user interaction.

Sources: backend/server.py:21-25, backend/server.py:160-162, test_result.md:120-131

Data Models and Architecture

The Trial Tracking system relies on structured Pydantic models for data validation and MongoDB for persistence. The architecture follows a multi-tenant approach where each trial record is strictly bound to a user_id.

Trial Data Structures

The system distinguishes between the database representation (Trial) and the input schema for creating/updating records (TrialCreate).

Field	Type	Description
id	str	Unique UUID for the trial record.
user_id	str	Owner of the record (extracted from JWT).
platform	str	The name or ID of the service platform.
email_used	str	The email address used for the trial.
trial_type	str	Type description (e.g., "Free Trial", "Premium").
start_date	datetime	Commencement date of the trial.
end_date	datetime	Expiration date of the trial.
price_after_trial	float	Projected cost if the trial converts to a subscription.
is_cancelled	bool	Current status of the trial cancellation.

Sources: backend/server.py:160-189, frontend/src/App.js:779-790

Entity Relationships

This diagram illustrates how the Trial entity relates to Users and other system components like Accounts and Emails.

The Trial entity maintains loose coupling with Accounts and Emails through string identifiers (email_used and platform), allowing flexibility in how users track their digital footprint.

Sources: backend/server.py:160-174, backend_test.py:265-274

API Endpoint Specification

All Trial Tracking endpoints are prefixed with /api and require a valid Bearer Token in the Authorization header.

Endpoints Overview

Method	Endpoint	Description
POST	/api/trials	Create a new trial record.
GET	/api/trials	Retrieve all trials for the authenticated user.
GET	/api/trials/{trial_id}	Retrieve details of a specific trial.
PUT	/api/trials/{trial_id}	Update an existing trial (e.g., mark as cancelled).
DELETE	/api/trials/{trial_id}	Remove a trial record from the system.

Sources: backend/server.py:317-360, backend_test.py:277-360

Logic Flow: Creating a Trial

When a user submits a trial via the frontend, the system validates the dates and associates the entry with the user's unique ID retrieved from the session token.

Integration with Dashboard Statistics

Trial data is a primary input for the system's global statistics calculation. The /api/dashboard/stats endpoint performs real-time aggregation of trial records to provide the user with their current "Active Trials" count.

• Active Trial Logic: A trial is considered active if the is_cancelled flag is false.
• Security Context: Trial metrics contribute to the overall Security Score by highlighting potentially forgotten subscriptions that could lead to unauthorized charges.

# Backend logic for aggregating active trials
active_trials = await db.trials.count_documents({
    "user_id": current_user.id, 
    "is_cancelled": False
})

Sources: backend/server.py:372-386, frontend/src/App.js:237-248

Frontend Implementation

The frontend utilizes a React-based component architecture to interact with the Trial API. The Trials component manages the state for trial lists and form toggles, while TrialForm handles the data submission.

Key Components

• Trials Component: Handles the GET request to /api/trials and renders the glassmorphic cards for each trial.
• TrialForm Component: Captures user input for platform, dates, and price. It converts local date strings into ISO format before sending POST or PUT requests to the backend.

// Example data transformation in TrialForm
const handleSubmit = async (e) => {
  e.preventDefault();
  const submitData = {
    ...formData,
    start_date: new Date(formData.start_date).toISOString(),
    end_date: new Date(formData.end_date).toISOString()
  };
  await axios.post(`${API}/trials`, submitData);
};

Sources: frontend/src/App.js:736-745, frontend/src/App.js:806-818

Conclusion

The Trial Tracking API Endpoints provide a robust foundation for managing digital trials within NEXUS. By enforcing user isolation through JWT and providing a comprehensive set of CRUD operations, the system ensures that users can accurately track their commitments. The integration between the FastAPI backend and the React frontend enables a seamless flow of data, from initial creation to dashboard-level insights.

Sources: test_result.md:131-133, backend/server.py:390-395