# davidmtp58/finlytics architecture

> Architecture diagram of the GitHub repository davidmtp58/finlytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davidmtp58/finlytics
- Repository: https://github.com/davidmtp58/finlytics

## Overview

Finlytics is a personal-finance statement analyzer. Its main workflow takes a user-uploaded CSV, PDF, or image through transaction extraction and categorization, then lets the user filter and correct transactions before viewing financial summaries and spending categories. The terminal report is a separate CSV-based workflow. The README documents image support; the sampled PDF-named extraction function also selects an image MIME type. The graph reflects documented capabilities, while omitting uncertain details beyond the sampled source.

Main entry points: [`finlytics.py`](https://github.com/davidmtp58/finlytics/blob/main/finlytics.py) (Hybrid classification), [`app.py`](https://github.com/davidmtp58/finlytics/blob/main/app.py) (Streamlit app), [`relatorio_financeiro.py`](https://github.com/davidmtp58/finlytics/blob/main/relatorio_financeiro.py) (Terminal report), [`categorias.py`](https://github.com/davidmtp58/finlytics/blob/main/categorias.py) (Local category rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_streamlit_app["Streamlit app<br/>[app.py]"]
  node_consent_privacy["Consent and privacy<br/>[app.py]"]
  node_transaction_editor["Filter and edit<br/>[app.py]"]
  node_financial_views["Metrics and chart<br/>[app.py]"]
  node_terminal_report["Terminal report"]
end

subgraph group_ingestion["Statement processing"]
  node_csv_reader["CSV loading<br/>[finlytics.py]"]
  node_document_extraction["PDF/image extraction<br/>[finlytics.py]"]
  node_transaction_data["Transaction DataFrame<br/>[finlytics.py]"]
end

subgraph group_analysis["Categorization and analysis"]
  node_local_rules["Local category rules<br/>[categorias.py]"]
  node_classification["Hybrid classification<br/>[finlytics.py]"]
  node_category_options["Valid categories<br/>[categorias.py]"]
  node_summary_calculation["Income and balance<br/>[finlytics.py]"]
  node_spending_ranking["Spending ranking<br/>[finlytics.py]"]
end

subgraph group_integration["External AI"]
  node_gemini{{"Gemini API"}}
end

node_user(("User"))

node_user -->|"confirms consent"| node_consent_privacy
node_consent_privacy -->|"permits use"| node_streamlit_app
node_user -->|"uploads statement"| node_streamlit_app
node_streamlit_app -->|"loads CSV"| node_csv_reader
node_streamlit_app -->|"sends PDF/image"| node_document_extraction
node_csv_reader -->|"reads into"| node_transaction_data
node_document_extraction -->|"sends document"| node_gemini
node_gemini -->|"returns JSON"| node_document_extraction
node_document_extraction -->|"builds DataFrame"| node_transaction_data
node_csv_reader -->|"classifies rows"| node_classification
node_document_extraction -->|"classifies rows"| node_classification
node_classification -->|"checks keywords"| node_local_rules
node_local_rules -->|"returns category"| node_classification
node_classification -.->|"classifies fallback"| node_gemini
node_gemini -.->|"returns category"| node_classification
node_classification -->|"uses category set"| node_category_options
node_streamlit_app -->|"filters and edits"| node_transaction_editor
node_transaction_data -->|"provides transactions"| node_transaction_editor
node_user -->|"selects month, edits"| node_transaction_editor
node_transaction_editor -->|"passes edited data"| node_financial_views
node_financial_views -->|"calculates totals"| node_summary_calculation
node_financial_views -->|"ranks expenses"| node_spending_ranking
node_user -->|"runs report"| node_terminal_report
node_terminal_report -->|"categorizes CSV rows"| node_local_rules
node_terminal_report -->|"reads example CSV"| node_transaction_data

click node_streamlit_app "https://github.com/davidmtp58/finlytics/blob/main/app.py"
click node_consent_privacy "https://github.com/davidmtp58/finlytics/blob/main/app.py"
click node_transaction_editor "https://github.com/davidmtp58/finlytics/blob/main/app.py"
click node_financial_views "https://github.com/davidmtp58/finlytics/blob/main/app.py"
click node_terminal_report "https://github.com/davidmtp58/finlytics/blob/main/relatorio_financeiro.py"
click node_csv_reader "https://github.com/davidmtp58/finlytics/blob/main/finlytics.py"
click node_document_extraction "https://github.com/davidmtp58/finlytics/blob/main/finlytics.py"
click node_transaction_data "https://github.com/davidmtp58/finlytics/blob/main/finlytics.py"
click node_local_rules "https://github.com/davidmtp58/finlytics/blob/main/categorias.py"
click node_classification "https://github.com/davidmtp58/finlytics/blob/main/finlytics.py"
click node_category_options "https://github.com/davidmtp58/finlytics/blob/main/categorias.py"
click node_summary_calculation "https://github.com/davidmtp58/finlytics/blob/main/finlytics.py"
click node_spending_ranking "https://github.com/davidmtp58/finlytics/blob/main/finlytics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit_app,node_consent_privacy,node_transaction_editor,node_financial_views,node_terminal_report,node_user toneBlue
class node_csv_reader,node_document_extraction,node_transaction_data toneAmber
class node_local_rules,node_classification,node_category_options,node_summary_calculation,node_spending_ranking toneMint
class node_gemini toneRose
```

## Components

### User interfaces

- [Streamlit app](https://github.com/davidmtp58/finlytics/blob/main/app.py): `app.py`
- [Consent and privacy](https://github.com/davidmtp58/finlytics/blob/main/app.py): `app.py`
- [Filter and edit](https://github.com/davidmtp58/finlytics/blob/main/app.py): `app.py`
- [Metrics and chart](https://github.com/davidmtp58/finlytics/blob/main/app.py): `app.py`
- [Terminal report](https://github.com/davidmtp58/finlytics/blob/main/relatorio_financeiro.py): `relatorio_financeiro.py`

### Statement processing

- [CSV loading](https://github.com/davidmtp58/finlytics/blob/main/finlytics.py): `finlytics.py`
- [PDF/image extraction](https://github.com/davidmtp58/finlytics/blob/main/finlytics.py): `finlytics.py`
- [Transaction DataFrame](https://github.com/davidmtp58/finlytics/blob/main/finlytics.py): `finlytics.py`

### Categorization and analysis

- [Local category rules](https://github.com/davidmtp58/finlytics/blob/main/categorias.py): `categorias.py`
- [Hybrid classification](https://github.com/davidmtp58/finlytics/blob/main/finlytics.py): `finlytics.py`
- [Valid categories](https://github.com/davidmtp58/finlytics/blob/main/categorias.py): `categorias.py`
- [Income and balance](https://github.com/davidmtp58/finlytics/blob/main/finlytics.py): `finlytics.py`
- [Spending ranking](https://github.com/davidmtp58/finlytics/blob/main/finlytics.py): `finlytics.py`

### External AI

- **Gemini API**

### Other components

- **User**

## Connections

- User → Consent and privacy: confirms consent
- Consent and privacy → Streamlit app: permits use
- User → Streamlit app: uploads statement
- Streamlit app → CSV loading: loads CSV
- Streamlit app → PDF/image extraction: sends PDF/image
- CSV loading → Transaction DataFrame: reads into
- PDF/image extraction → Gemini API: sends document
- Gemini API → PDF/image extraction: returns JSON
- PDF/image extraction → Transaction DataFrame: builds DataFrame
- CSV loading → Hybrid classification: classifies rows
- PDF/image extraction → Hybrid classification: classifies rows
- Hybrid classification → Local category rules: checks keywords
- Local category rules → Hybrid classification: returns category
- Hybrid classification → Gemini API: classifies fallback
- Gemini API → Hybrid classification: returns category
- Hybrid classification → Valid categories: uses category set
- Streamlit app → Filter and edit: filters and edits
- Transaction DataFrame → Filter and edit: provides transactions
- User → Filter and edit: selects month, edits
- Filter and edit → Metrics and chart: passes edited data
- Metrics and chart → Income and balance: calculates totals
- Metrics and chart → Spending ranking: ranks expenses
- User → Terminal report: runs report
- Terminal report → Local category rules: categorizes CSV rows
- Terminal report → Transaction DataFrame: reads example CSV