💰 Expense Tracker

A modern, full-stack expense tracking application built with Next.js 15, tRPC, and PostgreSQL. Track your expenses, manage shared costs with friends, and gain insights into your spending patterns with beautiful analytics.

✨ Features

• 💳 Multi-Account Management - Track expenses across multiple bank accounts
• 👥 Shared Expenses - Split costs with friends and track who owes what
• 📊 Analytics Dashboard - Visualize spending patterns with interactive charts
• 🔄 Self Transfers - Record transfers between your own accounts
• 📝 Transaction Sessions - Organize expenses into sessions for better tracking
• 🎨 Modern UI - Beautiful, responsive interface with dark/light theme support
• 🔐 Secure Authentication - Email/password authentication with session management
• ⚡ Real-time Updates - Optimistic updates with TanStack Query
• 📱 Mobile Responsive - Works seamlessly on desktop, tablet, and mobile devices
• 🔍 Advanced Filtering - Filter and search transactions with URL-persisted state

🚀 Tech Stack

Frontend

• Next.js 15 - React framework with App Router
• React 19 - UI library
• TypeScript - Type safety
• TailwindCSS - Utility-first styling
• shadcn/ui - Re-usable component library
• Radix UI - Accessible UI primitives
• Lucide Icons - Beautiful icon set
• Recharts - Charts and data visualization

Backend

• tRPC - End-to-end typesafe APIs
• Drizzle ORM - TypeScript ORM
• PostgreSQL - Relational database
• better-auth - Authentication solution

State Management & Forms

• TanStack Query - Server state management
• React Hook Form - Form handling
• Zod - Schema validation
• nuqs - URL state management

Developer Experience

• ESLint - Code linting with security plugins
• Prettier - Code formatting
• TypeScript - Static type checking
• Docker - Containerization

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 20.x or higher
• pnpm 8.x or higher (recommended) or npm/yarn
• PostgreSQL 14.x or higher
• Git

🛠️ Installation

1. Clone the repository

git clone https://github.com/jainhardik120/expense-tracker.git
cd expense-tracker

2. Install dependencies

pnpm install
# or
npm install
# or
yarn install

3. Set up environment variables

Create a .env file in the root directory:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/expense_tracker"

# App URL (optional)
NEXT_PUBLIC_BASE_URL="http://localhost:3000"

# Skip environment validation during build (optional)
SKIP_ENV_VALIDATION=false

4. Set up the database

Generate and run database migrations:

# Generate migration files
pnpm db:generate

# Apply migrations to database
pnpm db:migrate

5. Start the development server

pnpm dev

Open http://localhost:3000 in your browser to see the application.

🗄️ Database Schema

The application uses a multi-tenant architecture where all data is scoped by userId. Key entities include:

• users - User accounts and profiles
• sessions - Authentication sessions
• bankAccount - User's financial accounts
• statements - All transactions (expenses, transfers, etc.)
• friendsProfiles - People involved in shared expenses
• splits - How expenses are divided among friends
• selfTransferStatements - Transfers between user's own accounts

📁 Project Structure

src/
├── app/                    # Next.js App Router
│   ├── (auth)/            # Authentication routes (login/register)
│   ├── (main)/            # Protected app routes
│   │   ├── sessions/      # Expense tracking sessions
│   │   ├── statements/    # Transaction management
│   │   └── aggregated/    # Analytics and summaries
│   └── api/               # API routes
├── components/            # Reusable React components
│   ├── ui/               # shadcn/ui components
│   └── data-table/       # Table components with filtering
├── server/               # Backend logic
│   ├── routers/          # tRPC routers
│   └── helpers/          # Helper functions
├── db/                   # Database configuration
│   └── schema.ts         # Drizzle schema definitions
├── lib/                  # Utility functions and configurations
└── hooks/                # Custom React hooks

🎯 Available Scripts

# Development
pnpm dev              # Start development server with Turbopack
pnpm build            # Build for production
pnpm start            # Start production server

# Database
pnpm db:generate      # Generate migration files
pnpm db:migrate       # Run database migrations

# Code Quality
pnpm lint             # Run ESLint
pnpm lint:fix         # Fix ESLint errors
pnpm typecheck        # Run TypeScript type checking
pnpm format           # Format code with Prettier

