Aequitally 🧮

A modern expense sharing and settlement application built with Next.js 15, React 19, and Convex.

Aequitally helps you track shared expenses and settle up with friends, family, or colleagues in a fair and transparent way. Create tallies, add participants, split expenses, and see who owes what—all in real-time.

✨ Features

💰 Expense Tracking: Add, edit, and categorize shared expenses
👥 Participant Management: Easily manage group members and their contributions
⚡ Real-time Sync: Live updates across all devices using Convex
📊 Smart Settlements: Automatic calculation of who owes whom
📱 Responsive Design: Works seamlessly on desktop and mobile
🌙 Theme Support: Light and dark mode with system preference detection
📈 CSV Export: Export settlement data for record keeping
🔒 Type Safety: Built with TypeScript for robust development
🎨 Modern UI: Beautiful interface using shadcn/ui components

🛠️ Technology Stack

Frontend

Framework: Next.js 15 with App Router and Turbopack
UI Library: React 19 with TypeScript
Styling: Tailwind CSS 4 with CSS Variables
Components: shadcn/ui with accessible primitives
Forms: React Hook Form with Valibot validation
Icons: Lucide React
Animations: Motion for smooth interactions

Backend

Backend-as-a-Service: Convex for real-time data and serverless functions
Database: Convex's built-in real-time database
Schema Validation: Valibot for runtime type checking and form validation

Development Tools

Package Manager: pnpm for fast, efficient dependency management
Code Quality: Biome for linting and formatting
Git Hooks: Husky + lint-staged
Build Tool: Turbopack for lightning-fast builds

🚀 Quick Start

Prerequisites

Node.js: Version 18.0.0 or higher
pnpm: Latest version (recommended package manager)
Convex Account: Sign up at convex.dev

Installation

Clone the repository

git clone <repository-url>
cd aequitally

Install dependencies
```
pnpm install
```

Set up Convex

# Install Convex CLI globally (if not already installed)
pnpm add -g convex

# Initialize Convex project
npx convex dev

Configure environment variables

# Copy the example environment file
cp .env.example .env.local

# Add your Convex deployment URL
# NEXT_PUBLIC_CONVEX_URL=https://your-convex-deployment.convex.cloud

Start the development server
```
pnpm dev
```
Open your browser Navigate to http://localhost:3000 to see the application.

📜 Available Scripts

Command	Description
`pnpm dev`	Start development server with Turbopack
`pnpm build`	Build the application for production
`pnpm start`	Start the production server
`pnpm lint:fix`	Run Biome linter with automatic fixes
`pnpm format`	Format code using Biome
`pnpm format:fix`	Format and fix code issues
`npx convex dev`	Start Convex development backend
`npx convex deploy`	Deploy Convex functions to production

🏗️ Project Structure

aequitally/
├── app/                    # Next.js App Router pages and layouts
│   ├── tally/[id]/        # Dynamic tally pages
│   ├── about/             # About page
│   ├── privacy/           # Privacy policy
│   ├── terms/             # Terms of service
│   ├── layout.tsx         # Root layout with providers
│   ├── page.tsx           # Home page (create tally)
│   └── globals.css        # Global styles and CSS variables
├── components/            # React components
│   ├── ui/               # shadcn/ui base components
│   ├── common/           # Shared components (header, footer, etc.)
│   ├── home/             # Home page specific components
│   ├── tally/            # Tally feature components
│   └── layouts/          # Layout components
├── convex/               # Convex backend
│   ├── _generated/       # Auto-generated Convex files
│   ├── schema.ts         # Database schema definitions
│   ├── tally.ts          # Tally-related serverless functions
│   └── tsconfig.json     # TypeScript config for Convex
├── hooks/                # Custom React hooks
│   ├── use-currency.tsx  # Currency management hook
│   ├── use-expense-form.tsx # Expense form state management
│   └── use-toast.tsx     # Toast notification hook
├── lib/                  # Utilities, helpers, and configurations
│   ├── config/           # Configuration files
│   ├── data/             # Static data and constants
│   ├── handlers/         # Business logic handlers
│   ├── helpers/          # Utility functions
│   ├── schemas/          # Validation schemas
│   ├── services/         # External service integrations
│   ├── types/            # TypeScript type definitions
│   └── utils/            # General utility functions
├── providers/            # React context providers
│   ├── convex-client-provider.tsx # Convex client setup
│   ├── currency-provider.tsx     # Global currency state
│   ├── theme-provider.tsx        # Theme management
│   └── provider-wrapper.tsx      # Combined providers
└── public/               # Static assets
    ├── manifest.json     # PWA manifest
    └── robots.txt        # Search engine robots file

