splitwise/docs/code-plan.md

Splitwise Application - Code Plan

This document outlines the technical architecture, stack, and implementation plan for our Splitwise-style expense-splitting application.

Tech Stack

Frontend

• Runtime: Bun
• Framework: React 18+ with TypeScript
• Build Tool: Vite
• Styling: TailwindCSS with Shadcn UI component library
• State Management: Zustand
• Data Fetching: TanStack Query (React Query)
• Form Handling: React Hook Form with Zod validation
• Routing: React Router v6
• Testing: Vitest, React Testing Library
• Components: Shadcn UI (customizable Radix UI-based components)

Backend

• Runtime: Bun
• Language: TypeScript
• Framework: Hono (lightweight, fast, TypeScript-first)
• Database: PostgreSQL
• ORM: Drizzle (TypeScript-first ORM)
• Authentication: better-auth (framework-agnostic authentication with email/password and social sign-on)
• Validation: Zod
• File Storage: Local storage with Sharp for image processing (can be migrated to S3 later)
• Testing: Bun test

Architecture Overview

We'll implement a clean architecture with separation of concerns:

Frontend Architecture

• Application Layer: React components, hooks, and contexts
• Domain Layer: Zustand stores and business logic
• Infrastructure Layer: API clients and external service integrations

Key Frontend Modules:

1. Auth Module: Sign-up, sign-in, profile management
2. Expenses Module: Create, edit, delete expenses
3. Settlements Module: Balances, settle up functionality
4. Activity Module: Feed of expense and settlement activities
5. Notifications Module: In-app notifications
6. Settings Module: User preferences and application settings

Backend Architecture

• API Layer: Hono routes and controllers
• Service Layer: Business logic and core application services
• Data Access Layer: Drizzle ORM models and repositories
• Domain Layer: Entity definitions and domain logic

Key Backend Modules:

1. Auth Module: User authentication and authorization
2. Users Module: User management and profiles
3. Contacts Module: Contact relationships and invitations
4. Expenses Module: Expense tracking and splits
5. Settlements Module: Balance calculations and settlements
6. Notifications Module: Notification generation and delivery
7. Files Module: Receipt image upload and processing

Database Schema (Initial)

Users

• id: uuid (primary key)
• email: string (unique)
• display_name: string
• profile_photo_url: string (nullable)
• default_currency: string (default: 'USD')
• locale: string (default: 'en-US')
• timezone: string (default: 'UTC')
• created_at: timestamp
• updated_at: timestamp

Auth (managed by better-auth)

• id: uuid (primary key)
• user_id: uuid (foreign key -> Users.id)
• provider: string (e.g., 'email', 'google', 'github')
• provider_user_id: string (nullable, for social providers)
• email: string
• password_hash: string (nullable, for email provider)
• refresh_token: string (nullable)
• last_login: timestamp
• created_at: timestamp
• updated_at: timestamp

Contacts

• id: uuid (primary key)
• user_id: uuid (foreign key -> Users.id)
• contact_id: uuid (foreign key -> Users.id)
• status: enum ('pending', 'accepted', 'declined')
• created_at: timestamp
• updated_at: timestamp

Expenses

• id: uuid (primary key)
• title: string
• amount: decimal
• date: timestamp
• payer_id: uuid (foreign key -> Users.id)
• memo: text (nullable)
• receipt_image_url: string (nullable)
• created_at: timestamp
• updated_at: timestamp

ExpenseParticipants

• id: uuid (primary key)
• expense_id: uuid (foreign key -> Expenses.id)
• user_id: uuid (foreign key -> Users.id)
• share_amount: decimal
• created_at: timestamp
• updated_at: timestamp

Settlements

• id: uuid (primary key)
• payer_id: uuid (foreign key -> Users.id)
• receiver_id: uuid (foreign key -> Users.id)
• amount: decimal
• date: timestamp
• memo: text (nullable)
• created_at: timestamp
• updated_at: timestamp

Notifications

• id: uuid (primary key)
• user_id: uuid (foreign key -> Users.id)
• type: enum ('expense_added', 'expense_edited', 'settlement_received')
• content: jsonb
• is_read: boolean (default: false)
• created_at: timestamp

