Subscriptional

Subscriptional is a production-oriented Flutter + Node.js + PostgreSQL application for tracking subscriptions, renewal reminders, and cancellation workflows.

Monorepo structure

• apps/mobile - Flutter mobile app (Riverpod + GoRouter + Material 3)
• backend/api - Node.js + Express TypeScript API (PostgreSQL + JWT)
• sample_data - seed-style sample JSON datasets
• docs - architecture notes
• .github/workflows - CI pipelines

Tech stack

Mobile

• Flutter stable + Dart null safety
• Riverpod state management
• GoRouter
• Material 3 custom light/dark theme
• FL Chart + Shimmer for dashboard experience

Backend

• Node.js + Express + TypeScript
• PostgreSQL + node-postgres
• JWT authentication + bcrypt password hashing
• Zod validation + centralized error handling
• Node-cron schedulers for reminder/cancellation maintenance jobs

Prerequisites

• Flutter 3.41+
• Node 22+
• npm 11+
• PostgreSQL 16+ (local or cloud)

Environment setup

1) API environment

Copy backend/api/.env.example to backend/api/.env.

Required values:

• NODE_ENV
• PORT
• POSTGRES_URI
• JWT_SECRET

2) PostgreSQL setup

Use one of the following:

• local PostgreSQL instance
• managed PostgreSQL connection string

Quick local option:

docker compose up -d postgres

Run locally

Mobile app

cd apps/mobile
flutter pub get
flutter run --dart-define=SUBSCRIPTIONAL_API_BASE_URL=http://localhost:8080

API

cd backend/api
npm ci
npm run dev

API endpoints

• POST /api/v1/auth/register
• POST /api/v1/auth/login
• GET /api/v1/auth/me
• GET /api/v1/catalog/popular-subscriptions
• GET /api/v1/subscriptions
• POST /api/v1/subscriptions
• PATCH /api/v1/subscriptions/:id
• DELETE /api/v1/subscriptions/:id

Quality checks

Flutter

cd apps/mobile
flutter analyze
flutter test

Backend API

cd backend/api
npm run lint
npm run build

Security notes

• Do not commit .env files.
• Use a strong JWT_SECRET in each environment.
• Validate and sanitize all incoming API payloads.
• Hash passwords with bcrypt (already enforced in auth route).

Current implementation status

Implemented in this iteration:

• Flutter app shell with auth gate, session restore, and Cupertino-inspired liquid-glass UI
• Live mobile login/register and profile session against Node API
• Live subscription sync (list/add/update/delete) with PostgreSQL-backed API
• Smart popular-catalog flow with autofill for URLs, cancellation, and logos
• Node API foundation with JWT auth and PostgreSQL-backed subscription CRUD routes
• Background scheduler scaffolding via node-cron
• CI skeleton for mobile + backend

Next implementation steps:

1. Add offline-first Drift caching on top of live API repositories
2. Implement reminder delivery channels (email/push provider)
3. Add analytics persistence and export flows (CSV/PDF)
4. Expand unit/widget/integration tests for critical flows