# radebeneo/subscription-tracker architecture

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

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

## Overview

Subscription Tracker is an Express API for account identity and recurring-subscription management. Users sign up or sign in, or authenticate through Clerk; authenticated requests reach profile or subscription endpoints, where subscriptions are stored and creation schedules an Upstash reminder workflow. That workflow checks renewal status and sends reminder email at 7, 5, 2, and 1 days before renewal. The graph also preserves the documented security and persistence layers. Some subsystem links rely on README or SOURCE INDEX references because their implementation excerpts were not provided.

Main entry points: [`app.js`](https://github.com/radebeneo/subscription-tracker/blob/main/app.js) (Express application), [`routes/subscription.routes.js`](https://github.com/radebeneo/subscription-tracker/blob/main/routes/subscription.routes.js) (Subscription routes), [`models/user.model.js`](https://github.com/radebeneo/subscription-tracker/blob/main/models/user.model.js) (User model), [`controllers/subscription.controller.js`](https://github.com/radebeneo/subscription-tracker/blob/main/controllers/subscription.controller.js) (Subscription handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["Express application<br/>[app.js]"]
  node_authroutes["Auth routes<br/>[auth.routes.js]"]
  node_authcontroller["Signup and login<br/>[auth.controller.js]"]
  node_userroutes["User routes<br/>[user.routes.js]"]
  node_usercontroller["User profile<br/>[user.controller.js]"]
  node_jwtmiddleware["JWT authorization<br/>[auth.middleware.js]"]
end

subgraph group_identity["Identity"]
  node_identityroutes["Identity routes<br/>[identity.routes.js]"]
  node_clerkmiddleware["Clerk authorization"]
  node_clerkverifier["Clerk token verifier<br/>[clerk-verifier.js]"]
  node_identitycontroller["Identity handlers"]
  node_identityservice["Identity resolution"]
  node_clerkprofile["Clerk profile lookup<br/>[clerk-profile.js]"]
end

subgraph group_subscriptions["Subscriptions"]
  node_subscriptionroutes["Subscription routes"]
  node_subscriptioncontroller["Subscription handlers"]
  node_ownedservice["Owned subscriptions"]
end

subgraph group_reminders["Reminder delivery"]
  node_workflowroutes["Workflow route<br/>[workflow.routes.js]"]
  node_workflowcontroller["Reminder workflow"]
  node_email["Email delivery<br/>[send-email.js]"]
  node_emailtemplate["Reminder template<br/>[email-template.js]"]
  node_upstash["Upstash workflow service<br/>[upstash.js]"]
  node_mailerconfig["Mailer configuration<br/>[nodemailer.js]"]
end

subgraph group_platform["Persistence and security"]
  node_userstore[("User model<br/>[user.model.js]")]
  node_subscriptionstore[("Subscription model")]
  node_mongodb[("MongoDB connection<br/>[mongodb.js]")]
  node_arcjet["Arcjet protection"]
  node_arcjetconfig["Arcjet configuration<br/>[arcjet.js]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts auth"| node_authroutes
node_app -->|"mounts identity"| node_identityroutes
node_app -->|"mounts users"| node_userroutes
node_app -->|"mounts subscriptions"| node_subscriptionroutes
node_app -->|"mounts workflows"| node_workflowroutes
node_app -->|"connects database"| node_mongodb
node_app -->|"uses protection"| node_arcjet
node_authroutes -->|"dispatches"| node_authcontroller
node_authcontroller -->|"reads and creates"| node_userstore
node_client -->|"requests identity"| node_identityroutes
node_identityroutes -->|"authorizes"| node_clerkmiddleware
node_clerkmiddleware -->|"verifies token"| node_clerkverifier
node_identityroutes -->|"dispatches"| node_identitycontroller
node_identitycontroller -->|"resolves identity"| node_identityservice
node_identityservice -->|"finds or creates"| node_userstore
node_identityservice -->|"looks up profile"| node_clerkprofile
node_client -->|"requests profile"| node_userroutes
node_userroutes -->|"authorizes"| node_jwtmiddleware
node_userroutes -->|"dispatches"| node_usercontroller
node_jwtmiddleware -->|"loads user"| node_userstore
node_usercontroller -->|"reads profile"| node_userstore
node_client -->|"manages subscriptions"| node_subscriptionroutes
node_subscriptionroutes -->|"authorizes create"| node_jwtmiddleware
node_subscriptionroutes -->|"authorizes listing"| node_clerkmiddleware
node_subscriptionroutes -->|"dispatches"| node_subscriptioncontroller
node_subscriptioncontroller -->|"creates subscription"| node_subscriptionstore
node_subscriptioncontroller -->|"triggers workflow"| node_upstash
node_subscriptioncontroller -->|"lists owned items"| node_ownedservice
node_ownedservice -->|"queries subscriptions"| node_subscriptionstore
node_ownedservice -->|"checks ownership"| node_userstore
node_client -->|"workflow callback"| node_workflowroutes
node_workflowroutes -->|"dispatches"| node_workflowcontroller
node_workflowcontroller -->|"loads subscription"| node_subscriptionstore
node_workflowcontroller -->|"sends reminders"| node_email
node_email -->|"renders message"| node_emailtemplate
node_email -->|"uses transport"| node_mailerconfig
node_arcjet -->|"uses configuration"| node_arcjetconfig

click node_app "https://github.com/radebeneo/subscription-tracker/blob/main/app.js"
click node_authroutes "https://github.com/radebeneo/subscription-tracker/blob/main/routes/auth.routes.js"
click node_authcontroller "https://github.com/radebeneo/subscription-tracker/blob/main/controllers/auth.controller.js"
click node_userroutes "https://github.com/radebeneo/subscription-tracker/blob/main/routes/user.routes.js"
click node_usercontroller "https://github.com/radebeneo/subscription-tracker/blob/main/controllers/user.controller.js"
click node_jwtmiddleware "https://github.com/radebeneo/subscription-tracker/blob/main/middlewares/auth.middleware.js"
click node_identityroutes "https://github.com/radebeneo/subscription-tracker/blob/main/routes/identity.routes.js"
click node_clerkmiddleware "https://github.com/radebeneo/subscription-tracker/blob/main/middlewares/clerk-auth.middleware.js"
click node_clerkverifier "https://github.com/radebeneo/subscription-tracker/blob/main/services/clerk-verifier.js"
click node_identitycontroller "https://github.com/radebeneo/subscription-tracker/blob/main/controllers/identity.controller.js"
click node_identityservice "https://github.com/radebeneo/subscription-tracker/blob/main/services/identity-service.js"
click node_clerkprofile "https://github.com/radebeneo/subscription-tracker/blob/main/services/clerk-profile.js"
click node_subscriptionroutes "https://github.com/radebeneo/subscription-tracker/blob/main/routes/subscription.routes.js"
click node_subscriptioncontroller "https://github.com/radebeneo/subscription-tracker/blob/main/controllers/subscription.controller.js"
click node_ownedservice "https://github.com/radebeneo/subscription-tracker/blob/main/services/owned-subscription-service.js"
click node_workflowroutes "https://github.com/radebeneo/subscription-tracker/blob/main/routes/workflow.routes.js"
click node_workflowcontroller "https://github.com/radebeneo/subscription-tracker/blob/main/controllers/workflow.controller.js"
click node_email "https://github.com/radebeneo/subscription-tracker/blob/main/utils/send-email.js"
click node_emailtemplate "https://github.com/radebeneo/subscription-tracker/blob/main/utils/email-template.js"
click node_userstore "https://github.com/radebeneo/subscription-tracker/blob/main/models/user.model.js"
click node_subscriptionstore "https://github.com/radebeneo/subscription-tracker/blob/main/models/subscription.model.js"
click node_mongodb "https://github.com/radebeneo/subscription-tracker/blob/main/database/mongodb.js"
click node_arcjet "https://github.com/radebeneo/subscription-tracker/blob/main/middlewares/arcjet.middleware.js"
click node_arcjetconfig "https://github.com/radebeneo/subscription-tracker/blob/main/config/arcjet.js"
click node_upstash "https://github.com/radebeneo/subscription-tracker/blob/main/config/upstash.js"
click node_mailerconfig "https://github.com/radebeneo/subscription-tracker/blob/main/config/nodemailer.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_authroutes,node_authcontroller,node_userroutes,node_usercontroller,node_jwtmiddleware,node_client toneBlue
class node_identityroutes,node_clerkmiddleware,node_clerkverifier,node_identitycontroller,node_identityservice,node_clerkprofile toneAmber
class node_subscriptionroutes,node_subscriptioncontroller,node_ownedservice toneMint
class node_workflowroutes,node_workflowcontroller,node_email,node_emailtemplate,node_upstash,node_mailerconfig toneRose
class node_userstore,node_subscriptionstore,node_mongodb,node_arcjet,node_arcjetconfig toneIndigo
```

## Components

### API and access

- [Express application](https://github.com/radebeneo/subscription-tracker/blob/main/app.js): `app.js`
- [Auth routes](https://github.com/radebeneo/subscription-tracker/blob/main/routes/auth.routes.js): `routes/auth.routes.js`
- [Signup and login](https://github.com/radebeneo/subscription-tracker/blob/main/controllers/auth.controller.js): `controllers/auth.controller.js`
- [User routes](https://github.com/radebeneo/subscription-tracker/blob/main/routes/user.routes.js): `routes/user.routes.js`
- [User profile](https://github.com/radebeneo/subscription-tracker/blob/main/controllers/user.controller.js): `controllers/user.controller.js`
- [JWT authorization](https://github.com/radebeneo/subscription-tracker/blob/main/middlewares/auth.middleware.js): `middlewares/auth.middleware.js`

### Identity

- [Identity routes](https://github.com/radebeneo/subscription-tracker/blob/main/routes/identity.routes.js): `routes/identity.routes.js`
- [Clerk authorization](https://github.com/radebeneo/subscription-tracker/blob/main/middlewares/clerk-auth.middleware.js): `middlewares/clerk-auth.middleware.js`
- [Clerk token verifier](https://github.com/radebeneo/subscription-tracker/blob/main/services/clerk-verifier.js): `services/clerk-verifier.js`
- [Identity handlers](https://github.com/radebeneo/subscription-tracker/blob/main/controllers/identity.controller.js): `controllers/identity.controller.js`
- [Identity resolution](https://github.com/radebeneo/subscription-tracker/blob/main/services/identity-service.js): `services/identity-service.js`
- [Clerk profile lookup](https://github.com/radebeneo/subscription-tracker/blob/main/services/clerk-profile.js): `services/clerk-profile.js`

### Subscriptions

- [Subscription routes](https://github.com/radebeneo/subscription-tracker/blob/main/routes/subscription.routes.js): `routes/subscription.routes.js`
- [Subscription handlers](https://github.com/radebeneo/subscription-tracker/blob/main/controllers/subscription.controller.js): `controllers/subscription.controller.js`
- [Owned subscriptions](https://github.com/radebeneo/subscription-tracker/blob/main/services/owned-subscription-service.js): `services/owned-subscription-service.js`

### Reminder delivery

- [Workflow route](https://github.com/radebeneo/subscription-tracker/blob/main/routes/workflow.routes.js): `routes/workflow.routes.js`
- [Reminder workflow](https://github.com/radebeneo/subscription-tracker/blob/main/controllers/workflow.controller.js): `controllers/workflow.controller.js`
- [Email delivery](https://github.com/radebeneo/subscription-tracker/blob/main/utils/send-email.js): `utils/send-email.js`
- [Reminder template](https://github.com/radebeneo/subscription-tracker/blob/main/utils/email-template.js): `utils/email-template.js`
- [Upstash workflow service](https://github.com/radebeneo/subscription-tracker/blob/main/config/upstash.js): `config/upstash.js`
- [Mailer configuration](https://github.com/radebeneo/subscription-tracker/blob/main/config/nodemailer.js): `config/nodemailer.js`

### Persistence and security

- [User model](https://github.com/radebeneo/subscription-tracker/blob/main/models/user.model.js): `models/user.model.js`
- [Subscription model](https://github.com/radebeneo/subscription-tracker/blob/main/models/subscription.model.js): `models/subscription.model.js`
- [MongoDB connection](https://github.com/radebeneo/subscription-tracker/blob/main/database/mongodb.js): `database/mongodb.js`
- [Arcjet protection](https://github.com/radebeneo/subscription-tracker/blob/main/middlewares/arcjet.middleware.js): `middlewares/arcjet.middleware.js`
- [Arcjet configuration](https://github.com/radebeneo/subscription-tracker/blob/main/config/arcjet.js): `config/arcjet.js`

### Other components

- **API client**

## Connections

- API client → Express application: sends requests (evidence: `README.md`)
- Express application → Auth routes: mounts auth (evidence: `app.js`)
- Express application → Identity routes: mounts identity (evidence: `app.js`)
- Express application → User routes: mounts users (evidence: `app.js`)
- Express application → Subscription routes: mounts subscriptions (evidence: `app.js`)
- Express application → Workflow route: mounts workflows (evidence: `app.js`)
- Express application → MongoDB connection: connects database (evidence: `app.js`)
- Express application → Arcjet protection: uses protection (evidence: `app.js`)
- Auth routes → Signup and login: dispatches (evidence: `routes/auth.routes.js`)
- Signup and login → User model: reads and creates (evidence: `controllers/auth.controller.js`)
- API client → Identity routes: requests identity (evidence: `README.md`)
- Identity routes → Clerk authorization: authorizes (evidence: `routes/identity.routes.js`)
- Clerk authorization → Clerk token verifier: verifies token (evidence: `middlewares/clerk-auth.middleware.js`)
- Identity routes → Identity handlers: dispatches (evidence: `routes/identity.routes.js`)
- Identity handlers → Identity resolution: resolves identity (evidence: `controllers/identity.controller.js`)
- Identity resolution → User model: finds or creates (evidence: `services/identity-service.js`)
- Identity resolution → Clerk profile lookup: looks up profile (evidence: `services/identity-service.js`)
- API client → User routes: requests profile (evidence: `README.md`)
- User routes → JWT authorization: authorizes (evidence: `routes/user.routes.js`)
- User routes → User profile: dispatches (evidence: `routes/user.routes.js`)
- JWT authorization → User model: loads user (evidence: `middlewares/auth.middleware.js`)
- User profile → User model: reads profile (evidence: `controllers/user.controller.js`)
- API client → Subscription routes: manages subscriptions (evidence: `README.md`)
- Subscription routes → JWT authorization: authorizes create (evidence: `routes/subscription.routes.js`)
- Subscription routes → Clerk authorization: authorizes listing (evidence: `routes/subscription.routes.js`)
- Subscription routes → Subscription handlers: dispatches (evidence: `routes/subscription.routes.js`)
- Subscription handlers → Subscription model: creates subscription (evidence: `controllers/subscription.controller.js`)
- Subscription handlers → Upstash workflow service: triggers workflow (evidence: `controllers/subscription.controller.js`)
- Subscription handlers → Owned subscriptions: lists owned items (evidence: `controllers/subscription.controller.js`)
- Owned subscriptions → Subscription model: queries subscriptions (evidence: `services/owned-subscription-service.js`)
- Owned subscriptions → User model: checks ownership (evidence: `services/owned-subscription-service.js`)
- API client → Workflow route: workflow callback (evidence: `README.md`)
- Workflow route → Reminder workflow: dispatches (evidence: `routes/workflow.routes.js`)
- Reminder workflow → Subscription model: loads subscription (evidence: `controllers/workflow.controller.js`)
- Reminder workflow → Email delivery: sends reminders (evidence: `controllers/workflow.controller.js`)
- Email delivery → Reminder template: renders message (evidence: `utils/send-email.js`)
- Email delivery → Mailer configuration: uses transport (evidence: `utils/send-email.js`)
- Arcjet protection → Arcjet configuration: uses configuration (evidence: `middlewares/arcjet.middleware.js`)