Simple Portfolio Summarizer

Project Blueprint: Simple Portfolio Summarizer

Subtitle: Consolidate and visualize your investment holdings at a glance. Category: Wealth Management Difficulty: Beginner

1. The Business Problem (Why build this?)

In today's dynamic investment landscape, individuals often find their financial assets scattered across multiple platforms: traditional brokerage accounts, retirement funds (401k, IRA), cryptocurrency exchanges, and even cash savings. This fragmentation makes it challenging to gain a cohesive, real-time understanding of one's entire portfolio. Many existing wealth management solutions are either prohibitively expensive, overly complex for the beginner investor, or require invasive integrations that demand sensitive credentials, raising privacy and security concerns for many users.

For the burgeoning DIY investor, or simply someone looking to take a more active role in understanding their finances without the overhead, the current options are limited. Manually tracking holdings in spreadsheets is a common workaround, but it's tedious, prone to human error, and lacks the immediate gratification of real-time data and visual summaries. This often leads to a disjointed view of their investments, hindering informed decision-making regarding diversification, risk assessment, and overall financial health.

The "Simple Portfolio Summarizer" addresses this fundamental pain point. It caters to the beginner investor who desires a straightforward, privacy-centric, and user-friendly tool to manually input their holdings and instantly receive a consolidated overview. By abstracting away the complexities of API integrations with various financial institutions and offering a manual entry system, it empowers users with control over their data. The goal is to demystify portfolio tracking, providing a clear, at-a-glance summary that fosters greater understanding and confidence in managing personal investments, all without demanding sensitive access to their financial accounts. This project fills a crucial gap for those seeking simplicity, privacy, and an educational entry point into personal wealth visualization.

2. Solution Overview

The Simple Portfolio Summarizer is a web-based application designed to provide users with an intuitive interface to manually input their investment holdings and receive immediate, digestible insights. It acts as a personal, client-side financial dashboard, prioritizing ease of use and privacy for the beginner investor.

Core Functionality:

• Manual Holding Entry: Users can easily add individual investment holdings by specifying key details such as the stock ticker (e.g., GOOGL, MSFT), the number of shares owned, the average purchase cost, and the asset type (e.g., Equity, Cryptocurrency, Cash). This manual input ensures user control and data privacy.
• Real-time Valuation: Upon entry or page load, the application intelligently fetches the latest market prices for specified tickers (stocks, ETFs, cryptocurrencies) from external market data APIs. This allows for an accurate, up-to-date calculation of each holding's current market value.
• Total Portfolio Value Calculation: The system aggregates the current market value of all entered holdings, providing an immediate, consolidated figure for the user's total investment portfolio.
• Basic Asset Allocation: Beyond a simple sum, the application categorizes holdings by predefined asset types (e.g., Equities, Cash, Cryptocurrencies, Bonds) and, where possible, by sector (e.g., Technology, Healthcare). It then calculates and displays the percentage distribution across these categories, offering a fundamental understanding of portfolio diversification.
• Simple Dashboard with Visualizations: A central dashboard presents the summarized data in an easily digestible format. This includes a clear display of the total portfolio value, a tabular list of all holdings with their current values and profit/loss, and interactive charts (e.g., pie charts for asset allocation, bar charts for sector distribution) powered by Chart.js.
• Gemini-powered Insights: Leveraging the Gemini API, the application offers high-level, educational summaries and observations about the user's portfolio. These insights focus on common investment principles like diversification, potential concentrations, and general characteristics of asset classes, providing context without offering direct financial advice. This feature helps beginners interpret their portfolio structure in plain language.
• Local Storage Persistence: All user-entered data is securely stored directly within the user's browser's local storage. This ensures that the portfolio data is retained between sessions without requiring user accounts, server-side databases, or transmitting sensitive financial information to a backend, further enhancing privacy.

User Journey:

