FinFlow — Full-Stack Personal Finance Manager

FinFlow is a robust, high-performance personal finance management system designed for modern personal accounting. It allows users to track incomes and expenses, manage flexible categories and accounts, and analyze financial health with real-time multi-currency conversion and smart data processing.

Production Status: The project has successfully passed the staging phase and is fully deployed in a secure production environment. Active support, monitoring, and regular architectural improvements are performed 24/7.

---

Live Production

The application is fully operational and accessible globally via secure HTTPS protocol: https://finflow.website

---

Deployment & DevOps Architecture

The production environment is built with fault-tolerance, isolation, and industry-standard security practices in mind:

• Web Server & Reverse Proxy: Nginx handles high-performance static file serving for the React frontend (/dist package compiled via pnpm) and acts as a reverse proxy for the backend, managing transparent route rewrites (stripping /api/ prefixes) and custom header injection (X-Real-IP, X-Forwarded-For).
• Containerization & Isolation: The entire backend ecosystem (FastAPI ASGI application, PostgreSQL database, and Redis cache) is containerized via Docker Compose. Container ports are strictly isolated within an internal virtual bridge network, leaving no exposed database ports to the host network.
• SSL/TLS Encryption: Automated cryptographic certificates provided by Let's Encrypt (Certbot) with enforced global HTTP-to-HTTPS redirection.
• Server Hardening & Security: Host-level access is restricted strictly to authorized SSH keys with password authentication completely disabled. The server utilizes automated brute-force protection, strict network-level firewalls, and active log parsing to mitigate remote access risks.

Awards & Recognition

FinFlow secured 1st Place at a regional college web development and programming competition (May 2026) and has received official accreditation from the Ministry of Education and Science of Ukraine. The project was highly evaluated by the expert jury for its complex asynchronous backend architecture, Redis caching integration, and fault-tolerant external API parsing.

Note: To maintain the developer's privacy and anonymity in the open-source community, real names (FIO) are not published publicly. For official verification, accreditation details, or further inquiries regarding the competition, please contact the repository owner via Direct Messages.

Key Features

• Secure Authentication: JWT-based system with Access & Refresh token rotation, Argon2 password hashing, and built-in rate limiting (SlowAPI).
• Two-Step Email Verification: Registration requires email confirmation via a 6-digit one-time code (valid for 10 minutes), delivered through the Resend API. Disposable and temporary email addresses are blocked at the schema level.
• Real-time Multi-currency: Automatic exchange rate synchronization (via NBU API) with Redis caching. View your balance in USD, EUR, UAH, PLN (Zloty), RUB, or CZK.
• Accounts Management: Flexible multi-account system to organize finances by wallet, card, cash, or savings.
  • Two default accounts are automatically created for every new user upon registration.
  • Free-tier users are limited to 2 accounts: one can be deleted (with data reassigned/removed accordingly), while the other is protected — the app enforces at least one active account at all times.
  • Accounts can be renamed at any time.
  • A custom icon is selected once, at account creation time; icon changes after creation are not yet supported (planned for a future release).
• Financial Analytics:
  • Summary dashboards for Balance, Income, and Expenses.
  • Average daily spending and income calculation for specific periods.
  • Real-time balance conversion based on live market rates.
• Advanced Transaction Management:
  • Cursor-based Pagination: Optimized infinite scrolling for smooth browsing of large transaction histories.
  • Dynamic Filtering: Comprehensive data filtering by date range, category, or type.
  • Smart Date Parsing: Intelligent input processor (English/Russian support).
• Data Portability: Full support for Importing and Exporting financial history via JSON files (with strict backend payload size validation).
• Modern UI/UX: Clean, responsive dashboard with native Dark Mode support.

UI & Application Flow

Main Dashboard

A comprehensive overview of your current balance, incomes, and expenses, automatically converted into your preferred currency using live NBU rates.

Profile

Profile where you can change your account information.

Accounts

Manage your accounts (cards, cash, savings, etc.) from a dedicated section. Every user starts with 2 default accounts; free-tier users can rename an account or delete one (a single active account is always required and cannot be removed). A custom icon is chosen when creating a new account.

