📊 Subscription Tracker - Guida Completa

Una moderna webapp per gestire e tracciare tutti i tuoi abbonamenti online con AI insights.

---

📑 Indice

1. Caratteristiche
2. Stack Tecnologico
3. Installazione Rapida
4. Configurazione
5. Database Setup
6. Funzionalità
7. Deployment
8. Troubleshooting

---

✨ Caratteristiche

Core Features

• ✅ Dashboard Completa: Visualizza tutti gli abbonamenti con filtri e ordinamento
• ✅ Smart Onboarding: Ricerca servizi popolari e creazione automatica subscription
• ✅ Analytics Avanzate: Grafici e statistiche spese mensili/annuali
• ✅ Multi-Valuta: Supporto per 15+ valute con conversione automatica
• ✅ AI Insights: Analisi intelligente delle spese con OpenAI GPT-4
• ✅ Lista/Griglia: Toggle tra visualizzazione lista e griglia
• ✅ Ricerca Dinamica: Cerca tra nome, categoria, note ed email
• ✅ Supporto Crediti: Traccia servizi a crediti (Runway, Midjourney, etc.)
• ✅ Multi-Account: Associa email diverse a diversi abbonamenti
• ✅ Dark/Light Mode: Toggle tema scuro/chiaro
• ✅ Multilingua: Italiano, Inglese, Spagnolo, Francese, Tedesco
• ✅ Responsive: Design mobile-first ottimizzato

---

🛠️ Stack Tecnologico

• Next.js 14: App Router con Server Components
• TypeScript: Type-safe con strict mode
• Supabase: PostgreSQL + Auth + RLS
• Tailwind CSS + shadcn/ui: UI Components
• Zustand: State management
• OpenAI: GPT-4o-mini per AI insights
• Vercel Analytics: Web analytics

---

🚀 Installazione Rapida

1. Clona il repository

git clone https://github.com/gignus79/Subscription-Tracker-App.git
cd Subscription-Tracker-App

2. Installa dipendenze

npm install

3. Configura variabili d'ambiente

Crea .env.local:

# Supabase (OBBLIGATORIO)
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbG...
SUPABASE_SERVICE_ROLE_KEY=eyJhbG...

# OpenAI (OBBLIGATORIO per AI Insights)
OPENAI_API_KEY=sk-proj-xxx...

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

4. Setup Database

1. Vai su Supabase Dashboard
2. Crea nuovo progetto
3. Vai su SQL Editor
4. Esegui il contenuto di supabase/schema.sql
5. Esegui le migrations in supabase/migrations/ (in ordine)

5. Avvia il server

npm run dev

Apri http://localhost:3000

---

⚙️ Configurazione Dettagliata

Supabase Setup

1. Crea Progetto

• Vai su supabase.com
• New Project → scegli nome e region
• Attendi creazione (~2 min)

2. Credenziali API

Settings → API:

• Project URL → NEXT_PUBLIC_SUPABASE_URL
• anon public → NEXT_PUBLIC_SUPABASE_ANON_KEY
• service_role → SUPABASE_SERVICE_ROLE_KEY

3. Autenticazione

Authentication → Providers:

• Abilita Email provider
• (Opzionale) Disabilita "Confirm email" per test

OpenAI Setup

1. Vai su platform.openai.com/api-keys
2. Crea nuova secret key
3. Copia in OPENAI_API_KEY

Costi: ~$0.50 per 1000 richieste (GPT-4o-mini)

---

🗄️ Database Setup

Schema Principale

-- Esegui nel SQL Editor di Supabase
-- Copia il contenuto di supabase/schema.sql

Lo schema crea:

• profiles: Profili utente
• subscriptions: Abbonamenti
• categories: Categorie servizi
• services: 80+ servizi predefiniti

Migrations

Esegui in ordine:

1. add_account_email.sql - Supporto email multiple
2. add_credits_support.sql - Crediti e rinnovi
3. add_default_currency.sql - Valuta default
4. add_dev_services.sql - Servizi sviluppo
5. ensure_profiles_table.sql - Verifica profiles

Verifica

-- Controlla tabelle create
SELECT table_name FROM information_schema.tables 
WHERE table_schema = 'public';

