integreat/docs/testing/behaviors/dashboard.md

Dashboard Behaviors

Overview

The Dashboard is an admin-only, SSR-based overview page that displays financial summary cards across selected clients. It provides at-a-glance visibility into bank account balances, outstanding tasks, recent sales trends, expense breakdowns, and profit/loss summaries. Cards are loaded lazily via HTMX for progressive rendering.

Routes

Route	Handler	Purpose
GET /	::page	Main dashboard page with stub cards
GET /expense-card	::expense-card	Expense pie chart (top 5 accounts, last month)
GET /pnl-card	::pnl-card	Profit & Loss bar chart (last month)
GET /sales-card	::sales-card	Gross sales bar chart (last 14 days)
GET /bank-accounts-card	::bank-accounts-card	Bank account balances and sync status
GET /tasks-card	::tasks-card	Unpaid invoices and uncategorized transactions

Behaviors

Unit Test Behaviors

• extract-client-ids returns intersection of user's allowed clients and requested clients
• is-admin? returns true only when user/role equals "admin"
• Client trimming takes only first 20 clients from the valid set
• clients-trimmed? is true when the count of trimmed clients differs from valid clients
• Bank account card excludes accounts with bank-account-type/cash
• Bank account card displays ledger balance formatted as $X,XXX.XX
• Bank account card shows sync timestamp in standard-time format when present
• Sales chart queries use ISO date range from 14 days ago to tomorrow
• Expense pie chart queries use date range from 1 month ago to tomorrow
• P&L card aggregates accounts into :sales and :cogs :payroll :controllable :fixed-overhead :ownership-controllable categories
• Tasks card queries invoices with invoice-status/unpaid and transactions with transaction-approval-status/requires-feedback
• Tasks card only renders task sections when counts are non-zero

Integration Test Behaviors

• Main page GET / returns 200 with base layout and 6 stub cards for admin users
• Each card endpoint returns 200 with HTML response containing chart canvas or data
• Bank accounts card performs Datomic pull for each client's bank accounts with nested Intuit/Yodlee/Plaid data
• Sales card executes Datomic query summing sales-order/total by ISO date
• Expense card executes Datomic query summing invoice-expense-account/amount by account name
• P&L card calls GraphQL get-profit-and-loss-raw with trimmed client IDs and last-month date range
• Tasks card executes two separate Datomic queries for unpaid invoices and uncategorized transactions
• Expense breakdown card (from company/reports/expense) executes query with optional vendor and account filters
• All card endpoints apply wrap-trim-clients and wrap-admin middleware
• Non-admin requests to any dashboard route receive 302 redirect to /login
• Unauthenticated requests receive 302 redirect to /login with redirect-to parameter

UI Test Behaviors (SSR)

Happy Path: Dashboard Loads Successfully

1. Admin user navigates to /
2. Page renders with main navigation, client selector, and breadcrumb "Dashboard"
3. Six stub cards appear with loading spinners:
   • Expenses (pie chart)
   • Tasks
   • Bank Accounts (tall card, row-span-2)
   • Gross Sales, last 14 days (bar chart)
   • Profit and Loss, last month (horizontal bar chart)
   • Expense breakdown (bar chart, wide card)
4. Each stub card triggers hx-get on load to fetch its content
5. Cards progressively render with actual data
6. User sees bank account balances, task counts, sales chart, expense charts, and P&L summary

Card Interactions

• Bank Accounts card displays each client's name, account name, ledger balance, and last sync time
• When a bank account has Intuit/Yodlee/Plaid sync, the external balance and sync time display alongside the ledger balance
• Yodlee accounts additionally show "Pending Txs" with pending balance
• Tasks card shows "Pay now" link for unpaid invoices (links to unpaid invoices page with date-range=year)
• Tasks card shows "Review now" link for uncategorized transactions (links to requires-feedback transactions page)
• Expense breakdown card has Vendor and Account typeahead filters
• Changing Vendor or Account filter triggers HTMX request to reload the breakdown chart with filtered data
• Expense breakdown chart updates URL via hx-push-url with query params

Client Selection Effects