1. Access: The user navigates to the Simple Portfolio Summarizer web application.
2. Initial Setup: If it's their first visit, the dashboard will be empty.
3. Add Holding: The user clicks an "Add Holding" button, which presents a form.
4. Data Input: They fill in details: Ticker (e.g., AAPL), Shares (e.g., 5.5), Average Cost (e.g., 150.25), Asset Type (e.g., Equity).
5. Instant Update: Upon submission, the application immediately fetches the current price for AAPL, calculates its value, updates the total portfolio value, and reflects the new allocation in the dashboard's charts.
6. Review & Refine: The user reviews their holdings, edits any entries as needed, and sees the dashboard adjust in real-time.
7. Generate Insights: The user clicks a "Generate Insights" button, which sends a sanitized summary of their holdings to the Gemini API via a secure backend route.
8. Receive Summary: Gemini's response, a high-level educational summary, is displayed on the dashboard.
9. Persistence: The user can close their browser, and upon returning, their entered portfolio data will be automatically loaded from local storage.

This solution prioritizes a low barrier to entry, a strong focus on user privacy, and an educational approach, making it an ideal tool for beginners to consolidate and visualize their investments effectively.

3. Architecture & Tech Stack Justification

The Simple Portfolio Summarizer will adopt a client-side-centric architecture, leveraging serverless functions for secure API interactions. This approach minimizes backend complexity, aligns with the "beginner" difficulty, and enhances privacy by keeping user data primarily client-side.

Overall Architecture Diagram (Conceptual):

+-------------------+
|     User Browser  |
| (Client-side App) |
+---------+---------+
          |
          | 1. Render UI, User Input (Holdings)
          | 2. Store/Retrieve Holdings (Local Storage)
          | 3. Request Market Data / Gemini Insights (Next.js API Routes)
          V
+---------+---------+
|     Next.js App   |
| (Frontend + API Routes) |
+---------+---------+
    |           |
    | (Market Data API Call)  | (Gemini API Call)
    V           V
+---+-------------+---+
| Market Data API   |   Gemini API    |
| (e.g., Alpha Vantage) |             |
+-------------------+---+

Tech Stack Justification:

1. Next.js (Frontend & API Routes):

   • Justification: Next.js is a React framework that excels in building modern web applications. Its file-system-based routing simplifies page creation, and its performance optimizations (like image optimization and code splitting) contribute to a smooth user experience. Crucially for this project, Next.js provides API Routes. These allow us to create serverless functions within the same Next.js project. This is vital for securely proxying calls to external APIs (like market data providers and the Gemini API) without exposing API keys directly on the client-side. It effectively provides a "backend for frontend" capability without requiring a separate server setup, keeping the project contained and manageable for a beginner.

2. Gemini API (AI Insights):

   • Justification: The Gemini API provides powerful large language model capabilities. Instead of building complex analytical models from scratch, Gemini allows us to generate intelligent, human-like summaries and observations about the user's portfolio based on its composition (asset types, sectors, values). This immediately elevates the application beyond a simple calculator by offering qualitative insights, fulfilling the "smart summarizer" aspect of the project. Its ease of integration via client libraries (used within our Next.js API routes) makes it accessible for a beginner-level project.

3. Local Storage (Data Persistence):

   • Justification: For a "beginner" project with a strong emphasis on privacy and minimal setup, localStorage is the ideal persistence mechanism. It allows the application to store user-entered portfolio data directly in their browser. This eliminates the need for a backend database, user authentication systems, or complex data management. Data never leaves the user's device unless explicitly sent (e.g., a sanitized version for Gemini insights). While it has limitations (data loss on browser cache clear, no multi-device sync), these are acceptable trade-offs for the project's simplicity, privacy-first design, and target audience.

4. Chart.js (Data Visualization):

   • Justification: Chart.js is a lightweight, flexible, and open-source JavaScript charting library. It's easy to integrate into a React/Next.js application and provides a wide variety of chart types (pie, bar, line, etc.) that are perfect for visualizing asset allocation and other portfolio metrics. Its simplicity and extensive documentation make it an excellent choice for beginner developers to implement visually appealing and informative dashboards without significant overhead.

