gizmoduck/README.md

Gizmoduck

Gizmoduck is a privacy-conscious personal finance application for importing, organizing, and understanding financial activity. It is a clean successor to the Robopato prototype, carrying forward what was learned from parsing Banco do Brasil account statements and Ourocard invoices without inheriting the prototype's notebook-driven architecture or historical data.

Goals

The initial product should make it possible to:

• manage bank accounts and credit cards;
• import supported statement and invoice formats;
• preview and validate an import before committing it;
• detect duplicates and preserve import provenance;
• organize transactions by payee and category;
• represent transfers, refunds, and installments correctly;
• inspect monthly cash flow and spending summaries; and
• export and back up user-owned data.

The first release is intended to be a reliable local application. Bank APIs, investment tracking, mobile clients, receipt recognition, forecasting, and AI categorization are possible later additions, not MVP requirements.

Project documentation

Start with contributor instructions, then read the product scope, architecture, data policy, and delivery roadmap. Owners can follow the copy-paste local workflow guide from reviewed import through reports, export, and verified backup restoration.

Reconciliation

Open Reconciliation, select an account, and enter a checkpoint date with the institution balance. Review the preview before confirming the checkpoint. Checkpoint dates are inclusive, so they include activity posted on that date. A new checkpoint corrects a prior checkpoint. Newly imported activity or a later backdated transaction can change a previously reconciled status, so review the status and record a new checkpoint after verifying the institution balance.

Architecture

The approved technical choices are:

• Python and Django for the application;
• PostgreSQL for persistent storage;
• schema migrations from the first release;
• Docker Compose for local infrastructure;
• pytest for automated tests; and
• pure, source-specific parsers feeding a normalized import pipeline.

Changes require explicit owner approval and a documented architectural decision. Bank-account imports use CSV; Banco do Brasil/Ourocard credit-card imports use TXT. OFX is not supported.

The import flow should remain separate from database persistence:

source document
    -> source-specific parser
    -> normalized candidate transactions
    -> validation and duplicate detection
    -> import preview
    -> committed transactions
    -> categorization and reporting

Privacy and security

Financial documents, database exports, credentials, and local application data must never be committed to Git. The repository .gitignore excludes common financial source formats and local data directories, but contributors must still inspect staged changes before every commit.

Development and application processes should use separate, least-privilege database accounts. Imports and material data changes should record their actor, source, timestamp, and outcome so human, application, and automated activity can be distinguished.

Use only synthetic or thoroughly sanitized financial fixtures in automated tests and documentation.

Project status

The local MVP is implemented: contributor foundation, application skeleton, financial domain, reviewed imports, owner screens, monthly reports, portable exports, and verified PostgreSQL backups. The local Django application uses PostgreSQL, explicit migrations, and isolated tests. See the financial domain guide for supported writes and accounting conventions, and reviewed imports for the local CSV/Ourocard preview and commit workflow.

Implemented milestones:

1. Define the MVP and privacy model.
2. Scaffold the application, database, migrations, and test suite.
3. Implement and test the core financial domain model.
4. Build the import-preview pipeline using sanitized fixtures.
5. Add transaction management, categorization, and basic reports.

Development

Follow the local development guide for configuration, Docker Compose startup, migrations, tests, and database-role details, then use the local owner workflows for daily operation and recovery.

The readiness endpoint is available at http://127.0.0.1:8000/health/ after startup. Do not place real financial files inside tracked directories.