persona-finance-tracker-demo/plan.md

Personal Finance Tracking API Backend - Simplified Plan

Overview

A streamlined personal finance tracking API backend using Flask, Flask-SQLAlchemy, and PostgreSQL. This simplified version focuses on core functionality for quick development and local showcase, with no authentication required.

Technical Stack

• Framework: Flask
• Database: PostgreSQL
• ORM: Flask-SQLAlchemy
• Environment: python-dotenv for configuration
• Testing: pytest

API Endpoints Structure

Transaction Management

• POST /api/transactions - Add transaction (income or expense)
• GET /api/transactions - Get all transactions (with optional filtering)
• GET /api/transactions/{id} - Get specific transaction
• PUT /api/transactions/{id} - Update transaction
• DELETE /api/transactions/{id} - Delete transaction

Categories Management

• GET /api/categories - Get all categories
• POST /api/categories - Create new category
• PUT /api/categories/{id} - Update category
• DELETE /api/categories/{id} - Delete category

Basic Analytics

• GET /api/analytics/summary - Basic financial summary
• GET /api/analytics/spending-by-category - Simple spending analysis

Database Schema Design

Core Tables

1. categories - Transaction categories
2. transactions - Individual income/expense records

Schema Details

-- categories table
CREATE TABLE categories (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL UNIQUE,
    description TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- transactions table
CREATE TABLE transactions (
    id SERIAL PRIMARY KEY,
    description VARCHAR(200) NOT NULL,
    amount DECIMAL(10,2) NOT NULL,
    type VARCHAR(10) NOT NULL CHECK (type IN ('income', 'expense')),
    category_id INTEGER REFERENCES categories(id),
    date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Project Structure

persona-finance-test/
├── app/
│   ├── __init__.py
│   ├── app.py              # Flask app initialization
│   ├── config.py           # Configuration settings
│   ├── models/
│   │   ├── __init__.py
│   │   ├── category.py
│   │   └── transaction.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── transactions.py
│   │   ├── categories.py
│   │   └── analytics.py
│   └── utils/
│       └── __init__.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_transactions.py
│   └── test_categories.py
├── requirements.txt
├── .env.example
├── .env
└── README.md

Dependencies

requirements.txt

Flask
Flask-SQLAlchemy
python-dotenv
psycopg2-binary
pytest

Configuration

.env.example

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost/personal_finance_db

# Application Configuration
SECRET_KEY=your-secret-key-here
DEBUG=True
FLASK_ENV=development

Key Features

• Simple Setup: Flask-SQLAlchemy handles PostgreSQL complexity
• No Authentication: Open endpoints for local showcase
• Clean Architecture: Separated models, API routes, and configuration
• Basic Validation: Input validation for transactions and categories
• Simple Analytics: Basic financial summary and spending analysis
• Testing: pytest setup for unit tests

Implementation Phases

Phase 1: Basic Setup

• Flask app structure
• Flask-SQLAlchemy configuration
• PostgreSQL connection setup
• Basic models (Category, Transaction)
• Database initialization

Phase 2: Core Functionality

• Transaction CRUD operations
• Category management
• Basic validation and error handling
• API response formatting

Phase 3: Basic Analytics

• Simple summary endpoints
• Basic spending analysis
• Final testing and documentation

Development Workflow

Setup Commands

# Install dependencies
pip install -r requirements.txt

# Set up environment
cp .env.example .env
# Edit .env with your database credentials

# Initialize database
flask shell
>>> from app import db
>>> db.create_all()
>>> exit()

# Run the application
flask run

Testing

# Run tests
pytest

# Run with coverage
pytest --cov=app

API Response Format

Success Response

{
  "success": true,
  "data": {
    "id": 1,
    "description": "Grocery shopping",
    "amount": 85.50,
    "type": "expense",
    "category": "Food"
  }
}

Error Response

{
  "success": false,
  "error": "Validation error",
  "message": "Description is required"
}

This simplified architecture provides a solid foundation for a personal finance API that can be developed quickly while maintaining clean code structure and using PostgreSQL's robust features. The focus is on core functionality without the complexity of authentication, budgets, or recurring transactions.