5. Market Data API (e.g., Alpha Vantage, Finnhub, Polygon.io - proxied via Next.js API route):

   • Justification: While not directly listed as a core tech stack, a market data API is crucial for fetching real-time stock, ETF, and cryptocurrency prices. We will abstract this behind a Next.js API route. This approach is vital for:
     • Security: Protecting the API key from being exposed on the client-side.
     • CORS: Bypassing Cross-Origin Resource Sharing restrictions that might prevent direct client-side calls to external APIs.
     • Flexibility: Allowing easy swapping of market data providers in the future if needed, without changing client-side code.
     • Rate Limiting: Potentially implementing server-side caching or rate limit management if the chosen API has strict free-tier limits.

This selected stack ensures a performant, maintainable, and secure application development experience suitable for a beginner project while delivering powerful features.

4. Core Feature Implementation Guide

This section details the implementation steps for the primary features, including data structures, component design, and interaction flows.

4.1. Data Structure (Local Storage Schema)

All user holdings will be stored as an array of objects in localStorage. Each object represents a single investment.

// Defined Type for a single Holding
interface Holding {
  id: string;              // Unique identifier (UUID recommended)
  ticker: string;          // Stock/Crypto ticker (e.g., "GOOGL", "BTC", "CASH")
  shares: number;          // Number of shares/units owned
  avgCost: number;         // Average purchase cost per share/unit
  assetType: 'Equity' | 'Crypto' | 'Cash' | 'Bond' | 'Other'; // Categorization
  sector?: string;         // Optional: e.g., "Technology", "Financials". Can be user-inputted or derived.
  currentPrice: number;    // Dynamically fetched latest market price
  currentValue: number;    // Calculated: shares * currentPrice
  gainLoss: number;        // Calculated: (currentPrice - avgCost) * shares
  gainLossPercent: number; // Calculated: (gainLoss / (avgCost * shares)) * 100
}

// Local Storage Key: "portfolioHoldings"
// Value: JSON.stringify(Holding[])

4.2. Manual Holding Entry

This involves a form component for users to add new or edit existing holdings.

• Component: components/HoldingForm.tsx
• Inputs:
  • Ticker: Text input.
  • Shares: Number input.
  • Average Cost: Number input.
  • Asset Type: Dropdown (select) with options like 'Equity', 'Crypto', 'Cash', 'Bond', 'Other'.
  • Sector (optional): Text input, could be left blank initially.
• Validation: Basic client-side validation (e.g., ticker not empty, shares/cost are positive numbers).
• Submission (handleSubmit):
  1. Generate a unique id (e.g., crypto.randomUUID() or a simple timestamp-based ID).
  2. Create a new Holding object with currentPrice, currentValue, gainLoss, gainLossPercent initially set to 0 or derived from avgCost for CASH type.
  3. Retrieve existing holdings from localStorage.
  4. Add the new holding to the array.
  5. Save the updated array back to localStorage.
  6. Trigger a re-fetch of market data for the newly added ticker (or all tickers if simpler).
  7. Clear the form or close the modal.

Pseudo-code (HoldingForm.tsx):

import React, { useState } from 'react';
// Assume Holding interface is imported

const HoldingForm = ({ onAddHolding }) => {
  const [ticker, setTicker] = useState('');
  const [shares, setShares] = useState('');
  const [avgCost, setAvgCost] = useState('');
  const [assetType, setAssetType] = useState('Equity');
  const [sector, setSector] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();
    // Basic validation
    if (!ticker || parseFloat(shares) <= 0 || parseFloat(avgCost) <= 0) {
      alert('Please fill in all required fields with valid numbers.');
      return;
    }

    const newHolding: Holding = {
      id: crypto.randomUUID(), // Unique ID
      ticker: ticker.toUpperCase(),
      shares: parseFloat(shares),
      avgCost: parseFloat(avgCost),
      assetType: assetType,
      sector: sector || undefined, // Optional
      currentPrice: 0, // Will be fetched
      currentValue: 0, // Will be calculated
      gainLoss: 0,
      gainLossPercent: 0,
    };

    onAddHolding(newHolding); // Callback to parent to update state & local storage
    // Reset form
    setTicker('');
    setShares('');
    setAvgCost('');
    setAssetType('Equity');
    setSector('');
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* ... input fields with onChange handlers ... */}
      <button type="submit">Add Holding</button>
    </form>
  );
};

