PyFinBot

Table of Contents

• Introduction
• Key Features
• Tech Stack
• Project Structure
• Getting Started
• API Overview
• Testing
• Roadmap
• License
• Citation

---

Introduction

PyFinBot is a lightweight, extensible financial tracking tool built in Python, designed to help users manage and analyse their stock trading activity. By leveraging relational database design and SQL-based reporting, PyFinBot offers precise insights into holdings, transaction history, and capital gains or losses per financial year. Ideal for personal investors or hobbyist traders, it serves as a transparent and customisable alternative to spreadsheet-based tracking.

🚀 Key Features

• 📊 Transaction Recording: Track Buy/Sell orders with support for fees, prices, values, and financial year grouping.
• 📥 CSV/Excel Import: Bulk-import transactions from a spreadsheet — via the API or the web Import page — with per-row validation and error reporting.
• 📆 Holdings Snapshot: Query real-time or historical stock units held as of any given date.
• 💰 Capital Gain/Loss Calculation: Determine net gains/losses per stock by financial year using average cost basis.
• 🔗 Relational Database Design: Clean, normalised schema to ensure data integrity and efficient queries.
• 🔐 Multi-user Support: JWT-authenticated accounts — each user only sees their own transactions and reports.
• 📦 Modular Architecture: Built to be extended with additional features like tax reports, visualisations, or API integration.

Tech Stack

• API: FastAPI + Uvicorn
• ORM / Models: SQLModel on top of SQLAlchemy 2.0 (async)
• Migrations: Alembic
• Database: PostgreSQL (asyncpg / psycopg2) in production, SQLite (aiosqlite) for tests
• Import/Reporting: pandas, openpyxl
• Testing: pytest, pytest-asyncio, httpx

Project Structure

src/pyfinbot/
├── api/       # FastAPI routers — users, stocks, transactions, import, reports (auto-registered under /api)
├── core/      # Settings, auth dependencies, sorting/filtering helpers, market sync
├── db/        # Async SQLAlchemy engine/session setup
├── models/    # SQLModel ORM models (User, Stock, Transaction)
├── schemas/   # Pydantic request/response schemas
├── alembic/   # Database migrations
└── pyfinbot.py  # FastAPI app factory / entrypoint

Getting Started

Prerequisites

• Python 3.12+
• A PostgreSQL database (or SQLite for local experimentation)

Installation

git clone https://github.com/GreenMachine582/PyFinBot.git
cd PyFinBot
pip install -r requirements.txt

Configuration

Copy .env.example to .env in the project root and fill in your values:

cp .env.example .env

SECRET_KEY signs JWT access tokens. If unset, a random key is generated on every process start (fine for local dev, but every restart invalidates all issued tokens) — set it explicitly for any deployment that needs to survive a restart.

GMAIL_ADDRESS/GMAIL_APP_PASSWORD are only required to use POST /api/emails/sync-commsec, which reads Commsec trade confirmation emails via IMAP. An App Password grants full mailbox read access (not scoped to Commsec mail), so a dedicated Gmail account or label is recommended over your primary inbox.

ENVIRONMENT/CORS_ORIGINS control cross-origin access: in development (the default), all origins are allowed when CORS_ORIGINS is unset, for frictionless local testing; in production, no cross-origin access is allowed unless CORS_ORIGINS is set to an explicit comma-separated allow-list.

Database Migrations

Apply the schema to your database:

alembic upgrade head

Running the App

uvicorn src.pyfinbot.pyfinbot:app --reload

Or with Docker Compose:

docker compose up

Once running, interactive API docs are available at http://localhost:8000/docs (or port 8001 under Docker Compose).

API Overview

All routes are mounted under /api. See /docs for full request/response schemas. Every route except POST /api/users/ (registration) and POST /api/auth/login requires a Bearer token — register a user, log in to get a token, then pass Authorization: Bearer <token> on subsequent requests.

Router	Prefix	Purpose
Auth	/api/auth	POST /login — exchange a user id + password for a JWT access token
Users	/api/users	Create (register) and manage users
Stocks	/api/stocks	CRUD for tracked stocks, plus market sync
Transactions	/api/transactions	CRUD for Buy/Sell transactions (PUT accepts any subset of fields; total/cost/FY are recomputed)
Import	/api/transactions/import	Bulk-import transactions from CSV/Excel
Emails	/api/emails	Sync Commsec bought/sold confirmation emails into transactions
Dividends	/api/dividends	Sync per-stock dividend history (yfinance)
Reports	/api/reports	Holdings, FY capital-gains, and dividend-income reports

Testing

PyFinBot includes a pytest suite covering all routers, models/schemas, and core utilities.

pytest

🎯 Roadmap

1. ✅ MVP – Schema design, transaction insertion, and SQL-based queries.
2. ✅ Import System – CSV or Excel import of stock transactions.
3. ✅ Reporting Module – FY-based reports for holdings and capital gains.
4. ✅ Commsec Email Ingestion – Parse bought/sold confirmation emails (Gmail IMAP) into transactions.
5. ✅ Dividend Tracking – Pull per-stock dividend history (yfinance) and report income by FY.
6. 🧮 FIFO Method Support – Accurate gain/loss computation based on FIFO accounting.
7. 🌐 CLI Interface – Interact via command line with exportable summaries.
8. 🖥️ Web Dashboard (optional) – View and interact with data through a simple front end.

Day-to-day and in-progress work is tracked in todo.md, which serves as the project's living backlog across sessions. Shipped versions and their notes: CHANGELOG.md and the Releases page, both written by release-please. Branches, PRs and how a release is cut: CONTRIBUTING.md.

License

PyFinBot is licensed under the MIT License, see LICENSE for more information.

Citation

If you use this software, please cite it using the metadata in CITATION.cff.