Skip to content

SKOHscripts/finance-tracker

BranchesTags

Repository files navigation

💼 Finance Tracker – Gestion de Portefeuille Intelligente

Version License Tests Python

Finance Tracker un outil complet et facile à utiliser pour gérer, analyser et optimiser vos investissements, comprendre l'impact des intérêts composés et des impôts, ou simplement planifier un budget. Bien que pensée d'abord pour les francophones, elle sera bientôt traduite pour une diffusion maximale. La protection de votre vie privée et de votre souveraineté est assurée par le stockage local des informations.

📑 Table des Matières

✨ Présentation Générale

Finance Tracker est une application de gestion de portefeuille qui permet de :

  • Centraliser vos produits financiers (cash, SCPI, assurance-vie, PER, Bitcoin, etc.) ou vos projets (achat de vélo électrique, etc.).
  • Suivre vos transactions et valorisations dans le temps.
  • Calculer des indicateurs de performance réalistes (MWRR, rendement annualisé, etc.).
  • Visualiser l’évolution de votre patrimoine via un dashboard web clair.
  • Générer des rapports PDF et utiliser une CLI pour les utilisateurs avancés.

Deux publics cibles :

  • 👤 Utilisateurs finaux : veulent utiliser l’application web et suivre leurs investissements.
  • 💻 Développeurs / power users : veulent installer en local, utiliser la CLI ou contribuer au projet.

⚡ Quick Start

Utilisateur – Zéro installation

  1. Ouvrez l’application hébergée : 👉 https://finance-tracker-skohscripts.streamlit.app/
  2. Créez / chargez quelques produits et transactions de test.
  3. Explorez le 📊 Tableau de bord et les graphiques.
  4. Consultez la page 📖 Documentation intégrée pour les explications rapides.

Toutes les données restent stockées côté app / base configurée, vous n’avez rien à installer localement.

Développeur – Démarrage rapide

Pour un setup minimal de développement :

git clone https://github.com/SKOHscripts/finance-tracker.git
cd finance-tracker

python3 -m venv venv
source venv/bin/activate      # macOS / Linux
# ou
venv\Scripts\activate         # Windows

pip install -r requirements.txt

# Initialiser la base de données
finance-tracker init-db
finance-tracker seed-products

# Lancer l'application web
streamlit run app.py

Pour un guide complet, voir : 👉 docs/INSTALLATION_SETUP.md

🌐 Fonctionnalités Principales

Interface Web (Streamlit)

  • 📊 Tableau de bord Vue globale du portefeuille, répartition par produit/catégorie, graphiques temporels, performance globale vs objectifs.

  • ➕ Gestion des transactions Achat / vente, rebalance, historique détaillé, filtrage et export.

  • 💰 Valorisation des positions Suivi des valorisations, comparaison valeur actuelle vs coût d’acquisition, distributions reçues.

  • ₿ Espace Bitcoin Prix en temps réel (API CoinGecko), conversions EUR/BTC, historique sur 1 an, scénarios simples.

  • 📄 Rapports PDF Génération de rapports complets, prêts à être partagés (PDF via WeasyPrint).

  • 📈 Simulateur long terme Projections multi‑scénarios, croissance composée, analyse de sensibilité.

👉 Détails : docs/INTERFACE_WEB.md

📚 Documentation Spécialisée

La documentation est découpée en plusieurs guides thématiques pour rester claire et ciblée :

Concepts fondamentaux

Comprendre les types de produits supportés (cash, SCPI, assurance‑vie, PER, crypto…), les notions de rendement, risque, distributions, valorisation, etc.

Interface web

Guide pas à pas de chaque page Streamlit :

  • Tableau de bord

  • Formulaires d’ajout / édition

  • Espace Bitcoin

  • Rapports PDF

  • Simulateur long terme

  • 👉 docs/INTERFACE_WEB.md

Base de données

Description de la structure SQLite (tables products, transactions, valuations, etc.), types de champs, contraintes, et conventions de nommage.

Formules & modèles