• User selects different clients from the client dropdown
• Page triggers clientSelected event on body
• HTMX swaps #app-contents with fresh dashboard content for newly selected clients
• All cards re-fetch with new client context
• If more than 20 clients selected, a yellow warning banner appears: "Warning: These reports are only for twenty of the selected customers. Please select a specific customer to see more detail."

Edge Cases

No Clients Selected

• Dashboard page renders but all cards show empty state
• Bank Accounts card renders empty list
• Sales chart shows empty bar chart with no data points
• Expense pie chart shows empty pie chart
• P&L card shows zero income and expenses
• Tasks card shows no task notifications (sections hidden when count is zero)

Many Clients (Trimming Warning)

• When user has access to more than 20 clients and selects all, only first 20 are used
• Yellow warning banner displays below breadcrumb
• All card queries execute against trimmed client set only
• Warning persists across client selection changes until fewer than 21 clients selected

No Data for Date Ranges

• Sales chart (14-day window): Empty chart renders with no bars when no sales orders exist
• Expense pie chart (last month): Empty pie chart renders when no invoices with expense accounts exist
• P&L card: Shows $0.00 for both income and expenses
• Tasks card: No task sections render (conditional on non-zero counts)
• Bank Accounts: Accounts still display with zero/null balances if they exist but have no transactions

Error Loading Individual Cards

• Each card loads independently via separate HTMX request
• Failure in one card endpoint does not prevent other cards from loading
• Stub card shows spinner until successful response or timeout
• Server errors in card endpoints return appropriate HTTP status without breaking page layout

Permissions (Admin vs User)

• Only users with user/role = "admin" can access dashboard routes
• Non-admin authenticated users receive 302 redirect to /login
• Unauthenticated users receive 302 redirect to /login with redirect-to parameter
• Admin role is verified by wrap-admin middleware before any data queries execute

Bank Account Sync States

• Account with no external sync (Intuit/Yodlee/Plaid): Shows only ledger balance and sync time
• Account with Intuit sync: Shows Intuit balance and last synced timestamp
• Account with Yodlee sync: Shows available balance, last synced timestamp, and pending balance
• Account with Plaid sync: Shows Plaid balance and last synced timestamp
• Missing/null balances display as $0.00

Test Data Requirements

Users

• Admin user (:user/role "admin") with access to multiple clients
• Non-admin user (:user/role "user") to test permission denial

Clients (minimum 2, ideally 25+)

• Client with client/name and at least one bank account
• Mix of clients with Intuit, Yodlee, and Plaid synced accounts
• Client with :bank-account-type/cash account (should be excluded from display)

Bank Accounts

• Bank account with :bank-account/current-balance and :bank-account/current-balance-synced
• Bank account linked to Intuit (:bank-account/intuit-bank-account)
• Bank account linked to Yodlee (:bank-account/yodlee-account with available + pending balance)
• Bank account linked to Plaid (:bank-account/plaid-account)

Sales Orders

• Sales orders dated within last 14 days with :sales-order/total
• Sales orders dated outside 14-day window (should not appear)

Invoices

• Invoices with :invoice/expense-accounts (with :invoice-expense-account/amount and :account/name) within last month
• Invoices with :invoice/status :invoice-status/unpaid within last year
• Invoices with :invoice/outstanding-balance
• Voided invoices (should be excluded from expense breakdown)

Transactions

• Transactions with :transaction/approval-status :transaction-approval-status/requires-feedback within last year
• Transactions with :transaction/amount

P&L Data

• Chart of accounts with categories :sales, :cogs, :payroll, :controllable, :fixed-overhead, :ownership-controllable
• Account balances within last month for selected clients

Dependencies

External Services

• Datomic: All card data queried from Datomic database
• GraphQL endpoint: P&L card calls get-profit-and-loss-raw (Lacinia GraphQL)
• Intuit/Yodlee/Plaid: Bank account sync data for external balances (data stored in Datomic)

Frontend Libraries

• HTMX: Progressive card loading via hx-get/hx-trigger/hx-swap
• Chart.js: Canvas-based chart rendering (bar, pie, horizontal bar charts)
• Alpine.js: Chart data binding via x-data/x-init attributes

Middleware Stack

• wrap-admin: Enforces admin-only access
• wrap-client-redirect-unauthenticated: Handles auth redirects
• wrap-trim-clients: Limits client scope to 20
• wrap-hydrate-clients: Populates client data in request