Skip to content

Getting Started

Relevant source files - .env.example - README.md - config/env.js - package.json

This page provides a comprehensive technical guide for setting up the Subscription Tracker API locally. It covers prerequisites, installation, environment configuration, and execution modes.

Prerequisites

Before setting up the project, ensure the following environment requirements are met:

  • Node.js: Version 18.0.0 or higher is required as indicated in the engine specifications README.md3
  • MongoDB: A running instance (local or MongoDB Atlas) is required for data persistence README.md70
  • Package Manager: npm is used for dependency management package.json1-37

  • Third-Party Accounts:

  • Upstash: For QStash and Workflow management config/env.js13-16

  • Arcjet: For security and rate limiting config/env.js11-12
  • Brevo (formerly Sendinblue): For SMTP email delivery config/env.js20-21

Sources:

Installation

The project uses the ESM (ECMAScript Modules) system as defined by "type": "module" in the package configuration package.json5

  1. Clone the repository:
git clone https://github.com/HetulMistry/subscription-tracker.git
cd subscription-tracker
  1. Install dependencies: The project relies on express for the server framework, mongoose for ODM, and specialized libraries like @arcjet/node and @upstash/workflowpackage.json10-28
npm install

Sources:

Environment Configuration

The application uses a dynamic environment loading strategy. The configuration utility in config/env.js loads .env files based on the NODE_ENV variable config/env.js3

Configuration Mapping

Variable Description Source
PORT The port the Express server listens on (default: 5500) .env.example1
DB_URI MongoDB connection string .env.example3
JWT_SECRET Secret key for signing JSON Web Tokens .env.example4
ARCJET_KEY API key for Arcjet security services .env.example6
QSTASH_TOKEN Authentication token for Upstash QStash .env.example9
BREVO_SMTP_KEY SMTP key for email notifications .env.example15

Setup Steps

  1. Create a local environment file based on the environment you wish to run (e.g., .env.development.local) config/env.js3
  2. Populate the file with the required keys as shown in .env.example.env.example1-16

Sources:

Running the Application

The project defines two primary execution scripts in package.jsonpackage.json6-9

Development Mode

Uses nodemon to automatically restart the server on file changes package.json8

npm run dev

Production Mode

Runs the application using the standard Node.js runtime package.json7

npm run start

Application Initialization Flow

The following diagram illustrates the startup sequence from the entry point app.js through the configuration and database layers.

Startup Sequence Diagram

sequenceDiagram
    participant User
    participant App as "app.js"
    participant Env as "config/env.js"
    participant DB as "database/mongodb.js"
    participant Express as "Express Framework"
    User->>App: npm run dev
    App->>Env: Import Config
    Note over Env: Loads .env.[NODE_ENV].local
    App->>DB: connectToDatabase()
    DB->>DB: mongoose.connect(DB_URI)
    App->>Express: app.listen(PORT)
    Express-->>User: Server Running

Sources:

Quick Start: API Interaction

Once the server is running (defaulting to http://localhost:3000 or the PORT defined in your env), you can interact with the API using curlREADME.md17-28

1. Register a User

This creates a new user entity in the MongoDB collection managed by models/user.model.js.

curl -X POST http://localhost:3000/api/v1/auth/sign-up \
     -H "Content-Type: application/json" \
     -d '{"name":"Dev User","email":"dev@example.com","password":"password123"}'

2. Authenticate

The auth.controller.js will return a JWT if credentials match.

curl -X POST http://localhost:3000/api/v1/auth/sign-in \
     -H "Content-Type: application/json" \
     -d '{"email":"dev@example.com","password":"password123"}'

3. Access Protected Resource

Use the token received from the sign-in step in the Authorization header. This is validated by the authorize middleware in middlewares/auth.middleware.js.

curl -H "Authorization: Bearer <your_token>" \
     http://localhost:3000/api/v1/users/

Data Flow: Request to Controller

The diagram below shows how a request for a protected resource (like getting users) moves through the system.

Request Processing Diagram

[Flowchart Diagram]

Sources: