CloudInsights.ai — Complete Project Documentation

Version: 2025-01-27 (consolidated documentation)

---

Table of Contents

1. Product Overview
2. Technical Architecture
3. Development Status & Sprint Progress
4. Implementation Details
5. Testing & Quality Assurance
6. API Documentation
7. Component Library
8. Data Models & Schemas
9. Deployment & Infrastructure
10. Development Guidelines

---

Product Overview

What is CloudInsights.ai?

CloudInsights.ai is a financial monitoring and analysis dashboard platform that provides business owners with real-time insights into their financial performance. It connects to QuickBooks Online data and presents comprehensive financial metrics, trends, and alerts through an organized, navigable dashboard interface.

The system transforms raw financial data into actionable business intelligence through pre-built analysis views, eliminating the need for manual spreadsheet analysis or accounting expertise.

Target Users

Primary: Small business owners who need continuous visibility into their financial performance and want to monitor key metrics without building custom reports.

Secondary: Startup founders who need to track revenue, expenses, and profitability trends to make informed business decisions.

Problem Statement

Small business owners struggle to:

• Monitor financial health in real-time without manual analysis
• Identify trends and patterns in revenue, expenses, and profitability
• Spot anomalies that could indicate problems or opportunities
• Understand financial performance without accounting expertise
• Maintain consistent financial oversight across different business areas

Solution Summary

CloudInsights.ai provides a comprehensive financial monitoring dashboard with:

• Real-time financial metrics from QuickBooks Online
• Pre-built analysis views for different business areas (Revenue, Expenses, Profitability, Anomalies)
• Automated trend detection and anomaly identification
• Visual data representation through charts, graphs, and tables
• Mobile-responsive design for monitoring anywhere, anytime

Key Product Features

Dashboard Hub Navigation

• Overview Section: High-level financial summary with key performance indicators
• Revenue Analysis: Income trends, growth rates, and revenue health scoring
• Expense Monitoring: Cost structure analysis, spending patterns, and expense drivers
• Profitability Tracking: Margin analysis, profit trends, and financial health metrics
• Anomaly Detection: Automated identification of unusual financial patterns and alerts

Financial Data Integration

• QuickBooks Online Connector: Seamless OAuth integration with live data sync
• Data Normalization: Automatic conversion of QBO data into standardized formats
• Historical Analysis: 12-month trend analysis with customizable date ranges

Visual Analytics Engine

• Chart Components: Line, Bar, Pie, Area, and Table charts for different data types
• Responsive Design: Mobile and desktop optimized viewing experiences
• Interactive Elements: Hover tooltips, drill-down capabilities, and data exploration
• Customizable Layouts: Adaptive dashboard layouts based on data and analysis type

Business Intelligence Features

• Trend Analysis: Automated identification of growth, decline, and seasonal patterns
• Anomaly Detection: Statistical analysis to flag unusual financial events
• Performance Scoring: Health scores and ratings for different financial areas
• Comparative Analysis: Period-over-period and year-over-year comparisons

---

Technical Architecture

High-Level Architecture

Layer	Key Elements
Frontend	Dashboard UI with dynamic rendering (Next.js 15.3 + React 19 + Tailwind + shadcn/ui)
API Layer	/api/analyze, /api/qbo/sync, /api/ai/narrator
Analysis Engine	Deterministic financial analysis modules with layout generation
Data Source	QuickBooks Online (Profit & Loss report) + mock data fallback
Persistence	Firestore (dashboards, user data)
Authentication	Firebase Auth (email/password)
Infrastructure	Vercel hosting · GitHub Actions CI/CD · Automated testing

Technology Stack & Dependencies

Frontend Framework

• Next.js 15.3: Latest version with App Router and Turbopack for 40% faster builds
• React 19: Latest React version with concurrent features and improved performance
• TypeScript 5.8: Strict type checking with comprehensive interface definitions
• Tailwind CSS 3.4: Utility-first CSS with custom design system (15+ color variables)

State Management & Data

• Zustand 5.0: Lightweight state management with TypeScript support
• Firebase 11.9: Authentication, Firestore database, and real-time updates
• Zod 3.25: Runtime type validation and schema definition

AI & External APIs

• OpenAI GPT-4o-mini: Financial analysis and narrative generation
• QuickBooks API: OAuth 2.0 integration with P&L report fetching
• Intuit OAuth 4.2: Secure authentication flow

Testing & Quality

