💎 CashTrack: Premium Noir Edition

Sophisticated Financial Intelligence & Enterprise-Grade Accounting

CashTrack is a premium web application designed for users who demand precision, elegance, and deep insights into their financial lifecycle. Built with a "Premium Noir" aesthetic, it combines high-performance real-time synchronization with a sophisticated multi-ledger architecture.

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• A Supabase account (sign up)
• Google Chrome (for OAuth)

Installation

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Add your Supabase credentials to .env
# VITE_SUPABASE_URL=your_project_url
# VITE_SUPABASE_ANON_KEY=your_anon_key

Database Setup

1. Go to your Supabase project dashboard
2. Navigate to the SQL Editor
3. Run the complete schema from src/lib/schema.sql
4. Verify the handle_new_user trigger was created

Running the App

# Development server
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

The dev server will start at http://localhost:5173

🏗️ Tech Stack

Core

• React 18 - UI framework
• TypeScript - Type safety
• Vite - Fast build tool
• React Router - Client-side routing

Styling

• Tailwind CSS v3 - Utility-first CSS
• Custom Dark Theme - Premium aesthetic
• Inter Font - Clean typography
• Lucide React - Icon library

Backend & Data

• Supabase - Backend as a service
  • PostgreSQL database
  • Row-level security (RLS)
  • Real-time subscriptions
  • File storage
• TanStack Query - Server state management

Forms & Validation

• React Hook Form - Form state management
• Zod - Schema validation

📁 Project Structure

src/
├── components/          # Reusable UI components
│   └── ProtectedRoute.tsx
├── context/             # React contexts
│   └── AuthProvider.tsx
├── lib/                 # Utilities and configs
│   ├── schema.sql       # Database schema
│   ├── supabase.ts      # Supabase client
│   └── utils.ts         # Helper functions
├── pages/               # Route pages
│   ├── AuthCallback.tsx
│   ├── Dashboard.tsx
│   └── Login.tsx
├── types/               # TypeScript types
│   └── database.types.ts
├── App.tsx              # Main app component
├── index.css            # Global styles
└── main.tsx             # App entry point

🔐 Authentication

The app supports multiple authentication methods:

Email/Password

• Standard email and password authentication
• Secure password requirements
• Email verification

Google OAuth

• One-click Google sign-in
• Automatic profile creation
• Seamless authentication flow

🗃️ Database Schema

The application uses a sophisticated multi-ledger architecture:

Tables

• profiles - User profiles linked to Supabase Auth
• businesses - Business entities
• business_members - Junction table for business membership
• ledgers - Financial ledgers (personal or business)
• entries - Financial transactions
• invites - Business invitation codes
• audit_logs - Immutable change history

Key Features

• Per-Member Ledgers: Each business member has their own ledger
• Soft Deletes: Entries are never truly deleted
• Audit Trail: Complete history of all changes
• RLS Policies: Row-level security for data isolation

🎨 Design System

Color Palette

The app uses a custom dark theme with HSL-based color tokens:

• Primary: hsl(217.2 91.2% 59.8%) - Blue accent
• Background: hsl(222.2 84% 4.9%) - Dark background
• Foreground: hsl(210 40% 98%) - Light text
• Muted: hsl(217.2 32.6% 17.5%) - Subdued elements

Typography

• Font: Inter variable font
• Weights: 300-900
• Optimized for readability

📋 Roadmap

• Phase 1: Foundation & Infrastructure ✅
• Phase 2: Core Personal Finance (MVP)
• Phase 3: Business Architecture & Roles
• Phase 4: Per-Member Ledger Logic
• Phase 5: Offline-First & Sync
• Phase 6: Data Integrity & Advanced Features
• Phase 7: Analytics & KPIs
• Phase 8: Testing & Deployment

🔧 Configuration

Environment Variables

# Required
VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

Supabase OAuth Setup

To enable Google OAuth:

1. Go to Supabase Dashboard → Authentication → Providers
2. Enable Google provider
3. Add OAuth credentials from Google Cloud Console
4. Set redirect URL: https://your-project.supabase.co/auth/v1/callback

🧪 Development

Code Quality

# Type checking
npm run build

# Linting
npm run lint

Path Aliases

The project uses @/ as an alias for src/:

import { supabase } from '@/lib/supabase'
import { useAuth } from '@/context/AuthProvider'

📦 Building for Production

# Create production build
npm run build

# Output will be in /dist folder
# dist/
# ├── index.html
# ├── assets/
# │   ├── index-[hash].css
# │   └── index-[hash].js

Deploy the dist folder to any static hosting service:

• Vercel
• Netlify
• Cloudflare Pages
• AWS S3 + CloudFront

🤝 Contributing

This is a personal project, but suggestions and bug reports are welcome!

📄 License

Private project - All rights reserved

---

Built with ❤️ using React, TypeScript, and Supabase