post_title	author1	post_slug	microsoft_alias	featured_image	categories	tags	ai_note	summary	post_date
Personal Finance Platform	Mauricio Silva	personal-finance	n/a		finance	django celery analytics sphinx polars	Generated with AI assistance following repository guidelines.	Full-stack personal finance platform with analytics, automation, and documentation pipelines.	2025-09-28

Personal Finance Platform

A production-minded personal finance suite built on Django, Celery, and rich analytics tooling. It ingests market data, computes portfolio metrics, and surfaces dashboards and APIs that are ready for Portainer or Leapcell deployments.

Note

The repository is organized as a multi-app Django project with Celery workers, Redis integration, and a Sphinx documentation site. Explore AGENTS.md for agent-focused guidance and the memory-bank/ folder for current project context.

Capabilities

• Unified Django apps for analytics, backtesting, tax, realtime streaming, and portfolio management.
• Data ingestion adapters (e.g., Yahoo Finance) with asynchronous pipelines powered by Celery + Redis.
• Analytics built on Polars/Pandas, QuantStats, and visualization helpers including Plotly dashboards.
• REST and WebSocket surfaces prepared via Django REST Framework and Channels-compatible patterns.
• Comprehensive Sphinx documentation with reusable toctrees, autogenerated API docs, and changelog tooling.

Architecture at a glance

Layer	Highlights
Presentation	Django templates, DRF endpoints, websocket routing in config/
Domain	Modular apps under personal_finance/ for analytics, portfolios, assets, tax, realtime, and visualization
Data & Storage	PostgreSQL (default) with SQLite fallback, Redis for async coordination
Automation	Celery workers, scheduled tasks via django-celery-beat, ETL scripts (run_finance.py, setup_database.py)
Documentation	Sphinx site with docs/index.rst toctree, sphinx-apidoc pipeline, changelog automation

Quickstart

Prerequisites

• Python 3.10 – 3.13 with pip
• PostgreSQL (optional; falls back to SQLite)
• Redis (required for Celery, optional for simple local runs)
• Docker + Docker Compose (optional, but recommended for parity)
• just command runner (optional convenience)

Local setup (virtual environment)

1. Clone and enter the repository.

2. Create a virtual environment and install dependencies.

   python -m venv .venv
   source .venv/bin/activate
   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt
   python -m pip install -r requirements-dev.txt

3. Configure environment variables.

   cp .env.example .env
   # Edit .env to set DATABASE_URL, REDIS_URL, DJANGO_SECRET_KEY, etc.

4. Initialize the database and static assets.

   python manage.py migrate
   python manage.py collectstatic --noinput

5. Start the web server (Celery optional for simple flows).

   python manage.py runserver

Docker compose workflow

just up          # or: docker compose -f docker-compose.local.yml up -d
just logs django # view container logs
just down        # or: docker compose down

Tip

The just manage <command> shortcut wraps python manage.py <command> inside the Docker Compose environment, keeping dependencies aligned with container images.

Environment configuration

Variable	Purpose	Default/Fallback
DJANGO_SETTINGS_MODULE	Controls settings module (config.settings.local for dev)	Set in .env
DJANGO_SECRET_KEY	Secret for cryptographic signing	Required
DATABASE_URL	Database connection string	Defaults to SQLite if unset
REDIS_URL	Redis connection for Celery & Channels	Required for async tasks
ALLOWED_HOSTS	Comma-separated hosts for Django	Defaults to localhost
CELERY_BROKER_URL	Broker override when not using Redis	Optional
EMAIL_*	SMTP configuration for alerts	Optional

Warning

Never commit .env or secrets. Store production credentials in your platform's secret manager (Portainer, Leapcell, GitHub Actions, etc.).

Essential workflows

• python manage.py check — validates Django configuration.
• python run_finance.py — orchestrates ETL/backtesting routines.
• python personal_finance/scripts/<name>.py — run bespoke data tasks.
• alembic upgrade head — apply non-Django schema migrations from alembic/.

Quality checks

pytest -q
ruff check .
black .
flake8 src tests --max-line-length=88 --select=E9,F63,F7,F82
pip-audit

Redis-dependent tests require a running Redis instance (docker compose up redis).

Documentation (Sphinx essentials)

The docs live in docs/ and follow Sphinx best practices:

• The index.rst root defines navigation via a .. toctree:: directive with :maxdepth: 2.
• RestructuredText directives (.. code-block::, .. glossary::, etc.) provide rich formatting.
• sphinx-apidoc generates API stubs from Django modules, and changelog_utils.py enforces release notes.
• sphinx-quickstart metadata was bootstrapped and can be revisited with sphinx-quickstart for new projects.

Build and serve docs:

make -C docs html
make -C docs livehtml          # requires sphinx-autobuild for live reload
make -C docs apidocs APP=personal_finance

Generated HTML appears under docs/_build/html. Publish via static hosting or integrate into your deployment pipeline.

Project layout

config/                   # Django settings, URLs, ASGI/WSGI, Celery app
personal_finance/
  analytics/              # Portfolio analytics services
  assets/                 # Asset import and enrichment
  backtesting/            # Strategy simulation utilities
  data_profiler/          # DataProfiler integrations and validators
  data_sources/           # Market data adapters (e.g., yfinance)
  realtime/               # Streaming & polling services
  tax/                    # Tax and compliance modules
  visualization/          # Dashboard + plotting helpers
docs/                     # Sphinx documentation suite
deploy/                   # Portainer and Leapcell deployment artifacts
docker-compose.*.yml      # Local and production compose stacks
memory-bank/              # Living context for AI agents
AGENTS.md                 # Agent operating handbook

Deployment playbook

• Portainer: Use assets under deploy/portainer/ to ship containers with Redis, PostgreSQL, Celery, and web services.
• Leapcell: Follow deploy/leapcell/ templates and ensure environment variables align with cloud secrets.
• Docker Compose (production): docker-compose.production.yml includes hardened settings, static file serving via WhiteNoise, and background workers.

Documentation

📚 Comprehensive Sphinx documentation is available at: https://maugx3.github.io/personal-finance/

Documentation Structure

The documentation follows the Diátaxis framework and includes:

• 🚀 Quick Start Guide: Get up and running in minutes
• 🏗️ Architecture Overview: System design and component interactions
• ⚙️ Configuration Reference: Environment variables, Django settings, and security
• 🔌 API Documentation: Complete REST API reference with examples
• 📊 Feature Modules: Deep-dive guides for backtesting, visualization, tax reporting, real-time data, and data profiling
• 🚀 Deployment Guide: Production deployment for Docker, cloud platforms, and security hardening
• 🔧 Development Guide: Local setup, testing, code quality, and contribution guidelines

Building Documentation Locally

# Install documentation dependencies
pip install -r requirements-docs.txt

# Build documentation
./build-docs.sh

# Or manually:
cd docs
make html
# Open docs/_build/html/index.html in your browser

Documentation Deployment

Documentation is automatically built and deployed to GitHub Pages via GitHub Actions when changes are pushed to the main branch. The workflow builds the Sphinx documentation and publishes it at the GitHub Pages URL.

Reference materials

• AGENTS.md for deep-dive operational procedures.
• memory-bank/ for active decisions, progress tracking, and task backlog.
• docs/ for narrative guides (howto.rst, users.rst, changelog utilities`).
• Top-level usage guides (BACKTESTING_USAGE.md, REALTIME_USAGE.md, VISUALIZATION_USAGE.md, TAX_USAGE.md) for feature-specific walkthroughs.