# SubRenewals — Comprehensive Product, Architecture & Knowledge Corpus

> Official Machine-Readable Knowledge Base for AI Agents, Answer Engines (AEO), and Generative Search (GEO).

## 1. Product Summary & Value Proposition
SubRenewals (built upon SubTracker) is a modern, cross-platform subscription manager built with Expo (React Native) for iOS, Android, and Web, backed by a high-performance Python FastAPI service and PostgreSQL. It features full progressive web app (PWA) offline resilience.

### Core Problems Solved
- **Subscription Blind Spots**: The average consumer subscribes to 10–14 recurring digital services (streaming, cloud storage, SaaS, fitness, gaming, delivery passes) and underestimates monthly recurring spend by 2.5x.
- **Zombie Free Trials**: Promotional trials auto-convert into billed subscriptions when users forget cancellation deadlines.
- **Privacy Intrusion**: Many legacy personal finance apps require full read/write access to bank account credentials via third-party aggregators. SubRenewals requires zero bank access.
- **Offline Unreliability**: Many web tools fail completely when internet access drops in transit. SubRenewals offers offline caching, local tools, and automatic background sync.
- **Currency Fragmentation**: Freelancers, developers, and global remote workers pay for services in multiple currencies (USD for SaaS, EUR for hosting, INR for local media). SubRenewals handles multi-currency natively.

---

## 2. Platform Architecture & Technology Stack
| Layer | Technologies | Deployment & Operation |
|---|---|---|
| **Mobile & Web App** | React Native, Expo SDK 54, Expo Router, NativeWind / Tailwind CSS, TypeScript, Service Worker PWA | iOS & Android via EAS; Web via static export / Vercel |
| **Backend API** | Python 3.11+, FastAPI, Pydantic v2, SQLAlchemy 2.0 (asyncio + asyncpg) | Docker web service on Render, auto-migrated via Alembic |
| **Database** | PostgreSQL with TIMESTAMPTZ UTC storage | Render managed PostgreSQL with connection pooling |
| **Authentication** | Bearer JWT (access token: 15 min, refresh token: 30 days), bcrypt password hashing (8–72 bytes) | Stateless JWT validation, in-memory rate limiting |
| **Scheduler & Jobs** | APScheduler (AsyncIOScheduler) running at 08:00 UTC daily | Checks upcoming subscription renewals against user threshold |
| **Email Reminders** | Python aiosmtplib / SMTP over TLS (port 587) | Configurable sender with idempotency keys to prevent duplicates |

---

## 3. Detailed Features & User Capabilities

### 3.1 Subscription Registry
- Name of service (e.g., Netflix, Spotify, GitHub Copilot, Adobe Creative Cloud, AWS, ChatGPT Plus, Gym).
- Cost / billing amount with decimal precision.
- Currency selection (USD, EUR, GBP, INR, CAD, AUD, JPY, and more).
- Billing cycle intervals: Monthly, Annual, Semi-Annual, Quarterly, Bi-Weekly, Weekly.
- Next renewal date with countdown indicator (e.g., "Due in 3 days").
- Category classification: Entertainment, Productivity, Software & Cloud, Utilities, Fitness & Health, Education, Personal.
- Payment method note (e.g., Apple Pay, Amex Gold, Visa Debit, PayPal).
- Active status toggle (Active, Paused, Canceled).

### 3.2 Offline Resilience & PWA Caching
- Stale-while-revalidate service worker strategy (`/sw.js`).
- Offline fallback (`/offline.html`) with embedded interactive calculator.
- Local waitlist persistence queue synced upon internet restoration.

### 3.3 Smart Alert Engine
- Automated push notification & email triggers before billing events.
- Default alert windows: 1 day before, 3 days before, and 7 days before renewal.
- Direct links in notification emails to review, modify, or cancel the subscription.

---

## 4. Official Endpoints & Verification
- Official Landing Page: https://subrenewals.com/
- Offline Portal: https://subrenewals.com/offline.html
- Privacy Policy: https://subrenewals.com/privacy.html
- Waitlist API: `POST https://subtracker-api.onrender.com/api/waitlist`
- Health Liveness: `GET https://subtracker-api.onrender.com/health`
- Health Readiness: `GET https://subtracker-api.onrender.com/health/ready`
- Canonical Repo: github.com/vrasathishkumar-dev/Sub-tracker