Skip to content

README.md

Latest commit

 

History

History
183 lines (143 loc) · 6.04 KB

README.md

File metadata and controls

183 lines (143 loc) · 6.04 KB

Canadian Credit Card Points Optimizer

An AI-powered application that maximizes credit card rewards for Canadians based on their financial and lifestyle profiles.

Prerequisites

Tool Version Notes
Node.js 20+
JDK 21+
PostgreSQL 16+
Auth0 account free tier SPA application required (see setup below)

Quick Start

1. Set Up the Database

Install PostgreSQL (first time only) — run in PowerShell as Administrator:

winget install PostgreSQL.PostgreSQL.16

During installation, set the password for the postgres user to postgres to match the default config.

Create the database — after install, open a new terminal:

createdb -U postgres creditoptimizer

PostgreSQL runs as a Windows service and starts automatically on boot. To start/stop it manually:

net start postgresql-x64-16   # start
net stop  postgresql-x64-16   # stop

2. Configure Auth0

  1. Create a free account at auth0.com and set up a tenant.
  2. In the Auth0 Dashboard → Applications → Create Application → choose Regular Web Application.
  3. Under Settings, add to the allowed URLs:
    • Allowed Callback URLs: http://localhost:3000/auth/callback
    • Allowed Logout URLs: http://localhost:3000
    • Allowed Web Origins: http://localhost:3000
  4. Create frontend/.env.local (never commit this file): 
    AUTH0_DOMAIN=<your-tenant>.us.auth0.com
AUTH0_CLIENT_ID=<client-id>
AUTH0_CLIENT_SECRET=<client-secret>
AUTH0_SECRET=<random-32+-char-string>
APP_BASE_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:8080
AUTH0_AUDIENCE=https://<your-tenant>.us.auth0.com/api/v2/

3. Start the Backend (Ktor API)

Add your keys to backend/local.properties (never commit this file):

geminiApiKey=<your_gemini_key>
auth0Domain=<your-tenant>.us.auth0.com
auth0Audience=https://<your-tenant>.us.auth0.com/api/v2/

Or set GEMINI_API_KEY, AUTH0_DOMAIN, and AUTH0_AUDIENCE as environment variables.

cd backend
./gradlew run

The API will be available at http://localhost:8080. Health check: GET http://localhost:8080/health

Windows users: use gradlew.bat run or ./gradlew.bat run

4. Start the Frontend (Next.js)

cd frontend
npm install   # first time only
npm run dev

The web app will be available at http://localhost:3000.

Project Structure

.
├── frontend/               # Next.js frontend (TypeScript, Tailwind CSS v4)
│   ├── proxy.ts            # Auth0 middleware proxy (Next.js 16 pattern)
│   ├── next.config.ts      # Image remote patterns for avatars
│   ├── app/                # App Router pages, layouts, and components
│   │   └── components/     # AuthProvider, AuthButtons, SplashScreen, ChatPanel, ArsenalModal, ...
│   ├── context/            # ProfileContext (auth-aware), ThemeContext
│   ├── hooks/              # useChat, useRecommendations
│   └── lib/
│       ├── api.ts          # Shared types + fetch wrappers (Bearer token on profile calls)
│       └── auth0.ts        # Auth0Client singleton
├── backend/                # Ktor backend (Kotlin, Gradle)
│   ├── src/
│   │   └── main/
│   │       ├── kotlin/com/creditoptimizer/
│   │       │   ├── Application.kt
│   │       │   ├── dto/            # Dtos.kt, ProfileDtos.kt, ChatDtos.kt
│   │       │   ├── service/        # ProfileService (per-user), GeminiService
│   │       │   └── plugins/        # Auth.kt, Database.kt, Routing.kt, Serialization.kt
│   │       └── resources/
│   │           ├── application.conf
│   │           ├── logback.xml
│   │           └── db/migration/   # V1__init.sql (consolidated schema)
│   └── build.gradle.kts
└── CLAUDE.md

Available Commands

Frontend

Command Description
npm run dev Start development server
npm run build Build for production
npm run lint Run ESLint

Backend

Command Description
./gradlew run Start the Ktor server
./gradlew test Run backend tests
./gradlew build Build the project JAR

Database

Command Description
net start postgresql-x64-16 Start the PostgreSQL service
net stop postgresql-x64-16 Stop the PostgreSQL service

Environment Variables

Backend (backend/local.properties or environment)

Variable Default Description
PORT 8080 API server port
DATABASE_URL jdbc:postgresql://localhost:5432/creditoptimizer JDBC connection string
DATABASE_USER postgres Database username
DATABASE_PASSWORD postgres Database password
GEMINI_API_KEY (required) Gemini API key for /api/chat
AUTH0_DOMAIN (required) Auth0 tenant domain (e.g. dev-xxx.us.auth0.com)
AUTH0_AUDIENCE (required) Auth0 API audience — must match frontend exactly

Frontend (frontend/.env.local — never commit)

Variable Description
AUTH0_DOMAIN Auth0 tenant domain
AUTH0_CLIENT_ID Auth0 application client ID
AUTH0_CLIENT_SECRET Auth0 application client secret
AUTH0_SECRET Random secret used to encrypt the session cookie
APP_BASE_URL Frontend base URL (e.g. http://localhost:3000)
NEXT_PUBLIC_API_URL Backend API URL (defaults to http://localhost:8080)
AUTH0_AUDIENCE Auth0 API audience — must match backend exactly

Regional Scope

This application is scoped to Canadian credit card issuers only:

  • Major banks: Amex CA, RBC, TD, Scotiabank, BMO, CIBC
  • Digital banks: Wealthsimple, EQ Bank
  • Telecom & retail: Rogers, PC Financial

All amounts are in CAD. Address fields support Canadian provinces and postal codes.