# thedarkking01/subscription-tracker architecture

> Architecture diagram of the GitHub repository thedarkking01/subscription-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thedarkking01/subscription-tracker
- Repository: https://github.com/thedarkking01/subscription-tracker

## Overview

##### Main Components
- API Entry Point: The application starts at app.js, which bootstraps the Express server.
- Configuration: The config directory holds configurations for various services (e.g., Arcjet for rate limiting/security, environment configuration, Nodemailer for email, Upstash for workflow/email reminders).
- Routing Layer: The routes directory defines API endpoints with different files (auth, subscription, user, workflow). These route files map HTTP requests to controller actions.
- Controllers: The controllers directory contains business logic for different functionalities – authentication (auth.controller.js), subscriptions (subscription.controller.js), user management (user.controller.js), and workflow management (workflow.controller.js).
- Middleware: The middlewares directory includes various middleware functions:
- Auth middleware for JWT authentication.
- Arcjet middleware to protect endpoints.
- Error middleware to handle exceptions.
- Database Layer: The database folder holds a module for setting up and managing the MongoDB connection.
- Data Models: The models directory defines Mongoose models (e.g., subscription.model.js and user.model.js) that represent data schemas and business objects.
- Utilities: The utils folder provides helper functions for tasks like sending emails (send-email.js) and building email templates.

##### Relationships and Data Flow
- Clients (e.g., frontend apps or external services) make HTTP requests to the API endpoints.
- Requests are routed via the Express router to the appropriate controllers.
- Controllers execute business logic and interact with the database layer using Mongoose.
- Authentication is enforced via JWTs, with auth middleware intercepting requests.
- Security and Rate Limiting are applied through the Arcjet middleware.
- The email functionalities operate through configurations in Nodemailer and Upstash with workflow controllers triggering email reminders.
- Global error handling is applied through error middleware to manage and log errors.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The clear division between routes, controllers, models, middleware, and utilities enhances modularity and maintainability.
- Middleware Pipeline: Requests pass through a series of middleware allowing for cross-cutting concerns (authentication, error handling, rate limiting) to be managed uniformly.
- Config-Driven: Configuration files for different services allow the application to easily adapt between development and production environments.
- RESTful API Design: The application follows RESTful conventions with distinct routes and controllers handling specific types of interactions.

##### Relevant Technologies and Frameworks
- Node.js and Express.js provide the foundation for the web server and request handling.
- MongoDB (with Mongoose in models) is used for data persistence.
- JWT Authentication integrated via middleware for secure endpoints.
- Third-party integrations for rate limiting (Arcjet) and automated emailing (Nodemailer and Upstash).

