# dineshkumarclg/financeflow architecture

> Architecture diagram of the GitHub repository dineshkumarclg/financeflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dineshkumarclg/financeflow
- Repository: https://github.com/dineshkumarclg/financeflow

## Overview

##### Project type and purpose
- FinanceFlow is a full-stack, Next.js/React web application for personal and business finance management.
- It combines a rich frontend (UI pages, components) with a server side/API layer (Next.js app), a Firebase backend (Auth + Firestore + Storage), and AI-powered flows (using GenKit to orchestrate OpenAI or similar services).

##### File structure
- Top level:
- next.config.ts, tsconfig.json, tailwind.config.ts, postcss.config.mjs → build & toolchain configs
- apphosting.yaml, components.json → deployment metadata
- README.md → project overview
- src/app → Next.js “app router” pages & layouts (UI routes: login, signup, dashboard, journal, ledger, chat, settings, upload)
- src/components → atomic to composite React components broken out by feature (auth, dashboard, journal, ledger, chat, settings, layout, shared, ui controls)
- src/ai → server-side AI workflows (chat assistant, data extraction, parsing, tagging) invoked via GenKit
- src/lib → shared libraries for constants, utilities, Firebase initialization, data service wrappers
- src/contexts + src/hooks → client-side React context & custom hooks (auth, toast notifications, responsive behaviors)

##### README for additional insights
- Core features: user auth, transactional journal & ledger, dashboards with charts, AI-driven document parsing & chat
- Technology stack: Next.js, React, TypeScript, Tailwind CSS, Firebase, GenKit