🎨 UI Components & Customization

shadcn/ui Integration

This project uses shadcn/ui components with accessible primitives. These components are:

Fully customizable through CSS variables
Accessible by default with ARIA attributes
Type-safe with TypeScript
Themeable with light/dark mode support

Component Configuration

The project is configured with shadcn/ui using the "New York" style:

{
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "lucide"
}

Theme Customization with tweakcn

For easy theme customization, we recommend using tweakcn - a visual theme editor for shadcn/ui:

Visit tweakcn.com
Import your current theme or start with a preset
Customize colors, spacing, and typography visually
Export CSS variables and update your globals.css

Theme Variables

Customize the application theme by modifying CSS variables in app/globals.css:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  /* ... more variables */
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 47.4% 11.2%;
  /* ... more variables */
}

Adding New shadcn/ui Components

To add new shadcn/ui components to your project:

# Add a specific component
npx shadcn@latest add button

# Add multiple components
npx shadcn@latest add button card dialog

# List available components
npx shadcn@latest add

🌐 Core Features

Tally Management

Create new expense tallies with customizable names and descriptions
Set tally dates and manage participant lists
Real-time synchronization across all connected devices

Expense Tracking

Add expenses with detailed descriptions and amounts
Support for different split methods (equal, by percentage, custom amounts)
Date tracking for each expense
Search and sort expenses by various criteria

Settlement Calculation

Automatic calculation of who owes whom
Optimized settlement suggestions to minimize transactions
Export settlement data to CSV for record keeping
Visual representation of balances and transfers

Multi-Currency Support

Support for 150+ global currencies
Real-time currency formatting
Consistent currency display throughout the application

🚀 Deployment

Vercel Deployment (Recommended)

Push your code to GitHub
Deploy to Vercel
- Connect your GitHub repository to Vercel
- Vercel will automatically detect Next.js and configure build settings
- Add your environment variables in the Vercel dashboard
Deploy Convex backend
```
npx convex deploy
```
Update environment variables
- Update NEXT_PUBLIC_CONVEX_URL with your production Convex URL

Environment Variables

Required environment variables for deployment:

# Convex
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

# Optional: Analytics, monitoring, etc.
# Add additional environment variables as needed

Build Optimization

The project is optimized for production with:

Turbopack for fast builds
Automatic tree shaking for smaller bundle sizes
Image optimization with Next.js Image component
CSS optimization with Tailwind CSS purging

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Development Workflow

Fork the repository

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
Run quality checks
```
pnpm format:fix
pnpm lint:fix
```

Commit your changes

git commit -m "feat: add your feature description"

Push and create a Pull Request

Code Style

Formatting: Automated with Biome
Linting: Enforced with Biome
TypeScript: Strict mode enabled
Commits: Use conventional commit messages

Pre-commit Hooks

The project uses Husky and lint-staged to run quality checks on commit:

Code formatting with Biome
Linting with Biome
TypeScript type checking

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

shadcn for the amazing UI component library
Convex for the powerful backend-as-a-service platform
Vercel for Next.js and deployment platform
Valibot for schema validation and type safety

Built with ❤️ using modern web technologies

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.github/workflows		.github/workflows
.husky		.husky
app		app
components		components
convex		convex
hooks		hooks
lib		lib
providers		providers
public		public
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Aequitally 🧮

✨ Features

🛠️ Technology Stack

Frontend

Backend

Development Tools

🚀 Quick Start

Prerequisites

Installation

📜 Available Scripts

🏗️ Project Structure

🎨 UI Components & Customization

shadcn/ui Integration

Component Configuration

Theme Customization with tweakcn

Theme Variables

Adding New shadcn/ui Components

🌐 Core Features

Tally Management

Expense Tracking

Settlement Calculation

Multi-Currency Support

🚀 Deployment

Vercel Deployment (Recommended)

Environment Variables

Build Optimization

🤝 Contributing

Development Workflow

Code Style

Pre-commit Hooks

📄 License

🙏 Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages