📋 Step-by-step installation guide

Follow these steps in order. Each step is illustrated with a real screenshot. Anyone can do it! 😊

1

Open the app in your browser

Go to the app's URL (or open the file budget_familial.html). The start screen appears with two choices.

The welcome screen with user profiles

💡 If it's your very first time, you'll first see the onboarding screen with two big cards: Demo Mode and Create my account.

2

Click your name to log in

Click on the card with your name. If you set a PIN code, you will be asked for it. Once logged in, the app opens directly.

On first launch, the guided tour starts automatically 🎉

💡 The guided tour walks you through each part of the app in 12 steps (including quick add, Google sign-in and the AI assistant). You can navigate with the ← → arrow keys.

3

Discover the header buttons

At the top of the page you'll find all the important buttons:

The top bar with all control buttons

• 🔵 Your name — click to switch user
• 💾 Save — VERY IMPORTANT: click here after every change!
• 📥 Export CSV — export your data to an Excel file
• 📦 Backups — access your automatic backups
• ❓ Help — restart the guided tour or open this guide
• 🌙 Dark mode — switch between light/dark theme

⚠️ Never forget to click 💾 Save after entering data! Otherwise everything will be lost if you close the page.

4

Navigate between years using the tabs

Below the header, you can see the year tabs. Click on a year to display it. Use ＋ Year to create a new year.

The tabs: Global Summary, 2025, 2026, + Year, Charts, Settings

💡 In the free version, you can have 1 year only. With a Premium licence you can have as many as you want.

5

Enter your starting balances

At the top of each year, there are 4 important fields you only need to fill in once:

The 4 balance indicators at the top of each year

• Account (01/01) — Your checking account balance on January 1st
• Current account — Calculated automatically ✨
• Initial savings — Your savings account balance on January 1st
• Current savings — Calculated automatically ✨

💡 For subsequent years, the initial savings balance is filled in automatically from the ending balance of the previous year.

6

Enter your monthly revenues

In the green 💼 Revenues section, click on each cell to enter the amount for each month. You can have multiple revenue rows (salary, benefits, etc.).

Revenue section with amounts month by month — here €4,500/month

💡 If your salary is the same every month, enter the value in January then right-click on the cell to copy it across the whole row.

7

Enter your fixed costs and check them when paid

In the pink 🏠 Fixed Costs & Expenses section, enter your recurring costs (rent, electricity, subscriptions…). Each month, click on the cell to check it green when you have paid.

Fixed costs section — click a cell to mark it as "paid" (green)

⚠️ Only checked (paid) costs are counted in your real balance calculation. Don't forget to check them!

8

Record your variable expenses as you go

In the yellow 🛒 Variable Expenses section, click the small ＋ in the correct month column to add an expense (groceries, fuel, miscellaneous…).

Variable expenses section with colour-coded categories

💡 You can add a comment (e.g. "Lidl"), today's date and the payment method (card, cash, meal voucher).

9

Check the automatic monthly summary

The blue 📊 Monthly Summary section calculates everything automatically for each month of the year.

The monthly summary — everything is calculated automatically!

• 🟢 Revenues — total income for the month
• 🔴 Paid costs — total of checked costs
• 🟡 Variable expenses — total of entered expenses
• 🔵 Real balance — your calculated actual bank balance
• 💰 Savings — your calculated savings account balance

🚀 Getting Started

Mon Budget is a Progressive Web App (PWA). It works offline and can be installed on your device just like a native app.

First launch

On first launch, you can choose between:

Account creation (6-step wizard)

1. Profile — Your name and avatar colour
2. Revenues — Your usual monthly revenues (salary, benefits…)
3. Fixed costs — Your recurring fixed costs (rent, energy, subscriptions…)
4. Budgets — Suggested monthly budget for each expense category (automatically converted to annual)
5. PIN — Optional security code to protect your data
6. Cloud — Optional Google sign-in for Premium sync

Install on mobile / desktop

On mobile (Chrome/Safari), tap "Add to Home Screen". On PC (Chrome/Edge), click the install icon in the address bar. The app then works offline.

🎮 Demo Mode

Demo mode loads fictional data so you can explore all features without any risk.

Activate demo mode

On first launch, click the Demo Mode card. The app loads with sample data (Jean & Marie, 2025–2026).

Exit demo mode

Click ✕ Exit demo mode in the banner. Confirm the deletion: all fictional data is erased and you return to the start screen to create your real account.

🖥️ General interface

The app is organised by years (tabs) and by months (columns in each table).

Header