Détail des formules de calcul utilisées par le cœur métier :

  • Modified Dietz Return (MWRR)

  • Rendement annualisé

  • Concepts issus de la théorie moderne du portefeuille (MPT) pour la volatilité et la corrélation

  • Autres indicateurs clés utilisés par les vues et services.

  • 👉 docs/FORMULES_CALCULS.md

Lignes de commande & installation avancée

Pour les utilisateurs qui veulent toucher aux lignes de commande ou développer dans le projet :

  • Installation détaillée.

  • Commandes CLI principales (dashboard, add-transaction, report, etc.).

  • Structure du projet et organisation des modules.

  • Déploiement et troubleshooting.

  • 👉 Guide installation & setup complet : docs/INSTALLATION_SETUP.md

  • 👉 Guide CLI : docs/CLI_GUIDE.md

🧱 Architecture du Projet

Structure simplifiée du dépôt :

finance-tracker/
├── README.md                    # Ce fichier
├── requirements.txt             # Dépendances pip
├── pyproject.toml               # Config Poetry
├── docs/                        # Documentation spécialisée
│   ├── CONCEPTS_FONDAMENTAUX.md
│   ├── INTERFACE_WEB.md
│   ├── BASE_DONNEES.md
│   ├── FORMULES_CALCULS.md
│   ├── CLI_GUIDE.md
│   ├── INSTALLATION_SETUP.md
│   └── ROADMAP.md
├── finance_tracker/
│   ├── web/                     # Interface Streamlit
│   │   ├── app.py               # Point d'entrée Streamlit
│   │   └── views/               # Pages individuelles
│   │       ├── dashboard.py
│   │       ├── transactions.py
│   │       ├── valuations.py
│   │       ├── bitcoin.py
│   │       ├── products.py
│   │       ├── simulation.py
│   │       └── documentation.py
│   ├── cli/                     # Interface en ligne de commande
│   │   ├── main.py
│   │   ├── commands.py
│   │   └── formatters.py
│   ├── core/                    # Logique métier
│   │   ├── models.py            # Modèles SQLModel
│   │   ├── schemas.py           # Schémas Pydantic
│   │   ├── database.py          # Accès / init BD
│   │   └── calculations.py      # Calculs financiers
│   └── services/                # Services métier
│       ├── portfolio.py
│       ├── bitcoin.py
│       ├── export.py
│       └── simulator.py
├── tests/                       # Tests automatiques
│   ├── test_models.py
│   ├── test_calculations.py
│   └── conftest.py
└── finance_tracker.db           # Base SQLite (générée)

👉 Pour une description plus détaillée de chaque dossier et composant, voir : docs/INSTALLATION_SETUP.md et docs/ROADMAP.md.

🧪 Tests & Qualité

Le projet s’appuie sur un ensemble d’outils pour garantir la qualité :

  • Tests : pytest, pytest-cov
  • Formatage : black
  • Linting : ruff
  • Typing : mypy

Commandes usuelles :

# Lancer la suite de tests
pytest

# Couverture
pytest --cov=finance_tracker

# Formatage
black finance_tracker tests

# Lint
ruff check finance_tracker tests

# Typage
mypy finance_tracker

🤝 Contribution

Les contributions sont les bienvenues !

  1. Forker le dépôt.
  2. Créer une branche de fonctionnalité : 
    git checkout -b feature/ma-fonctionnalite
  3. Installer en mode développement : 
    pip install -e ".[dev]"
  4. Lancer les tests et le lint : 
    pytest
black finance_tracker tests
ruff check finance_tracker tests
  5. Ouvrir une Pull Request avec une description claire.

Ou simplement proposer une feature dans les issues.

Pour plus de détails sur les conventions et la roadmap : 👉 docs/ROADMAP.md

📄 Licence

Voir le fichier LICENSE pour plus de détails.

🔗 Liens Utiles

About

Finance Tracker is a comprehensive and user-friendly tool for managing, analyzing, and optimizing your investments, understanding the impact of compound interest and taxes, or simply planning a budget, all privately.

Topics

python portfolio finance simulation sqlite private financial-analysis streamlit

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v1.0.0 Latest
Mar 1, 2026
+ 1 release

Sponsor this project

  •  
Learn more about GitHub Sponsors

Packages

 
 
 

Contributors

Languages