# jruttan1/walletwise architecture

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

- Interactive diagram: https://gitdiagram.com/jruttan1/walletwise
- Repository: https://github.com/jruttan1/walletwise

## Overview

##### Project type and purpose
- WalletWise is a full-stack, React-based web application built on Next.js 14.
- Its purpose is to provide new investors with portfolio analysis, individual stock insights, and an AI-driven finance coach.

##### File structure
- Top-level “app” directory: Next.js App Router with server & client components.
- app/page.tsx, app/layout.tsx – global layout and home page
- app/dashboard/page.tsx, app/dashboard/loading.tsx – protected dashboard views
- app/api/* – API routes for portfolio, Q&A, ticker data, and AI analyses
- “components”: reusable UI pieces (StockCardLink, dashboard widgets, UI primitives)
- “hooks”: client-side React hooks (use-mobile, use-toast)
- “lib”: server utilities for environment, Sonar AI, Yahoo Finance data, general utils
- Configs: next.config.js, tailwind.config.js, tsconfig.json, .env.example

##### README insights
- Two-phase loading (fast core data + background AI)
- Tech stack: Next.js, TypeScript, Tailwind CSS, Recharts, Yahoo Finance library, Perplexity Sonar API

##### Main components and their relationships
a. Frontend (Next.js App)
- Pages & Layout (app/page.tsx, app/layout.tsx)
- Dashboard & Stock Detail screens (client components under app/dashboard and app/page.tsx)
- UI library components (components/ui/*) and domain widgets (components/dashboard/*)
- Hooks for responsive design and toast notifications
b. Backend (Next.js API Routes)
- /api/portfolio: parse CSV, fetch portfolio valuations via lib/yahoo.ts
- /api/portfolio/ai-analysis: wrap Sonar calls to generate portfolio recommendations
- /api/ticker/[symbol]: fetch real-time stock fundamentals & history via Yahoo
- /api/ticker/[symbol]/ai-analysis: call Sonar for movement explanations & risk
- /api/qna: route user questions to Sonar with portfolio context
c. External Services
- Yahoo Finance REST endpoints via lib/yahoo.ts
- Perplexity Sonar AI API via lib/sonar.ts
d. (No persistent database in current scope)

##### Architectural patterns and design principles
- Next.js App Router with Server Components for API calls and data fetching.
- Two-phase data loading: initial server render with charts & fundamentals, incremental AI insights via client fetches.
- Separation of concerns:
- UI primitives vs. domain components
- Data-fetching in API routes vs. rendering in React components
- Utility libraries (lib) abstract third-party integrations

a. Components to include:
- User’s Browser (Next.js React client)
- Next.js Server (App Router) subdivided into:
- Page & Layout Rendering
- API Route Handlers (Portfolio, QnA, Ticker, AI-Analysis)
- External Services: Yahoo Finance API, Perplexity Sonar AI API
b. Relationships & Data Flow:
- Two-phase flow: Phase-1 data fetch vs. Phase-2 AI calls
c. Highlighted patterns:
- Server Components vs. Client Components
- Two-phase loading and progressive data enhancement
d. Key technologies: Next.js, React, Tailwind, Recharts, lib/yahoo.ts, lib/sonar.ts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    subgraph "Frontend (Browser + Next.js React)"
        direction TB
        UX["User's Browser"]:::frontend
        subgraph "Next.js Pages & Components"
            direction TB
            Layout["Global Layout"]:::frontend
            Home["Home Page"]:::frontend
            Dashboard["Dashboard Page"]:::frontend
            Loading["Dashboard Loading"]:::frontend
            UIPrimitives["UI Primitives"]:::frontend
            Widgets["Dashboard Widgets"]:::frontend
            StockCard["StockCardLink"]:::frontend
            ThemeProv["Theme Provider"]:::frontend
            ModeToggle["Mode Toggle"]:::frontend
            HooksM["use-mobile Hook"]:::frontend
            HooksT["use-toast Hook"]:::frontend
        end
    end

    %% Backend
    subgraph "Backend (Next.js Server & API)" 
        direction TB
        Render["Page & Layout Rendering"]:::backend
        subgraph "API Routes"
            direction TB
            Portfolio["/api/portfolio"]:::backend
            PortfolioAI["/api/portfolio/ai-analysis"]:::backend
            QnA["/api/qna"]:::backend
            Ticker["/api/ticker/[symbol]"]:::backend
            TickerAI["/api/ticker/[symbol]/ai-analysis"]:::backend
        end
        subgraph "Lib Utilities"
            direction TB
            Env["Env & Config Utilities"]:::backend
            SonarUtil["Sonar AI Utility"]:::backend
            YahooUtil["Yahoo Finance Utility"]:::backend
            Utils["General Utility Functions"]:::backend
        end
    end

    %% External
    subgraph "External Services"
        direction TB
        YahooAPI["Yahoo Finance API"]:::external
        SonarAPI["Perplexity Sonar AI"]:::external
    end

    %% Connections
    UX -->|"view Home"| Home
    UX -->|"view Dashboard"| Dashboard
    Home --> Render
    Dashboard --> Render

    Render -->|"phase1 fetch"| Portfolio
    Render -->|"phase1 fetch"| Ticker
    UX -->|"phase1 fetch"| Portfolio
    UX -->|"phase1 fetch"| Ticker
    UX -->|"phase2 AI fetch"| PortfolioAI
    UX -->|"phase2 AI fetch"| TickerAI
    UX -->|"ask question"| QnA

    Portfolio --> Env
    Portfolio --> YahooUtil
    Portfolio --> Utils

    PortfolioAI --> SonarUtil
    PortfolioAI --> Env

    Ticker --> YahooUtil
    TickerAI --> SonarUtil

    QnA --> SonarUtil

    YahooUtil --> YahooAPI
    SonarUtil --> SonarAPI

    UIPrimitives --> Home
    Widgets --> Dashboard
    StockCard --> Dashboard
    ThemeProv --> Home
    ModeToggle --> Home
    HooksM --> Home
    HooksT --> Home

    %% Click Events
    click Layout "https://github.com/jruttan1/walletwise/blob/main/app/layout.tsx"
    click Home "https://github.com/jruttan1/walletwise/blob/main/app/page.tsx"
    click Dashboard "https://github.com/jruttan1/walletwise/blob/main/app/dashboard/page.tsx"
    click Loading "https://github.com/jruttan1/walletwise/blob/main/app/dashboard/loading.tsx"
    click Portfolio "https://github.com/jruttan1/walletwise/blob/main/app/api/portfolio/route.ts"
    click PortfolioAI "https://github.com/jruttan1/walletwise/blob/main/app/api/portfolio/ai-analysis/route.ts"
    click QnA "https://github.com/jruttan1/walletwise/blob/main/app/api/qna/route.ts"
    click Ticker "https://github.com/jruttan1/walletwise/blob/main/app/api/ticker/[symbol]/route.ts"
    click TickerAI "https://github.com/jruttan1/walletwise/blob/main/app/api/ticker/[symbol]/ai-analysis/route.ts"
    click UIPrimitives "https://github.com/jruttan1/walletwise/tree/main/components/ui/"
    click Widgets "https://github.com/jruttan1/walletwise/tree/main/components/dashboard/"
    click StockCard "https://github.com/jruttan1/walletwise/blob/main/components/StockCardLink.tsx"
    click ThemeProv "https://github.com/jruttan1/walletwise/blob/main/components/theme-provider.tsx"
    click ModeToggle "https://github.com/jruttan1/walletwise/blob/main/components/mode-toggle.tsx"
    click HooksM "https://github.com/jruttan1/walletwise/blob/main/hooks/use-mobile.tsx"
    click HooksT "https://github.com/jruttan1/walletwise/blob/main/hooks/use-toast.tsx"

    %% Styles
    classDef frontend fill:#D6E6FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D6FFD6,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
```