• 💾 Save — Saves all changes in the browser
• 📥 Export CSV — Exports the current month's data as CSV
• 🖨️ PDF — Generates a structured PDF report: annual KPIs, full monthly table and expense breakdown by category for each year
• 📂 Import CSV — Imports transactions from a bank statement CSV (automatic column detection, category choice, payment method, selected total and automatic duplicate detection ⚠️)
• 📦 Backups — Shows the list of automatic backups (one per day, 20 max)
• 🔐 Login — Sign in with Google for Premium cloud sync
• ❓ Help — Restart the guided tour or open this guide
• 🌙 / ☀️ — Switch between light and dark mode

Floating buttons (bottom right)

• ➕ Green — Quick add a variable expense
• 🤖 Purple — AI Assistant (chat)

Year tabs

Each tab represents a year. Click ＋ Year to create a new year.1 year max in free Unlimited in Premium

Month columns

Each table has 12 columns (Jan–Dec). Enter amounts directly in the cells. Press Enter or Tab to move to the next cell.

🏠 Monthly Dashboard

The Home tab is your monthly overview: at a glance you can see where you stand financially without browsing the detailed tables.

Navigating between months

Use the ← and → buttons to move from one month to another. Year changes happen automatically (January → December of the previous year and vice versa). Use the year selector to jump directly to a year.

📅 Monthly view / 📊 Annual view

A toggle at the top right lets you switch between the monthly view (detail of one month) and the annual view which shows yearly totals, savings rate, average monthly savings, best and worst month, and a bar chart of balances month by month.

4 key indicators (KPIs)

Each card shows the selected month's value and an SVG sparkline — a mini chart representing the trend over the 12 months of the year. At a glance, you can see whether an indicator is rising or falling.

🍩 Donut chart

When there are at least 2 active variable expense categories in the month, an SVG donut chart appears below the KPIs. It shows the expense breakdown by category with the amount and percentage.

🔄 Comparison vs previous year

If you have data for the previous year, a comparison table is displayed automatically for the same month. It shows the delta (+ or −) for each indicator with green (improvement) or red (regression) colouring.

⚠️ Budget exceeded alerts

If a variable expense category exceeds its monthly budget (defined in category management), a red alert appears in the dashboard with the amount spent vs the budget.

🛒 Latest expenses

The list of variable expenses for the month is displayed, sorted by descending amount (up to 8 entries + a counter for the rest).

📅 "Go to current year" button

A quick button lets you navigate directly to the current year's tab (e.g. 2026) from the dashboard.

🏠 Monthly fixed costs detail

Below the KPIs and comparison, a section lists all costs for the current month (rent, subscriptions, savings transfers…) with their amount and paid status ✓.

📱 Swipe navigation (mobile)

On mobile, swiping left goes to the next month, swiping right goes back to the previous month — without needing to tap the ← → buttons.

📝 Monthly note

At the bottom of Home, a free text field lets you add a monthly note (e.g. "busy month, holidays", "bonus received"). The note is saved automatically and appears in the PDF report in a dedicated section.

🔍 Global search

Instantly find any revenue, fixed cost or variable expense row across all your years, without browsing the tables.

Open search

Click the 🔍 tab in the navigation bar (far right). Search can also be closed with the Escape key.

What is indexed

• Revenue labels — e.g. "Salary", "Bonus"
• Fixed cost labels — e.g. "Rent", "Insurance"
• Variable expenses — label, category, comment and amount of each transaction

Filters

Filters appear below the search bar to narrow results:

• Year — limit the search to a specific year
• Month — filter by a specific month
• Type — All / Revenue / Fixed costs / Variables

A Reset button appears as soon as a filter is active.

Results

Results are grouped by year with the type and amount. Clicking a result opens the transaction directly in its category and month (the detail row expands automatically) and closes the search.

🎯 Monthly savings goal

Set a monthly savings goal in euros. A progress bar is displayed in the Home tab to track your progress.

Configure the goal

1. Open the ⚙️ Settings tab
2. Scroll down to the 🎯 Monthly savings goal section
3. Enter the target amount (e.g. €500/month)
4. Click ✅ to save

Progress bar

In the 🏠 Home tab, the bar shows the percentage of the goal reached for the displayed month:

• Green — Goal reached or exceeded 🎉
• Blue — On track (positive balance but below the goal)
• Red — Negative balance, goal not achievable this month

💼 Revenues

Enter your monthly revenues (salary, benefits, bonuses…) in the green section.

Add a revenue

Click ＋ Add a revenue at the bottom of the section. Enter the label and amounts month by month.

Toggle "Included in calculation"

The ∑ column (included in calculation) determines whether this revenue is counted in the monthly summary. Uncheck to temporarily exclude a revenue without deleting it.

Delete a row

