# bscott/subtrackr architecture

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

- Interactive diagram: https://gitdiagram.com/bscott/subtrackr
- Repository: https://github.com/bscott/subtrackr

## Overview

SubTrackr is a self-hosted subscription tracker. Its main workflow is managing subscriptions, then viewing spending and renewal dates and receiving reminders; additional branches cover authentication, settings, integrations and MCP access. The README documents several capabilities whose internal wiring was not sampled, so those links are attributed to the README rather than presented as inspected call paths.

Main entry points: [`cmd/server/main.go`](https://github.com/bscott/subtrackr/blob/main/cmd/server/main.go) (Web server and routes), [`internal/service/notification_dispatcher.go`](https://github.com/bscott/subtrackr/blob/main/internal/service/notification_dispatcher.go) (Notification dispatch), [`internal/database/database.go`](https://github.com/bscott/subtrackr/blob/main/internal/database/database.go) (SQLite database), [`internal/service/subscription.go`](https://github.com/bscott/subtrackr/blob/main/internal/service/subscription.go) (Subscription operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Web application"]
  node_server["Web server and routes<br/>[main.go]"]
  node_database[("SQLite database<br/>[database.go]")]
  node_migrations["Schema migrations<br/>[migrations.go]"]
  node_settings["Settings handlers<br/>[settings.go]"]
end

subgraph group_domain["Subscription domain"]
  node_subscriptions["Subscription handlers<br/>[subscription.go]"]
  node_subscription_service["Subscription operations<br/>[subscription.go]"]
  node_subscription_model["Subscription rules<br/>[subscription.go]"]
  node_subscription_repo["Subscription repository<br/>[subscription.go]"]
  node_category["Category management<br/>[category.go]"]
  node_calendar["Calendar and iCal<br/>[subscription.go]"]
  node_analytics["Spending analytics<br/>[subscription.go]"]
end

subgraph group_services["Services and integrations"]
  node_settings_service["Settings service<br/>[settings.go]"]
  node_currency["Currency conversion<br/>[currency.go]"]
  node_reminders["Reminder scheduling<br/>[reminder_runner.go]"]
  node_notifications["Notification dispatch"]
  node_email["Email delivery<br/>[email.go]"]
  node_push["Push notifications<br/>[ntfy.go]"]
  node_webhook["Webhook delivery<br/>[webhook.go]"]
end

subgraph group_access["Access and interfaces"]
  node_auth["Authentication handlers<br/>[auth.go]"]
  node_middleware["Authentication middleware<br/>[auth.go]"]
  node_sessions["Session management<br/>[session.go]"]
  node_mcp["MCP server<br/>[main.go]"]
end

subgraph group_ui["Browser interface"]
  node_themes["Themes and appearance<br/>[themes.js]"]
  node_sorting["Subscription sorting<br/>[sorting.js]"]
  node_modal["Form modals<br/>[modal.js]"]
end

node_user(("User"))
node_external{{"External notification services"}}
node_browser(("Browser"))

node_user -->|"uses"| node_server
node_server -->|"initializes"| node_database
node_server -->|"routes auth"| node_auth
node_server -->|"routes requests"| node_subscriptions
node_server -->|"routes categories"| node_category
node_server -.->|"protects routes"| node_middleware
node_auth -->|"creates sessions"| node_sessions
node_subscriptions -.->|"manages subscriptions"| node_subscription_service
node_subscription_service -.->|"persists records"| node_subscription_repo
node_subscription_repo -->|"reads and writes"| node_database
node_subscription_model -->|"models records"| node_subscription_repo
node_database -.->|"uses schema"| node_migrations
node_user -->|"views renewals"| node_calendar
node_user -->|"views spending"| node_analytics
node_user -->|"configures app"| node_settings
node_settings -.->|"updates preferences"| node_settings_service
node_user -->|"organizes subscriptions"| node_category
node_user -->|"uses conversion"| node_currency
node_reminders -.->|"dispatches reminders"| node_notifications
node_notifications -.->|"delivers email"| node_email
node_notifications -.->|"delivers push"| node_push
node_notifications -.->|"delivers webhooks"| node_webhook
node_email -->|"sends email"| node_external
node_push -->|"sends push"| node_external
node_webhook -.->|"sends events"| node_external
node_user -->|"uses AI tools"| node_mcp
node_mcp -.->|"manages subscriptions"| node_subscription_service
node_browser -->|"requests pages"| node_server
node_browser -->|"selects appearance"| node_themes
node_browser -->|"sorts subscriptions"| node_sorting
node_browser -->|"edits subscriptions"| node_modal

click node_server "https://github.com/bscott/subtrackr/blob/main/cmd/server/main.go"
click node_auth "https://github.com/bscott/subtrackr/blob/main/internal/handlers/auth.go"
click node_middleware "https://github.com/bscott/subtrackr/blob/main/internal/middleware/auth.go"
click node_sessions "https://github.com/bscott/subtrackr/blob/main/internal/service/session.go"
click node_subscriptions "https://github.com/bscott/subtrackr/blob/main/internal/handlers/subscription.go"
click node_subscription_service "https://github.com/bscott/subtrackr/blob/main/internal/service/subscription.go"
click node_subscription_model "https://github.com/bscott/subtrackr/blob/main/internal/models/subscription.go"
click node_subscription_repo "https://github.com/bscott/subtrackr/blob/main/internal/repository/subscription.go"
click node_database "https://github.com/bscott/subtrackr/blob/main/internal/database/database.go"
click node_migrations "https://github.com/bscott/subtrackr/blob/main/internal/database/migrations.go"
click node_settings "https://github.com/bscott/subtrackr/blob/main/internal/handlers/settings.go"
click node_settings_service "https://github.com/bscott/subtrackr/blob/main/internal/service/settings.go"
click node_category "https://github.com/bscott/subtrackr/blob/main/internal/handlers/category.go"
click node_currency "https://github.com/bscott/subtrackr/blob/main/internal/service/currency.go"
click node_reminders "https://github.com/bscott/subtrackr/blob/main/internal/service/reminder_runner.go"
click node_notifications "https://github.com/bscott/subtrackr/blob/main/internal/service/notification_dispatcher.go"
click node_email "https://github.com/bscott/subtrackr/blob/main/internal/service/email.go"
click node_push "https://github.com/bscott/subtrackr/blob/main/internal/service/ntfy.go"
click node_webhook "https://github.com/bscott/subtrackr/blob/main/internal/service/webhook.go"
click node_mcp "https://github.com/bscott/subtrackr/blob/main/cmd/mcp/main.go"
click node_calendar "https://github.com/bscott/subtrackr/blob/main/internal/handlers/subscription.go"
click node_analytics "https://github.com/bscott/subtrackr/blob/main/internal/handlers/subscription.go"
click node_themes "https://github.com/bscott/subtrackr/blob/main/web/static/js/themes.js"
click node_sorting "https://github.com/bscott/subtrackr/blob/main/web/static/js/sorting.js"
click node_modal "https://github.com/bscott/subtrackr/blob/main/web/static/js/modal.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_server,node_database,node_migrations,node_settings,node_user,node_browser toneBlue
class node_subscriptions,node_subscription_service,node_subscription_model,node_subscription_repo,node_category,node_calendar,node_analytics toneAmber
class node_settings_service,node_currency,node_reminders,node_notifications,node_email,node_push,node_webhook toneMint
class node_auth,node_middleware,node_sessions,node_mcp toneRose
class node_themes,node_sorting,node_modal,node_external toneIndigo
```

## Components

### Web application

- [Web server and routes](https://github.com/bscott/subtrackr/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [SQLite database](https://github.com/bscott/subtrackr/blob/main/internal/database/database.go): `internal/database/database.go`
- [Schema migrations](https://github.com/bscott/subtrackr/blob/main/internal/database/migrations.go): `internal/database/migrations.go`
- [Settings handlers](https://github.com/bscott/subtrackr/blob/main/internal/handlers/settings.go): `internal/handlers/settings.go`

### Subscription domain

- [Subscription handlers](https://github.com/bscott/subtrackr/blob/main/internal/handlers/subscription.go): `internal/handlers/subscription.go`
- [Subscription operations](https://github.com/bscott/subtrackr/blob/main/internal/service/subscription.go): `internal/service/subscription.go`
- [Subscription rules](https://github.com/bscott/subtrackr/blob/main/internal/models/subscription.go): `internal/models/subscription.go`
- [Subscription repository](https://github.com/bscott/subtrackr/blob/main/internal/repository/subscription.go): `internal/repository/subscription.go`
- [Category management](https://github.com/bscott/subtrackr/blob/main/internal/handlers/category.go): `internal/handlers/category.go`
- [Calendar and iCal](https://github.com/bscott/subtrackr/blob/main/internal/handlers/subscription.go): `internal/handlers/subscription.go`
- [Spending analytics](https://github.com/bscott/subtrackr/blob/main/internal/handlers/subscription.go): `internal/handlers/subscription.go`

### Services and integrations

- [Settings service](https://github.com/bscott/subtrackr/blob/main/internal/service/settings.go): `internal/service/settings.go`
- [Currency conversion](https://github.com/bscott/subtrackr/blob/main/internal/service/currency.go): `internal/service/currency.go`
- [Reminder scheduling](https://github.com/bscott/subtrackr/blob/main/internal/service/reminder_runner.go): `internal/service/reminder_runner.go`
- [Notification dispatch](https://github.com/bscott/subtrackr/blob/main/internal/service/notification_dispatcher.go): `internal/service/notification_dispatcher.go`
- [Email delivery](https://github.com/bscott/subtrackr/blob/main/internal/service/email.go): `internal/service/email.go`
- [Push notifications](https://github.com/bscott/subtrackr/blob/main/internal/service/ntfy.go): `internal/service/ntfy.go`
- [Webhook delivery](https://github.com/bscott/subtrackr/blob/main/internal/service/webhook.go): `internal/service/webhook.go`

### Access and interfaces

- [Authentication handlers](https://github.com/bscott/subtrackr/blob/main/internal/handlers/auth.go): `internal/handlers/auth.go`
- [Authentication middleware](https://github.com/bscott/subtrackr/blob/main/internal/middleware/auth.go): `internal/middleware/auth.go`
- [Session management](https://github.com/bscott/subtrackr/blob/main/internal/service/session.go): `internal/service/session.go`
- [MCP server](https://github.com/bscott/subtrackr/blob/main/cmd/mcp/main.go): `cmd/mcp/main.go`

### Browser interface

- [Themes and appearance](https://github.com/bscott/subtrackr/blob/main/web/static/js/themes.js): `web/static/js/themes.js`
- [Subscription sorting](https://github.com/bscott/subtrackr/blob/main/web/static/js/sorting.js): `web/static/js/sorting.js`
- [Form modals](https://github.com/bscott/subtrackr/blob/main/web/static/js/modal.js): `web/static/js/modal.js`

### Other components

- **User**
- **External notification services**
- **Browser**

## Connections

- User → Web server and routes: uses
- Web server and routes → SQLite database: initializes (evidence: `cmd/server/main.go`)
- Web server and routes → Authentication handlers: routes auth (evidence: `cmd/server/main.go`)
- Web server and routes → Subscription handlers: routes requests (evidence: `cmd/server/main.go`)
- Web server and routes → Category management: routes categories (evidence: `cmd/server/main.go`)
- Web server and routes → Authentication middleware: protects routes
- Authentication handlers → Session management: creates sessions (evidence: `internal/handlers/auth.go`)
- Subscription handlers → Subscription operations: manages subscriptions
- Subscription operations → Subscription repository: persists records
- Subscription repository → SQLite database: reads and writes (evidence: `internal/repository/subscription.go`)
- Subscription rules → Subscription repository: models records (evidence: `internal/repository/subscription.go`)
- SQLite database → Schema migrations: uses schema
- User → Calendar and iCal: views renewals
- User → Spending analytics: views spending
- User → Settings handlers: configures app
- Settings handlers → Settings service: updates preferences
- User → Category management: organizes subscriptions
- User → Currency conversion: uses conversion
- Reminder scheduling → Notification dispatch: dispatches reminders
- Notification dispatch → Email delivery: delivers email
- Notification dispatch → Push notifications: delivers push
- Notification dispatch → Webhook delivery: delivers webhooks
- Email delivery → External notification services: sends email
- Push notifications → External notification services: sends push
- Webhook delivery → External notification services: sends events
- User → MCP server: uses AI tools
- MCP server → Subscription operations: manages subscriptions
- Browser → Web server and routes: requests pages
- Browser → Themes and appearance: selects appearance
- Browser → Subscription sorting: sorts subscriptions
- Browser → Form modals: edits subscriptions