export default HoldingForm;

4.3. Real-time Price Fetching & Total Value Calculation

This is a critical pipeline involving both client-side and Next.js API route logic.

Pipeline:

1. Client (Dashboard Component):
   • On initial load and whenever holdings change (add/edit/delete), extract unique tickers from all holdings.
   • Make a POST request to /api/market-data with the list of tickers.
2. Next.js API Route (/pages/api/market-data.ts):
   • Receives the list of tickers.
   • Iterates through tickers, making individual (or batched, if supported by the provider) calls to the external Market Data API (e.g., Alpha Vantage, Finnhub).
   • Securely handles the API key using process.env.YOUR_MARKET_DATA_API_KEY.
   • Parses the responses, extracts current prices.
   • Returns a JSON object mapping tickers to their current prices (e.g., { "GOOGL": 150.25, "MSFT": 400.10 }).
   • Includes logic for special tickers like "CASH" (its price is always its avgCost).
3. Client (Dashboard Component):
   • Receives the price data.
   • Iterates through its local holdings state:
     • Updates currentPrice for each holding.
     • Calculates currentValue = shares * currentPrice.
     • Calculates gainLoss = (currentPrice - avgCost) * shares.
     • Calculates gainLossPercent.
   • Updates the holdings array in localStorage and component state.
   • Calculates totalPortfolioValue by summing all currentValue.

Pseudo-code (Dashboard/Main component pages/index.tsx or components/Dashboard.tsx):

import React, { useState, useEffect, useCallback } from 'react';
// Assume Holding interface, localStorage utils, Chart components are imported

const Dashboard = () => {
  const [holdings, setHoldings] = useState<Holding[]>([]);
  const [totalPortfolioValue, setTotalPortfolioValue] = useState(0);
  const [allocationData, setAllocationData] = useState({}); // For Chart.js

  // Function to load holdings from local storage
  const loadHoldings = useCallback(() => {
    const stored = localStorage.getItem('portfolioHoldings');
    return stored ? JSON.parse(stored) : [];
  }, []);

  // Function to save holdings to local storage
  const saveHoldings = useCallback((newHoldings: Holding[]) => {
    localStorage.setItem('portfolioHoldings', JSON.stringify(newHoldings));
  }, []);

  // Effect to load holdings on component mount
  useEffect(() => {
    setHoldings(loadHoldings());
  }, [loadHoldings]);

  // Effect to fetch prices and calculate values whenever holdings change
  useEffect(() => {
    const fetchPricesAndCalculate = async () => {
      if (holdings.length === 0) {
        setTotalPortfolioValue(0);
        setAllocationData({});
        return;
      }

      const tickersToFetch = [...new Set(holdings.map(h => h.ticker))];
      const prices: { [ticker: string]: number } = {};

      // Handle CASH holdings immediately
      holdings.forEach(h => {
        if (h.assetType === 'Cash') {
          prices[h.ticker] = h.avgCost; // Cash value is its avgCost
        }
      });

      // Call Next.js API route for market data for non-cash tickers
      const equityCryptoTickers = tickersToFetch.filter(t => t !== 'CASH');
      if (equityCryptoTickers.length > 0) {
        try {
          const response = await fetch('/api/market-data', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ tickers: equityCryptoTickers }),
          });
          const marketPrices = await response.json();
          Object.assign(prices, marketPrices); // Merge fetched prices
        } catch (error) {
          console.error('Error fetching market data:', error);
          // Fallback or display error to user
        }
      }

      let newTotalValue = 0;
      const updatedHoldings = holdings.map(h => {
        const currentPrice = prices[h.ticker] !== undefined ? prices[h.ticker] : h.currentPrice; // Fallback to old price if new not found
        const currentValue = currentPrice * h.shares;
        const gainLoss = (currentPrice - h.avgCost) * h.shares;
        const gainLossPercent = h.avgCost > 0 ? (gainLoss / (h.avgCost * h.shares)) * 100 : 0;

        newTotalValue += currentValue;
        return { ...h, currentPrice, currentValue, gainLoss, gainLossPercent };
      });

      setHoldings(updatedHoldings);
      saveHoldings(updatedHoldings); // Persist updated values
      setTotalPortfolioValue(newTotalValue);

      // Trigger allocation calculation
      calculateAllocation(updatedHoldings, newTotalValue);
    };

    fetchPricesAndCalculate();
  }, [holdings.length, saveHoldings, calculateAllocation]); // Recalculate if number of holdings changes, or saveHoldings/calculateAllocation reference changes

  // Function to add a new holding (passed to HoldingForm)
  const handleAddHolding = (newHolding: Holding) => {
    const updated = [...holdings, newHolding];
    setHoldings(updated); // This will trigger the price fetching effect
  };

  // ... rest of dashboard components (display holdings, total value, charts) ...
};

Pseudo-code (Next.js API Route: /pages/api/market-data.ts):

import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method Not Allowed' });
  }

  const { tickers } = req.body;
  if (!tickers || !Array.isArray(tickers) || tickers.length === 0) {
    return res.status(400).json({ message: 'No tickers provided' });
  }

  const MARKET_DATA_API_KEY = process.env.ALPHA_VANTAGE_API_KEY; // Or your chosen provider
  if (!MARKET_DATA_API_KEY) {
    console.error('MARKET_DATA_API_KEY not set');
    return res.status(500).json({ message: 'Server configuration error' });
  }

  const prices: { [ticker: string]: number } = {};

  for (const ticker of tickers) {
    if (ticker === 'CASH') continue; // Handled client-side

    try {
      // Example using Alpha Vantage GLOBAL_QUOTE
      const response = await fetch(
        `https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol=${ticker}&apikey=${MARKET_DATA_API_KEY}`
      );
      const data = await response.json();

      if (data && data['Global Quote'] && data['Global Quote']['05. price']) {
        prices[ticker] = parseFloat(data['Global Quote']['05. price']);
      } else {
        console.warn(`Could not fetch price for ${ticker}:`, data);
        // Optionally, store an error message or use a fallback price here
      }
    } catch (error) {
      console.error(`Error fetching price for ${ticker}:`, error);
      // Optionally, store an error message or use a fallback price here
    }
  }

  return res.status(200).json(prices);
}

4.4. Basic Asset Allocation

This involves processing the holdings array to group and sum values by categories.

Logic (within Dashboard component or a utility function):

const calculateAllocation = useCallback((currentHoldings: Holding[], totalVal: number) => {
  if (totalVal === 0) {
    setAllocationData({});
    return;
  }

  const assetTypeAllocation: { [type: string]: number } = {};
  const sectorAllocation: { [sector: string]: number } = {}; // If sector data is present

  currentHoldings.forEach(h => {
    // By Asset Type
    assetTypeAllocation[h.assetType] = (assetTypeAllocation[h.assetType] || 0) + h.currentValue;

    // By Sector (if available)
    if (h.sector) {
      sectorAllocation[h.sector] = (sectorAllocation[h.sector] || 0) + h.currentValue;
    }
  });

  const processedAssetTypeData = {
    labels: Object.keys(assetTypeAllocation),
    datasets: [{
      data: Object.values(assetTypeAllocation).map(val => (val / totalVal) * 100),
      backgroundColor: ['#FF6384', '#36A2EB', '#FFCE56', '#4BC0C0', '#9966FF'], // Chart colors
    }],
  };

  const processedSectorData = { /* similar structure for Chart.js bar chart */ };

  setAllocationData({ assetType: processedAssetTypeData, sector: processedSectorData });
}, []); // No dependencies that change, only re-evaluate when holdings or totalVal change