# Analysis
pnpm duplicate:check  # Check for code duplication
pnpm update:check     # Check for dependency updates

🐳 Docker Deployment

Local development database

The local database stack runs separately from Next.js:

# From the repository root, after local credentials have been provisioned
docker compose -f docker-compose.local.yml up -d --wait

# Run the app using web/.env.local
cd web
pnpm dev

PostgreSQL is available at 127.0.0.1:5432, with database and application username expense_tracker. pgAdmin is at http://localhost:5050, with login [email protected]; its registered server connects to postgres:5432 inside Docker. The generated passwords are in .local-db/app-password and .local-db/pgadmin-password. .local-db/postgres-password is the separate PostgreSQL administrator password. These files are private local configuration and must remain ignored by Git.

For the initial setup, provision those three files with separate random passwords and .local-db/servers.json with the pgAdmin server registration before starting Compose. The .local-db/ directory should have mode 0700; the two container-mounted password files and server registration must be readable by the containers. Keep the application password file at mode 0600. Set DATABASE_URL in web/.env.local to use the local application credentials. An existing remote database can be copied using PostgreSQL 18 pg_dump and pg_restore, preserving application schemas, data, sequences, and Drizzle's migration history while omitting remote ownership and grants.

The initial switch preserves the previous environment in web/.env.remote.local. Next.js does not automatically load that backup. Restore it to web/.env.local and restart Next.js to reconnect to the remote database. The clone is independent; local changes do not sync back to remote.

# Stop the containers while preserving their database volumes
docker compose -f docker-compose.local.yml down

The named volumes persist across restarts. down --volumes deletes local data. The local PostgreSQL image includes Debian's tzdata-legacy package so browser timezone names such as Asia/Calcutta work in dashboard aggregation queries. The database works without network access once images are downloaded; features that call external services, including email, GitHub sign-in, AI, and market data, still require connectivity.

For local SQL tracing, start this repository's Jaeger service:

docker compose --env-file .env.observability.local -f docker-compose.observability.yml up -d

The ignored .env.observability.local selects the already downloaded Jaeger image. Without that file, omit --env-file to use the default Jaeger 2 image. web/.env.local exports traces to http://127.0.0.1:4318 using OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf, and OTEL_TRACES_SAMPLER=always_on. Open http://localhost:16686, select service expense-tracker, and expand drizzle.select spans to inspect SQL and timings. The app sends traces directly to Jaeger; an additional collector is unnecessary for this setup. Traces are held in memory and disappear when Jaeger restarts.

Build and run with Docker:

# Build the Docker image
docker build -t expense-tracker .

# Run the container
docker run -p 3000:3000 \
  -e DATABASE_URL="your_database_url" \
  expense-tracker

🌐 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Import your repository to Vercel
3. Add environment variables
4. Deploy!

Other Platforms

The application can be deployed to any platform that supports Node.js and Docker:

• Railway
• Render
• Fly.io
• AWS/GCP/Azure

Ensure you:

1. Set up a PostgreSQL database
2. Configure environment variables
3. Run database migrations
4. Deploy the application

🤖 Android Release Automation

The Android GitHub Actions workflow at .github/workflows/main.yml now publishes the release .aab to the Google Play internal track as part of the master release pipeline. A separate release trigger remains as a fallback for manually published GitHub releases.

Before that release job can succeed:

1. Enable the Google Play Android Developer API for the Google Cloud project tied to your Play Console account.
2. Create a service account key in JSON format.
3. Add that service account under Google Play Console Users and permissions and grant it access to com.jainhardik120.expensetracker.
4. Add the JSON file contents to the repository GitHub secret PLAYSTORE_SERVICE_ACCOUNT_JSON.
5. Make sure the app already exists in Play Console and has had its first upload created manually.

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow the existing code style
• Run pnpm lint and pnpm typecheck before committing
• Write meaningful commit messages
• Update documentation as needed

📝 License

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

🙏 Acknowledgments

• Next.js - The React Framework
• shadcn/ui - Beautiful UI components
• tRPC - End-to-end typesafe APIs
• Drizzle ORM - TypeScript ORM

📧 Contact

For questions or feedback, please open an issue on GitHub.

---

Built with ❤️ using Next.js 15