This is a locally-deployed, privacy-focused Budgeting Application designed to replace complex Excel spreadhseets with a modern, responsive Web Interface. It features a React frontend for a premium user experience and a lightweight Node.js backend for reliable file-based storage.

• Monthly Organization: Data is isolated by month (e.g., 2025-12, 2026-01). You can navigate forward and backward in time.
• Income Tracking: Add unlimited income sources with "Projected" vs "Actual" values.
• Expense Categorization: Organize expenses into categories (Housing, Food, etc.). Each category has its own sub-table of items.
• Real-time Variance: The app automatically calculates the difference between Projected and Actual costs. Variances are color-coded (Green for good, Red for overspending).

• File-Based Database: All data is stored as transparent JSON files in the data/ directory. No complex database installation is required.
• Templating System: You can design a "Perfect Month" (with all your standard rents/bills set up) and save it as a Default Template. Any new month you visit will automatically clone this structure.
• Import/Export:
  • Export: Download the current month's data as a JSON file backup.
  • Import: Upload a JSON file to overwrite/restore data for the current month.
• Reset: One-click reset to wipe the current month and re-apply the Default Template.

• Dashboard Charts:
  • Expense Breakdown: Pie chart showing percentage of spending per category.
  • Income vs Expense: Bar chart for quick monthly health check.
• Historical Statistics:
  • Cash Flow Trend: Line chart tracking Income vs Expenses over the last 6-12 months.
  • Savings Rate: Analysis of your savings percentage over time.
  • Budget Accuracy: Comparison of how well you stick to your Projected Budget.

graph TD
    User[User Browser] <-->|HTTP/JSON| Frontend[React App (Vite)]
    Frontend <-->|REST API| Backend[Node.js Server]
    Backend <-->|Read/Write| Storage[File System (./data/*.json)]

1. Frontend (React + Vite):

   • Built with React 18.
   • Uses recharts for visualization.
   • Uses react-router-dom for navigation.
   • Styled with modular CSS and a global Design System (index.css) for a premium look.

2. Backend (Node.js + Express):

   • A lightweight REST API running on port 3001.
   • Handles file I/O operations (Reading and Writing JSON files).
   • Zero-config: Uses the local filesystem directly.

3. Data Persistence:

   • Data is stored in the data/ folder in the project root.
   • Format: YYYY-MM.json (e.g., 2025-12.json).
   • Template: default_template.json.

This custom hook is the "Brain" of the frontend.

• Fetching: On mount, it fetches the list of available months from /api/months.
• Loading: When curMonth changes, it queries the API for that specific month's data. If the API returns null, it initializes a fresh state using client-side defaults.
• Auto-Save: It implements a "Debounced Save". It waits for the user to stop typing (500ms) before sending a POST request to the backend, ensuring distinct updates without spamming the server.
• Actions: Exposes atomic actions (addIncome, updateCategory, saveAsTemplate) to the UI components.

• GET /api/months/:id: Checks for a file named {id}.json. If not found, checks for default_template.json. If neither, returns empty.
• POST /api/months/:id: Receives JSON body and writes it directly to disk.
• GET /api/months: Scans the directory using fs.readdirSync, filters for valid regex ^\d{4}-\d{2}\.json$, and returns the sorted list. This powers the trend charts.

Since this app uses a local filesystem backend, it is designed to be Self-Hosted or run Locally.

• Node.js: You must have Node.js installed (Version 18 or higher recommended).
  • Mac: brew install node
  • Windows: Download installer from nodejs.org

To use the app on your personal computer:

1. Open Terminal in the project folder (budgetApp).
2. Install Dependencies (only needed once):

   npm install

3. Start the App:

   npm run dev

   • This command uses concurrently to start BOTH the React frontend (Vite) and the Node backend (server.cjs).
   • You will see output indicating the server is running on http://localhost:3001 and Vite on http://localhost:5173.
4. Access App: Open your browser to http://localhost:5173.

If you want to run it as a stable service (e.g., on a Raspberry Pi or a Home Server):

1. Build the Frontend: This compiles the React code into static HTML/CSS/JS files.

   npm run build

   This creates a dist/ folder.

2. Serve the Build: The server.cjs file is already configured to serve the frontend!

3. Run the Server:

   node server.cjs

   Now the app is running in production mode at http://localhost:3001.

   Benefits: Faster than npm run dev, no formatting/linting overhead. Ideal for running on a personal server without Docker.

The easiest way to run the app in production or on a server (NAS, Raspberry Pi).

1. Build & Run:

   docker-compose up -d --build

2. Access: Go to http://localhost:3001
3. Data Persistence: Your data is safe! The docker-compose.yml file maps the container's storage to your local ./data folder. You can see your JSON files updating in real-time on your host machine.

budgetApp/
├── data/                  # <--- YOUR DATA LIVES HERE (JSON files)
├── public/                # Public assets
├── src/
│   ├── components/        # React Components
│   │   ├── BudgetView.jsx # Main Dashboard
│   │   ├── StatsView.jsx  # Analytics Page
│   │   └── FinanceTable.jsx # Reusable Table
│   ├── hooks/
│   │   └── useBudgetData.js # State Management & API Calls
│   ├── App.jsx            # Main Layout & Routing
│   └── main.jsx           # Entry point
├── server.cjs             # Node.js Backend Server
├── package.json           # Dependencies & Scripts
└── vite.config.js         # Vite Configuration