4.5. Simple Dashboard (Chart.js Integration)

• Component: components/PortfolioCharts.tsx
• Pie Chart: For assetType allocation.
• Bar Chart: For sector allocation.
• Integration: Use react-chartjs-2 library for easy React integration.

Pseudo-code (PortfolioCharts.tsx):

import React from 'react';
import { Pie } from 'react-chartjs-2';
import { Chart as ChartJS, ArcElement, Tooltip, Legend } from 'chart.js';

ChartJS.register(ArcElement, Tooltip, Legend);

const PortfolioCharts = ({ allocationData }) => {
  if (!allocationData || !allocationData.assetType || allocationData.assetType.labels.length === 0) {
    return <p>No data to display charts.</p>;
  }

  const pieChartOptions = {
    responsive: true,
    plugins: {
      legend: {
        position: 'top' as const,
      },
      title: {
        display: true,
        text: 'Asset Type Allocation',
      },
    },
  };

  return (
    <div style={{ maxWidth: '500px', margin: 'auto' }}>
      <Pie data={allocationData.assetType} options={pieChartOptions} />
      {/* <Bar data={allocationData.sector} options={barChartOptions} /> */}
    </div>
  );
};

export default PortfolioCharts;

5. Gemini Prompting Strategy

The Gemini API will be used to provide high-level, educational insights based on the structure of the user's portfolio, not to give direct financial advice. This feature adds significant value by helping beginners understand the implications of their current holdings.

5.1. Data Sent to Gemini:

To maintain privacy and focus on structural insights, we will send a sanitized and aggregated summary of the holdings to Gemini, avoiding personal financial details or identifiers.

// Example of `holdingsSummary` array to be sent to API route
const holdingsSummary = holdings.map(h => ({
  ticker: h.ticker,
  assetType: h.assetType,
  sector: h.sector || 'N/A',
  currentValue: h.currentValue,
  // Note: avgCost, shares, gainLoss are NOT sent
}));

This data should include:

• ticker: The stock/crypto symbol.
• assetType: The general category (Equity, Crypto, Cash, etc.).
• sector: The industry sector (if available).
• currentValue: The current market value of that specific holding.
• totalPortfolioValue: The sum of all currentValue.

5.2. API Route for Gemini: /pages/api/gemini-insights.ts

This route will receive the holdingsSummary from the client, construct the prompt, call the Gemini API, and return the generated insight.

5.3. Prompt Engineering:

The effectiveness of Gemini's insights heavily relies on well-crafted prompts. We need a System Prompt to set the AI's persona and User Prompt to provide the context and data.

• System Prompt (Implicit in the overall prompt design): "You are an AI assistant specialized in simplifying investment portfolio analysis for beginners. Your primary goal is to provide high-level, educational insights and observations based on provided portfolio data, not to offer specific financial advice, recommendations, or predictions. Focus on common investment principles like diversification, asset class characteristics, and potential concentration risks. Maintain a neutral, informative, and easy-to-understand tone."

• User Prompt (Dynamic based on holdingsSummary):

  "Please provide a concise summary and a few high-level educational observations for the following simplified investment portfolio. Do not give financial advice, specific recommendations, or predict market movements. Focus purely on general observations related to asset class distribution, potential sector concentration, and typical characteristics of the included asset types. Structure your response with a brief summary paragraph followed by bulleted observations.
  
  Holdings Data:
  ${holdingsSummary.map(h => `- Ticker: ${h.ticker}, Asset Type: ${h.assetType}, Sector: ${h.sector}, Current Value: $${h.currentValue.toFixed(2)}`).join('\n')}
  
  Total Portfolio Value: $${totalPortfolioValue.toFixed(2)}
  
  Please consider the following points in your analysis:
  1.  Overall asset class distribution (e.g., how much in Equities vs. Crypto vs. Cash).
  2.  Any noticeable concentration in specific sectors (e.g., heavy in Technology).
  3.  General characteristics or common implications of having these asset types (e.g., volatility of crypto, stability of cash).
  Keep the language simple and accessible for a beginner investor."
  