##### Detailed capture of essential elements
- Inside the API layer, show GenKit flow handlers and Next.js server actions/api routes
- Inside the data layer, show Firestore collections (users, transactions, suggestions) and Storage bucket for documents
- Cross-cutting contexts/hooks lining the client side (AuthContext, use-toast)
- Build pipeline & config at the bottom or side: node/npm scripts, Tailwind, PostCSS, TypeScript compiler

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client / Browser"
        direction TB
        UI_Pages["UI Pages & Layouts"]:::frontend
        React_Components["React Components"]:::frontend
        AuthContext["Authentication Context"]:::frontend
        Hook_Mobile["use-mobile Hook"]:::frontend
        Hook_Toast["use-toast Hook"]:::frontend
        UI_Pages -->|uses| React_Components
        React_Components -->|uses| AuthContext
        React_Components -->|uses| Hook_Mobile
        React_Components -->|uses| Hook_Toast
    end

    %% API Layer
    subgraph "Next.js Server / API Layer"
        direction TB
        NextJS_Server["Next.js Server"]:::api
        Server_Actions["Server Actions / API Routes"]:::api
        Data_Service["Data Service Wrappers"]:::api
        Firebase_Init["Firebase Initialization"]:::api
        NextJS_Server -->|handles SSR/SSG| UI_Pages
        UI_Pages -->|navigates| NextJS_Server
        NextJS_Server -->|calls| Server_Actions
        Server_Actions -->|uses| Data_Service
        Data_Service -->|initializes| Firebase_Init
    end

    %% AI Layer
    subgraph "AI Service Layer"
        direction TB
        GenKit["GenKit Orchestrator"]:::ai
        ChatFlow["Chat AI Flow"]:::ai
        ExtractFlow["Extract Data Flow"]:::ai
        ParseFlow["Parse Entry Flow"]:::ai
        SuggestFlow["Suggest Tags Flow"]:::ai
        Server_Actions -->|invokes| GenKit
        GenKit -->|runs| ChatFlow
        GenKit -->|runs| ExtractFlow
        GenKit -->|runs| ParseFlow
        GenKit -->|runs| SuggestFlow
    end

    %% Data Layer
    subgraph "Data Storage Layer"
        direction TB
        Firebase_Auth["Firebase Auth"]:::db
        Firestore["Firestore Database"]:::db
        Storage["Firebase Storage"]:::db
        Data_Service -->|reads/writes| Firestore
        Data_Service -->|auth| Firebase_Auth
        UI_Pages -->|direct calls| Data_Service
        UI_Pages -->|uploads| Storage
        Storage -.->|upload triggers| ExtractFlow
        ChatFlow -->|store results| Firestore
        ExtractFlow -->|store parsed data| Firestore
        ParseFlow -->|store parsed entry| Firestore
        SuggestFlow -->|store suggestions| Firestore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI / AI Provider"]:::external
        Vercel["Vercel Hosting"]:::external
        GenKit -->|calls| OpenAI
        NextJS_Server -->|deployed on| Vercel
    end

    %% Configuration & Metadata
    subgraph "Build & Config"
        direction TB
        NextConfig["next.config.ts"]:::config
        TailwindConfig["tailwind.config.ts"]:::config
        PostCSSConfig["postcss.config.mjs"]:::config
        TSConfig["tsconfig.json"]:::config
        AppHosting["apphosting.yaml"]:::config
        ComponentsMeta["components.json"]:::config
        README["README.md"]:::config
        PackageJSON["package.json"]:::config
        PackageLock["package-lock.json"]:::config
    end

    %% Class Definitions
    classDef frontend fill:#D0E8FF,stroke:#1E70BF,color:#000;
    classDef api fill:#E8F4FF,stroke:#4096EE,color:#000;
    classDef ai fill:#FFE5B4,stroke:#FF8C00,color:#000;
    classDef db fill:#DFFFE0,stroke:#2E8B57,color:#000;
    classDef external fill:#F0F0F0,stroke:#A0A0A0,color:#000;
    classDef config fill:#EEEEEE,stroke:#888888,color:#000;

    %% Click Events
    click UI_Pages "https://github.com/dineshkumarclg/financeflow/tree/master/src/app"
    click React_Components "https://github.com/dineshkumarclg/financeflow/tree/master/src/components"
    click AuthContext "https://github.com/dineshkumarclg/financeflow/blob/master/src/contexts/AuthContext.tsx"
    click Hook_Mobile "https://github.com/dineshkumarclg/financeflow/blob/master/src/hooks/use-mobile.tsx"
    click Hook_Toast "https://github.com/dineshkumarclg/financeflow/blob/master/src/hooks/use-toast.ts"
    click Firebase_Init "https://github.com/dineshkumarclg/financeflow/blob/master/src/lib/firebase.ts"
    click Data_Service "https://github.com/dineshkumarclg/financeflow/blob/master/src/lib/data-service.ts"
    click NextConfig "https://github.com/dineshkumarclg/financeflow/blob/master/next.config.ts"
    click TailwindConfig "https://github.com/dineshkumarclg/financeflow/blob/master/tailwind.config.ts"
    click PostCSSConfig "https://github.com/dineshkumarclg/financeflow/blob/master/postcss.config.mjs"
    click TSConfig "https://github.com/dineshkumarclg/financeflow/blob/master/tsconfig.json"
    click AppHosting "https://github.com/dineshkumarclg/financeflow/blob/master/apphosting.yaml"
    click ComponentsMeta "https://github.com/dineshkumarclg/financeflow/blob/master/components.json"
    click README "https://github.com/dineshkumarclg/financeflow/blob/master/README.md"
    click PackageJSON "https://github.com/dineshkumarclg/financeflow/blob/master/package.json"
    click PackageLock "https://github.com/dineshkumarclg/financeflow/blob/master/package-lock.json"
    click GenKit "https://github.com/dineshkumarclg/financeflow/blob/master/src/ai/genkit.ts"
    click ChatFlow "https://github.com/dineshkumarclg/financeflow/blob/master/src/ai/flows/chat-with-ai-assistant.ts"
    click ExtractFlow "https://github.com/dineshkumarclg/financeflow/blob/master/src/ai/flows/extract-accounting-data.ts"
    click ParseFlow "https://github.com/dineshkumarclg/financeflow/blob/master/src/ai/flows/parse-accounting-entry.ts"
    click SuggestFlow "https://github.com/dineshkumarclg/financeflow/blob/master/src/ai/flows/suggest-ledger-tags.ts"
```