API Endpoints

Authentication (managed by better-auth)

• POST /api/auth/register
• POST /api/auth/login
• POST /api/auth/social/:provider
• POST /api/auth/social/:provider/callback
• POST /api/auth/logout
• GET /api/auth/me
• POST /api/auth/refresh-token
• POST /api/auth/forgot-password
• POST /api/auth/reset-password

Users

• GET /api/users/profile
• PUT /api/users/profile
• PUT /api/users/settings

Contacts

• GET /api/contacts
• POST /api/contacts
• PUT /api/contacts/:id
• DELETE /api/contacts/:id

Expenses

• GET /api/expenses
• POST /api/expenses
• GET /api/expenses/:id
• PUT /api/expenses/:id
• DELETE /api/expenses/:id
• POST /api/expenses/:id/receipt

Balances

• GET /api/balances
• GET /api/balances/:contactId

Settlements

• POST /api/settlements
• GET /api/settlements
• GET /api/settlements/:id

Notifications

• GET /api/notifications
• PUT /api/notifications/:id/read
• PUT /api/notifications/read-all

Implementation Plan

Phase 1: Project Setup

1. Initialize frontend and backend projects with Bun
2. Set up TypeScript configuration
3. Configure Vite for the frontend
4. Install and configure Shadcn UI with TailwindCSS
5. Set up Hono for the backend
6. Configure Drizzle ORM with PostgreSQL
7. Set up development environment with Docker for database

Phase 2: Core Authentication

1. Install and configure better-auth library
2. Set up authentication adapters for Hono and PostgreSQL
3. Configure email/password and social sign-on providers
4. Create authentication forms on frontend
5. Implement profile management

Phase 3: Expense Tracking

1. Implement expense CRUD operations on backend
2. Create expense form components on frontend
3. Implement expense splitting logic
4. Add receipt image upload functionality

Phase 4: Balances and Settlements

1. Implement balance calculation logic
2. Create settlement endpoints
3. Build balance visualization components
4. Implement settlement UI

Phase 5: Activity Feed and Notifications

1. Create activity tracking for expenses and settlements
2. Implement notification generation
3. Build activity feed UI
4. Add in-app notification components

Phase 6: Settings and Refinement

1. Implement user settings
2. Add locale and currency formatting
3. Refine UI/UX
4. Performance optimizations

Folder Structure

Frontend

frontend/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   │   ├── auth/
│   │   ├── expenses/
│   │   ├── settlements/
│   │   ├── activity/
│   │   ├── notifications/
│   │   ├── settings/
│   │   └── ui/
│   ├── hooks/
│   │   └── useBetterAuth.ts
│   ├── pages/
│   ├── services/
│   │   ├── api.ts
│   │   └── auth.ts
│   ├── stores/
│   ├── types/
│   ├── utils/
│   ├── lib/
│   │   └── shadcn-ui/
│   ├── styles/
│   │   └── globals.css
│   ├── App.tsx
│   └── main.tsx
├── components.json
├── tailwind.config.js
├── .env
├── package.json
└── tsconfig.json

Backend

backend/
├── src/
│   ├── controllers/
│   ├── db/
│   │   ├── schema/
│   │   └── migrations/
│   ├── middleware/
│   ├── services/
│   ├── auth/
│   │   ├── config.ts
│   │   ├── providers/
│   │   └── adapters/
│   ├── types/
│   ├── utils/
│   └── index.ts
├── .env
├── package.json
└── tsconfig.json

Getting Started

Prerequisites

• Bun installed
• PostgreSQL database
• Node.js 18+ (for additional tools)

Setup Instructions

1. Clone the repository
2. Install dependencies for both frontend and backend with bun install
3. Set up environment variables (.env files)
4. Run database migrations with Drizzle
5. Start the development servers:
   • Frontend: bun run dev
   • Backend: bun run dev

Development Practices

• TypeScript for type safety
• Feature branch workflow
• Write tests for critical functionality
• Use Zod schemas for validation and type inference
• Follow REST principles for API design
• Document API endpoints with JSDoc or Swagger