From ee2f58e4a43a364d63eceaa786ab44232ffef851 Mon Sep 17 00:00:00 2001 From: Pratik Narola Date: Sat, 13 Sep 2025 17:44:57 +0530 Subject: [PATCH] Added markdowns --- instructions.md | 31 ++++++++ plan.md | 196 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 227 insertions(+) create mode 100644 instructions.md create mode 100644 plan.md diff --git a/instructions.md b/instructions.md new file mode 100644 index 0000000..aecef7f --- /dev/null +++ b/instructions.md @@ -0,0 +1,31 @@ +# Task Instructions and Guidelines + +This file contains important instructions and suggestions provided during the development process. These instructions must be followed at all times. + +## Instructions + +1. **Package Management**: We will be using uv for package management. No need to specify versions - let uv handle the latest available versions. + +2. **MCP Servers Usage**: We must use the following MCP servers throughout the development process: + - **Context7**: To fetch and verify latest docs and examples (as of Sept 2025) + - **Zen MCP server**: To chat, analyze and think properly about complex problems + - **Archon MCP server**: To track the progress of the task and manage project workflow + +3. **Task-Driven Development**: Always complete the full Archon task cycle before any coding: + - Check Current Task → Review task details and requirements + - Research for Task → Search relevant documentation and examples using Context7 + - Implement the Task → Write code based on research + - **Code Review with Zen**: Before marking task as "review" or "done", MUST use Zen MCP server to analyze and review the implementation for quality and functionality. while security is important, it will be reviewed and verified separately. + - Update Task Status → Move task from "todo" → "doing" → "review" + - Get Next Task → Check for next priority task + - Repeat Cycle + +4. **Error Resolution**: When encountering any errors, bugs, or implementation issues: + - **First**: Use Context7 or Perplexity MCP servers to research the latest documentation and solutions + - **Second**: Analyze the problem using Zen MCP server for complex debugging + - **Last**: Only remove or comment out code as a temporary measure if research confirms it's a compatibility issue + - **Never**: Remove functionality without first attempting to research and fix the problem properly + +--- + +**Important**: Always review and follow these instructions before making any changes to the codebase. diff --git a/plan.md b/plan.md new file mode 100644 index 0000000..c6fff26 --- /dev/null +++ b/plan.md @@ -0,0 +1,196 @@ +# 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.