nate/budget
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README with dashboard customization features and Capsule branding

Browse Source
This commit is contained in:
nmemmert committed 2026-01-13 15:42:32 -05:00
1 parent 4d7f301c61
commit 0b9ab53266
1 file changed
+189 -61
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+189 -61
View File
@@ -1,26 +1,61 @@
# Envelope Budgeting App
# Capsule by NeCloud
A modern web-based envelope budgeting application built with Next.js, TypeScript, and Tailwind CSS. This app helps you manage your finances using the traditional envelope budgeting method in a digital format.
A modern, privacy-focused envelope budgeting application built with Next.js, TypeScript, and Tailwind CSS. Capsule helps you manage your finances using the traditional envelope budgeting method in a beautiful, digital format with complete control over your data.
**🔒 Privacy-First Design**: All your financial data is stored locally on your server in encrypted files. No cloud services, no data sharing, complete control over your information.
## Features
- **🔐 Secure Local Storage**: File-based storage with AES-GCM encryption
- **👤 User Authentication**: Secure sign-up and login with password hashing
- **💰 Envelope Management**: Create and manage budget envelopes for different spending categories
- **📊 Visual Progress Tracking**: See spending progress with color-coded progress bars
- **💳 Account Management**: Support for multiple accounts (checking, savings, credit cards, etc.)
- **📝 Transaction History**: Track and view recent transactions
- **📥 Data Input Options**:
- **Manual Entry**: Add individual transactions with amount, description, date, and envelope assignment
- **File Import**: Import transactions from bank exports (CSV, OFX, QFX, QBO formats)
- **✏️ Transaction Editing**: Edit existing transactions with full details
- **🎨 Envelope Creation**: Add new budget envelopes with custom colors and allocations
- **💸 Get Paid Feature**: Automatically distribute income across envelopes
- **📤 Data Export**: Export all data to CSV or JSON formats for backup or analysis
- **📈 Budget Overview**: Monitor total allocated, spent, and remaining amounts
- **📱 Responsive Design**: Works seamlessly on desktop and mobile devices
### 🎨 Customizable Dashboard
- **Drag & Drop Sections**: Rearrange dashboard sections exactly how you want them
- **Show/Hide Controls**: Toggle visibility of dashboard components
- **5 Summary Cards**: Quick view of Assets, Debt, Balance, Envelopes, and Transactions
- **Analytics Charts**: Income vs Expenses, Budget Alerts, Assets vs Debt breakdown
- **Quick Actions**: One-click access to common tasks
- **Budget Progress**: Visual tracking of monthly spending against budget
### 🔐 Security & Privacy
- **Secure Local Storage**: File-based storage with AES-GCM encryption
- **User Authentication**: Secure sign-up and login with password hashing
- **No Cloud Dependencies**: Your data never leaves your server
### 💰 Smart Money Management
- **Envelope Budgeting**: Create and manage budget envelopes for different spending categories
- **Multiple Account Support**: Track checking, savings, credit cards, mortgages, loans, and investments
- **Account Normalization**: Liabilities (credit cards, loans) automatically display as negative balances
- **Net Worth Tracking**: Automatic calculation of assets minus debt
- **Get Paid Feature**: Automatically distribute income across envelopes
### 📊 Transaction Management
- **Multiple Input Methods**:
- **Manual Entry**: Add individual transactions with full details
- **File Import**: Import from bank exports (CSV, OFX, QFX, QBO)
- **Get Paid**: Record income with automatic envelope distribution
- **Transaction Editing**: Full edit capabilities with real-time updates
- **Recent History**: Quick view of latest transactions
- **Smart Filtering**: View transactions by account, envelope, or date range
### 📈 Analytics & Insights
- **Income vs Expenses**: Monthly income and spending comparison
- **Budget Alerts**: Notifications for envelopes over 80% or overspent
- **Daily Spending Chart**: 7-day spending visualization
- **Envelope Progress**: Color-coded spending progress for each category
- **Account Balances**: Visual breakdown of all account balances
### 🎨 Beautiful Design
- **Capsule Branding**: Modern cloud-themed design with professional color palette
- **Responsive Layout**: Seamless experience on desktop, tablet, and mobile
- **Customizable Colors**: Choose colors for envelopes and visual organization
- **Interactive Elements**: Clickable cards, hover effects, and smooth transitions
- **Data Export**: Export to CSV or JSON formats for backup or analysis
## Brand Colors
- **Primary Blue**: #1E73BE - Main brand color
- **Finance Green**: #28A745 - Positive balances and income
- **Cloud Blue**: #A7D8F8 - Secondary accents
- **Dark Navy**: #0F2C4C - Text and headers
- **Neutral Gray**: #F4F4F4 - Backgrounds
## Getting Started
@@ -32,7 +67,7 @@ A modern web-based envelope budgeting application built with Next.js, TypeScript
1. Clone the repository:
```bash
git clone <repository-url>
git clone https://github.com/nmemmert/budget.git
cd budget
```
@@ -41,27 +76,42 @@ cd budget
npm install
```
3. Create environment file:
```bash
cp .env.local.example .env.local
```
4. Generate a secure encryption key:
```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
5. Update `.env.local` with your encryption key:
```bash
ENCRYPTION_KEY=your-generated-key-here
```
6. Run the development server:
3. Run the development server:
```bash
npm run dev
```
7. Open [http://localhost:7654](http://localhost:7654) in your browser.
4. Open [http://localhost:7654](http://localhost:7654) in your browser
### First Time Setup
1. **Create Account**: Click "Sign Up" to create your secure account
2. **Setup Wizard**: Complete the guided setup:
- Add your first account (checking, savings, etc.)
- Create initial budget envelopes with default budgets
- Configure income allocation rules
3. **Customize Dashboard**: Click the ⚙️ Customize button to:
- Drag and drop sections to rearrange
- Show or hide dashboard components
- Create your perfect financial overview
## Dashboard Customization
### Available Sections
1. **Summary Cards** - Quick overview of total assets, debt, balance, envelope count, and transaction count
2. **Analytics Charts** - Six detailed charts including income/expenses, alerts, and spending patterns
3. **Budget Progress** - Visual progress bar showing monthly budget utilization
4. **Quick Actions** - Fast access buttons for common tasks
5. **Recent Transactions** - Latest 5 transactions with edit/delete options
### How to Customize
- Click **⚙️ Customize** at the top of the dashboard
- **Drag & Drop**: Click and hold the ⋮⋮ handle to drag sections
- **Up/Down Arrows**: Use ▲ ▼ buttons for precise positioning
- **Toggle Visibility**: Check/uncheck boxes to show or hide sections
- Your preferences are automatically saved
## Storage System
@@ -86,43 +136,121 @@ For detailed information about the storage system, see [FILE_STORAGE.md](./FILE_
```
src/
├── app/
│ ├── layout.tsx # Root layout component
│ ├── page.tsx # Main budgeting dashboard
│ └── globals.css # Global styles
public/ # Static assets
│ ├── layout.tsx # Root layout with Capsule branding
│ ├── page.tsx # Main dashboard with customization
│ ├── globals.css # Global styles with brand colors
│ └── api/
│ ├── auth/ # Authentication endpoints
│ └── data/ # Data persistence endpoints
├── components/
│ ├── AccountManagement.tsx # Account CRUD operations
│ ├── DashboardCharts.tsx # Analytics visualizations
│ ├── DataInput.tsx # Transaction entry forms
│ ├── EnvelopeCreate.tsx # Envelope creation
│ ├── EnvelopeEdit.tsx # Envelope editing
│ ├── GetPaid.tsx # Income distribution
│ ├── SetupWizard.tsx # First-time setup flow
│ ├── TransactionEdit.tsx # Transaction editing
│ └── ... # Additional components
├── lib/
│ ├── authService.ts # Authentication logic
│ ├── dataService.ts # Data persistence layer
│ ├── fileStorage.ts # Encrypted file storage
│ └── crypto.ts # Encryption utilities
data/ # User data storage (gitignored)
public/
├── capsule-icon.svg # App favicon
└── images/
└── capsule-logo.svg # Brand logo
```
## Technologies Used
- **Next.js 16** - React framework with App Router and API routes
- **Next.js 16** - React framework with App Router and Turbopack
- **TypeScript** - Type-safe JavaScript
- **Tailwind CSS 4** - Utility-first CSS framework
- **React 19** - UI library
- **Node.js Crypto** - Encryption and password hashing
- **ESLint** - Code linting
- **Tailwind CSS 4** - Utility-first CSS framework with custom properties
- **React 19** - UI library with modern hooks
- **Node.js Crypto** - AES-GCM encryption and SHA-256 password hashing
- **ESLint** - Code quality and consistency
## Key Features in Detail
### Envelope Budgeting System
The envelope method divides your income into categories (envelopes), each with a budget allocation. When you spend money, it's deducted from the appropriate envelope, helping you stay within your budget limits.
### Automatic Income Distribution
The "Get Paid" feature automatically splits your paycheck across envelopes based on percentages you set during setup. For example:
- Rent: 40%
- Groceries: 15%
- Savings: 20%
- etc.
### Visual Progress Tracking
Each envelope shows:
- Allocated amount (your budget)
- Spent amount (what you've used)
- Remaining balance
- Progress bar with color coding (green → yellow → red as you approach limits)
### Smart Alerts
Get notified when:
- An envelope reaches 80% of its budget
- An envelope is overspent
- Your daily spending exceeds normal patterns
## How to Use
### First Time Setup
### Dashboard Navigation
1. **Create Account**: Open the app and click "Sign Up" to create your account
2. **Setup Wizard**: Follow the guided setup to:
- Add your first account (checking, savings, etc.)
- Create initial budget envelopes
- Set income allocation rules
3. **Start Budgeting**: Begin tracking your income and expenses
The dashboard provides a complete overview of your finances:
### Daily Use
- **Summary Cards**: Click any card to navigate to the detailed view
- Assets → View all asset accounts
- Debt → View all liability accounts
- Balance → View all accounts
- Envelopes → Manage budget envelopes
- Transactions → View transaction history
1. **View Dashboard**: The main page shows your budget overview and envelope cards
2. **Add Transactions**:
- **Manual Entry**: Click "Manual Entry" and fill in transaction details
- **File Import**: Click "Import from File", select your bank export format, and upload the file
- **Get Paid**: Use the "Get Paid" feature to record income and automatically distribute to envelopes
3. **Monitor Envelopes**: Each envelope displays allocated amount, spent amount, and remaining balance
4. **Track Progress**: Visual progress bars show spending percentage for each envelope
5. **View Transactions**: Recent transactions are listed with envelope associations
6. **Manage Accounts**: Switch between different accounts to track multiple bank accounts, credit cards, etc.
- **Analytics**: Monitor your financial health with real-time charts
- Income vs Expenses (current month)
- Budget Alerts (overspent or near-limit envelopes)
- Assets vs Debt breakdown with Net Worth
- Envelope spending progress
- Account balance distribution
- Daily spending trends (last 7 days)
### Managing Money
1. **Record Income**:
- Click "💰 Get Paid" button
- Enter amount and select deposit account
- Funds are automatically distributed to envelopes based on allocation percentages
2. **Track Expenses**:
- Use "Manual Entry" for individual transactions
- Import bank files for bulk transaction entry
- Assign each expense to an envelope for tracking
3. **Monitor Budgets**:
- View envelope spending progress in real-time
- Get alerts when approaching or exceeding budget limits
- Track monthly spending against allocated amounts
### Account Types
Capsule supports multiple account types with automatic balance normalization:
- **Assets** (positive balances):
- Checking accounts
- Savings accounts
- Investment accounts
- **Liabilities** (negative balances):
- Credit cards
- Mortgages
- Loans
Your Net Worth is automatically calculated as: Total Assets - Total Debt
## Data Import