Cashflow App - Features & Capabilities Report

Template Version: 1.0.0 Generated: 2026-01-22 Package: @epicdm/flowstate-app-cashflow App ID: cashflow

Table of Contents

1. Overview
2. App Identity
3. Feature Categories
4. Capabilities
5. Data Models
6. User Workflows
7. Integration Points
8. Architecture Summary
9. Quality & Compliance

Overview

Purpose

The Cashflow App is a comprehensive financial tracking and income statement management application for FlowState. It provides real-time visibility into personal or business finances through a 4-quadrant income statement dashboard, account management, transaction tracking, scheduled transactions with cash flow projections, and seamless YNAB integration for data synchronization.

Target Users

Value Proposition

• 4-Quadrant Income Statement: Visual dashboard showing Income, Expenses, Assets, and Liabilities
• YNAB Integration: Seamless OAuth sync with existing YNAB budgets and accounts
• Cash Flow Projections: 30-day forward-looking projections from scheduled transactions
• Guided Setup Wizard: Multi-step wizard for easy onboarding (manual or YNAB import)
• Flexible Period Views: Monthly, quarterly, and annual period filtering
• Real-time Net Worth: Automatic calculation from asset and liability accounts
• Category Management: Customizable hierarchical categories for transaction organization
• CSV Import: Bulk transaction import from bank exports

App Identity

Entry Points

Feature Categories

Category 1: Income Statement Dashboard

Core financial dashboard with 4-quadrant layout

Feature: 4-Quadrant Dashboard

Description: Main dashboard displaying income statement data in a 4-quadrant layout: Income (top-left), Assets (top-right), Expenses (bottom-left), and Liabilities (bottom-right). Includes net worth summary and cash flow overview.

User Story: As a user, I want to see my financial position at a glance so that I can understand my income, expenses, and net worth.

Acceptance Criteria:

• [x] Display income quadrant with period totals
• [x] Display expense quadrant with budgeted vs actual
• [x] Display assets quadrant with account balances
• [x] Display liabilities quadrant with debt balances
• [x] Show net worth summary
• [x] Show cash flow summary (income - expenses)

Implementation:

Routes:

• /dashboard - Main dashboard (default route)

Feature: Period Navigation

Description: Navigate between monthly, quarterly, and annual periods with forward/back controls. Data automatically filters to the selected period.

User Story: As a user, I want to view my finances by different time periods so that I can track trends over time.

Acceptance Criteria:

• [x] Toggle between monthly, quarterly, annual views
• [x] Navigate forward/backward in time
• [x] Display current period label
• [x] Filter all dashboard data by selected period

Implementation:

Category 2: Account Management

Track and manage financial accounts

Feature: Account CRUD Operations

Description: Create, view, edit, and delete financial accounts including checking, savings, credit cards, loans, and other account types.

User Story: As a user, I want to manage my accounts so that I can track balances across all my financial institutions.

Acceptance Criteria:

• [x] Create accounts with name, type, and initial balance
• [x] View accounts in grouped list (assets/liabilities)
• [x] Edit account details
• [x] Delete/close accounts
• [x] Track cleared and uncleared balances
• [x] Support debt-specific fields (interest rate, minimum payment)

Implementation:

Routes:

• /accounts - Account list
• /accounts/:accountId - Account detail with transactions

Category 3: Transaction Management

Track and categorize financial transactions

Feature: Transaction List & Filtering

Description: View all transactions with comprehensive filtering by date range, account, category, amount, and cleared status. Includes search functionality.

User Story: As a user, I want to view and filter my transactions so that I can find specific transactions and understand spending patterns.

Acceptance Criteria:

• [x] Display transactions in sortable list
• [x] Filter by date range
• [x] Filter by account
• [x] Filter by category
• [x] Filter by amount range
• [x] Filter by cleared status
• [x] Search by payee name
• [x] Show active filter badges

Implementation:

Routes:

• /transactions - Transaction list with filters

Feature: Bulk Category Assignment

Description: Select multiple transactions and assign a category to all of them at once for efficient categorization of imported transactions.

User Story: As a user, I want to categorize multiple transactions at once so that I can quickly organize imported transactions.