• Jest 29.7: Testing framework with 150+ test cases across unit, integration, and component testing
• Playwright 1.52: End-to-end testing with automated browser testing
• Testing Library: React component testing utilities
• Coverage Thresholds: 60% minimum for statements, branches, functions, and lines

Core System Architecture (Product View)

Component	Role
Dashboard Hub	Central navigation and overview of all financial analysis sections
Analysis Sections	Specialized views for Revenue, Expenses, Profitability, and Anomalies
Chart Engine	Custom SVG chart components for data visualization
Data Normalizer	Converts QuickBooks data into standardized, analyzable formats
Analysis Pipeline	Processes normalized data to generate insights, trends, and metrics
Layout Engine	Dynamically arranges dashboard components based on data and analysis type
QuickBooks Connector	Handles OAuth authentication and data retrieval
State Management	Zustand stores for dashboard state and user preferences

End-to-End Execution Flow

1. User logs in and connects their QuickBooks account via OAuth 2.0 flow.
2. System fetches the latest 12-month Profit & Loss report with chunked processing (6-month intervals).
3. User clicks on a dashboard section to trigger analysis.
4. /api/analyze receives the analysis plan and processes the financial data.
5. /api/analyze normalizes the P&L data and performs all calculations deterministically.
6. Layout system generates UI configuration based on analysis type and query intent.
7. AI-powered narrator generates insights using GPT-4o-mini with structured JSON responses.
8. A dynamic dashboard is rendered in the UI and can be saved to Firestore.

---

Development Status & Sprint Progress

Current Status: Sprint 2 (June 22 – July 12, 2025)

Note: Sprint 1 (June 1 – June 21, 2025) has been completed with foundational infrastructure, AI pipeline setup, and core dashboard rendering capabilities.

Sprint 2 In Progress (June 22 – July 12, 2025)

Goal: Deliver the complete /api/analyze multi-agent pipeline using OpenAI Agents SDK and deterministic backend analysis.

Completed:

• ✅ AI Agent Orchestration - All key Zod schemas defined and validated
• ✅ Clarifier, Planner, Analyzer, and Insight Agents implemented
• ✅ agentFlow.ts to chain agents end-to-end
• ✅ /api/plan refactored to invoke the new agent pipeline
• ✅ Jest e2e tests simulating prompt → dashboard flows
• ✅ Mock AWS dataset fully loaded and structured in Firestore
• ✅ SpendRecord type and filtering utilities defined
• ✅ Grouping, aggregation, and trend detection logic developed
• ✅ runBackendAnalysis(plan) returns schema-validated RawAnalysisResult
• ✅ CLI loader for mock datasets and UI toggle to switch mock/live data

In Progress:

• 🔄 UI System Design - Component library plan and theme palette
• 🔄 Visual QA & Testing - Accessibility and responsive design

Planned for Sprint 2:

• 📋 Chart-type toggle functionality
• 📋 Chat UI panel for follow-up queries
• 📋 Dashboard layout options (Grid/stacked/priority)
• 📋 Dashboard save/load functionality
• 📋 User preferences storage
• 📋 Filters sidebar with live chart updates

Sprint 3 Planned (July 13 – August 2, 2025)

Goal: AWS integration, authentication, and production readiness.

Planned:

• 📋 AWS IAM user setup and Cost Explorer API integration
• 📋 Firebase Email/Password Auth implementation
• 📋 Firestore security rules
• 📋 Rate limiting (25 GPT/day)
• 📋 Error handling and empty-state components
• 📋 Usage telemetry and feedback systems
• 📋 Accessibility sweep and testing
• 📋 Final landing page polish

Sprint Plan Summary

The project has 74+ planned tasks across 3 sprints, with clear dependencies and deliverables. Current focus is on Sprint 2: completing the AI analysis pipeline and UI system design, with Sprint 3 focused on AWS integration and production readiness.

---

Implementation Details

AI Agent Architecture

The system uses a sophisticated multi-agent AI system with the following components:

Agent Types

1. Clarifier Agent: Handles user queries and asks clarification questions
2. Planner Agent: Converts user intent into structured analysis plans
3. Analyzer Agent: Processes financial data and generates analysis results
4. Insight Agent: Generates AI-written insights from backend data

Agent Flow

User Query → Clarifier Agent → Planner Agent → Analyzer Agent → Insight Agent → Dashboard Response

Key Features

• OpenAI Agents SDK Integration: Full GPT-4o integration with structured JSON responses
• Schema Validation: Comprehensive Zod schema validation for all data structures
• Deterministic Analysis: Backend analysis pipeline for consistent results
• Fallback Handling: Neutral responses when AI refuses or encounters errors