Hover over the label of a row to reveal the red ✕ button. Click it to delete (confirmation is requested).

🏠 Fixed Costs

Fixed costs are recurring expenses: rent, energy, subscriptions, insurance…

"Paid" status

Each cost cell has a payment indicator. Click the cell to toggle between paid (green) and unpaid (grey). Only costs marked as paid are included in the real balance calculation.

Cost types

• Fixed — Same amount every month
• Occasional — Variable amount depending on the month
• Savings ↑ — Transfer to the savings account
• Savings ↓ — Withdrawal from savings to checking account

Remaining to pay

At the bottom of each summary table, a "Remaining to pay" row shows the total of costs not yet paid for the month.

🛒 Variable Expenses

Variable expenses (groceries, fuel, miscellaneous…) are entered as individual transactions.

Available categories

In the free version you have 3 categories (groceries, fuel, miscellaneous). In Premium, create as many as you want from ⚙️ Settings → Categories.3 max in free Unlimited in Premium

🔎 Filter categories

A search field at the top of the "Variable Expenses" section lets you filter categories by name in real time. Useful when you have many categories (Premium).

Add an expense

Click the ＋ button in the correct month column. A row is added with the amount, an optional comment, the date and the payment method.

Payment methods

• Card — Bank card payment (default)
• Cash — Cash payment
• Meal voucher — Restaurant tickets / meal vouchers

Category colours

🎯 Category budgets

Set an annual budget for each variable expense category and track your progress in real time.

How it works

For each category (groceries, fuel…), you can set an annual budget. A progress bar is displayed below the category title, showing how much you have spent relative to the goal.

Set a budget

Three ways to set a budget:

1. At account creation — The setup wizard suggests amounts (e.g. groceries €300/month) at step 4. Adjust them, then confirm. Amounts in €/month are automatically converted to €/year.
2. When adding a category — In ⚙️ Settings → Categories, enter an amount in €/month or €/year when adding a new category.
3. Via Settings — In ⚙️ Settings → Categories, edit the Budget/year € field directly on the existing category row.

Missing budget alert

When you click ⚡ + or use Quick add for a category without a budget, an orange alert appears in the form with a Set a budget → link. Click it to enter a monthly amount immediately.

Edit a category

In ⚙️ Settings → Categories, you can now directly edit the icon and label of an existing category by clicking the corresponding fields. No need to delete and recreate.

💰 Savings account

The savings account is managed automatically from special cost rows.

Dedicated savings rows

• 📈 Standing order — Savings (cat: livret_in) — Automatic monthly transfer from checking to savings. Increases savings balance, decreases checking balance.
• 💰 Account → Savings (cat: livret_in) — Manual deposit. Same effect.
• 📉 Savings withdrawal → account (cat: livret_out) — Withdrawal from savings to checking. Decreases savings, increases checking.

Initial savings balance

For the first year, enter the savings balance on January 1st in the Initial savings (01/01) field.

For subsequent years, this field is calculated automatically from the ending balance of the previous year — nothing to enter.

Entering amounts

Always enter positive values. The app automatically handles the direction (deposit or withdrawal) based on the row type.

📊 Monthly summary

The summary table shows the full breakdown for each month: revenues, costs, expenses and balances.

Summary rows

• Revenues — Total revenues marked as "included in calculation"
• Paid costs — Total costs marked as paid
• Variable expenses — Total of entered transactions
• 🔴 Remaining to pay — Costs not yet paid
• Available — Revenues − paid costs − variable expenses
• REAL BALANCE — Checking account balance calculated from the start of the year
• Savings — Savings account balance at the end of the month

🏆 Annual statistics

Below the summary table, statistics cards are displayed for each year: annual savings rate, average monthly savings, best and worst month (by balance), highest variable spending month, and the most costly variable expense category.

Starting balances

At the top of the page (section Starting balances), enter:

• Account (01/01) — Checking account balance on January 1st
• Initial savings — Savings balance on January 1st (auto-calculated for subsequent years)

📈 Financial indicators (KPI)

Four key indicators are displayed automatically at the top of each year to evaluate your financial health at a glance.

Year-end projection

In the monthly summary, a projection row appears if you have at least 1 month of data and the year is not yet over. It calculates your estimated annual savings based on your current monthly average.

📉 Charts

The Charts tab offers several visualisations of your finances, filterable by year. A 📅 Go to [current year] button lets you jump back directly to the current year's tab.

💾 Backup and backups

All data is stored locally in your browser (localStorage). Remember to save regularly.

Manual save

Click 💾 Save in the header. A green notification confirms the save. The date/time of the last save is displayed on the right.

Automatic daily backup

