Splitable

A modern expense-splitting and subscription-sharing application built with a clean, scalable architecture.

🏗️ Architecture

Monorepo Structure

splitable/
├── apps/
│   ├── api/          # Express.js backend
│   └── web/          # React frontend
├── packages/
│   └── shared/       # Shared types, enums, validation
├── infra/
│   └── docker/       # Docker configurations
└── docs/             # Documentation

Tech Stack

Backend:

• Node.js + Express.js + TypeScript
• PostgreSQL with Drizzle ORM
• JWT authentication (access + refresh tokens)
• REST API architecture

Frontend:

• React + TypeScript
• Tailwind CSS
• React Query for server state
• Zustand for client state
• React Router for navigation

Infrastructure:

• Docker + Docker Compose
• Nginx (production)
• PostgreSQL
• Redis (caching/sessions)

🚀 Getting Started

Prerequisites

• Node.js 20+
• npm 10+
• Docker & Docker Compose
• PostgreSQL (or use Docker)

Development Setup

1. Clone and install dependencies:

   git clone <repo-url>
   cd splitable
   npm install

2. Start the database:

   cd infra/docker
   docker-compose up -d

3. Configure environment:

   cp apps/api/.env.example apps/api/.env
   # Edit .env with your settings

4. Run database migrations:

   npm run db:generate
   npm run db:migrate

5. Start development servers:

   npm run dev

   This starts:

   • API server at http://localhost:3001
   • Web app at http://localhost:5173

Docker Development

For a full Docker development environment:

cd infra/docker
docker-compose -f docker-compose.yml up -d

This starts:

• PostgreSQL at localhost:5432
• Redis at localhost:6379
• MailHog (SMTP) at localhost:1025 (Web UI at localhost:8025)

📁 Project Structure

Backend (apps/api)

src/
├── config/           # Environment configuration
├── controllers/      # Request handlers
├── database/
│   └── schema/       # Drizzle schema definitions
├── middleware/       # Express middleware
├── routes/           # API routes
├── services/         # Business logic
└── utils/            # Utilities and helpers

Frontend (apps/web)

src/
├── components/       # Reusable UI components
│   ├── auth/         # Auth-related components
│   └── ui/           # Base UI components
├── contexts/         # React contexts
├── layouts/          # Page layouts
├── lib/              # Utilities and API client
├── pages/            # Page components
└── stores/           # Zustand stores

Shared Package (packages/shared)

src/
├── enums/            # Shared enumerations
├── types/            # TypeScript interfaces
├── validation/       # Zod schemas
└── constants/        # Shared constants

🔐 Authentication

The application uses JWT-based authentication with:

• Access tokens: Short-lived (15 minutes)
• Refresh tokens: Long-lived (7 days) with rotation
• Password hashing: bcrypt with 12 rounds
• Rate limiting: On auth endpoints

Auth Endpoints

Method	Endpoint	Description
POST	/api/v1/auth/register	Create account
POST	/api/v1/auth/login	Login
POST	/api/v1/auth/refresh-token	Refresh access token
POST	/api/v1/auth/logout	Logout
POST	/api/v1/auth/verify-email	Verify email
POST	/api/v1/auth/forgot-password	Request password reset
POST	/api/v1/auth/reset-password	Reset password
GET	/api/v1/auth/me	Get current user

🗄️ Database Schema

Key entities:

• users: User accounts and profiles
• groups: Expense groups
• group_members: Group memberships with roles
• expenses: Expense records
• expense_participants: Expense splits
• debts: Debt records between users
• payments: Payment records
• subscriptions: Shared subscription services
• notifications: User notifications
• activity_logs: Audit trail

🎨 UI Components

Tailwind CSS-based design system with:

• Buttons: Primary, secondary, outline, ghost, danger variants
• Inputs: With labels, error states, helper text
• Cards: Header, body, footer sections
• Avatars: With initials fallback
• Badges: Status indicators

Dark mode support built-in.

📋 Next Steps

Immediate Priorities

1. Complete API endpoints:

   • User profile management
   • Group CRUD operations
   • Expense creation and splitting
   • Debt management
   • Payment workflow

2. Frontend features:

   • Expense creation form
   • Group management
   • Debt settlement flow
   • Real-time notifications

3. Infrastructure:

   • Email service integration
   • File upload service
   • Background job processing

Future Enhancements

• Mobile apps (React Native)
• Push notifications
• Multi-currency support with exchange rates
• CSV/PDF export
• OAuth providers (Google, Apple)
• Debt simplification algorithm
• Receipt OCR

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

📦 Building for Production

# Build all packages
npm run build

# Build Docker images
docker-compose -f infra/docker/docker-compose.prod.yml build

# Deploy
docker-compose -f infra/docker/docker-compose.prod.yml up -d

📄 License

MIT License - see LICENSE file for details.