Dashboard Rendering System

Core Components

• DashboardRenderer: Main component that renders multiple chart sections
• Chart Components: Bar, Line, Pie, Area, and Table charts for different data types
• Layout Engine: Dynamic arrangement of dashboard components based on data characteristics
• Responsive Design: Mobile and desktop optimized viewing experiences

Chart Features

• Interactive Elements: Hover tooltips, drill-down capabilities, and data exploration
• Customizable Layouts: Adaptive dashboard layouts based on analysis type and query intent
• Data Visualization: Custom SVG chart components for optimal performance
• Theme Integration: Consistent color scheme and typography across all components

UnifiedNarratorPanel Component

Overview

The UnifiedNarratorPanel is a consolidated component that provides AI-generated financial summaries across all dashboard pages.

Features

• Unified Interface: Single component for all dashboard pages
• Dual Mode Support: Works with both local state and global store
• LocalStorage Persistence: Automatically saves and restores AI summaries
• Enhanced UI: Modern card-based design with better visual hierarchy
• Context Information: Shows financial context when available

Usage Modes

1. Local State Mode: When onGenerate prop is provided, uses local state management
2. Global Store Mode: When no onGenerate is provided, uses global dashboard store

Dashboard Types

• "overview" - Financial Overview dashboard
• "revenue" - Revenue Analysis dashboard
• "expenses" - Expense Drivers dashboard
• "profitability" - Profitability Analysis dashboard
• "anomalies" - Anomaly Detection dashboard
• "test" - Development/testing pages

---

Testing & Quality Assurance

Testing Infrastructure Overview

CloudInsights.ai implements a comprehensive testing strategy with multiple testing layers, automated CI/CD integration, and strict quality thresholds.

Testing Stack & Tools

Core Testing Framework

• Jest 29.7: Primary testing framework with SWC transformer for fast execution
• Testing Library: React component testing utilities with accessibility focus
• Playwright 1.52: End-to-end testing with cross-browser support
• SWC/Jest: Fast TypeScript compilation for improved test performance

Quality Assurance Tools

• ESLint: Code quality and style enforcement
• Prettier: Automated code formatting and consistency
• TypeScript: Static type checking with strict mode
• Lighthouse CI: Performance and accessibility testing

Test Organization & Structure

Directory Structure

tests/
├── unit/           # Core business logic testing
├── components/     # React component testing
├── integration/    # API and service integration testing
├── api/           # API endpoint testing
├── e2e/           # End-to-end user journey testing
├── utils/         # Test utilities and setup
└── data/          # Test data fixtures and mocks

Test File Naming Convention

• Unit Tests: *.test.ts for business logic
• Component Tests: *.test.tsx for React components
• Integration Tests: *.test.ts for API and service integration
• E2E Tests: *.spec.ts for Playwright tests

Jest Configuration

Core Configuration

const config: Config = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/tests/utils/setupTestEnv.ts'],
  testMatch: [
    '<rootDir>/tests/unit/**/*.test.{ts,tsx}',
    '<rootDir>/tests/components/**/*.test.{ts,tsx}',
    '<rootDir>/tests/api/**/*.test.{ts,tsx}',
    '<rootDir>/tests/integration/**/*.test.{ts,tsx}'
  ],
  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx'],
  transform: {
    '^.+\\.(ts|tsx)$': '@swc/jest',
  },
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/$1',
  }
}

Coverage Configuration

collectCoverage: true,
collectCoverageFrom: [
  'lib/**/*.{ts,tsx}',
  'components/**/*.{ts,tsx}',
  'stores/**/*.{ts,tsx}',
  '!**/*.d.ts',
  '!**/node_modules/**',
  '!**/tests/**',
  '!**/coverage/**'
],
coverageDirectory: 'coverage',
coverageReporters: ['text', 'lcov', 'html'],
coverageThreshold: {
  global: {
    branches: 60,
    functions: 60,
    lines: 60,
    statements: 60
  }
}

Test Coverage & Metrics

The project maintains strict coverage thresholds:

• Minimum Coverage: 60% for all metrics (statements, branches, functions, lines)
• Test Types: Unit, integration, component, and end-to-end testing
• Automation: All tests run automatically on CI/CD pipeline
• Quality Gates: Builds fail if coverage thresholds are not met

---

API Documentation

API Architecture Overview

The system uses a layered API architecture with clear separation of concerns:

Core Endpoints