With each save, a dated copy is created automatically. The app keeps the last 20 backups (one per day).

Restore a backup

Click 📦 Backups in the header. The list of backups appears with their dates. Click Restore to go back to a previous state.

📥 External backup — Export / Import JSON

To avoid any risk of loss when clearing cache, you can export your data as a JSON file:

1. Go to ⚙️ Settings
2. In the 📥 External backup section, click ⬇️ Export JSON
3. A file budget_backup_XXXX.json is downloaded — keep it somewhere safe (cloud, USB drive…)
4. To restore, click ⬆️ Import JSON and select the file

🐙 Free cloud sync via GitHub Gist

GitHub Gist sync saves your data online automatically with every save. If you clear your cache or switch device, your data can be recovered in one click.

Export CSV

Click 📥 Export CSV to download your monthly data as a spreadsheet. This file can be re-imported via 📂 Import CSV.

🌙 Dark mode / Light mode

Switch between light and dark theme at any time.

Click the 🌙 (dark mode) or ☀️ (light mode) button in the top right corner of the header. The choice is remembered and will persist on the next visit.

📅 Create a new year

Each year is independent. Create a new year to start tracking a new financial period.1 year max in free Unlimited in Premium

Procedure

1. Click ＋ Year to the right of the year tabs
2. A window appears with your usual revenues (based on the average of the previous year)
3. Adjust the amounts if needed
4. Click ✅ Create year

The year is created with:

• The revenues you confirmed
• The same fixed costs as the previous year
• The initial savings balance calculated automatically from the end of the previous year
• No variable expenses (to be entered throughout the year)

Delete a year

Hover over the year tab → click the ✕ that appears. Confirmation is requested with an option for automatic backup.

🔐 Login & Cloud Account

Create an account with your email address to access cloud sync and activate Premium.

Why log in?

Without a login, your data is stored only in your browser. With a connected account:

• ✅ Automatic sync in Firebase cloud (Premium)
• ✅ Access from multiple devices (PC, phone, tablet)
• ✅ Your data is recoverable if you change browser
• ✅ Automatic Premium activation after Stripe payment

How to create an account / log in

1. Go to the ⚙️ Settings tab and click 🔐 Log in
2. Enter your email address and a password
3. If it's your first time: click Create account — a verification email is sent
4. If you already have an account: click Log in
5. Your email appears in Settings — you are logged in ✅

➕ Quick Add button

The green ➕ button at the bottom right lets you add a variable expense quickly, from any view.

How to use it

1. Click the green ➕ button at the bottom right of the screen
2. A form appears with fields: category, amount, month, comment, payment method, day
3. The year and month are pre-filled based on the active tab
4. Enter the amount and click ✅ Add

Available fields

• Category — Groceries, fuel, miscellaneous, or your custom categories Premium
• Amount — The expense amount in euros
• Month — The month to assign the expense to
• Comment — Optional note (e.g. "Lidl", "Full tank")
• Payment method — Card, cash, meal voucher…
• Day — The day of the month (optional)

🤖 AI Assistant (Groq)

The AI assistant answers questions about your 10 most recent transactions in natural language. Powered by Groq — free, no credit card required.

Activate the assistant (2 minutes)

1. Go to console.groq.com/keys
2. Create a free account (email + password, no credit card)
3. Click Create API Key
4. Give it a name (e.g. "Mon Budget") and copy the generated key (starts with gsk_…)
5. In the app, go to ⚙️ Settings → AI Assistant
6. Paste the key in the field and click ✅ Save

Using the chat

1. Click the purple 🤖 button at the bottom right
2. The chat panel opens
3. Type your question and press Enter
4. The assistant replies based on your real data

Example questions

Conversation history

The chat history is saved automatically on your device (localStorage). You'll find your previous exchanges every time you open the chat. The 🗑️ Clear button wipes the history.

Privacy

Your budget data is sent to the Groq API only when you ask a question. Groq uses the Llama 3.1 model (open-source). The API key is stored only in your browser, never on our servers.

💬 Feedback & Suggestions

Send your ideas, bug reports or questions directly from the app. Every message is read and handled personally.

Send a message

1. Click the 💬 icon at the bottom right of the app
2. Choose the category: 🐛 Bug, 💡 Idea, ❓ Question or 💬 Other
3. Enter a subject and your message
4. Give an optional ⭐ rating
5. Click 📤 Send

Tracking your request

Each feedback receives a status that evolves as it is processed:

• 🟠 New — received, not yet read
• 🔵 Read — taken into account
• 🟣 In progress — being processed
• 🟢 Replied — a reply has been sent to you by email
• ⚫ Closed — processing complete