Available account icons to choose from during creation:

Analytics & Visualizations

Dynamic charts and diagrams breaking down expense categories and balance dynamics over time.

Transaction Management

Intuitive modals for quick entry creation with category, account, and currency selection.

Transparent Backend Logging

The backend features a strict, time-zone-aware logging system capturing everything from JWT rotation and payload validation to asynchronous Redis caching and Telegram Bot notifications. Note: All tokens, usernames, endpoints, and credentials shown in the documentation and screenshots are strictly mock data used for demonstration purposes and do not represent real-world active secrets.

Tech Stack

Backend

Frontend

Authentication Flow

Registration is a two-step process designed to ensure account validity:

1. Step 1 — Sign Up: The user submits a username, email, and password. The backend validates the input (password: 12–64 characters, no disposable email domains) and sends a 6-digit verification code to the provided email via Resend.
2. Step 2 — Email Verification: The user enters the code received in the email. Upon successful verification, the account is created (along with 2 default financial accounts) and the user is automatically signed in via HttpOnly cookie-based tokens.

Password reset is also fully supported — a time-limited reset link (valid 10 minutes) is sent to the user's email and processed on a dedicated /reset-password page.

Project Structure

├── app/                        # FastAPI Application (Endpoints & Main)
├── core/                       # Security, JWT, Dependencies, and Exceptions
├── database/                   # SQLAlchemy Models and Engine setup
├── frontend/                   # React/TypeScript source code
├── limiter/                    # Rate limiting configuration
├── migrations/                 # Database migration history (Alembic)
├── schemes/                    # Pydantic models for data validation
├── services/                   # Data access and business logic
├── telegram/                   # Admin panel & Logs (Telegram Bot integration)
├── tests/                      # Integration and Mock test suites
├── .dockerignore               # Docker ignore rules
├── .env                        # Environment variables (Local)
├── .gitattributes              # Git attributes config
├── .gitignore                  # Git ignore rules
├── alembic.ini                 # Alembic configuration
├── config.py                   # Global application configuration
├── docker-compose.test.yml     # Orchestration for testing environment
├── docker-compose.yml          # Production/Dev orchestration config
├── Dockerfile                  # Docker image build instructions
├── pytest.ini                  # Pytest configuration
├── README.md                   # Project documentation
├── requirements.txt            # Backend dependencies
└── script.py                   # External API integration (Currency parsing)

Testing

The system is covered by a comprehensive test suite to ensure reliability and security.

pytest

CI/CD Pipeline

FinFlow uses GitHub Actions to automate testing and deployment on every push to the main branch (or via manual trigger through workflow_dispatch). The pipeline consists of two sequential jobs:

1. test — spins up a clean environment on ubuntu-latest:

   • Checks out the repository.
   • Reconstructs the .env file from a GitHub Secret (ENV_FILE), keeping sensitive configuration out of the codebase.
   • Starts an isolated test database via docker-compose.test.yml.
   • Sets up Python 3.12 and installs backend dependencies.
   • Runs the full pytest suite. Deployment is blocked if any test fails.

2. deploy — runs only after test succeeds (needs: test):

   • Connects to the production VPS over SSH (appleboy/ssh-action), using host, username, and private key stored as encrypted GitHub Secrets (VPS_HOST, VPS_USER, VPS_SSH_KEY).
   • Pulls the latest changes on the server (git pull).
   • Rebuilds and restarts backend containers via docker compose up -d --build.
   • Rebuilds the frontend production bundle (pnpm run build) inside the frontend/ directory.

Security & Performance

• Brute-force protection: Strict rate limiting implemented on sensitive endpoints.
• Email Verification: All new accounts require confirmation via a one-time 6-digit code. Disposable email domains are blocked via disposable-email-domains.
• Data Integrity: Powered by Pydantic v2, ensuring strict validation at the schema level.
• Asynchronous Architecture: Fully non-blocking I/O operations for high concurrency.
• Secure Data Storage: Professional standards using HttpOnly, Secure, and SameSite cookie attributes.

---

Note: Local deployment instructions and environment configurations are restricted for security reasons. For access or inquiries, please contact the repository owner.