/api/analyze - Analysis Entry Point

• Receives structured analysis plans and financial data
• Processes the data through deterministic analysis modules
• Returns the complete analysis with layout

/api/analyze - Core Processing Engine

• Plan Validation: Uses Zod schemas to validate incoming analysis plans
• Data Normalization: Converts QuickBooks data into normalized financial records
• Analysis Execution: Runs the financial analysis pipeline
• Layout Generation: Creates UI layouts based on analysis type and query intent

/api/qbo/sync - QuickBooks Integration

• OAuth 2.0 Authentication: Secure token management with refresh handling
• Data Synchronization: Daily automated sync via Vercel cron jobs
• Chunked Processing: Handles 12+ months of data in 6-month intervals
• Error Handling: Exponential backoff retry logic and fallback mechanisms

/api/ai/narrator - AI Analysis Engine

• OpenAI Integration: GPT-4o-mini with structured JSON responses
• Prompt Engineering: 5+ specialized financial analysis templates
• Performance Optimization: 500-token limit, 0.3 temperature, refusal detection
• Fallback Handling: Neutral responses when AI refuses or encounters errors

Data Flow Architecture

Client Request → /api/analyze → AI Narrator → Response

Data Processing Pipeline:

1. Request Validation: Zod schema validation of incoming requests
2. Data Fetching: Retrieval of QuickBooks data with error handling
3. Normalization: Conversion of raw data into standardized formats
4. Analysis: Deterministic financial analysis using business logic
5. AI Enhancement: GPT-powered insights and narrative generation
6. Response Formatting: Structured response with layout and data

Error Handling & Resilience

• Rate Limiting: 25 GPT requests per day per user
• Exponential Backoff: Automatic retry logic for transient failures
• Fallback Mechanisms: Graceful degradation when external services fail
• Comprehensive Logging: Detailed error tracking and monitoring

---

Component Library

Chart Components

Core Chart Types

• BarChart: Vertical and horizontal bar charts for categorical data
• LineChart: Time-series data visualization with trend lines
• PieChart: Proportional data representation
• AreaChart: Filled area charts for cumulative data
• TableChart: Tabular data presentation with sorting and filtering
• SparklineChart: Compact trend indicators
• CombinedChart: Multi-series chart combinations
• TrendBarChart: Bar charts with trend indicators

Chart Features

• Responsive Design: Automatic scaling and layout adaptation
• Interactive Elements: Hover tooltips, click handlers, and drill-down
• Theme Integration: Consistent color schemes and typography
• Accessibility: ARIA labels and keyboard navigation support
• Performance: Optimized rendering for large datasets

Common Components

UI Elements

• Button: Primary, secondary, and tertiary button variants
• Card: Content containers with consistent styling
• Input: Form input components with validation
• Badge: Status and category indicators
• Tooltip: Contextual information display

Layout Components

• Header: Navigation and branding
• Sidebar: Navigation menu and user controls
• Footer: Additional links and information
• PageTransition: Smooth page transitions and animations

Dashboard Components

Core Dashboard Elements

• DashboardTable: Data table with sorting and filtering
• DataTable: Enhanced table with pagination and search
• HealthScoreCard: Financial health indicators and scoring
• QboStatusCard: QuickBooks connection status
• SummaryCard: Key metric summaries
• UnifiedNarratorPanel: AI-powered insights and analysis

Section Components

• RevenueSection: Revenue analysis and trends
• ExpensesSection: Expense monitoring and analysis
• ProfitabilitySection: Profitability metrics and insights
• AnomaliesSection: Anomaly detection and alerts
• OverviewSection: High-level financial summary

---

Data Models & Schemas

Core Data Types

Financial Data Models

• SpendRecord: Individual financial transaction records
• AnalysisResult: Processed analysis outputs
• DashboardResponse: Complete dashboard configurations
• ChartSection: Individual chart configurations

User Data Models

• UserProfile: User account information
• UserPreferences: User settings and preferences
• DashboardState: Saved dashboard configurations
• AnalysisHistory: Historical analysis requests and results

Schema Validation

Zod Schemas

• ChartSectionSchema: Chart configuration validation
• FinanceAnalysisPlan: Analysis plan structure validation
• FinanceAnalysisResult: Analysis result validation
• FinanceUILayout: UI layout configuration validation

Validation Features

• Runtime Type Checking: Comprehensive data validation
• Error Handling: Clear error messages for invalid data
• Type Safety: Full TypeScript integration
• Documentation: Self-documenting schema definitions