Acceptance Criteria:

• [x] Multi-select transactions in list
• [x] Show selection count
• [x] Open category assignment modal
• [x] Apply category to all selected
• [x] Clear selection after assignment

Implementation:

Feature: CSV Import

Description: Import transactions from CSV files exported from banks or other financial software with column mapping wizard.

User Story: As a user, I want to import transactions from CSV so that I can bring in data from my bank.

Acceptance Criteria:

• [x] Upload CSV file
• [x] Preview data before import
• [x] Map CSV columns to transaction fields
• [x] Validate data before import
• [x] Create transactions from import

Implementation:

Category 4: Budget Management

Create and track budgets

Feature: Budget Display

Description: View budgets with their associated accounts, date ranges, and currency information. Supports YNAB-synced budgets.

User Story: As a user, I want to see my budgets so that I can track my spending against planned amounts.

Acceptance Criteria:

• [x] Display budget cards with key information
• [x] Show date range (first/last month)
• [x] Show associated accounts with balances
• [x] Display currency format
• [x] Link to budget creation/setup wizard

Implementation:

Routes:

• /budgets - Budget list

Category 5: Category Management

Organize transactions with categories

Feature: Category CRUD Operations

Description: Create, view, edit, and delete categories organized in category groups. Supports both income and expense categories.

User Story: As a user, I want to manage categories so that I can organize my transactions meaningfully.

Acceptance Criteria:

• [x] Create categories with name and group
• [x] View categories grouped by category group
• [x] Edit category details
• [x] Delete categories
• [x] Support income vs expense categorization
• [x] Provide default category templates

Implementation:

Routes:

• /categories - Category management

Category 6: Scheduled Transactions

Manage recurring transactions and cash flow projections

Feature: Scheduled Transaction Management

Description: View and manage scheduled/recurring transactions with various frequency options (daily, weekly, monthly, etc.). Filter by income or expenses.

User Story: As a user, I want to manage scheduled transactions so that I can track recurring income and expenses.

Acceptance Criteria:

• [x] Display scheduled transactions in table
• [x] Show frequency, next date, amount
• [x] Filter by income/expenses
• [x] Sort by next date
• [x] Support multiple frequency options

Implementation:

Routes:

• /scheduled - Scheduled transactions list

Feature: Cash Flow Projections

Description: Calculate and display 30-day forward-looking cash flow projections based on scheduled transactions.

User Story: As a user, I want to see projected cash flow so that I can plan for upcoming income and expenses.

Acceptance Criteria:

• [x] Calculate projected income for 30 days
• [x] Calculate projected expenses for 30 days
• [x] Calculate net cash flow
• [x] Show count of upcoming transactions
• [x] Display summary cards

Implementation:

Category 7: YNAB Integration

Sync data with YNAB (You Need A Budget)

Feature: YNAB OAuth Connection

Description: Connect to YNAB using OAuth 2.0 authentication flow. Manage connection status and disconnect when needed.

User Story: As a YNAB user, I want to connect my YNAB account so that I can sync my data into FlowState.

Acceptance Criteria:

• [x] OAuth connect button
• [x] Handle OAuth callback
• [x] Store tokens securely
• [x] Display connection status
• [x] Disconnect functionality
• [x] Show connection timestamp

Implementation:

Routes:

• /settings - YNAB connection settings
• /settings/ynab-callback - OAuth callback handler

Feature: YNAB Data Sync

Description: Synchronize accounts, categories, transactions, and scheduled transactions from YNAB with configurable polling interval.

User Story: As a user, I want to sync my YNAB data so that I can see my YNAB information in FlowState.

Acceptance Criteria:

• [x] Select budget to sync
• [x] Manual sync on demand
• [x] Background auto-sync with interval
• [x] Show sync progress and status
• [x] Display sync results (created/deleted counts)
• [x] Test sync mode (limited records)
• [x] Configure polling interval (5-60 minutes)

Implementation:

Feature: YNAB Import in Setup Wizard

Description: Import YNAB data as part of the setup wizard flow for easy onboarding of existing YNAB users.

