Finance Report Documentation¶

Welcome to the Finance Report documentation — your comprehensive guide to building and using a personal financial management system with double-entry bookkeeping and bank reconciliation.

🎯 Project Vision¶

Read the North Star goals and decision criteria before deep technical work:

Project Vision (North Star)

📖 Documentation Guide¶

This documentation is organized into four main sections to help you find what you need quickly:

:material-book-open-page-variant:{ .lg .middle } User Guide

Learn how to use Finance Report for daily financial management

:octicons-arrow-right-24: Start here
:material-api:{ .lg .middle } API Reference

Complete REST API documentation for developers

:octicons-arrow-right-24: View APIs
:material-file-document-multiple:{ .lg .middle } Technical Documentation

Architecture, design decisions, and implementation details

:octicons-arrow-right-24: SSOT Docs
:material-hammer-wrench:{ .lg .middle } Development Guide

Setup development environment and contribute to the project

:octicons-arrow-right-24: Project Overview

🚀 Quick Start¶

New to Finance Report? Follow these steps:

:material-rocket-launch:{ .lg .middle } Getting Started

Set up your account and start tracking finances in minutes

:octicons-arrow-right-24: Quick start
:material-bank:{ .lg .middle } Account Management

Create and organize accounts using the Chart of Accounts

:octicons-arrow-right-24: Learn more
:material-book-open-variant:{ .lg .middle } Journal Entries

Record transactions with double-entry bookkeeping

:octicons-arrow-right-24: View guide
:material-sync:{ .lg .middle } Bank Reconciliation

Match bank statements with your records automatically

:octicons-arrow-right-24: Reconcile

🌟 Key Features¶

Feature	Description	Status
Double-Entry Bookkeeping	Every transaction balanced with debits and credits	✅ Available
Chart of Accounts	5 account types: Asset, Liability, Equity, Income, Expense	✅ Available
Bank Statement Import	Upload PDF/CSV bank statements	✅ Available
AI-Powered Parsing	Gemini 2.0 Flash (free) extracts transactions from statements	✅ Available
Smart Reconciliation	Multi-dimensional matching with confidence scoring	✅ Available
Financial Reports	Balance sheet, income statement, cash flow	🚧 Coming Soon
AI Financial Advisor	Personalized insights and recommendations	✅ Available

📚 Documentation Structure¶

This documentation site is organized as follows:

User Guide¶

Step-by-step guides for end users:

Getting Started — Setup and first steps
Account Management — Creating and managing accounts
Journal Entries — Recording transactions
Bank Reconciliation — Matching bank statements
Reports & Dashboards — Financial reporting
AI Advisor — Using the AI financial advisor

API Reference¶

Complete REST API documentation:

API Overview — Authentication and common patterns
Accounts API — Account management endpoints
Journal Entries API — Transaction recording endpoints
Reconciliation API — Bank reconciliation endpoints
AI Advisor API — Chat and insights endpoints

Technical Documentation (SSOT)¶

Single Source of Truth for technical decisions:

Architecture Overview — System architecture and design principles
Accounting Model — Double-entry bookkeeping rules
Reconciliation Engine — Matching algorithms
Statement Extraction — AI parsing pipeline
Reporting — Report generation logic
AI Advisor — AI advisor implementation
Database Schema — Database design and migrations
Development Guide — Development environment setup

Development & Project Management¶

Project tracking and development guides:

Project Overview — EPIC tracking and roadmap
Design Decisions — Key architectural decisions
EPICs: Setup | Double-Entry | Statement Parsing | Reconciliation | Reporting | AI Advisor | Deployment

🏗️ System Architecture¶

graph TB
    subgraph Frontend["Frontend (Next.js 14)"]
        UI[React UI]
        TQ[TanStack Query]
    end

    subgraph Backend["Backend (FastAPI)"]
        API[REST API]
        SVC[Services Layer]
        DB[(PostgreSQL)]
    end

    subgraph AI["AI Services"]
        Gemini[Gemini 2.0 Flash (free)]
    end

    UI --> TQ --> API
    API --> SVC --> DB
    SVC --> Gemini

For detailed architecture documentation, see Architecture Overview.

🔗 Quick Links¶

Live Application: report.zitian.party
API Documentation: report.zitian.party/api/docs
GitHub Repository: github.com/wangzitian0/finance_report
Report Issues: GitHub Issues

🤝 Contributing¶

Interested in contributing? Check out:

Development Guide — Setup your development environment
Project Overview — Understand the project structure and roadmap

📄 License¶

MIT License — See repository for details.