3. Dashboard

The Dashboard is the default landing page after you log in to NkapBooks. It provides an at-a-glance view of your business's financial health through interactive charts and summary widgets — all updated in real time from your accounting data.

3.1 Overview

The Dashboard is organized into four distinct sections, laid out vertically:

Each section operates independently with its own Period Selector, but a global Period Selector in the page header can synchronize all sections at once.

Dark Mode Support

Every chart and widget on the Dashboard fully supports dark mode. Colors, grid lines, fonts, and background shades adapt automatically when you toggle dark mode from the sidebar. For example:

• Chart grid lines become semi-transparent white (rgba(200, 200, 200, 0.2))
• Font colors shift to gray-400
• Bar and line colors use the 600 shade variants instead of 500

Empty States

When there is no data for a particular section, the Dashboard displays a friendly placeholder message instead of an empty chart:

• Cashflow: Shows a dimmed placeholder line chart with dummy data points in gray tones, giving you a preview of what the chart will look like once you start recording transactions.
• Profit and Loss: Displays "No transactions yet"
• Top Expenses: Displays "No expenses in this period"
• Unpaid Invoices: Shows a grayed-out bar with no amounts

3.2 Dashboard Components

3.2.1 Cashflow

The Cashflow section occupies the full width at the top of the Dashboard. It uses a Line Chart with two data series:

How it works:

1. The system queries all AccountingLedgerEntry records linked to accounts of type Cash or Bank.
2. Data is aggregated by month (format: yyyy-MM) within the selected period.
3. Each month shows two data points — total inflow and total outflow.
4. Hovering over any data point shows a tooltip with the formatted currency value.

Legend: A color-coded legend appears between the title and the period selector, showing:

• 🟦 Inflow — Blue indicator
• 🟥 Outflow — Pink indicator

Period Options: This Year, This Quarter, YTD

3.2.2 Unpaid Invoices

The Unpaid Invoices section is split into two side-by-side widgets:

Each widget displays:

• Paid Amount — Total amount already paid across all invoices in the period, shown on the left. Clicking this navigates to a filtered list of paid invoices (outstandingAmount = 0).
• Unpaid Amount — Total outstanding amount across all invoices in the period, shown on the right. Clicking this navigates to a filtered list of unpaid invoices (outstandingAmount != 0).
• Progress Bar — A horizontal bar showing the proportion of paid (filled) vs. unpaid (unfilled). The filled portion uses the theme color (blue for sales, pink for purchases).
• Hover Tooltip — A MouseFollower tooltip appears on hover, showing the count of paid and unpaid invoices.

How it works:

1. Queries getTotalOutstanding from the database for the selected date range.
2. Separately counts total invoices and outstanding invoices using raw queries on outstandingAmount.
3. Calculates the bar width as: paid / total × 100%.

Period Options: This Year, YTD, This Quarter, This Month

Interactivity:

• Click the Paid amount to navigate to: /list/SalesInvoice/Paid Sales Invoice (filtered)
• Click the Unpaid amount to navigate to: /list/SalesInvoice/Unpaid Sales Invoice (filtered)
• The + action (via the section header) creates a new invoice directly

3.2.3 Profit and Loss

The Profit and Loss section appears in the bottom-left quadrant. It uses a Bar Chart that shows net profit (or loss) for each month in the selected period.

How it works:

1. Calls getIncomeAndExpenses from the database for the selected date range.
2. For each month in the period list, calculates: net = income - expenses.
3. Positive values appear as upward bars (blue), negative values as downward bars (pink).
4. The Y-axis automatically scales to accommodate both positive and negative values (yMax and yMin).
5. X-axis labels are formatted as abbreviated month-year (e.g., "Jan 25", "Feb 25").

Period Options: This Year, This Quarter, YTD

3.2.4 Top Expenses

The Top Expenses section appears in the bottom-right quadrant. It uses a Donut Chart showing the top expense accounts for the selected period.

How it works:

1. Calls getTopExpenses from the database for the selected date range.
2. Returns up to 5 expense accounts, sorted by total amount descending.
3. Each account is assigned a shade of pink (from darkest to lightest):
   • Pink 500, 400, 300, 200, 100 (light mode)
   • Pink 600, 500, 400, 300, 200 (dark mode)

Visual Elements:

Period Options: This Year, YTD, This Quarter, This Month

3.3 Period Selector

The Period Selector is a dropdown component used throughout the Dashboard (and in other parts of the application). It allows you to filter data by time range.

Available Periods

Global vs. Local Period Selectors

The Dashboard has two levels of period selection:

1. Global Period Selector — Located in the Page Header (top-right of the Dashboard). When you select a period here, it broadcasts the change to all four sections simultaneously.
2. Local Period Selectors — Each section (Cashflow, Unpaid Invoices, Profit & Loss, Top Expenses) has its own period selector. Changing a local selector updates only that section.

Synchronization behavior:

• Selecting a period in the global selector sets the commonPeriod prop on all child components, which updates their local period to match (if the period is available in their options).
• Selecting a period in a local selector emits a period-change event upward. The Dashboard's handlePeriodChange method then clears the global period to indicate that sections are no longer synchronized.
• This means: after using the global selector, all sections are in sync. After changing any individual section's period, only that section changes — the others remain at their previous selection.

Period Calculation

Under the hood, the getDatesAndPeriodList utility function converts a period key into:

• fromDate — The start date (e.g., January 1 for "This Year")
• toDate — The end date (e.g., December 31 for "This Year")
• periodList — An array of DateTime objects representing each month in the range, used to generate X-axis labels and fill in months with zero data

Localized Labels

Period labels are fully translated via the i18n system:

3.4 Keyboard Shortcuts

The Dashboard supports the following global keyboard shortcuts:

Since the Dashboard is the root page, pressing the sidebar shortcut or using the search command will always bring you back here.

3.5 Data Sources

The Dashboard charts pull data from the following database methods:

All amounts are displayed in your company currency using the configured currency format. Multi-currency invoices are converted using their exchange rate to the base currency before aggregation.

3.6 Tips & Best Practices

• Check the Dashboard daily to stay on top of unpaid invoices and cash flow trends.
• Click on Paid/Unpaid amounts in the invoice widgets to jump directly to filtered invoice lists for follow-up.
• Watch for negative bars in the Profit & Loss chart — they indicate months where expenses exceeded income.
• Review Top Expenses monthly to identify cost-saving opportunities or unexpected spending patterns.
• Use "This Month" for operational monitoring and "This Year" for strategic overview.