Dashboard Statistics API Endpoint

Relevant source files

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

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

The Dashboard Statistics API Endpoint is a critical backend component of the NEXUS system designed to provide a high-level overview of a user's digital footprint. It aggregates data from various modules—Accounts, Emails, and Trials—to compute real-time metrics including total account counts, financial commitments, active trial tracking, and a calculated security posture.

This endpoint serves as the primary data source for the "Command Center" in the frontend, enabling the display of animated stat cards that give users immediate insight into their managed assets. Access to this data is strictly protected, requiring valid JWT authentication to ensure that users only view statistics derived from their own isolated data.
Sources: backend/server.py:382-409, frontend/src/App.js:213-248

API Definition and Authentication

The endpoint is defined as a GET request to the /api/dashboard/stats path. It utilizes FastAPI's dependency injection system to enforce security, requiring a valid JWT token that maps to an existing user in the database.

Endpoint Specification

Detail	Value
Method	GET
Path	/api/dashboard/stats
Authentication	Bearer Token (JWT)
Response Model	DashboardStats
Access Control	User-isolated data only

Sources: backend/server.py:382-384, backend_test.py:284-287

Security Verification Flow

Before any data aggregation occurs, the system verifies the requester's identity. The following diagram illustrates the sequence from the initial frontend request to the backend validation.

Data Aggregation Logic

The backend performs four distinct aggregation tasks within the get_dashboard_stats function to populate the DashboardStats pydantic model.

1. Total Accounts

The system counts all documents in the accounts collection where the user_id matches the current authenticated user.
Sources: backend/server.py:385-386

2. Monthly Spend Calculation

The endpoint retrieves all account objects for the user and iterates through them to sum the monthly_cost field. The logic includes a safety check to handle None or missing values by defaulting them to 0.
Sources: backend/server.py:388-390

3. Active Trials

The system filters the trials collection for documents belonging to the user where the is_cancelled flag is set to False.
Sources: backend/server.py:392-393

4. Security Score

Currently, the system returns a fixed placeholder value of 75.0. The implementation notes indicate this is intended to be replaced with logic calculating scores based on 2FA status and password strength in future iterations.
Sources: backend/server.py:395-396

Data Models

The interaction between the backend and frontend is governed by specific data structures defined in the source code.

DashboardStats Schema (Backend)

Used by FastAPI for response serialization and validation.
Sources: backend/server.py:155-159

Field	Type	Description
total_accounts	int	Count of accounts registered to the user
monthly_spend	float	Cumulative sum of monthly_cost across all accounts
active_trials	int	Count of trials where is_cancelled is false
security_score	float	Percentage representing overall security health

Frontend State Structure

The React frontend initializes a local state to match the expected API response structure.
Sources: frontend/src/App.js:214-219

const [stats, setStats] = useState({
    total_accounts: 0,
    monthly_spend: 0,
    active_trials: 0,
    security_score: 0
});

Frontend Integration and Visualization

The frontend consumes this API within the Dashboard component using the fetchStats function, which is triggered upon component mounting via the useEffect hook.

Visualization Components

Data is rendered into a "stats-grid" using glassmorphic cards. The CSS utilizes custom properties like --electric-blue and --glass-bg to maintain the cyberpunk aesthetic.
Sources: frontend/src/App.js:231-274, frontend/src/App.css:394-415

UI Display Logic

• Monthly Spend: Formatted using .toFixed(2) to display as currency (e.g., $19.99).
• Security Score: Appended with a % symbol.
• Animations: The animated-number class is applied to values for visual transitions.
  Sources: frontend/src/App.js:255-274, frontend/src/App.css:561-563

Testing and Verification

The endpoint's reliability is verified through a dedicated test suite in backend_test.py.

Test Scenario: test_dashboard_stats

The test suite performs a request with a valid JWT and validates the presence of all required fields in the JSON response.
Sources: backend_test.py:284-301

Observed Test Results:
Manual and automated tests confirm the endpoint returns correct data types:

• total_accounts: 0 (Initial state)
• monthly_spend: 0.0
• active_trials: 0
• security_score: 75.0
  Sources: test_result.md:95-101

Conclusion

The Dashboard Statistics API Endpoint serves as the central intelligence hub for the NEXUS interface. By efficiently aggregating user data across multiple MongoDB collections and enforcing strict JWT-based isolation, it provides the necessary metrics to power the application's Command Center while maintaining security and performance.
Sources: backend/server.py:382-409, test_result.md:210-216