Skip to content

Project Structure

Relevant source files - app.js - database/mongodb.js - eslint.config.js - package.json

This page details the directory layout and architectural organization of the Subscription Tracker API. The project follows a modular, layered architecture built on the Express.js framework using the ESM (ECMAScript Modules) system.

Architectural Overview

The codebase is organized into functional directories that separate concerns between configuration, business logic, data persistence, and middleware processing.

Directory Layout

Directory Purpose
config/ Centralized configuration for environment variables and third-party services (Arcjet, Upstash, Nodemailer, Swagger).
controllers/ Request handlers that contain business logic and interact with models.
database/ Database connection logic and configuration (MongoDB/Mongoose).
middlewares/ Custom Express middleware for security, authentication, and global error handling.
models/ Mongoose schemas and data validation logic.
routes/ API route definitions and versioning, mapping endpoints to controllers.
utils/ Shared utility functions, helper classes, and email templates.
public/ Static assets, including custom CSS/JS for Swagger and the browser-based test client.

Sources:

Module System and Entry Point

The project uses the modern ESM (ECMAScript Modules) system, as specified by "type": "module" in package.jsonpackage.json5 This allows for the use of import and export statements instead of CommonJS require.

Entry Point: app.js

The app.js file serves as the primary entry point and assembly layer for the application. Its responsibilities include:

  1. Server Initialization: Instantiates the Express application and sets up the port listener app.js16app.js53-59
  2. Global Middlewares: Configures standard middlewares like cors, json parsing, cookie-parser, and static file serving app.js20-24
  3. Security Integration: Mounts the arcjetMiddleware globally to protect all incoming requests app.js25
  4. Routing: Mounts domain-specific routers (Auth, Users, Subscriptions, Workflows) under the /api/v1 namespace app.js27-31
  5. Documentation: Serves the Swagger UI at /api-docs/v1/app.js32-40
  6. Database Connection: Triggers the MongoDB connection via connectDb() when the server starts app.js58

Sources:

Data Flow and Component Interaction

The following diagram illustrates how a request flows through the project structure, from the entry point to the data layer.

Request Pipeline Flow

[Flowchart Diagram]

Sources:

Folder Details

config/

Contains service-specific configurations. By centralizing these, the application ensures that environment variables are validated and shared consistently across modules. Key files include env.js for environment validation and arcjet.js for security rules.

routes/ and controllers/

The application implements a strict separation between routing and logic.

  • Routes: Define the HTTP methods and paths. They apply specific middleware (like authorize) before passing the request to a controller.
  • Controllers: Contain the actual logic for processing the request, interacting with the database, and returning responses.

database/

Encapsulates the connection logic. The mongodb.js file uses mongoose.connect() to establish a connection to the URI provided in the environment variables database/mongodb.js8-16 It also handles connection errors by terminating the process to prevent the app from running in an unstable state database/mongodb.js14

public/

Used for serving static files. This includes test.html, which provides a UI for interacting with the API, and custom styling for the Swagger documentation app.js24app.js36-37

Component Mapping

The following diagram bridges the conceptual folders to specific code entities within the project.

[Flowchart Diagram]

Sources: