How jruttan1/walletwise works
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