Data Normalization

QuickBooks Integration

• Data Fetching: OAuth 2.0 authentication and data retrieval
• Format Conversion: Raw QBO data to standardized formats
• Historical Data: 12-month data retrieval with chunked processing
• Error Handling: Graceful fallback and retry mechanisms

Data Processing

• Aggregation: Time-based and categorical data grouping
• Trend Analysis: Statistical trend detection and analysis
• Anomaly Detection: Statistical outlier identification
• Performance Optimization: Efficient data processing algorithms

---

Deployment & Infrastructure

Hosting & Deployment

Vercel Integration

• Automatic Deployments: Deploy on every push to main branch
• Preview Deployments: Automatic preview builds for pull requests
• Edge Functions: Serverless API endpoints with global distribution
• Performance Monitoring: Built-in performance analytics and optimization

CI/CD Pipeline

• GitHub Actions: Automated testing and deployment workflows
• Quality Gates: Build failures on test failures or coverage issues
• Automated Testing: Unit, integration, and end-to-end test execution
• Deployment Automation: Seamless deployment to production

Database & Storage

Firebase Integration

• Firestore: NoSQL database for user data and dashboards
• Authentication: Email/password authentication system
• Security Rules: Comprehensive data access controls
• Real-time Updates: Live data synchronization across clients

Data Management

• Backup & Recovery: Automated data backup and recovery procedures
• Data Migration: Schema evolution and data migration tools
• Performance Optimization: Query optimization and indexing strategies
• Monitoring: Database performance and usage monitoring

Security & Compliance

Authentication & Authorization

• OAuth 2.0: Secure third-party authentication
• JWT Tokens: Secure session management
• Role-based Access: Granular permission controls
• Session Management: Secure session handling and timeout

Data Protection

• Encryption: Data encryption in transit and at rest
• Privacy Controls: User data privacy and GDPR compliance
• Audit Logging: Comprehensive access and change logging
• Security Monitoring: Real-time security threat detection

---

Development Guidelines

Code Quality Standards

TypeScript Guidelines

• Strict Mode: Enable all TypeScript strict checks
• Type Definitions: Comprehensive interface and type definitions
• Documentation: JSDoc comments for all public APIs
• Error Handling: Proper error types and error handling patterns

Code Style & Formatting

• ESLint Configuration: Enforce consistent code style
• Prettier Integration: Automated code formatting
• Naming Conventions: Consistent naming patterns across the codebase
• File Organization: Logical file and directory structure

Testing Requirements

Test Coverage

• Minimum Threshold: 60% coverage for all metrics
• Test Types: Unit, integration, component, and end-to-end tests
• Test Quality: Meaningful tests that validate business logic
• Test Maintenance: Regular test updates and maintenance

Testing Best Practices

• Test Isolation: Independent test execution
• Mock Management: Proper use of mocks and test doubles
• Test Data: Comprehensive test data and fixtures
• Performance Testing: Performance validation for critical paths

Documentation Standards

Code Documentation

• API Documentation: Comprehensive API endpoint documentation
• Component Documentation: Component usage and prop documentation
• Architecture Documentation: System design and architecture decisions
• Change Logs: Detailed change tracking and version history

User Documentation

• User Guides: Step-by-step user instructions
• API Reference: Complete API documentation
• Troubleshooting: Common issues and solutions
• Best Practices: Usage recommendations and tips

Performance & Optimization

Frontend Optimization

• Bundle Optimization: Code splitting and lazy loading
• Image Optimization: Efficient image formats and loading strategies
• Caching Strategies: Client-side and server-side caching
• Performance Monitoring: Real-time performance metrics

Backend Optimization

• Database Optimization: Query optimization and indexing
• API Performance: Response time optimization and caching
• Resource Management: Efficient resource utilization
• Scalability Planning: Horizontal and vertical scaling strategies

---

Quick Reference

Development Commands

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build for production
npm run build

# Lint code
npm run lint

# Format code
npm run format

Environment Variables

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=

# OpenAI Configuration
OPENAI_API_KEY=

# QuickBooks Configuration
QBO_CLIENT_ID=
QBO_CLIENT_SECRET=
QBO_ENVIRONMENT=

Key File Locations

• Source Code: /app, /components, /lib
• Tests: /tests
• Configuration: /next.config.ts, /tailwind.config.js, /jest.config.ts
• Documentation: /docs
• Types: /types

---

This documentation consolidates all important information from the scattered documentation files. For specific implementation details, refer to the individual component files and test suites.