Family financial management system with a predictive engine based on seasonal harmonic regression.
- User registration and authentication for users and households
- Import and categorization of financial transactions
- Dashboard with consolidated view of income, expenses, and balance
- Predictive engine for cash flow projection (3-6 months) using seasonal harmonic regression via OLS
- Residual analysis and statistical diagnostics (Ljung-Box, Shapiro-Wilk, ACF/PACF)
- Financial chatbot integrated with generative AI (Google Gemini)
- Python >= 3.13
- uv (package manager)
# Clone the repository
git clone https://github.com/your-username/moneyin.git
cd moneyin
# Install dependencies with uv
uv sync
# Copy the environment configuration file
cp .env.example .env
# Edit .env with your API keys (GEMINI_API_KEY, JWT_SECRET, etc.)# Start the development server
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000The server will be available at http://localhost:8000.
# Start JupyterLab
uv run jupyter labOpen the notebook notebooks/analise_preditiva_sazonal.ipynb and run all cells in sequence.
| # | Cell | Description |
|---|---|---|
| 1 | Imports | Loads libraries and configures visual style |
| 2 | Data loading | Reads transactions from the SQLite database and builds monthly series |
| 3 | Time decomposition | Decomposes the series into trend, seasonality, and residuals |
| 4 | White noise | Tests whether residuals are white noise (Ljung-Box) |
| 5 | HarmonicRegression class | OLS implementation with Gauss-Jordan (pure Python) |
| 6 | Residual diagnostics | Complete analysis (9 plots: QQ-Plot, ACF, PACF, etc.) |
| 7 | Walk-forward validation | Step-by-step cross-validation without data leakage |
| 8 | Delivery chart | Final forecast with 95% confidence interval |
| 9 | Figure 3 | Descriptive residual chart (white paper style) |
Results obtained with a 12-month series (Jul/2025 - Jun/2026). MAE and RMSE are normalized as a percentage of the mean absolute monthly cash flow, making the metrics scale-free and directly comparable across different households:
| Metric | Value |
|---|---|
| Mean MAE | 151.65% |
| Mean RMSE | 171.22% |
| Mean MAPE | 270.43% |
| Ljung-Box p_min | 0.1077 |
Note: The high MAPE is inflated by values close to zero and sign changes in the series. MAE and RMSE are normalized by the mean absolute monthly cash flow, expressing the average forecast error as a percentage of a typical month's flow.
These values are high, but that is expected given the nature of the data rather than a flawed implementation:
- MAE (~152%) and RMSE (~171%) of the typical monthly flow mean the average error is larger than a typical month itself. RMSE > MAE also signals the presence of occasional large errors (e.g., window
8-->11reached a MAE of R$ 8,029). - Short and volatile series: only 12 observations, with training windows of 4-9 months in walk-forward validation (near cold-start), and monthly flows swinging from about -R$ 1,717 to +R$ 12,510.
- Near-unpredictable signal: the Ljung-Box test (p_min = 0.1077) does not reject white noise, so there is little seasonal/trend structure to exploit. When residuals are white noise, no model can do much better than the historical mean.
- Wide confidence intervals: with a residual standard error of ~R$ 4,467, the 95% CI for a 6-month projection is very wide (e.g., Jul/2026 forecast of R$ 1,422 with bounds -7,333 to +10,178).
Conclusion: for a 3-6 month projection, the model should not be used for exact figures, but as a directional signal (trend and seasonal behavior). Accuracy is expected to improve substantially once the series reaches 24-36 months of history. The main value of this study is the statistical diagnosis (residuals behaving as white noise), not the point forecast precision.
Figures are saved automatically during notebook execution:
| Figure | File | Description |
|---|---|---|
| Time decomposition | figs/decomposicao_temporal.png |
Series decomposed into trend, seasonality, and residuals |
| White noise | figs/white_noise_analysis.png |
Histogram, QQ-Plot, ACF, and PACF of decomposition residuals |
| Full diagnostics | figs/residual_diagnostics.png |
9 diagnostic plots of the harmonic model |
| Final forecast | figs/previsao_final.png |
History + projection with 95% CI and residuals |
| Residuals (white paper) | figs/residuos_ruido_branco.png |
Residuals, density, and ACF in 1x3 format |
moneyin/
├── app/ # FastAPI application
│ ├── api/routers/ # REST endpoints
│ ├── core/ # Configuration and database
│ ├── models/ # SQLModel models
│ ├── schemas/ # Pydantic schemas
│ ├── services/ # Business logic
│ └── templates/ # Jinja2 templates
├── data/ # Example data
├── figs/ # Generated figures
├── notebooks/ # Jupyter notebooks
│ └── analise_preditiva_sazonal.ipynb
├── moneyin.db # SQLite database
├── pyproject.toml # uv configuration
└── relatorio_tecnico_sbc_finep.md # Technical report
Families with variable income can use the predictive engine to anticipate periods of negative balance and take preventive decisions (postponing purchases, negotiating payment terms).
The dashboard allows visualizing the evolution of income and expenses over time, identifying spending trends and savings opportunities.
Time decomposition reveals cyclical patterns (13th salary, vacations, school holidays) that influence cash flow, enabling advanced planning.
Normality (Shapiro-Wilk), autocorrelation (Ljung-Box), and homoscedasticity tests ensure the model is reliable for decision-making.
- Backend: FastAPI, SQLModel, Uvicorn
- Database: SQLite
- Data Science: pandas, numpy, scipy, scikit-learn, statsmodels, matplotlib, seaborn
- AI: Google Gemini (financial chatbot)
- Package Management: uv