User Story: As a YNAB user, I want to import my data during setup so that I can quickly get started with FlowState.

Acceptance Criteria:

• [x] YNAB import path in wizard
• [x] Budget selection during import
• [x] Import progress display
• [x] Import accounts, categories, transactions

Implementation:

Category 8: Setup Wizard

Guided setup for new income statements

Feature: Multi-Step Setup Wizard

Description: Multi-step wizard guiding users through income statement setup with options for manual creation or YNAB import.

User Story: As a new user, I want a guided setup process so that I can easily configure my income statement.

Acceptance Criteria:

• [x] Choose path (manual vs YNAB)
• [x] Basics step (name, description)
• [x] Categories step (configure categories)
• [x] Accounts step (add accounts)
• [x] Income step (configure income sources)
• [x] Expenses step (configure expense budgets)
• [x] Review step (confirm and activate)
• [x] Progress indicator
• [x] Draft persistence (resume incomplete setup)

Implementation:

Routes:

• /setup/new - New income statement wizard
• /setup/:id - Resume draft wizard

Capabilities

Core Capabilities

Technical Capabilities

Integration Capabilities

Data Models

Collections Used

Entity Relationships

IncomeStatement
    |
    +-- Accounts (hasMany via budget)
    |       |
    |       +-- Transactions (hasMany)
    |
    +-- Categories (hasMany via budget)
    |       |
    |       +-- Transactions (belongsTo)
    |
    +-- ScheduledTransactions (hasMany)

Budget
    |
    +-- Accounts (hasMany)
    |
    +-- Categories (hasMany)
    |
    +-- Transactions (hasMany)

Key Data Flows

User Action --> Component --> Hook --> RxDB Collection --> UI Update
                                  |
                                  +--> YNAB Sync Service
                                  |
                                  +--> Replication --> Server

User Workflows

Workflow 1: Initial Setup (Manual)

Set up first income statement manually

Trigger: Click "New" or navigate to /setup/new

Steps:

Success Outcome: Income statement created and visible on dashboard Failure Handling: Draft saved, can resume from /setup/:id

Workflow 2: YNAB Connection & Sync

Connect YNAB and sync data

Trigger: Navigate to Settings, click "Connect YNAB"

Steps:

Success Outcome: YNAB data visible in app Failure Handling: Error displayed, retry option available

Workflow 3: Transaction Categorization

Categorize uncategorized transactions

Trigger: View transactions with missing categories

Steps:

Success Outcome: Transactions categorized, appear in expense reports Failure Handling: Error toast, selection preserved

Workflow 4: CSV Import

Import transactions from bank CSV

Trigger: Click "Import CSV" on transactions page

Steps:

Success Outcome: Transactions imported and visible in list Failure Handling: Validation errors shown, can adjust mapping

Integration Points

Internal Integrations

External Integrations

MCP Integration

Architecture Summary

Directory Structure

src/
├── components/          # UI components (30+ files)
│   ├── accounts/       # Account components (8 files)
│   ├── categories/     # Category components (5 files)
│   ├── dashboard/      # Dashboard quadrants (8 files)
│   └── transactions/   # Transaction components (6 files)
├── hooks/              # Custom React hooks (15 hooks)
├── services/           # Business logic
│   ├── sync/          # YNAB sync service
│   └── ynab/          # YNAB OAuth/API
├── pages/              # Page components (13 pages)
│   └── SetupWizard/   # Multi-step wizard (7 steps)
├── constants/          # Default categories, config
├── utils/              # Utility functions
└── styles/             # Tailwind CSS

Key Architectural Patterns

Services Overview

Hooks Overview

Quality & Compliance

Test Coverage

Accessibility

Security Considerations

FlowState Alignment

Spec-Driven Development

This app follows the FlowState Standard for spec-driven development:

• Requirements: .flowstate/specs/{{feature-name}}/requirements.md
• Design: .flowstate/specs/{{feature-name}}/design.md
• Wireframes: .flowstate/specs/{{feature-name}}/wireframes.html
• Tasks: .flowstate/specs/{{feature-name}}/tasks.md

Quality Gates

Appendix

Related Documentation

Version History