CoinGuard

Take control of your personal finances with comprehensive tracking and insights
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Project Structure
3. Getting Started
   • Prerequisites
   • Installation
4. Usage
5. Roadmap
6. Contributing
7. License
8. Contact
9. Acknowledgments

About The Project

CoinGuard is a self-hostable web application for tracking personal finances - transactions, categories, bank accounts, and the analytics that come from them.

Key features include:

• Transaction Tracking: Record income, expenses and transfers, or import them from a bank export
• Categories: Organize transactions into categories
• Bank Accounts: Track balances across multiple accounts
• Monthly & Yearly Analytics: Break down spending and income over time
• Import Enrichment: Attach categories and descriptions to imported transactions before they're saved

(back to top)

Built With

CoinGuard is a pnpm/Turborepo monorepo built with:

• 
• 
• 
• 
• 
• 
• 

(back to top)

Project Structure

CoinGuard is a pnpm workspace managed by Turborepo:

coin-guard/
├── apps/
│   └── web/           # Next.js app (routes, pages, UI logic)
├── packages/
│   ├── db/            # Prisma schema, migrations, and DB client
│   ├── ui/            # Shared component library (Base UI + shadcn)
│   ├── biome-config/  # Shared Biome (lint/format) config
│   └── ts-config/     # Shared TypeScript config
├── docker-compose.yml # Local PostgreSQL for development
└── Dockerfile         # Production image for the web app

(back to top)

Getting Started

To get a local copy of CoinGuard up and running, follow these simple steps.

Prerequisites

Make sure you have the following installed on your system:

• Node.js (version 20.9 or higher)
• pnpm (via corepack, which ships with Node)

  corepack enable

• Docker (to run the local PostgreSQL database)

Installation

1. Clone the repository

   git clone https://github.com/StereoPT/coin-guard.git
   cd coin-guard

2. Install dependencies

   pnpm install

3. Create your root env file and fill in the Postgres credentials and DATABASE_URL

   cp .env.example .env.local

   apps/web/.env.local and packages/db/.env are symlinks to this root file, so this is the only one you need to edit.

4. Create the web app's env file

   cp apps/web/.env.example apps/web/.env

5. Start the local PostgreSQL database

   docker compose up -d

6. Apply database migrations and generate the Prisma client

   pnpm db:migrate
   pnpm db:generate

7. Start the development server

   pnpm dev

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

(back to top)

Usage

Track Your Finances

• Add transactions manually, or import them from a bank export (CSV)
• Organize transactions into categories you create and manage
• Track balances across multiple bank accounts

Import Transactions

• During import, enrich each transaction with a category and description before it's saved

Dashboard & Analytics

• Get a quick snapshot of your financial health, with recent transactions at a glance
• Break down spending and income by category over the month or year

(back to top)

Roadmap

Shipped

• Unified Analytics page (merge Monthly & Yearly views, with flexible date filtering)
• Flexible date filtering on Category Details
• Default bank account
• Grouped Lookup Descriptions
• Delete action for Lookup Logs

Up Next

• Optimistic UI updates
• Loading States

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make CoinGuard better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors:

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

StereoPT - @StereoPT - stereopt@gmail.com

Project Link: https://github.com/StereoPT/coin-guard

(back to top)

Acknowledgments

Special thanks to the following resources and tools that made CoinGuard possible:

• Next.js Documentation
• shadcn/ui Components

(back to top)