High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
NEXUS is a full-stack digital account and trial tracking system built with a decoupled architecture consisting of a Python-based FastAPI backend and a React-based frontend. The system is designed to manage digital subscriptions, email identities, and free trial lifecycles through a centralized command center. It features a "cyberpunk-meets-luxury" aesthetic utilizing glassmorphism, particle animations, and high-contrast visual elements.
The architecture emphasizes secure data management through JWT-based authentication and a document-oriented storage approach using MongoDB. The backend provides a RESTful API that handles business logic for account CRUD, trial countdowns, and dashboard statistics, while the frontend manages user state, visual effects, and interactive management interfaces.
Sources: test_result.md:59-63, backend/server.py:20-23, frontend/src/App.js:1-12
System Component Overview
The NEXUS ecosystem is divided into three primary layers: the User Interface (Frontend), the Application Programming Interface (Backend), and the Persistence Layer (Database).
This diagram illustrates the flow of data from the React frontend through the FastAPI backend to the MongoDB database.
Sources: backend/server.py:16-30, frontend/src/App.js:10-50
Backend Architecture
The backend is built using FastAPI and utilizes asynchronous drivers for database communication. It follows a modular structure where routes are organized under a global /api prefix.
Data Modeling and Enums
The system uses Pydantic models to enforce strict schema validation and Enums for standardized status tracking.
| Category | Model Class | Key Fields |
|---|---|---|
| Authentication | User | username, email, hashed_password |
| Account | Account | platform_name, subscription_type, monthly_cost |
Email | email_address, provider, purpose | |
| Trial | Trial | start_date, end_date, is_cancelled |
Sources: backend/server.py:33-146
Authentication System
NEXUS implements a Bearer Token authentication scheme using JSON Web Tokens (JWT) and password hashing via bcrypt.
The sequence diagram describes the registration and login flows, highlighting the use of bcrypt for credential validation.
Sources: backend/server.py:157-190, backend_test.py:75-100
Frontend Architecture
The frontend is a Single Page Application (SPA) built with React 19, utilizing react-router-dom for navigation and axios for API interaction.
State Management and Context
NEXUS uses the React Context API to manage global authentication state via the AuthProvider. This provider handles token persistence in localStorage and automatically attaches authorization headers to outgoing requests.
Sources: frontend/src/App.js:13-75, frontend/package.json:52-60
Visual Identity System
The UI architecture relies on a custom CSS framework defined in App.css, which uses CSS variables for theme management and Tailwind CSS for utility-first styling.
| Feature | Implementation | Source |
|---|---|---|
| Glassmorphism | backdrop-filter: blur(20px) and semi-transparent borders | App.css:127-142 |
| Background | Canvas-based dynamic particle animation | App.js:88-140 |
| Typography | Orbitron (Titles), Inter (Body), JetBrains Mono (Stats) | App.css:2-20 |
| Animations | Keyframe-based pulse and breathe effects | App.css:835-845 |
Sources: frontend/src/App.css:1-50, frontend/src/App.js:88-142
API Integration and Data Flow
The frontend interacts with the backend through several functional modules, each corresponding to a specific business domain.
This diagram maps the frontend management interfaces to their respective RESTful API endpoint groups.
Sources: backend/server.py:171-330, frontend/src/App.js:210-650
Dashboard Logic
The Dashboard (Command Center) aggregates data across all collections to provide high-level metrics.
- Total Accounts: Count of documents in the
accountscollection. - Monthly Spend: Summation of
monthly_costfields across active accounts. - Security Score: A placeholder calculation (currently set at 75.0) intended to evaluate 2FA adoption and password health.
Sources: backend/server.py:333-355, frontend/src/App.js:275-310
Deployment and Configuration
The system utilizes environment variables for critical configuration, managed via .env files and process.env in the frontend.
| Variable | Description | Target |
|---|---|---|
MONGO_URL | Connection string for MongoDB instance | Backend |
DB_NAME | Name of the primary database | Backend |
JWT_SECRET_KEY | Secret used for signing access tokens | Backend |
REACT_APP_BACKEND_URL | Base URL for the API server | Frontend |
Sources: backend/server.py:16-19, frontend/src/App.js:6-7
Conclusion
The NEXUS architecture provides a robust foundation for digital identity management by separating the aesthetic-heavy frontend from a data-consistent backend. The use of FastAPI and MongoDB allows for high-performance asynchronous operations, while the React-based frontend provides a modern, immersive user experience through sophisticated CSS effects and canvas animations. The system ensures user isolation by scoping all CRUD operations to the authenticated user_id extracted from JWT payloads.
Sources: test_result.md:59-65, backend/server.py:151-155, frontend/src/App.js:725-750