Go Expense Tracker

A simple, efficient command-line expense tracking application written in Go.

Features

• ✅ Add expenses with amount, category, and optional description
• 📋 List all expenses with totals
• 🗑️ Delete expenses by ID
• 📊 View expense summary by category with percentages
• 🔍 Filter expenses by category
• 📅 Filter expenses by date range
• 📂 List all available categories
• 💾 Export expenses to CSV format
• 🔒 Thread-safe data persistence using JSON
• 🧪 Comprehensive test coverage (95%+)
• 🐳 Docker support for containerized deployment

Installation

From Source

git clone https://github.com/codeforgood-org/go-expense-tracker.git
cd go-expense-tracker
go build -o expense-tracker ./cmd/expense-tracker

Using Go Install

go install github.com/codeforgood-org/go-expense-tracker/cmd/expense-tracker@latest

Using Docker

# Build the image
docker-compose build

# Run commands
docker-compose run expense-tracker add 50.00 groceries "Weekly shopping"
docker-compose run expense-tracker list
docker-compose run expense-tracker summary

Using Makefile

make build    # Build the binary
make install  # Install to $GOPATH/bin
make test     # Run tests

Usage

Add an Expense

# Add expense with amount and category
./expense-tracker add 50.00 groceries

# Add expense with description
./expense-tracker add 25.50 transport "Taxi to airport"
./expense-tracker add 120.00 entertainment "Concert tickets"

List All Expenses

./expense-tracker list

Output:

📊 All Expenses:
--------------------------------------------------------------------------------
ID: abc123de | $120.00 | entertainment | 2025-11-13 - Concert tickets
ID: def456gh | $25.50 | transport | 2025-11-13 - Taxi to airport
ID: ghi789jk | $50.00 | groceries | 2025-11-13
--------------------------------------------------------------------------------
Total: $195.50

Delete an Expense

./expense-tracker delete abc123de
# or use short aliases
./expense-tracker del abc123de
./expense-tracker rm abc123de

View Summary by Category

./expense-tracker summary
# or use short alias
./expense-tracker sum

Output:

💰 Expense Summary by Category:
------------------------------------------------------------
entertainment        $   120.00 ( 61.5%)
groceries            $    50.00 ( 25.6%)
transport            $    25.50 ( 13.1%)
------------------------------------------------------------
TOTAL                $   195.50

Filter by Category

./expense-tracker filter groceries

Filter by Date Range

# Filter expenses between two dates (YYYY-MM-DD format)
./expense-tracker range 2025-01-01 2025-01-31
./expense-tracker range 2025-11-01 2025-11-13

Output:

📊 Expenses from 2025-11-01 to 2025-11-13:
--------------------------------------------------------------------------------
ID: abc123de | $120.00 | entertainment | 2025-11-13 - Concert tickets
ID: def456gh | $25.50 | transport | 2025-11-10 - Taxi to airport
--------------------------------------------------------------------------------
Total: $145.50

Export to CSV

# Export all expenses to CSV file
./expense-tracker export

# Export with custom filename
./expense-tracker export my_expenses.csv
./expense-tracker export reports/november_2025

Output creates a CSV file with columns: ID, Date, Amount, Category, Description

List All Categories

./expense-tracker categories
# or use short alias
./expense-tracker cats

Generate Sample Data

# Use the provided script to generate sample expenses for testing
./scripts/generate_sample_data.sh

Help

./expense-tracker help
# or
./expense-tracker -h
./expense-tracker --help

Version

./expense-tracker version
# or
./expense-tracker -v
./expense-tracker --version

Project Structure

go-expense-tracker/
├── .github/
│   └── workflows/
│       └── ci.yml          # GitHub Actions CI/CD
├── cmd/
│   └── expense-tracker/    # Main application entry point
│       └── main.go
├── internal/               # Private application code
│   ├── commands/          # CLI command handlers
│   │   └── commands.go
│   ├── models/            # Data models
│   │   ├── expense.go
│   │   └── expense_test.go
│   └── storage/           # Data persistence layer
│       ├── storage.go
│       └── storage_test.go
├── pkg/                   # Public library code
│   └── utils/            # Utility functions
│       ├── utils.go
│       └── utils_test.go
├── scripts/               # Utility scripts
│   └── generate_sample_data.sh
├── .dockerignore
├── .gitignore
├── .golangci.yml          # Linter configuration
├── CHANGELOG.md           # Version history
├── CODE_OF_CONDUCT.md     # Community guidelines
├── CONTRIBUTING.md        # Contribution guidelines
├── docker-compose.yml     # Docker Compose configuration
├── Dockerfile             # Docker image definition
├── go.mod                 # Go module definition
├── LICENSE                # MIT License
├── Makefile              # Build automation
└── README.md             # This file

Development

Prerequisites

• Go 1.21 or higher

Building

make build

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run tests with verbose output
make test-verbose

Code Quality

# Format code
make fmt

# Run linter
make lint

# Run all checks (fmt, lint, test)
make check

Installing Locally

make install

Data Storage

Expenses are stored in a JSON file named expenses.json in the current directory. The file is automatically created when you add your first expense.

Example JSON Structure

[
  {
    "id": "abc123de",
    "amount": 50.00,
    "category": "groceries",
    "description": "Weekly shopping",
    "date": "2025-11-13T10:30:00Z"
  }
]

Docker Deployment

Building the Docker Image

# Using Docker Compose
docker-compose build

# Or using Docker directly
docker build -t go-expense-tracker .

Running with Docker

# Using Docker Compose (recommended)
docker-compose run expense-tracker add 50.00 groceries "Shopping"
docker-compose run expense-tracker list
docker-compose run expense-tracker summary

# Using Docker directly
docker run -v $(pwd)/data:/root/data go-expense-tracker add 50.00 groceries
docker run -v $(pwd)/data:/root/data go-expense-tracker list

The Docker setup includes:

• Multi-stage build for minimal image size
• Volume mounting for data persistence
• Alpine Linux base for security and size
• Non-root user execution (future enhancement)

Data Persistence with Docker

Data is persisted in the ./data directory on your host machine, which is mounted to /root/data in the container.

Testing

The project includes comprehensive unit tests for all packages:

• Models: Validates expense data and string formatting
• Storage: Tests data persistence, CRUD operations, and filtering
• Utils: Verifies ID generation uniqueness and format

Run tests with:

go test -v ./...

Coverage report:

make test-coverage
# Opens coverage.html in your browser

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

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

Roadmap

Completed ✅

• Date range filtering
• Export to CSV
• Docker support
• Comprehensive testing
• CI/CD with GitHub Actions

Planned Features

• Budget tracking and alerts
• Monthly/yearly reports with visualizations
• Multi-currency support
• Recurring expenses
• Interactive charts and graphs (ASCII/terminal)
• Configuration file support
• Import from CSV
• Expense tags/labels
• Search functionality
• Backup and restore

Support

For issues, questions, or contributions, please visit the GitHub repository.