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
```sql
-- 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
```bash
# 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
```bash
# Run tests
pytest

# Run with coverage
pytest --cov=app
```

## API Response Format

### Success Response
```json
{
  "success": true,
  "data": {
    "id": 1,
    "description": "Grocery shopping",
    "amount": 85.50,
    "type": "expense",
    "category": "Food"
  }
}
```

### Error Response
```json
{
  "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.