##### Detailed Structural Breakdown
- Controllers & Business Logic: For each controller, show connections to both Models and Utilities as needed.
- Middleware Layer: Position middleware nodes (auth, Arcjet, error handling) spanning the request flow from entry to controller processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client (Frontend/External Service)"]:::external

    %% API Entry Point
    API["API Server (app.js)"]:::entry

    %% Configuration Files Subgraph
    subgraph "Configuration Files"
        ARC_CONF["Arcjet Config"]:::config
        ENV_CONF["Environment Config"]:::config
        NODEMAILER_CONF["Nodemailer Config"]:::config
        UPSTASH_CONF["Upstash Config"]:::config
    end

    %% Middleware Components Subgraph
    subgraph "Middleware Components"
        AUTH_MW["Auth Middleware"]:::middleware
        ARC_MW["Arcjet Middleware"]:::middleware
        ERROR_MW["Error Middleware"]:::middleware
    end

    %% API Routes Subgraph
    subgraph "API Routes"
        AUTH_R["Auth Routes"]:::routes
        SUB_R["Subscription Routes"]:::routes
        USER_R["User Routes"]:::routes
        WORKFLOW_R["Workflow Routes"]:::routes
    end

    %% Controller Operations Subgraph
    subgraph "Controller Operations"
        AUTH_CTRL["Auth Controller"]:::controller
        SUB_CTRL["Subscription Controller"]:::controller
        USER_CTRL["User Controller"]:::controller
        WORKFLOW_CTRL["Workflow Controller"]:::controller
    end

    %% Data Models Subgraph
    subgraph "Data Models"
        SUB_MODEL["Subscription Model"]:::model
        USER_MODEL["User Model"]:::model
    end

    %% Utility Functions Subgraph
    subgraph "Utility Functions"
        EMAIL_TEMP["Email Template"]:::utility
        SEND_EMAIL["Send Email"]:::utility
    end

    %% Database Layer
    DATABASE["Database (MongoDB)"]:::databaseGroup

    %% Connections
    Client -->|"HTTP_Request"| API
    API -->|"loads"| ENV_CONF
    API -->|"loads"| ARC_CONF

    %% API initializes middleware chain
    API -->|"invokes"| AUTH_MW
    AUTH_MW -->|"passes_to"| ARC_MW
    ARC_MW -->|"passes_to"| ERROR_MW
    ERROR_MW -->|"routes_to"| AUTH_R
    ERROR_MW -->|"routes_to"| SUB_R
    ERROR_MW -->|"routes_to"| USER_R
    ERROR_MW -->|"routes_to"| WORKFLOW_R

    %% Routes to Controllers
    AUTH_R -->|"calls"| AUTH_CTRL
    SUB_R -->|"calls"| SUB_CTRL
    USER_R -->|"calls"| USER_CTRL
    WORKFLOW_R -->|"calls"| WORKFLOW_CTRL

    %% Controllers interact with Models and Utilities
    AUTH_CTRL -->|"queries"| USER_MODEL
    SUB_CTRL -->|"queries"| SUB_MODEL
    USER_CTRL -->|"queries"| USER_MODEL
    WORKFLOW_CTRL -->|"triggers"| SEND_EMAIL
    WORKFLOW_CTRL -->|"uses"| EMAIL_TEMP

    %% Models persist data via Database
    SUB_MODEL -->|"persists_to"| DATABASE
    USER_MODEL -->|"persists_to"| DATABASE

    %% External Integrations via Configurations
    ARC_CONF -->|"configures"| ARC_MW
    NODEMAILER_CONF -->|"configures"| WORKFLOW_CTRL
    UPSTASH_CONF -->|"configures"| WORKFLOW_CTRL

    %% Click Events
    click API "https://github.com/thedarkking01/subscription-tracker/blob/main/app.js"
    click ARC_CONF "https://github.com/thedarkking01/subscription-tracker/blob/main/config/arcjet.js"
    click ENV_CONF "https://github.com/thedarkking01/subscription-tracker/blob/main/config/env.js"
    click NODEMAILER_CONF "https://github.com/thedarkking01/subscription-tracker/blob/main/config/nodemailer.js"
    click UPSTASH_CONF "https://github.com/thedarkking01/subscription-tracker/blob/main/config/upstash.js"
    click AUTH_R "https://github.com/thedarkking01/subscription-tracker/blob/main/routes/auth.routes.js"
    click SUB_R "https://github.com/thedarkking01/subscription-tracker/blob/main/routes/subscription.routes.js"
    click USER_R "https://github.com/thedarkking01/subscription-tracker/blob/main/routes/user.routes.js"
    click WORKFLOW_R "https://github.com/thedarkking01/subscription-tracker/blob/main/routes/workflow.routes.js"
    click AUTH_CTRL "https://github.com/thedarkking01/subscription-tracker/blob/main/controllers/auth.controller.js"
    click SUB_CTRL "https://github.com/thedarkking01/subscription-tracker/blob/main/controllers/subscription.controller.js"
    click USER_CTRL "https://github.com/thedarkking01/subscription-tracker/blob/main/controllers/user.controller.js"
    click WORKFLOW_CTRL "https://github.com/thedarkking01/subscription-tracker/blob/main/controllers/workflow.controller.js"
    click AUTH_MW "https://github.com/thedarkking01/subscription-tracker/blob/main/middlewares/auth.middleware.js"
    click ARC_MW "https://github.com/thedarkking01/subscription-tracker/blob/main/middlewares/arcjet.middleware.js"
    click ERROR_MW "https://github.com/thedarkking01/subscription-tracker/blob/main/middlewares/error.middleware.js"
    click DATABASE "https://github.com/thedarkking01/subscription-tracker/blob/main/database/mongodb.js"
    click SUB_MODEL "https://github.com/thedarkking01/subscription-tracker/blob/main/models/subscription.model.js"
    click USER_MODEL "https://github.com/thedarkking01/subscription-tracker/blob/main/models/user.model.js"
    click EMAIL_TEMP "https://github.com/thedarkking01/subscription-tracker/blob/main/utils/email-template.js"
    click SEND_EMAIL "https://github.com/thedarkking01/subscription-tracker/blob/main/utils/send-email.js"

    %% Styles
    classDef external fill:#F9E79F,stroke:#000,stroke-width:2px;
    classDef entry fill:#AED6F1,stroke:#000,stroke-width:2px;
    classDef config fill:#A9DFBF,stroke:#000,stroke-width:2px;
    classDef middleware fill:#F5B7B1,stroke:#000,stroke-width:2px;
    classDef routes fill:#D2B4DE,stroke:#000,stroke-width:2px;
    classDef controller fill:#F7DC6F,stroke:#000,stroke-width:2px;
    classDef model fill:#DCEEFC,stroke:#000,stroke-width:2px;
    classDef databaseGroup fill:#FADBD8,stroke:#000,stroke-width:2px;
    classDef utility fill:#C0E1FF,stroke:#000,stroke-width:2px;
```
