> INDEX.NAVIGATION — TABLE OF CONTENTS

#	SECTION	LINK
01	About the Project	PROJECT.ABOUT
02	Feature Overview	FEATURES.DECK
03	Technology Stack	STACK.LOAD
04	Repository Layout	PROJECT.STRUCTURE
05	Quickstart	QUICKSTART.SETUP
06	Development Guide	DEV.WORKFLOW
07	API Surface	ROUTES.MAP
08	Security & Data	SECURITY.MODEL
09	Roadmap	ROADMAP
10	Contribution Guide	CONTRIBUTION.PROTOCOL
11	Visual Identity	DESIGN.AESTHETIC
12	License & Support	SUPPORT.LICENSE

> PROJECT.ABOUT — WHAT IS SPENDLY?

Spendly is a personal expense tracking web application built with Flask. It helps you log expenses, spot spending patterns, and stay on budget — without the spreadsheet headache.

Users can register, sign in, add expenses with category, amount, date, and description, then visualise their spending through category breakdowns, monthly summaries, and date-range filters on a personal profile dashboard.

Built with Flask + Jinja2 for server-side rendering, SQLite for zero-config storage, and custom CSS with design tokens for a warm editorial aesthetic. Features automatic dark/light theme detection with a manual toggle, CSRF-protected forms, and Werkzeug password hashing.

Why Spendly?

PROBLEM	SOLUTION
Spreadsheets are tedious and error-prone	One-click expense logging with structured fields
No insight into spending habits	Category breakdowns, recent transactions, and date filtering
Complex finance apps are overkill	A clean, focused, personal tracker

> FEATURES.DECK — KEY CAPABILITIES

FEATURE	DESCRIPTION	STATUS
🔐 User Accounts	Register, sign in, sign out with Werkzeug-hashed passwords	✅ LIVE
💰 Log Expenses	Add any expense in seconds with all details	✅ LIVE
✏️ Edit Expenses	Update any field of an existing expense	✅ LIVE
🗑️ Delete Expenses	Remove expenses with CSRF-protected POST	✅ LIVE
� Category Breakdown	Per-category totals and share of spending	✅ LIVE
📈 Profile Dashboard	Summary stats, recent transactions, category cards	✅ LIVE
🗓️ Date Filtering	Preset ranges (this month, 3 months, 6 months) + custom range	✅ LIVE
📊 Analytics Page	Dedicated analytics view	✅ LIVE
🛡️ CSRF Protection	Token-based form protection on every state-changing request	✅ LIVE
🌓 Theme Support	Automatic dark/light detection + manual toggle	✅ LIVE
📱 Responsive Design	Works on desktop and mobile devices	✅ LIVE
🧪 Test Suite	pytest + pytest-flask covering every shipped feature	✅ LIVE

> STACK.LOAD — TECHNOLOGIES

LAYER	TECHNOLOGY	PURPOSE
Backend	Flask 3.1.3 / Werkzeug 3.1.6	Routing, sessions, password hashing
Language	Python 3.13	Core application logic
Storage	SQLite (stdlib sqlite3)	Local, zero-config database
Templating	Jinja2	Dynamic HTML generation
Forms	CSRF tokens + flask.session	Cross-site request forgery protection
Frontend	CSS3 + vanilla JS	Design tokens, theme toggle
Testing	pytest 8.3.5 + pytest-flask 1.3.0	Feature-level integration tests
Tooling	uv	Dependency + environment management

> PROJECT.STRUCTURE — REPO LAYOUT

expense-tracker/
├── app.py                          ← Flask app, all routes, CSRF middleware
├── pyproject.toml                  ← Project metadata + dependencies
├── uv.lock                         ← uv lockfile for reproducible installs
├── .python-version                 ← Python version pin (3.13)
├── opencode.json                   ← OpenCode agent/command config
│
├── database/
│   ├── __init__.py
│   ├── db.py                       ← init_db, seed_db, CATEGORIES, get_db
│   └── queries.py                  ← CRUD + analytics SQL helpers
│
├── static/
│   ├── css/
│   │   ├── style.css               ← Global styles + design tokens
│   │   └── landing.css             ← Landing page styles
│   └── js/
│       └── main.js                 ← Theme toggle + shared JS
│
├── templates/
│   ├── base.html                   ← Shared navbar + footer
│   ├── landing.html                ← Marketing landing page
│   ├── register.html               ← Registration form
│   ├── login.html                  ← Sign-in form
│   ├── profile.html                ← User dashboard (stats, transactions, categories)
│   ├── analytics.html              ← Analytics view
│   ├── add_expense.html            ← Create-expense form (CSRF)
│   ├── edit_expense.html           ← Edit-expense form (CSRF)
│   ├── terms.html                  ← Terms and Conditions
│   └── privacy.html                ← Privacy Policy
│
├── tests/
│   ├── test_backend_connection.py  ← Smoke tests for the app boot
│   ├── test_date_filter.py         ← Profile date-filter helpers
│   ├── test_06-date-filter-profile.py
│   ├── test_07-add-expense.py      ← Add-expense flow (validation, CSRF, DB)
│   ├── test_08-edit-expense.py     ← Edit-expense flow (ownership, validation)
│   └── test_09-delete-expense.py   ← Delete-expense flow (CSRF, ownership)
│
├── seed_user.py                    ← Seed a demo user
├── seed_expenses.py                ← Seed demo expenses
└── expense_tracker.db              ← Local SQLite database (gitignored)

> QUICKSTART.SETUP — GET RUNNING IN 5 MINUTES

Prerequisites

• Python 3.13 — pinned via .python-version
• uv — fast dependency manager (recommended)

Option A — With uv (recommended)

# 1. Clone the repo
git clone https://github.com/SalikAhmad702/expense-tracker.git
cd expense-tracker

# 2. Create venv and install dependencies
uv sync

# 3. Start the development server
python app.py

The database is initialised and seeded automatically on app boot — no manual step required.

Option B — With pip

# 1. Clone the repo
git clone https://github.com/SalikAhmad702/expense-tracker.git
cd expense-tracker

# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # On Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -e .

# 4. Start the development server
python app.py

Open http://localhost:5001 in your browser 🎉

> DEV.WORKFLOW — TESTS & COMMANDS

TASK	COMMAND
Run the app	python app.py
Run the full test suite	pytest
Run a single test file	pytest tests/test_07-add-expense.py
Initialise the database only	python -c "from database.db import init_db; init_db()"
Seed the database only	python -c "from database.db import seed_db; seed_db()"
Seed a demo user	python seed_user.py
Seed demo expenses	python seed_expenses.py
Sync dependencies	uv sync
Lint / format (via opencode)	configured in opencode.json

💡 app.py calls init_db() and seed_db() on startup, so the database is ready the first time you boot the server.

> ROUTES.MAP — AVAILABLE ENDPOINTS

ROUTE	METHOD	DESCRIPTION	STATUS
/	GET	Landing page	✅ ACTIVE
/register	GET, POST	Create an account	✅ ACTIVE
/login	GET, POST	Sign in	✅ ACTIVE
/logout	GET	Sign out and clear session	✅ ACTIVE
/profile	GET	User dashboard (stats, transactions, categories, filters)	✅ ACTIVE
/analytics	GET	Analytics view	✅ ACTIVE
/expenses/add	GET, POST	Add a new expense (CSRF)	✅ ACTIVE
/expenses/<int:id>/edit	GET, POST	Edit an existing expense (CSRF)	✅ ACTIVE
/expenses/<int:id>/delete	POST	Delete an expense (CSRF)	✅ ACTIVE
/terms	GET	Terms and Conditions	✅ ACTIVE
/privacy	GET	Privacy Policy	✅ ACTIVE

All mutating endpoints are gated by @app.before_request CSRF middleware and require a signed-in user (except /register and /login). Expense endpoints enforce ownership — a user can only see and mutate their own rows.

> SECURITY.MODEL — SESSIONS, CSRF & DATA

Spendly takes a pragmatic, dependency-light approach to security:

CONCERN	MITIGATION
Password storage	werkzeug.security.generate_password_hash (PBKDF2 by default)
Password verification	Constant-time check_password_hash on login
Session integrity	Flask's signed session cookie; SECRET_KEY read from SPENDLY_SECRET_KEY env var
CSRF	Per-session token generated by @app.before_request; validated on every POST
Cookie scope	SESSION_COOKIE_SAMESITE = "Lax"
Authorisation	Expense routes check expense.user_id == session["user_id"] and 404 otherwise
Input validation	Server-side checks on amount (> 0, finite), date (YYYY-MM-DD), category (allow-list), description (≤ 200 chars)

🔐 In production, set SPENDLY_SECRET_KEY to a long random value and run behind HTTPS.

> ROADMAP — FUTURE WORK

Shipped in v0.1 ✅

• User registration, login, logout with password hashing
• Personal profile dashboard (stats, transactions, categories)
• Add / edit / delete expenses with CSRF protection
• Date filtering with presets + custom range
• Analytics view
• Dark / light theme with manual toggle
• pytest + pytest-flask test suite per feature

Next up

• CSV / Excel export of expenses
• Search across expense descriptions
• Monthly budget caps with progress bars
• Chart.js visualisations on the analytics page
• Password reset flow
• Email verification on registration

Quality of life

• Pagination on the transactions list
• Bulk delete
• Receipt attachments
• Recurring-expense templates

> CONTRIBUTION.PROTOCOL — HOW TO HELP

Quick workflow

# Fork → Branch → Commit → Push → PR
git checkout -b feature/your-improvement
git add .
git commit -m "feat: describe your change"
git push origin feature/your-improvement

Guidelines

• ✅ Follow the existing code style
• ✅ Describe what your PR changes and why
• ✅ Keep commits focused and atomic
• 🧪 Run pytest before opening a PR — every shipped feature has a matching test file

> DESIGN.AESTHETIC — VISUAL IDENTITY

Spendly uses a warm editorial aesthetic with:

ELEMENT	DETAILS
🎨 Color Palette	Deep green accent (#1a472a), warm paper tones (#f7f6f3)
✍️ Typography	DM Serif Display for headings, DM Sans for body text
🌗 Theme Support	Automatic dark/light mode detection + manual override
🔷 Icons	Custom CSS icons with geometric shapes

> SUPPORT.LICENSE — STAR · REPORT · FOLLOW

License: This project is currently unlicensed — no formal license file yet. Please reach out before using it commercially.

Found a bug? Have a feature idea? Open an Issue on GitHub — every report makes Spendly better.

If this project helped you with expense tracking or Flask development, consider giving it a ⭐ — it keeps the development going!

     

   

_{⭐ Star this repo if it helped you with expense tracking and Flask development.}