-- Test RLS
SELECT * FROM subscriptions WHERE user_id = auth.uid();

---

🎯 Funzionalità Principali

Dashboard

• Vista griglia con glassmorphism cards
• Vista lista compatta
• Filtri per categoria e stato
• Ordinamento multiplo
• Ricerca real-time

AI Insights

1. Dashboard → "Ottieni Insights AI"
2. Analisi automatica delle tue spese
3. Suggerimenti personalizzati
4. Identificazione duplicati
5. Raccomandazioni risparmio

Powered by OpenAI GPT-4o-mini.

Multi-Valuta

Valute supportate: EUR, USD, GBP, CHF, CAD, AUD, JPY, CNY, INR, BRL, MXN, SEK, NOK, DKK, PLN

Conversione automatica nelle statistiche.

Smart Onboarding

Database con 80+ servizi:

• Streaming (Netflix, Disney+, ...)
• Produttività (Notion, Slack, ...)
• Cloud (Dropbox, Google Drive, ...)
• Sviluppo (GitHub, Vercel, ...)
• Design (Adobe, Figma, ...)
• AI (ChatGPT, Midjourney, ...)

---

🚢 Deployment su Vercel

1. Push su GitHub

git add .
git commit -m "Deploy"
git push origin main

2. Deploy

1. vercel.com → New Project
2. Importa da GitHub
3. Aggiungi Environment Variables:
   • NEXT_PUBLIC_SUPABASE_URL
   • NEXT_PUBLIC_SUPABASE_ANON_KEY
   • SUPABASE_SERVICE_ROLE_KEY
   • OPENAI_API_KEY
4. Deploy!

3. Custom Domain (Opzionale)

Settings → Domains → Add Domain

Vercel Analytics è già configurato in app/layout.tsx.

---

🔧 Troubleshooting

Errore "Could not find column"

Soluzione: Esegui tutte le migrations nel SQL Editor

Subscriptions non si salvano

Soluzione: Verifica RLS policies abilitate

ALTER TABLE subscriptions ENABLE ROW LEVEL SECURITY;

AI Insights non funziona

Soluzione:

1. Verifica OPENAI_API_KEY in .env.local
2. Riavvia server: npm run dev

Errore 401 Unauthorized

Soluzione: Logout/Login, verifica cookies abilitati

Pulsante Add non visibile

Soluzione: Clearing cache browser, verifica z-index

---

📚 Struttura Progetto

subscription-tracker/
├── app/                    # Next.js App Router
│   ├── api/               # API Routes
│   │   ├── ai-insights/   # OpenAI
│   │   └── auth/          # Supabase auth
│   ├── dashboard/         # Main app
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx           # Landing
├── components/            # React components
│   ├── ui/               # shadcn/ui
│   ├── add-subscription-dialog.tsx
│   ├── ai-insights.tsx
│   └── ...
├── lib/                   # Utilities
│   ├── store/            # Zustand
│   ├── supabase/         # Clients
│   └── utils/            # Helpers
├── supabase/             # Database
│   ├── schema.sql
│   └── migrations/
├── types/                # TypeScript
└── .env.local           # Config (create this!)

---

🤝 Contributing

1. Fork il repository
2. Crea branch: git checkout -b feature/Feature
3. Commit: git commit -m 'Add Feature'
4. Push: git push origin feature/Feature
5. Pull Request

---

📄 License

MIT License - vedi LICENSE

---

🙏 Crediti

Sviluppato da Giorgio Lovecchio

Stack: Next.js • Supabase • Tailwind • OpenAI • Vercel

---

📞 Supporto

• 🐛 GitHub Issues
• 💬 Discussions

---

📋 Changelog

v2.0.0 (2025-11-18)

• ✨ AI Insights con OpenAI GPT-4
• ✨ Multi-valuta con conversione
• ✨ Vista lista/griglia
• ✨ Ricerca dinamica
• ✨ Vercel Analytics
• 🐛 Bug fixes e performance

v1.0.0 (2025-01-15)

• 🎉 Release iniziale

---

Made with ☕ in Italy 🇮🇹

Ultimo aggiornamento: 18 novembre 2025