SubsTrack

SubsTrack is a lightweight Go + SQLite application for managing recurring subscriptions, billing cycles, and payment history. It keeps your subscription catalog organized while remaining easy to deploy locally or via Docker.

Features

• Track multiple subscriptions with billing schedules and renewal reminders
• Categorize subscriptions (Streaming, Software, Productivity, etc.)
• Store costs, payment methods, and transaction history
• Auto-run SQL migrations on startup using embedded files
• Password-protect settings and enforce SQLite foreign-key safety
• Dockerfile included for reproducible deployments

Tech Stack

• Go 1.25.4
• SQLite3
• sqlc for type-safe queries
• Goose for migrations
• Go standard library HTTP server

Prerequisites

• Go 1.25.4+
• SQLite3 installed locally
• Docker (optional for container builds)

Getting Started

Local Development

git clone git.ramadhantriyant.id/ramadhantriyant/substrack.git
cd substrack
go mod download
go build -o substrack
./substrack

The HTTP server listens on http://localhost:8080 by default and automatically performs database migrations.

Docker

# Build
docker build -t substrack:latest .

# Run with default port
docker run -d \
  -p 8080:8080 \
  -v substrack-data:/app/data \
  --name substrack \
  substrack:latest

# Map to a different host port (container still listens on :8080)
docker run -d \
  -p 3000:8080 \
  -v substrack-data:/app/data \
  --name substrack \
  substrack:latest

Project Structure

substrack/
  internal/
    database/    # Generated sqlc code
    handlers/    # HTTP handlers
    models/      # Application domain models
    utils/       # Helper utilities
  sql/
    schema/      # Goose migrations
    queries/     # sqlc inputs
  data/          # SQLite storage (created at runtime)
  main.go        # Application entry point
  server.go      # HTTP server wiring
  Dockerfile     # Container build definition
  go.mod/go.sum  # Module metadata
  sqlc.yaml      # sqlc config

Database Overview

• app_settings: single-row configuration with hashed password support
• categories: predefined labels for organizing subscriptions
• subscriptions: primary subscription records
• payment_history: captures transaction details per subscription
• Constraints: integer primary keys, CASCADE/RESTRICT rules, timestamps, and validation checks

API Notes

• POST /appsettings initializes core settings (one-time)
• Categories are preseeded (Streaming, Software, Cloud Storage, Gaming, News & Media, Productivity, Health & Fitness, Education, Other)
• Subscription and payment endpoints are under development

Configuration

• Server listens on :8080 (not configurable yet); remap via Docker -p hostPort:8080 or proxy if needed
• SQLite database stored at data/substrack.db (created automatically)

Development Workflow

# Regenerate sqlc code after editing SQL files
sqlc generate

# Create migrations under sql/schema with Goose annotations
# Example naming: 000005_add_payments.sql

# Run tests
go test ./...

Additional Notes

• SQLite connection pool size tuned for single-process usage
• Docker image uses a non-root user and is ~37 MB
• Indexes and constraints keep reads fast and data consistent

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m "feat: add my feature")
4. Open a pull request