09 — Frontend & UX: React Components, Dashboards, Excel & Mobile
Domain: UI architecture, data visualization, spreadsheet integration, responsive design Dependencies: 05-Core Ops (APIs), 06-FP&A (planning APIs), 07-Agents (chat API) Outputs: Component architecture, design system, dashboard specs, Excel add-in architecture
ROLE
You are a Senior Frontend Architect specializing in financial application UX — the kind of interfaces that CFOs, controllers, and FP&A analysts use daily. You design systems that compete with Excel's flexibility while adding the intelligence and governance that spreadsheets lack. You understand that financial users demand pixel-perfect grids, keyboard navigation, and sub-second response times.
OBJECTIVE
Design the complete frontend layer that delivers a financial user experience superior to both legacy tools (Excel, SAP GUI) and modern competitors (Anaplan, Planful, Datarails). The UI must handle complex financial grids, real-time dashboards, conversational AI chat, mobile expense capture, and Excel bi-directional sync.
DELIVERABLES
D1. Component Architecture (React / Refine)
Application Shell:
┌─────────────────────────────────────────────────────────┐
│ Top Nav: Entity selector | Period selector | Search │
├──────────┬──────────────────────────────────────────────┤
│ │ │
│ Side │ Main Content Area │
│ Nav │ │
│ │ ┌──────────────────────────────────────┐ │
│ • Home │ │ Financial Grid / Chart / Form │ │
│ • AP │ │ │ │
│ • AR │ │ │ │
│ • Cash │ └──────────────────────────────────────┘ │
│ • Plan │ │
│ • Fcst │ ┌──────────────────────────────────────┐ │
│ • Rpts │ │ AI Chat Panel (collapsible right) │ │
│ • AI │ │ "Ask anything about your finances" │ │
│ • Admin │ └──────────────────────────────────────┘ │
│ │ │
├──────────┴──────────────────────────────────────────────┤
│ Status Bar: Sync status | Last refresh | User role │
└─────────────────────────────────────────────────────────┘
Core Component Library:
| Component | Library | Purpose |
|---|---|---|
| Financial Grid | AG Grid (Enterprise) or TanStack Table | Editable grids with Excel-like behavior |
| Charts | Plotly.js or Recharts | Interactive financial visualizations |
| Forms | React Hook Form + Zod | Validated data entry |
| Date/Period Picker | Custom (fiscal-aware) | BR/US fiscal calendar support |
| Currency Input | Custom | Multi-currency with live FX |
| Approval Workflow | Custom | Multi-step with visual status |
| Document Viewer | react-pdf + custom OCR overlay | Invoice/receipt viewing with AI highlights |
| Chat Interface | Custom (streaming) | AI chat with SSE streaming responses |
| Drag & Drop | dnd-kit | Report builder, dashboard customization |
| Export | Custom | PDF, Excel, CSV with formatting |
D2. Financial Grid Specification
Requirements (Excel-parity):
- Editable cells with formula support (SUM, IF, basic arithmetic)
- Copy/paste between grid and Excel (TSV clipboard format)
- Keyboard navigation: Tab, Enter, arrow keys, Ctrl+C/V
- Column freeze (accounts column always visible during horizontal scroll)
- Row grouping with expand/collapse (account hierarchy drill-down)
- Conditional formatting: variance colors (red negative, green positive)
- Cell-level permissions (locked cells for approved budgets)
- Undo/redo stack (Ctrl+Z/Y)
- Column sorting, filtering, search
- Inline comments on cells (threaded)
- Performance: render 10,000 rows with virtual scrolling at 60fps
Grid Contexts:
| Context | Columns | Editable | Special Features |
|---|---|---|---|
| Budget Entry | Account × Period (12 months) | Yes | Spreading, formulas, approval status |
| BvA Report | Account × (Budget, Actual, Variance $, Variance %) | No | Drill-down, conditional formatting |
| Cash Flow | Category × Week/Month | Partial | Manual overrides on forecasts |
| Trial Balance | Account, Debit, Credit, Balance | No | Period comparison, variance |
| Aging Report | Vendor/Customer × Aging Buckets | No | Collection priority sorting |
D3. Dashboard Framework
Dashboard Types:
- CFO Executive: Revenue, expenses, EBITDA, cash position, key KPIs (single screen)
- Controller: Month-end close progress, reconciliation status, open items
- FP&A Analyst: Forecast accuracy, budget utilization, scenario comparison
- AP Manager: Invoice pipeline, payment schedule, vendor spend
- AR Manager: Collection status, aging, DSO trend, revenue recognition
- Cash Manager: Multi-bank positions, investment yields, cash forecast
Widget Library:
- KPI card (actual vs. target with trend arrow)
- Waterfall chart (bridge between periods)
- Variance heatmap (accounts × periods)
- Cash flow timeline (stacked area with forecast overlay)
- Aging bucket chart (horizontal stacked bar)
- Forecast accuracy gauge (MAPE score with quality rating)
- Alert feed (real-time anomaly and threshold notifications)
- Mini P&L (condensed income statement)
Dashboard Customization:
- Drag-and-drop widget placement
- User-level dashboard persistence
- Role-based default dashboards
- Auto-refresh intervals (configurable per widget)
- Full-screen presentation mode for board meetings
- PDF export with consistent branding
D4. Excel Integration Architecture
Excel Add-In (Office.js):
- Bi-directional sync: read actuals/forecasts into Excel, push budgets back
- Named ranges mapped to platform data (e.g.,
=AVIVATEC.GL("Revenue", "2026-Q1")) - Custom functions:
=AVIVATEC.FORECAST("Revenue", 12)— inline forecast in cell - Ribbon integration: Sync, Publish Budget, Refresh, AI Assist buttons
- Template management: download/upload budget templates
- Conflict resolution: detect and merge concurrent edits
Google Sheets Add-On:
- Same functionality as Excel Add-In via Apps Script
- Real-time sync via WebSocket connection
- Sidebar for AI chat integration
D5. AI Chat Interface
Design:
┌──────────────────────────────────────────┐
│ 🤖 Avivatec AI [−] [×]│
├──────────────────────────────────────────┤
│ │
│ [User] Show me revenue by entity for Q3 │
│ │
│ [AI] Here's Q3 revenue by entity: │
│ ┌─────────────────────────────┐ │
│ │ 📊 Revenue by Entity - Q3 │ │
│ │ [Interactive Plotly Chart] │ │
│ └─────────────────────────────┘ │
│ Total revenue was R$2.4M, up 12% │
│ vs Q2. Entity A led with R$1.1M... │
│ │
│ [Source: 847 GL transactions] [Expand] │
│ │
│ [User] Why did Entity B decline? │
│ │
│ [AI] Entity B revenue declined 8%... │
│ • Client X contract ended (−R$45K) │
│ • Seasonal dip in services (−R$22K) │
│ Partially offset by new client Y (+R$18K)│
│ │
├──────────────────────────────────────────┤
│ [💬 Type a question... ] [Send ▶] │
│ [📎 Attach] [🎤 Voice] [📊 Quick Chart] │
└──────────────────────────────────────────┘
Chat Features:
- Streaming responses (SSE from FastAPI)
- Inline chart rendering (Plotly embedded in chat)
- Source attribution ("Based on 847 transactions" with expand to list)
- Quick action buttons: "Show details", "Export to Excel", "Create alert"
- Voice input (Whisper transcription)
- Context awareness: chat knows current page, selected entity, active period
- Multi-turn conversation with memory
D6. Mobile Application (Responsive PWA)
Mobile-Specific Screens:
- Dashboard (scrollable KPI cards with charts)
- Approval queue (swipe to approve/reject)
- Receipt capture (camera → OCR → review → submit)
- Expense entry (simplified form with photo upload)
- Cash position (bank balances with trend sparklines)
- AI chat (full chat experience with voice input)
- Push notifications (approval requests, threshold alerts, anomalies)
Offline Support:
- Service worker for offline dashboard viewing (last-synced data)
- Offline expense entry with queue-and-sync on reconnect
- Conflict resolution: server wins for financial data, client wins for drafts
D7. Design System
Brand Tokens:
- Primary palette: professional financial blues + accent greens
- Negative values: red (#DC2626), Positive: green (#16A34A)
- Typography: Inter (headings), JetBrains Mono (numbers/code)
- Spacing scale: 4px base unit
- Border radius: 6px (cards), 4px (inputs), 2px (badges)
- Shadows: 3-level elevation system
Accessibility (WCAG 2.1 AA):
- Keyboard navigation for all financial grids
- Screen reader support for charts (data table fallback)
- Color-blind safe palette (patterns in addition to colors)
- Minimum 4.5:1 contrast ratio for text
- Focus indicators on all interactive elements
CONSTRAINTS
- Financial grid must handle 10,000+ rows at 60fps
- All monetary values displayed with proper formatting (R$ 1.234,56 / $1,234.56)
- Locale-aware: PT-BR default for Brazilian tenants, EN-US for US
- RTL layout support not required (BR/US markets only)
- Bundle size: < 500KB initial load, code-split per route
- Time to interactive: < 3 seconds on 4G connection
RESEARCH QUESTIONS
- What is the optimal grid library for Excel-like editing with 10K+ rows (AG Grid Enterprise vs. TanStack + custom)?
- How should the Excel Add-In handle offline editing with eventual consistency?
- What is the best approach for streaming AI chat responses with inline chart rendering?
- How to implement fiscal-period-aware date pickers that support both BR (Jan-Dec) and US (custom fiscal year) calendars?
- What PWA capabilities are needed for reliable mobile expense capture in low-connectivity areas?
ADRs TO PRODUCE
- ADR-010: React (Refine) over Angular (component ecosystem, developer availability)
- ADR-UX-001: Grid library selection (AG Grid vs. TanStack vs. Handsontable)
- ADR-UX-002: Chart library selection (Plotly.js vs. Recharts vs. D3)
- ADR-UX-003: Mobile strategy (PWA vs. React Native vs. native)