5.4. Expected Output:

The Gemini response should be a plain text summary, suitable for direct display to the user.

Example Output: "Based on your provided portfolio data, your investments are primarily distributed across Equity, Cryptocurrency, and Cash. The total value of your portfolio is currently $X,XXX.XX.

Observations:

• Asset Class Diversification: You have a mix of traditional equities, digital assets, and cash. This represents a blend of growth potential (equities, crypto) and liquidity/stability (cash).
• Sector Concentration: Your equity holdings show a notable concentration in the Technology sector. While technology can be a high-growth area, a heavy focus here means your portfolio's performance in equities will be closely tied to the performance of this specific industry.
• Cryptocurrency Exposure: The inclusion of cryptocurrency (e.g., Bitcoin) adds exposure to a highly volatile asset class. Cryptocurrencies can experience significant price swings compared to more traditional investments.
• Cash Position: Your cash holding provides liquidity and a buffer against market downturns, but typically does not grow at the same rate as invested assets, especially in inflationary environments."

5.5. Pseudo-code (Next.js API Route: /pages/api/gemini-insights.ts):

import type { NextApiRequest, NextApiResponse } from 'next';
import { GoogleGenerativeAI } from '@google/generative-ai';

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY as string);

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method Not Allowed' });
  }

  const { holdingsSummary, totalPortfolioValue } = req.body; // Expect an array of sanitized holdings

  if (!holdingsSummary || !Array.isArray(holdingsSummary) || typeof totalPortfolioValue !== 'number') {
    return res.status(400).json({ message: 'Invalid holdings data provided.' });
  }

  const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
  if (!GEMINI_API_KEY) {
    console.error('GEMINI_API_KEY not set.');
    return res.status(500).json({ message: 'Server configuration error.' });
  }

  const formattedHoldings = holdingsSummary.map(h =>
    `- Ticker: ${h.ticker}, Asset Type: ${h.assetType}, Sector: ${h.sector || 'N/A'}, Current Value: $${h.currentValue.toFixed(2)}`
  ).join('\n');

  const prompt = `You are an AI assistant specialized in simplifying investment portfolio analysis for beginners. Your primary goal is to provide high-level, educational insights and observations based on provided portfolio data, *not* to offer specific financial advice, recommendations, or predictions. Focus on common investment principles like diversification, asset class characteristics, and potential concentration risks. Maintain a neutral, informative, and easy-to-understand tone.

  Please provide a concise summary and a few high-level educational observations for the following simplified investment portfolio. Do not give financial advice, specific recommendations, or predict market movements. Focus purely on general observations related to asset class distribution, potential sector concentration, and typical characteristics of the included asset types. Structure your response with a brief summary paragraph followed by bulleted observations.

  Holdings Data:
  ${formattedHoldings}

  Total Portfolio Value: $${totalPortfolioValue.toFixed(2)}

  Please consider the following points in your analysis:
  1.  Overall asset class distribution (e.g., how much in Equities vs. Crypto vs. Cash).
  2.  Any noticeable concentration in specific sectors (e.g., heavy in Technology).
  3.  General characteristics or common implications of having these asset types (e.g., volatility of crypto, stability of cash).
  Keep the language simple and accessible for a beginner investor.`;

  try {
    const model = genAI.getGenerativeModel({ model: "gemini-pro" });
    const result = await model.generateContent(prompt);
    const response = await result.response;
    const text = response.text();
    return res.status(200).json({ insight: text });
  } catch (error) {
    console.error('Error calling Gemini API:', error);
    return res.status(500).json({ message: 'Failed to generate insights.', error: error instanceof Error ? error.message : String(error) });
  }
}

6. Deployment & Scaling

For a beginner-friendly application utilizing Next.js, local storage, and serverless API routes, deployment and scaling are remarkably straightforward and cost-effective.

6.1. Deployment

