{"id":33830358,"url":"https://github.com/alcibiadesc/happy-balance","last_synced_at":"2026-04-02T22:02:03.473Z","repository":{"id":317025227,"uuid":"1052115037","full_name":"alcibiadesc/happy-balance","owner":"alcibiadesc","description":"🔒 The Private, Self-Hosted Alternative to Fintonic, Mint \u0026 YNAB - Take control of your financial data with this privacy-focused personal finance tracker","archived":false,"fork":false,"pushed_at":"2026-04-01T20:37:53.000Z","size":8771,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T06:47:55.349Z","etag":null,"topics":["budgeting","csv-import","docker","expense-tracker","finance","money-management","multi-language","n26","open-source","personal-finance","postgresql","privacy","self-hosted","sveltekit","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/alcibiadesc/happy-balance","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alcibiadesc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"alcibiadesc","custom":["https://www.buymeacoffee.com/happybalance","https://paypal.me/happybalance"]}},"created_at":"2025-09-07T12:41:55.000Z","updated_at":"2026-04-01T20:34:10.000Z","dependencies_parsed_at":"2025-12-03T04:03:36.164Z","dependency_job_id":null,"html_url":"https://github.com/alcibiadesc/happy-balance","commit_stats":null,"previous_names":["alcibiadesc/happy-balance"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/alcibiadesc/happy-balance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcibiadesc%2Fhappy-balance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcibiadesc%2Fhappy-balance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcibiadesc%2Fhappy-balance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcibiadesc%2Fhappy-balance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alcibiadesc","download_url":"https://codeload.github.com/alcibiadesc/happy-balance/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcibiadesc%2Fhappy-balance/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31317831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T21:35:00.834Z","status":"ssl_error","status_checked_at":"2026-04-02T21:34:59.806Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["budgeting","csv-import","docker","expense-tracker","finance","money-management","multi-language","n26","open-source","personal-finance","postgresql","privacy","self-hosted","sveltekit","typescript"],"created_at":"2025-12-07T13:00:20.727Z","updated_at":"2026-04-02T22:02:03.456Z","avatar_url":"https://github.com/alcibiadesc.png","language":"TypeScript","funding_links":["https://github.com/sponsors/alcibiadesc","https://www.buymeacoffee.com/happybalance","https://paypal.me/happybalance"],"categories":[],"sub_categories":[],"readme":"# 💰 Happy Balance - Personal Finance Tracker\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./static/logo/happy-balance-logo-with-text.png\" alt=\"Happy Balance Logo\" width=\"300\"\u003e\n\n![Status](https://img.shields.io/badge/Status-Experimental-orange)\n![License](https://img.shields.io/badge/License-GPL%20v3-blue.svg)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)\n![SvelteKit](https://img.shields.io/badge/SvelteKit-2.0-orange)\n![Docker](https://img.shields.io/badge/Docker-Ready-2496ED)\n![Docker Hub](https://img.shields.io/docker/pulls/alcibiadesc/happy-balance)\n\n**🔒 The Private, Self-Hosted Alternative to Fintonic, Mint \u0026 YNAB**\n\n_Take control of your financial data. No cloud, no tracking, no compromises._\n\n**⚠️ EXPERIMENTAL PROJECT - NOT PRODUCTION READY ⚠️**\n\n[Features](#-features) • [Screenshots](#-screenshots) • [Quick Start](#-quick-start) • [Docker](#-docker) • [Development](#-development) • [License](#-license)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 Why Happy Balance?\n\nUnlike Fintonic, Mint, or other cloud-based finance apps that monetize your data, Happy Balance runs entirely on your own infrastructure. Your financial data never leaves your control.\n\n### 📊 Compare with Popular Apps\n\n| Feature | Happy Balance | Fintonic | Mint | YNAB |\n|---------|--------------|----------|------|------|\n| 🔒 Self-Hosted | ✅ | ❌ | ❌ | ❌ |\n| 🕵️ Zero Tracking | ✅ | ❌ | ❌ | ❌ |\n| 💰 Free Forever | ✅ | Freemium | Ads | Paid |\n| 🌐 Open Source | ✅ | ❌ | ❌ | ❌ |\n| 🏠 Data Ownership | 100% Yours | Their Servers | Their Servers | Their Servers |\n| 🚫 No Ads | ✅ | ❌ | ❌ | ✅ |\n\nHappy Balance is an open-source personal finance tracker designed with simplicity and privacy in mind. Track expenses, manage budgets, and gain insights into your financial habits without compromising your data privacy.\n\n### 🌟 Key Principles\n\n- **Privacy First**: Your data stays yours - self-hosted solution\n- **Minimalist Design**: Clean, distraction-free interface\n- **No Tracking**: Zero telemetry, zero external analytics\n- **Open Source**: Transparent, auditable, and community-driven\n\n## ✨ Features\n\n### Core Functionality\n\n- 📊 **Expense Tracking** - Categorize and track all your expenses\n- 📈 **Visual Analytics** - Beautiful charts and insights\n- 🏷️ **Smart Categorization** - AI-powered transaction categorization\n- 💱 **Multi-Currency** - Support for multiple currencies\n- 🌐 **Multi-Language** - English and Spanish support\n- 🌙 **Dark Mode** - Eye-friendly dark theme\n- 📱 **Responsive** - Works on desktop, tablet, and mobile\n\n### Technical Features\n\n- 🔐 **JWT Authentication** - Secure user sessions\n- 👥 **Multi-User Support** - Role-based access control (Admin, User, Viewer)\n- 📁 **CSV Import** - Import transactions from your bank (N26 compatible)\n- 🔄 **Real-time Updates** - Instant UI updates\n- 🐳 **Docker Ready** - Easy deployment with Docker Compose\n- 🚀 **High Performance** - Built with SvelteKit and TypeScript\n\n### 🏦 Bank Import Compatibility\n\nHappy Balance currently supports CSV import from:\n\n- **N26** - Full support for N26 CSV export format\n- **Generic CSV** - Customizable import for other banks\n\nWant support for your bank? [Create an issue](https://github.com/alcibiadesc/happy-balance/issues) with a sample CSV format (with dummy data) and we'll implement it!\n\n## 📸 Screenshots\n\n\u003cdiv align=\"center\"\u003e\n\n### 💰 Dashboard Overview\nTrack your income, expenses, and financial health at a glance\n\n![Dashboard](./static/screenshots/dashboard.png)\n\n### 📊 Transaction Management\nCategorize and track every expense with powerful filtering\n\n![Transactions](./static/screenshots/transactions.png)\n\n### 🏷️ Smart Categories\nOrganize your expenses with customizable categories\n\n![Categories](./static/screenshots/categories.png)\n\n### 📱 Mobile Responsive\nManage your finances on the go\n\n\u003cimg src=\"./static/screenshots/mobile-dashboard.png\" alt=\"Mobile View\" width=\"375\"\u003e\n\n### ⚙️ User Settings\nCustomize your experience with comprehensive settings\n\n![Settings](./static/screenshots/settings.png)\n\n\u003c/div\u003e\n\n## 🚀 Quick Start\n\n### Option 1: Docker (Easiest) 🐳\n\n```bash\n# Clone the repo\ngit clone https://github.com/alcibiadesc/happy-balance.git\ncd happy-balance\n\n# Start everything with one command\ndocker-compose up -d\n```\n\nAccess at: `http://localhost:5173`\n- Username: `admin`\n- Password: `admin123`\n\nThat's it! 🎉 Everything is automatically configured.\n\n### Option 2: Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/alcibiadesc/happy-balance.git\ncd happy-balance\n\n# Install dependencies\npnpm install\ncd backend \u0026\u0026 pnpm install\n\n# Setup database\nnpx prisma migrate dev\n\n# Start development\npnpm dev # Frontend on :5173\ncd backend \u0026\u0026 pnpm dev # Backend on :3004\n\n  frontend:\n    build: .\n    environment:\n      VITE_API_URL: http://localhost:3004/api\n    ports:\n      - \"5173:5173\"\n```\n\n### Using Portainer\n\n1. Create a new stack in Portainer\n2. Use the repository URL: `https://github.com/alcibiadesc/happy-balance.git`\n3. Set the compose path to `docker-compose.yml`\n4. Configure environment variables\n5. Deploy the stack\n\n[Full Docker documentation →](./DOCKER_INSTALL.md)\n\n## 🛠️ Development\n\n### Tech Stack\n\n**Frontend:**\n\n- SvelteKit 2.0\n- TypeScript 5.0\n- Vite\n- TailwindCSS (via custom CSS variables)\n\n**Backend:**\n\n- Node.js + Express\n- Prisma ORM\n- PostgreSQL\n- JWT Authentication\n\n### Project Structure\n\n```\nhappy-balance/\n├── src/                    # Frontend (SvelteKit)\n│   ├── lib/               # Components and utilities\n│   ├── routes/            # SvelteKit routes\n│   └── app.html           # HTML template\n├── backend/               # Backend API\n│   ├── src/\n│   │   ├── domain/        # Business logic\n│   │   ├── infrastructure/# Database, external services\n│   │   └── application/   # Use cases\n│   └── prisma/            # Database schema\n├── docker-compose.yml     # Docker configuration\n└── package.json           # Frontend dependencies\n```\n\n### Development Commands\n\n```bash\n# Frontend\npnpm dev              # Start dev server\npnpm build            # Build for production\npnpm preview          # Preview production build\npnpm lint             # Run linter\npnpm format           # Format code\n\n# Backend\ncd backend\npnpm dev              # Start dev server\npnpm build            # Build TypeScript\npnpm start            # Start production server\npnpm db:migrate       # Run migrations\npnpm db:seed          # Seed database\n```\n\n### Environment Variables\n\nCreate a `.env` file in the root:\n\n```env\n# Backend\nDATABASE_URL=postgresql://user:pass@localhost:5432/happy_balance\nJWT_ACCESS_SECRET=your-secret-key-min-32-chars\nJWT_REFRESH_SECRET=another-secret-key-min-32-chars\nADMIN_USERNAME=admin\nADMIN_PASSWORD=secure_password\n\n# Frontend\nVITE_API_URL=http://localhost:3004/api\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### How to Contribute\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Code of Conduct\n\nPlease read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.\n\n## 📄 License\n\nThis project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details.\n\n### What this means:\n\n- ✅ You can use this software for personal and commercial purposes\n- ✅ You can modify and distribute the software\n- ⚠️ Any modifications must be released under GPLv3\n- ⚠️ If you distribute this software, you must provide the source code\n- 💼 For commercial licensing options, please contact us\n\n## 🔒 Security\n\n- **No telemetry or tracking**\n- **All data stored locally or on your server**\n- **Encrypted passwords (bcrypt)**\n- **JWT tokens for authentication**\n- **CORS protection**\n- **SQL injection prevention (Prisma ORM)**\n\nFound a security issue? Please open a security issue on GitHub.\n\n## 🗺️ Roadmap\n\n- [ ] Enhanced transaction categorization\n- [ ] Advanced reporting and insights\n- [ ] Data export in multiple formats\n- [ ] Multi-workspace support\n- [ ] Advanced budgeting rules\n\n## 🙏 Acknowledgments\n\n- Built with [SvelteKit](https://kit.svelte.dev/)\n- Database ORM by [Prisma](https://www.prisma.io/)\n- Icons by [Lucide](https://lucide.dev/)\n- Inspired by minimalist design principles\n\n## 📞 Support\n\n- 🐛 [Issue Tracker](https://github.com/alcibiadesc/happy-balance/issues)\n- 💬 [Discussions](https://github.com/alcibiadesc/happy-balance/discussions)\n\n## ⚠️ Disclaimer\n\nThis is an **experimental project** under active development. It may contain bugs and is not recommended for production use without thorough testing. Use at your own risk.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made for the open-source community**\n\n[⬆ Back to top](#-happy-balance---personal-finance-tracker)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falcibiadesc%2Fhappy-balance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falcibiadesc%2Fhappy-balance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falcibiadesc%2Fhappy-balance/lists"}