{"id":26320894,"url":"https://github.com/oxcened/vault","last_synced_at":"2026-05-07T21:36:56.321Z","repository":{"id":280033906,"uuid":"940798865","full_name":"oxcened/vault","owner":"oxcened","description":"Vault – A Modern Personal Finance Solution","archived":false,"fork":false,"pushed_at":"2025-03-15T13:07:24.000Z","size":327,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-15T13:19:04.193Z","etag":null,"topics":["budget","cash-flow","finance","money","net-worth","nextjs","personal-finance","t3-stack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxcened.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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-28T20:14:50.000Z","updated_at":"2025-03-15T12:40:48.000Z","dependencies_parsed_at":"2025-03-08T08:26:12.734Z","dependency_job_id":null,"html_url":"https://github.com/oxcened/vault","commit_stats":null,"previous_names":["oxcened/vault"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxcened%2Fvault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxcened%2Fvault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxcened%2Fvault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxcened%2Fvault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxcened","download_url":"https://codeload.github.com/oxcened/vault/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243754097,"owners_count":20342543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["budget","cash-flow","finance","money","net-worth","nextjs","personal-finance","t3-stack"],"created_at":"2025-03-15T16:15:20.963Z","updated_at":"2026-05-07T21:36:56.309Z","avatar_url":"https://github.com/oxcened.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  Vault\n\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003eA simple yet powerful personal finance app\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"GitHub License\" src=\"https://img.shields.io/github/license/oxcened/vault\"\u003e\n\u003c/p\u003e\n\n![Vault Dashboard](docs/screenshots/dashboard.png)\n\nVault helps you track **net worth**, **cash flow**, and **expenses** in a simple and effective way. Vault is an evolving project, with planned features like **multi-currency support**, **real-time exchange rates**, and **stock tracking**.\n\n## 📌 Table of Contents\n\n- [Key Features](#-key-features)\n- [Quick Start](#-quick-start)\n  - [Prerequisites](#prerequisites)\n  - [Spin up the dev server](#spin-up-the-dev-server)\n- [Other scripts](#other-scripts)\n- [Tech Stack](#tech-stack)\n  - [Core Technologies](#core-technologies)\n  - [UI \u0026 Components](#ui--components)\n- [Screenshots](#-screenshots)\n- [Reactive Architecture](#-reactive-architecture)\n- [Who's Behind This?](#-whos-behind-this)\n- [License](#-license)\n\n## ✨ Key Features\n\n- **Net Worth Tracking** – A simple way to see assets and liabilities in one place.\n- **Cash Flow Insights** – A glance at how money moves over time.\n- **Expense Tracking** – A lightweight way to keep an eye on spending.\n- **Multi-Currency Support** – Potential support for different currencies.\n- **Stock \u0026 Crypto Tracking** – Basic market tracking for stocks and crypto.\n- **Slick UI** – A clean and modern interface.\n- **Dark Mode** – Optimized for both light and dark themes.\n- **Multi-User** – Log in using Discord and manage your own finances.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\nMake sure you have the following installed:\n\n- 🏗️ [Node.js](https://nodejs.org/) (Required: v22.13.1)\n- 📦 [npm](https://www.npmjs.com/) (Vault uses `npm@10.9.2`)\n- 🐳 [Docker](https://www.docker.com/) (If you want to use the included DB spin up script)\n\n### Spin up the dev server\n\nHere’s what you need to do to get started quickly:\n\n1. **Clone the project**\n\n   ```sh\n   git clone https://github.com/oxcened/vault.git\n   cd vault\n   ```\n\n2. **Create a `.env` file** using the provided example:\n\n   ```sh\n   cp .env.example .env\n   ```\n\n3. **Generate an authentication secret**:\n\n   ```sh\n   npx auth secret\n   ```\n\n   Open `.env`, locate the `AUTH_SECRET` field, and paste the generated secret.\n\n4. **Set up Discord authentication**:\n\n   1. Go to the [Discord Developer Portal](https://discord.com/developers/applications).\n   2. Create a new application.\n   3. Under **OAuth2**, add a redirect URI matching:\n\n   ```\n   http://localhost:3000/api/auth/callback/discord\n   ```\n\n   4. Copy the **Client ID** and **Client Secret** from the OAuth2 settings.\n   5. In your `.env` file, paste them in `AUTH_DISCORD_ID` and `AUTH_DISCORD_SECRET`.\n\n5. **Configure the database**:\n\n   - Fill `DATABASE_URL` and `DATABASE_DIRECT_URL` with your database connection details.\n   - If you don’t have a database, run:\n     ```sh\n     ./start-database.sh\n     ```\n     _(Requires Docker to be installed)_\n\n6. **Install dependencies**:\n\n   ```sh\n   npm install\n   ```\n\n7. **Apply migrations and generate the Prisma client**:\n\n   ```sh\n   npm run db:generate\n   ```\n\n8. **Run the app**:\n   ```sh\n   npm run dev\n   ```\n\nNow, you’re ready to start using Vault!\n\n## Other scripts\n\n### Linting \u0026 Formatting\n\nCheck for linting errors:\n\n```sh\nnpm run lint\n```\n\nFormat code:\n\n```sh\nnpm run format:write\n```\n\n### Building for Production\n\nTo build and start the production server:\n\n```sh\nnpm run build\nnpm run start\n```\n\n## Tech Stack\n\nVault is built with the **T3 Stack**, making it scalable and efficient.\n\n### Core Technologies:\n\n- [TypeScript](https://www.typescriptlang.org/) – Ensuring type safety.\n- [Next.js](https://nextjs.org) – Full-stack framework with SSR and API routes.\n- [NextAuth.js](https://next-auth.js.org) – Secure authentication and session management.\n- [Prisma](https://prisma.io) – ORM for database management.\n- [Tailwind CSS](https://tailwindcss.com) – Modern styling with utility classes.\n- [tRPC](https://trpc.io) – Type-safe API communication.\n\n### UI \u0026 Components:\n\n- [Radix UI](https://www.radix-ui.com/) with [shadcn/ui](https://ui.shadcn.com) components.\n- [Lucide Icons](https://lucide.dev/) for sleek and simple icons.\n\n## 📸 Screenshots\n\nHere’s a quick look at Vault in action:\n\n- **Dashboard Overview**\n  ![Vault Dashboard](docs/screenshots/dashboard.png)\n\n- **Assets List**\n  ![Assets List](docs/screenshots/assets.png)\n\n- **Debts List**\n  ![Debts List](docs/screenshots/debts.png)\n\n- **Cash Flow Overview**\n  ![Cash Flow Overview](docs/screenshots/cash-flow.png)\n\n- **Transactions List**\n  ![Transactions List](docs/screenshots/transactions.png)\n\n## 🧠 Reactive Architecture\n\nThis app uses a fully reactive, event-driven architecture to keep derived financial data accurate and efficient. Here's how it works:\n\n### Event-Driven Data Flow\n\nWhenever core data changes — like assets, debts, transactions, stock prices, or exchange rates — the system emits events that represent **facts** about what happened. These events are handled by dedicated listeners that determine whether and how to trigger updates to derived data.\n\n**Example event types:**\n\n- `asset:updated`\n- `debt:updated`\n- `transaction:updated`\n- `exchangeRate:updated`\n- `stockPrice:updated`\n\n### Derived Data \u0026 Smart Recomputes\n\nDerived data (like Net Worth or Cash Flow) is not recomputed blindly. Instead:\n\n- **Shared data changes** (e.g. stock prices, exchange rates) trigger recomputes **only for affected snapshots**, based on a `DerivedDataDependency` table.\n- **User-specific changes** (assets, debts, transactions) use smart recompute functions like:\n  - `recomputeNetWorthForUserFrom(...)`\n  - `recomputeCashFlowForUserFrom(...)`\n\nThese functions only recompute data from the earliest relevant timestamp forward.\n\n### Dependency Graph\n\nEvery derived data snapshot tracks the specific inputs it used:\n\n- Exchange rates\n- Stock prices\n\nThis allows:\n\n- ✅ Precise invalidation when inputs change\n- ✅ No over-computation\n- ✅ Full traceability of what influenced what\n\n## 🛠 Who’s Behind This?\n\nBuilt by **Alen Ajam**, who made this for personal use and decided to share it. No guarantees, but if it works for you, great!\n\n- GitHub: [oxcened](https://github.com/oxcened)\n- Email: [hello@alenajam.dev](mailto:hello@alenajam.dev)\n- Website: [alenajam.dev](https://alenajam.dev)\n\n## 📜 License\n\nVault is open-source and licensed under the [MIT License](https://opensource.org/licenses/MIT).  \nWant to contribute? PRs are always welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxcened%2Fvault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxcened%2Fvault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxcened%2Fvault/lists"}