The recommended deployment strategy leverages platforms that are optimized for Next.js and serverless functions.

• Platform Choice: Vercel or Netlify
  • Vercel is the creator of Next.js and offers first-class integration, making deployment incredibly simple.
  • Netlify also provides excellent support for Next.js and serverless functions.
  • Advantages: Both platforms offer generous free tiers, automatic continuous deployment from Git repositories (GitHub, GitLab, Bitbucket), automatic HTTPS, and global CDNs.
• Deployment Process:
  1. Version Control: Push your Next.js project to a Git repository (e.g., GitHub).
  2. Platform Integration: Connect your Vercel/Netlify account to your Git repository.
  3. Environment Variables: Crucially, set your GEMINI_API_KEY and ALPHA_VANTAGE_API_KEY (or your chosen market data API key) as environment variables directly in the deployment platform's settings. These are securely injected into your Next.js API routes at build time or runtime and are never exposed to the client-side.
  4. Automatic Deployment: Vercel/Netlify will automatically detect your Next.js project, build it, and deploy it. Subsequent pushes to your configured branch will trigger automatic re-deployments.
  5. Domain: The application will be accessible via a default *.vercel.app or *.netlify.app domain, with options to configure a custom domain.

6.2. Scaling

Given the chosen architecture, the application is inherently designed for impressive scalability with minimal operational overhead, even for a "beginner" project.

• Frontend (Next.js Application):
  • Static Assets & Client-Side Rendering: Much of the UI rendering and user interaction happens directly in the user's browser. Next.js can output largely static bundles (if not using SSR heavily) that are served incredibly fast from Content Delivery Networks (CDNs).
  • Vercel/Netlify CDN: Both platforms automatically distribute your application's static assets globally, ensuring low latency for users worldwide. This scales effortlessly to handle millions of concurrent users viewing the interface.
  • Local Storage: Since user data resides in their browser's local storage, there are no server-side scaling concerns related to data persistence for this primary feature.
• API Routes (Next.js Serverless Functions):
  • Automatic Scaling: Next.js API routes are deployed as serverless functions (e.g., AWS Lambda, Google Cloud Functions). Vercel and Netlify manage this automatically. These functions scale elastically from zero to thousands of concurrent invocations based on demand, meaning you only pay for compute time actually used. This handles peak traffic spikes gracefully.
  • Statelessness: Our API routes are stateless, processing requests independently, which is a key characteristic for scalable serverless functions.
• External APIs (Gemini API & Market Data API):
  • Scalability: Both the Gemini API and reputable market data APIs are built to handle massive loads. Our application's scaling will be limited by the rate limits imposed by the free or chosen tier of these external services.
  • Rate Limit Management: For a beginner app, expected usage is low, so free-tier limits are usually sufficient. For future growth, monitoring API usage and potentially implementing simple caching strategies within the Next.js API routes (e.g., caching market data for a few minutes) could reduce calls to external APIs.
• Bottlenecks (and how to address them if the app grows significantly beyond "beginner"):
  • Local Storage Limitations: As mentioned, local storage is per-browser, lacks sync, and can be cleared. If the project evolves to require user accounts, multi-device sync, or more robust data security, transitioning to a dedicated backend database (e.g., Supabase, Firebase, PostgreSQL) would be necessary. This would introduce backend scaling concerns (database reads/writes, connection pooling, etc.).
  • External API Rate Limits: As usage grows, hitting free-tier rate limits for market data or Gemini could become an issue. Upgrading API plans or finding providers with higher limits would be the solution.
  • Cold Starts (Minor): Serverless functions can experience "cold starts" where the initial request to an idle function takes slightly longer to respond. For interactive features like "Generate Insights," this might introduce a minor delay, but it's generally negligible for an application of this scope.

In summary, the chosen architecture provides exceptional out-of-the-box scalability for a beginner project, allowing developers to focus on features rather than infrastructure. As the application matures, the modular nature of Next.js and serverless functions would facilitate a smooth transition to more robust backend solutions if required.