Robo-Advisor Onboarding

Project Blueprint: Robo-Advisor Onboarding

1. The Business Problem (Why build this?)

The wealth management industry is undergoing a significant transformation, driven by technological advancements and evolving client expectations. Traditional financial advisory models, while valuable, often suffer from high operational costs, limited accessibility to a broad demographic (particularly younger investors or those with smaller asset bases), and inherent human biases in recommendation processes. These factors create friction in client acquisition and retention, leading to suboptimal outcomes for both firms and their clients.

A critical juncture in the client journey is the initial onboarding phase, specifically the assessment of an individual's risk tolerance and the subsequent generation of a suitable investment portfolio. Manual processes are time-consuming, expensive, and prone to inconsistency. Existing digital solutions often rely on simplistic questionnaires that fail to capture the nuances of an individual's financial psychology, long-term aspirations, and comfort with market volatility. This can lead to misaligned portfolios, eroding client trust, increasing churn, and exposing firms to regulatory scrutiny regarding suitability.

There is a pressing need for a sophisticated, scalable, and highly personalized digital solution that streamlines the robo-advisor onboarding experience. Such a system would democratize access to high-quality financial guidance, reduce the cost-to-serve for wealth management firms, and enhance the accuracy of risk profiling. By leveraging advanced AI, firms can move beyond generic risk assessments to truly understand each client's unique financial fingerprint, leading to more appropriate portfolio recommendations and ultimately, better client outcomes and stronger relationships. This project aims to build the foundational components of such a system, focusing on intelligent risk assessment and personalized portfolio generation at scale.

2. Solution Overview

The "Robo-Advisor Onboarding" application is an advanced, intelligent platform designed to streamline and enhance the initial client onboarding process for wealth management firms. Its core function is to accurately assess a user's financial risk tolerance and subsequently generate a personalized, suitable model investment portfolio.

The solution will guide new clients through an intuitive and engaging digital journey:

1. Interactive Questionnaire: Users will complete a dynamic, multi-stage questionnaire designed to gather comprehensive data on their financial situation, investment objectives, time horizon, knowledge, and psychological comfort with risk. This questionnaire will incorporate various input types, including multiple-choice, slider-based scales, and crucially, open-ended text fields.
2. Intelligent Risk Tolerance Scoring: Utilizing a hybrid methodology, the system will process questionnaire responses. Quantitative answers will be numerically scored, while qualitative (open-ended) responses will be analyzed by the Gemini API for nuanced sentiment, tone, and underlying risk aversion/acceptance. These scores will be combined to derive a precise risk tolerance profile.
3. Personalized Portfolio Generation: Based on the calculated risk tolerance profile and other key inputs (e.g., investment horizon, initial capital), the system will intelligently match the user to one of a suite of pre-defined, diversified model portfolios. This matching will be transparent and justified.
4. Clear Asset Allocation Visualization: The recommended portfolio's asset allocation will be presented through interactive and visually appealing charts (e.g., pie charts, bar charts) using Recharts, allowing users to easily understand the composition of their proposed investments.
5. Comprehensive Onboarding Dashboard: A dedicated dashboard will serve as the central hub for users to review their calculated risk score, the recommended portfolio, a personalized explanation (generated by Gemini) for why that portfolio is suitable, and a clear call to action to proceed with account opening (or re-evaluate).

The value proposition is multi-fold: for the user, a highly personalized, transparent, and engaging onboarding experience that builds trust; for the wealth management firm, increased efficiency, reduced operational costs, improved compliance through robust suitability assessments, higher conversion rates, and richer data insights for ongoing client management.

3. Architecture & Tech Stack Justification

The architecture for "Robo-Advisor Onboarding" adheres to a modern, scalable, and cloud-native design pattern, leveraging Google Cloud Platform (GCP) for robust infrastructure and the Gemini API for advanced AI capabilities.

Overall Architecture: The system will operate on a client-server model, with a performant frontend interacting with a set of serverless backend services.

+----------------+       +-------------------+       +---------------------+
|   User Client  | <---> |   Next.js Frontend| <---> |  Backend Services   |
| (Web Browser)  |       | (SSR/SSG/API Rts) |       | (Cloud Functions/CR)|
+----------------+       +-------------------+       +---------------------+
                                  ^   |                      ^    |
                                  |   |                      |    |
                                  |   +----------------------+    |
                                  |                             +------------+
                                  |                             |   Gemini   |
                                  |                             |    API     |
                                  |                             +------------+
                                  |                                   |
                                  +-----------------------------------+
                                                                      |
                                                                   +----------+
                                                                   | Database |
                                                                   | (Firestore)|
                                                                   +----------+

Tech Stack Justification:

• Next.js (Frontend Framework):
  • Justification: As a React framework, Next.js provides a robust foundation for building interactive and performant user interfaces. Its key advantage for this project is its support for Server-Side Rendering (SSR) and Static Site Generation (SSG). While much of the application will likely be authenticated (rendering SSG less critical), SSR ensures fast initial page loads, better SEO (for potential landing pages or public sections), and a superior user experience by sending fully rendered HTML. Next.js API Routes also offer a convenient way to implement lightweight backend logic or act as a proxy layer to dedicated backend services, simplifying the initial development and deployment. The extensive React ecosystem ensures a rich component library and community support.
• Gemini API (AI/ML Engine):
  • Justification: The Gemini API is central to the "intelligent" aspect of this robo-advisor. Its advanced large language model capabilities provide unparalleled power for natural language understanding (NLU) and generation. This is crucial for:
    1. Nuanced Risk Assessment: Analyzing open-ended user responses to gauge sentiment, underlying risk appetite, and emotional resilience to market fluctuations, going beyond simplistic multiple-choice scoring.
    2. Personalized Explanations: Generating tailored, easy-to-understand justifications for portfolio recommendations, enhancing user trust and comprehension.
    3. Dynamic Interaction (Future): Potential for dynamic question generation or conversational interfaces.
  • Leveraging Google's cutting-edge AI ensures scalability, reliability, and seamless integration with other GCP services.
• Recharts (Data Visualization):
  • Justification: Recharts is a composable charting library built on React components. Its native integration with React (and thus Next.js) makes it an ideal choice for displaying asset allocation charts, projected growth graphs, and other financial visualizations. It offers a wide array of chart types (Pie, Bar, Line) and is highly customizable, allowing us to create clear, aesthetically pleasing, and informative data representations that are crucial for user comprehension of their portfolio.
• Framer Motion (Animations & Micro-interactions):
  • Justification: User experience is paramount in financial applications. Framer Motion is a production-ready, declarative animation library for React that simplifies adding sophisticated animations and transitions. It will be used to enhance the interactivity and engagement of the questionnaire (e.g., smooth transitions between questions), provide subtle feedback on user actions, and create a polished, modern feel for the overall application, contributing to a sense of professionalism and trustworthiness.
• Google Cloud Platform (GCP) (Cloud Infrastructure):
  • Justification: As a Staff AI Engineer at Google, GCP is the natural choice, offering a comprehensive suite of managed services that align perfectly with the project's scalability, reliability, and security requirements.
    • Cloud Run / Cloud Functions (Backend Services): Provides serverless compute, allowing backend logic for scoring, portfolio matching, and data persistence to scale automatically with demand without managing servers. Cost-effective (pay-per-use) and highly available.
    • Firestore (NoSQL Database): A highly scalable, flexible NoSQL document database. Ideal for storing user profiles, questionnaire responses, risk scores, and model portfolio definitions. Its real-time capabilities and seamless integration with other GCP services simplify development and ensure low-latency data access.
    • Identity Platform (Authentication): Provides robust, scalable authentication services, supporting various identity providers and ensuring secure user access.
    • Cloud Storage: For static assets (if not bundled with Next.js build) or larger documents.
    • Cloud Logging & Monitoring: Essential for observability, ensuring the application's health, performance, and quick issue resolution.
    • Secret Manager: Securely stores API keys (e.g., Gemini API key), database credentials, and other sensitive configuration data.

4. Core Feature Implementation Guide

This section outlines the detailed implementation strategy for the core features, including pipeline designs and pseudo-code snippets.

A. Interactive Questionnaire

Design & Flow: The questionnaire will be presented as a multi-step form, leveraging conditional logic to tailor subsequent questions based on previous answers (e.g., if a user indicates a short time horizon, follow-up questions about market volatility might be weighted differently). Questions will include:

• Demographic & Financial: Age, income, existing assets/liabilities.
• Goals: Retirement, home purchase, wealth preservation, growth.
• Time Horizon: Short, medium, long-term.
• Knowledge: Self-assessed understanding of investments.
• Risk Willingness: Multiple-choice scenarios (e.g., "If your portfolio dropped by 20%, what would you do?"), slider-based risk scales.
• Risk Capacity: Questions related to emergency funds, income stability, debt.
• Qualitative Risk Assessment: Open-ended questions like "Describe your feelings about market fluctuations and potential losses" or "What is your primary motivation for investing, and how would you react to significant market downturns?"

Frontend Implementation (Next.js with Framer Motion):

• Each question or group of questions will be a distinct React component.
• State management (e.g., React Context, Zustand, Jotai) will manage questionnaire progress and collected answers.
• Framer Motion will be used for smooth layout transitions between questions, adding a polished and engaging feel.

Pseudo-code (Frontend - Simplified):

// components/QuestionnaireForm.js
import { useState } from 'react';
import { motion, AnimatePresence } from 'framer-motion';
import QuestionCard from './QuestionCard'; // Component for individual question display

const questions = [
  { id: 'q1', type: 'multiple_choice', text: 'What is your primary investment goal?', options: ['Growth', 'Income', 'Preservation'] },
  { id: 'q2', type: 'slider', text: 'On a scale of 1-10, how comfortable are you with investment risk?', min: 1, max: 10 },
  { id: 'q3', type: 'text_area', text: 'Describe your feelings about market fluctuations and potential losses.', condition: (answers) => answers.q2 > 5 }, // Conditional question
  // ... more questions
];

export default function QuestionnaireForm() {
  const [currentQuestionIndex, setCurrentQuestionIndex] = useState(0);
  const [answers, setAnswers] = useState({});

  const handleAnswerChange = (questionId, value) => {
    setAnswers(prev => ({ ...prev, [questionId]: value }));
  };

  const handleNext = () => {
    if (currentQuestionIndex < questions.length - 1) {
      setCurrentQuestionIndex(prev => prev + 1);
    } else {
      handleSubmit();
    }
  };

  const handleSubmit = async () => {
    // Send answers to backend for processing
    console.log('Submitting answers:', answers);
    const response = await fetch('/api/onboarding/submit-answers', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(answers),
    });
    const result = await response.json();
    console.log('Backend response:', result);
    // Navigate to dashboard or next step
  };

  const currentQuestion = questions[currentQuestionIndex];

  // Apply conditional logic to determine if currentQuestion should be skipped or modified
  // For simplicity, this example assumes direct progression
  const shouldDisplayQuestion = !currentQuestion.condition || currentQuestion.condition(answers);
  if (!shouldDisplayQuestion && currentQuestionIndex < questions.length - 1) {
    // Automatically advance if a question is conditionally skipped
    setCurrentQuestionIndex(prev => prev + 1);
    return null; // Don't render anything for the skipped question this cycle
  }

  return (
    <div className="max-w-xl mx-auto p-4">
      <AnimatePresence mode="wait">
        <motion.div
          key={currentQuestion.id}
          initial={{ opacity: 0, y: 50 }}
          animate={{ opacity: 1, y: 0 }}
          exit={{ opacity: 0, y: -50 }}
          transition={{ duration: 0.3 }}
        >
          <QuestionCard
            question={currentQuestion}
            onAnswer={handleAnswerChange}
            currentAnswer={answers[currentQuestion.id]}
          />
          <div className="flex justify-end mt-6">
            <button onClick={handleNext} className="px-6 py-2 bg-blue-600 text-white rounded-md">
              {currentQuestionIndex < questions.length - 1 ? 'Next' : 'Submit'}
            </button>
          </div>
        </motion.div>
      </AnimatePresence>
    </div>
  );
}

B. Risk Tolerance Scoring

Pipeline Design (Backend - Cloud Function/Run):

1. Receive Answers: The backend API endpoint (/api/onboarding/submit-answers) receives the JSON payload of user answers.
2. Quantitative Scoring:
   • Iterate through predefined multiple-choice and slider questions.
   • Assign numerical scores based on pre-configured mappings (e.g., 'Aggressive' choice = +5, 'Conservative' = +1).
   • Apply weights to different question categories (e.g., risk scenario questions might be weighted higher than demographic questions).
3. Qualitative Scoring (Gemini API Integration):
   • Extract open-ended text responses (e.g., from q3: "Describe your feelings...").
   • Call the Gemini API with a specific prompt (see Section 5) to analyze the sentiment, tone, and extract a derived risk factor.
   • Input to Gemini: User's free-text response.
   • Output from Gemini: risk_score (e.g., 1-5), justification, confidence.
4. Aggregate & Normalize:
   • Combine the quantitative score and the Gemini-derived qualitative score using a weighted average. The Gemini score might have a significant weight due to its nuanced analysis.
   • Normalize the combined score to a final, standardized risk scale (e.g., 1-5, mapping to profiles like "Conservative", "Moderate", "Balanced", "Growth", "Aggressive").
   • Store the raw scores, normalized risk profile, and Gemini's justification in Firestore.

Pseudo-code (Backend - Node.js Cloud Function):

// api/onboarding/submit-answers (Next.js API Route or Cloud Function)
import { GoogleGenerativeAI } from '@google/generative-ai';
import { getFirestore } from 'firebase-admin/firestore'; // Assuming Firebase Admin SDK

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({ model: 'gemini-pro' });
const db = getFirestore();

// Example scoring weights and mappings
const scoringConfig = {
  q1: { 'Growth': 5, 'Income': 2, 'Preservation': 1 },
  q2: { type: 'slider', weight: 0.8 }, // Slider value directly contributes
  q3: { type: 'text_analysis', weight: 1.2 }, // Heavily weighted for Gemini
};

async function calculateRiskScore(answers, userId) {
  let quantitativeScore = 0;
  let qualitativeScore = 0;
  let totalWeight = 0;
  let geminiJustification = '';
  let geminiConfidence = 0;

  // 1. Quantitative Scoring
  for (const qId in answers) {
    if (scoringConfig[qId]) {
      const config = scoringConfig[qId];
      if (config.type === 'multiple_choice' && config[answers[qId]]) {
        quantitativeScore += config[answers[qId]];
        totalWeight += 1; // Simple weight for multiple choice
      } else if (config.type === 'slider') {
        quantitativeScore += answers[qId] * config.weight;
        totalWeight += config.weight;
      }
    }
  }

  // 2. Qualitative Scoring with Gemini
  if (answers.q3 && scoringConfig.q3?.type === 'text_analysis') {
    const prompt = `Analyze the user's risk tolerance, financial goals, and emotional response to market fluctuations based on their free-text response. Assign a risk score from 1 (Conservative) to 5 (Aggressive) and provide a concise justification. Output in JSON format: {'risk_score': int, 'justification': str, 'confidence': float}. User response: "${answers.q3}"`;
    try {
      const result = await model.generateContent(prompt);
      const response = await result.response;
      const text = response.text();
      const geminiOutput = JSON.parse(text.replace(/```json|```/g, '').trim()); // Clean up markdown
      
      qualitativeScore = geminiOutput.risk_score * scoringConfig.q3.weight;
      totalWeight += scoringConfig.q3.weight;
      geminiJustification = geminiOutput.justification;
      geminiConfidence = geminiOutput.confidence;

    } catch (error) {
      console.error('Gemini API error:', error);
      // Fallback or error handling for Gemini failure
    }
  }

  // 3. Aggregate & Normalize
  const rawCombinedScore = quantitativeScore + qualitativeScore;
  const normalizedScore = totalWeight > 0 ? rawCombinedScore / totalWeight : 0; // Simple average for now

  // Map normalized score to a risk profile (e.g., 1-5 scale)
  let riskProfile = 'Conservative';
  if (normalizedScore > 1.5 && normalizedScore <= 2.5) riskProfile = 'Moderate';
  else if (normalizedScore > 2.5 && normalizedScore <= 3.5) riskProfile = 'Balanced';
  else if (normalizedScore > 3.5 && normalizedScore <= 4.5) riskProfile = 'Growth';
  else if (normalizedScore > 4.5) riskProfile = 'Aggressive';

  // Store results in Firestore
  await db.collection('users').doc(userId).update({
    riskScore: normalizedScore,
    riskProfile: riskProfile,
    geminiAnalysis: {
      justification: geminiJustification,
      confidence: geminiConfidence,
      rawOutput: answers.q3 // Store raw input for audit
    },
    lastUpdated: new Date()
  });

  return { riskScore: normalizedScore, riskProfile, geminiJustification };
}

// In Next.js API route handler (pages/api/onboarding/submit-answers.js)
export default async function handler(req, res) {
  if (req.method === 'POST') {
    const { answers, userId } = req.body; // userId would come from authentication
    if (!answers || !userId) {
      return res.status(400).json({ message: 'Missing answers or userId' });
    }
    try {
      const result = await calculateRiskScore(answers, userId);
      res.status(200).json(result);
    } catch (error) {
      console.error('Error processing questionnaire:', error);
      res.status(500).json({ message: 'Error processing questionnaire', error: error.message });
    }
  } else {
    res.setHeader('Allow', ['POST']);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

C. Portfolio Generation

Logic (Backend - Cloud Function/Run):

1. Retrieve User Profile: Fetch the riskProfile (e.g., "Moderate Growth"), investmentHorizon, and initialCapital for the authenticated user from Firestore.

2. Model Portfolio Lookup: Access a predefined collection of modelPortfolios stored in Firestore or a configuration file. Each model portfolio is tied to a specific risk profile and defines target asset allocations (e.g., equities, fixed income, cash, alternatives).

   // Example Model Portfolio Structure (Firestore collection: 'modelPortfolios')
   {
     "id": "balanced_growth_v1",
     "name": "Balanced Growth Fund",
     "riskProfileMatch": ["Balanced", "Growth"],
     "description": "A diversified portfolio seeking capital appreciation with moderate risk.",
     "assetAllocations": [
       {"assetClass": "Domestic Equities", "percentage": 30, "details": "Large Cap Growth"},
       {"assetClass": "International Equities", "percentage": 25, "details": "Developed & Emerging Markets"},
       {"assetClass": "Fixed Income", "percentage": 20, "details": "Investment Grade Bonds"},
       {"assetClass": "Real Estate (REITs)", "percentage": 10, "details": "Diversified REITs"},
       {"assetClass": "Cash", "percentage": 15, "details": "Liquidity for rebalancing"}
     ],
     "projectedReturns": {"avg": 7.0, "low": 4.0, "high": 10.0}, // Annualized
     "riskMetrics": {"stdDev": 12.5, "maxDrawdown": 18.0}
   }
   

3. Matching Algorithm:

   • Find model portfolios whose riskProfileMatch array includes the user's riskProfile.
   • If multiple match, apply further filtering based on investmentHorizon (e.g., longer horizons might favor more equity-heavy options within the same risk band).
   • Select the most appropriate portfolio.

4. Output: Return the selected portfolioId, portfolioName, detailed assetAllocations, and associated projectedReturns and riskMetrics.

5. Store Recommendation: Persist the recommended portfolio's ID and details to the user's profile in Firestore for future reference and compliance.

Pseudo-code (Backend - Node.js Cloud Function):

// api/onboarding/generate-portfolio (Next.js API Route or Cloud Function)
async function generatePortfolio(userId) {
  const userDoc = await db.collection('users').doc(userId).get();
  if (!userDoc.exists) {
    throw new Error('User not found.');
  }
  const userData = userDoc.data();
  const { riskProfile, investmentHorizon } = userData; // Assume these are collected earlier

  const modelPortfoliosRef = db.collection('modelPortfolios');
  const snapshot = await modelPortfoliosRef.where('riskProfileMatch', 'array-contains', riskProfile).get();

  if (snapshot.empty) {
    throw new Error(`No model portfolio found for risk profile: ${riskProfile}`);
  }

  let recommendedPortfolio = null;
  // Simple logic: pick the first matching. More advanced: consider horizon, initial capital, etc.
  snapshot.forEach(doc => {
    // Implement more sophisticated selection logic here if multiple portfolios match the risk profile
    // e.g., filter by investmentHorizon bands, or choose a default
    if (!recommendedPortfolio) { // For simplicity, take the first one
        recommendedPortfolio = { id: doc.id, ...doc.data() };
    }
  });

  if (!recommendedPortfolio) {
    throw new Error('Could not determine a recommended portfolio.');
  }

  // Store the recommendation
  await db.collection('users').doc(userId).update({
    recommendedPortfolio: {
      id: recommendedPortfolio.id,
      name: recommendedPortfolio.name,
      assetAllocations: recommendedPortfolio.assetAllocations,
      // ... other relevant data
    },
    portfolioGeneratedAt: new Date()
  });

  return recommendedPortfolio;
}

// In Next.js API route handler (pages/api/onboarding/generate-portfolio.js)
export default async function handler(req, res) {
  if (req.method === 'POST') {
    const { userId } = req.body; // Get userId from authenticated session
    if (!userId) {
      return res.status(401).json({ message: 'Authentication required' });
    }
    try {
      const portfolio = await generatePortfolio(userId);
      res.status(200).json(portfolio);
    } catch (error) {
      console.error('Error generating portfolio:', error);
      res.status(500).json({ message: 'Error generating portfolio', error: error.message });
    }
  } else {
    res.setHeader('Allow', ['POST']);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

D. Asset Allocation Charts (Recharts)

Frontend Implementation (Next.js with Recharts):

• A dedicated React component (PortfolioAllocationChart) will receive the assetAllocations data.
• It will render a PieChart or BarChart from Recharts, dynamically displaying the proportions of each asset class.
• Customization will include color schemes, tooltips for detailed information on hover, and clear legends.

Pseudo-code (Frontend - Simplified):

// components/PortfolioAllocationChart.js
import React from 'react';
import { PieChart, Pie, Cell, ResponsiveContainer, Tooltip, Legend } from 'recharts';

const COLORS = ['#0088FE', '#00C49F', '#FFBB28', '#FF8042', '#AF19FF', '#FF0056'];

export default function PortfolioAllocationChart({ allocations }) {
  if (!allocations || allocations.length === 0) {
    return <p>No allocation data available.</p>;
  }

  // Recharts expects an array of objects with a 'value' key for PieChart
  const data = allocations.map(item => ({
    name: item.assetClass,
    value: item.percentage,
    details: item.details // Optional: for tooltip
  }));

  const CustomTooltip = ({ active, payload }) => {
    if (active && payload && payload.length) {
      const dataItem = payload[0].payload;
      return (
        <div className="bg-white p-2 border border-gray-300 rounded shadow-md text-sm">
          <p className="font-semibold text-gray-800">{dataItem.name}</p>
          <p className="text-gray-700">Percentage: {dataItem.value}%</p>
          {dataItem.details && <p className="text-gray-600">Details: {dataItem.details}</p>}
        </div>
      );
    }
    return null;
  };

  return (
    <ResponsiveContainer width="100%" height={300}>
      <PieChart>
        <Pie
          data={data}
          cx="50%"
          cy="50%"
          labelLine={false}
          outerRadius={100}
          fill="#8884d8"
          dataKey="value"
        >
          {data.map((entry, index) => (
            <Cell key={`cell-${index}`} fill={COLORS[index % COLORS.length]} />
          ))}
        </Pie>
        <Tooltip content={<CustomTooltip />} />
        <Legend />
      </PieChart>
    </ResponsiveContainer>
  );
}

E. Onboarding Dashboard

Frontend Implementation (Next.js):

• The dashboard will be a dedicated page (/dashboard or /onboarding/review).
• It fetches the user's riskProfile, riskScore, and recommendedPortfolio data from the backend.
• It will display:
  • A summary section with the user's risk profile name and score.
  • The PortfolioAllocationChart component.
  • A personalized portfolio explanation generated by Gemini (retrieved from user's Firestore profile).
  • Call-to-action buttons like "Proceed to Account Opening" or "Retake Questionnaire".

Pseudo-code (Frontend - Simplified):

// pages/onboarding/dashboard.js
import { useState, useEffect } from 'react';
import { useRouter } from 'next/router';
import PortfolioAllocationChart from '../../components/PortfolioAllocationChart';
import { motion } from 'framer-motion';

export default function OnboardingDashboard() {
  const router = useRouter();
  const [userData, setUserData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function fetchDashboardData() {
      // In a real app, userId would be retrieved from a secure authenticated session
      const userId = 'current_user_id'; // Placeholder
      try {
        const response = await fetch(`/api/onboarding/dashboard-data?userId=${userId}`);
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
        }
        const data = await response.json();
        setUserData(data);
      } catch (e) {
        setError(e.message);
      } finally {
        setLoading(false);
      }
    }
    fetchDashboardData();
  }, []);

  if (loading) return <div className="text-center p-8">Loading your personalized dashboard...</div>;
  if (error) return <div className="text-center p-8 text-red-600">Error: {error}</div>;
  if (!userData) return <div className="text-center p-8">No data found. Please complete the questionnaire.</div>;

  const { riskProfile, riskScore, recommendedPortfolio, geminiAnalysis } = userData;

  return (
    <motion.div
      initial={{ opacity: 0, y: 50 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.5 }}
      className="max-w-4xl mx-auto p-6 bg-white rounded-lg shadow-xl my-10"
    >
      <h1 className="text-4xl font-bold text-gray-900 mb-6">Your Personalized Investment Blueprint</h1>

      <div className="grid grid-cols-1 md:grid-cols-2 gap-8 mb-8">
        <div className="bg-blue-50 p-6 rounded-lg shadow-inner">
          <h2 className="text-2xl font-semibold text-blue-800 mb-3">Your Risk Profile</h2>
          <p className="text-lg text-gray-700 mb-2">
            **{riskProfile}** (Score: {riskScore ? riskScore.toFixed(2) : 'N/A'})
          </p>
          <p className="text-gray-600 italic text-sm">
            Based on your responses, you exhibit a {riskProfile.toLowerCase()} approach to investing.
          </p>
          {geminiAnalysis?.justification && (
            <div className="mt-4 p-3 bg-blue-100 rounded-md text-blue-800 text-sm">
              <p className="font-medium">AI Insights:</p>
              <p>{geminiAnalysis.justification}</p>
            </div>
          )}
        </div>

        <div className="bg-green-50 p-6 rounded-lg shadow-inner">
          <h2 className="text-2xl font-semibold text-green-800 mb-3">Recommended Portfolio</h2>
          <p className="text-xl font-bold text-green-900 mb-2">{recommendedPortfolio?.name || 'N/A'}</p>
          {recommendedPortfolio?.description && (
            <p className="text-gray-700">{recommendedPortfolio.description}</p>
          )}
        </div>
      </div>

      <div className="mb-8">
        <h2 className="text-2xl font-semibold text-gray-900 mb-4">Asset Allocation Breakdown</h2>
        {recommendedPortfolio?.assetAllocations ? (
          <PortfolioAllocationChart allocations={recommendedPortfolio.assetAllocations} />
        ) : (
          <p className="text-gray-600">No asset allocation details available.</p>
        )}
      </div>

      <div className="text-center">
        <button
          onClick={() => router.push('/account-opening')} // Placeholder for next step
          className="px-8 py-3 bg-indigo-600 text-white font-semibold rounded-lg hover:bg-indigo-700 transition-colors duration-200 mr-4"
        >
          Proceed to Account Opening
        </button>
        <button
          onClick={() => router.push('/onboarding/questionnaire')}
          className="px-8 py-3 border border-gray-300 text-gray-800 font-semibold rounded-lg hover:bg-gray-100 transition-colors duration-200"
        >
          Retake Questionnaire
        </button>
      </div>
    </motion.div>
  );
}

// pages/api/onboarding/dashboard-data.js (Backend API Route)
// This would fetch user data from Firestore for the dashboard
export default async function handler(req, res) {
  if (req.method === 'GET') {
    const { userId } = req.query; // From authenticated session in real app
    if (!userId) return res.status(401).json({ message: 'Authentication required' });

    try {
      const userDoc = await db.collection('users').doc(userId).get();
      if (!userDoc.exists) return res.status(404).json({ message: 'User data not found' });
      const userData = userDoc.data();

      // Ensure recommendedPortfolio is fully populated if stored as just an ID
      let fullRecommendedPortfolio = null;
      if (userData.recommendedPortfolio && userData.recommendedPortfolio.id) {
        const portfolioDoc = await db.collection('modelPortfolios').doc(userData.recommendedPortfolio.id).get();
        if (portfolioDoc.exists) {
            fullRecommendedPortfolio = { id: portfolioDoc.id, ...portfolioDoc.data() };
        }
      } else {
          // If the full object is stored directly
          fullRecommendedPortfolio = userData.recommendedPortfolio;
      }


      res.status(200).json({
        riskProfile: userData.riskProfile,
        riskScore: userData.riskScore,
        recommendedPortfolio: fullRecommendedPortfolio, // Use the fully resolved portfolio
        geminiAnalysis: userData.geminiAnalysis
      });
    } catch (error) {
      console.error('Error fetching dashboard data:', error);
      res.status(500).json({ message: 'Error fetching dashboard data', error: error.message });
    }
  } else {
    res.setHeader('Allow', ['GET']);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

5. Gemini Prompting Strategy

Leveraging the Gemini API effectively requires a strategic approach to prompt engineering, focusing on clarity, few-shot examples (if necessary), and structured output.

Core Principles:

• Clear Instructions: Provide explicit instructions on the task, desired output format, and any constraints (e.g., word count, tone).
• Role Assignment: Tell Gemini what role it's playing (e.g., "Analyze as a financial expert").
• Structured Output: Request output in easily parseable formats like JSON to simplify downstream processing.
• Grounding: Where possible, ground the model's responses with factual, application-specific data (e.g., details of a model portfolio).
• Temperature Control: Adjust temperature for different tasks: lower for factual extraction/classification (risk scoring), higher for creative generation (personalized explanations).

Specific Use Cases and Prompts:

1. Open-ended Question Analysis (Risk Assessment):

   • Goal: Extract a numerical risk score and justification from free-text.
   • Prompt:

     You are a financial risk assessment AI. Analyze the user's free-text response below to determine their financial risk tolerance, investment goals, and emotional reaction to market fluctuations. Assign a numerical risk score from 1 (Conservative - extremely risk-averse, prioritizes capital preservation) to 5 (Aggressive - highly comfortable with risk for maximum growth). Provide a concise justification for the score.
     
     Output in strict JSON format:
     {
       "risk_score": <int, 1-5>,
       "justification": "<string>",
       "confidence": <float, 0.0-1.0> // Self-assessed confidence in the score
     }
     
     User response: "{{USER_FREE_TEXT_RESPONSE}}"
     

   • Example Input: "I'm comfortable with some ups and downs for long-term growth, but I don't want to lose everything. I get a bit nervous if my portfolio drops too much in a short period, but I understand that markets fluctuate. My main goal is to save for retirement in 20 years."
   • Expected Output:

     {
       "risk_score": 3,
       "justification": "The user indicates comfort with 'some ups and downs' for 'long-term growth' (20 years for retirement), suggesting a moderate risk appetite. However, they express nervousness with 'too much' short-term drop and a desire not to 'lose everything,' indicating a need for balance. This aligns with a moderate risk profile seeking growth with a degree of capital preservation.",
       "confidence": 0.85
     }
     

   • Rationale: This prompt explicitly defines the scale, provides examples for the extremes, specifies the output format, and guides the AI on what to analyze.

2. Personalized Portfolio Explanation:

   • Goal: Generate a user-friendly, personalized explanation for the recommended portfolio.
   • Prompt:

     You are a friendly and knowledgeable financial advisor. Generate a concise (under 200 words) explanation for a user with the following profile, justifying why the recommended portfolio is suitable for them. Highlight the key asset classes and the overall investment philosophy.
     
     User Risk Profile: {{USER_RISK_PROFILE}} (Score: {{USER_RISK_SCORE}})
     Recommended Portfolio Name: "{{PORTFOLIO_NAME}}"
     Recommended Portfolio Description: "{{PORTFOLIO_DESCRIPTION}}"
     Key Asset Allocations: {{JSON_ARRAY_OF_ASSET_ALLOCATIONS}} // E.g., [{"assetClass": "Equities", "percentage": 60}, ...]
     
     Explanation:
     

   • Example Input:
     • User Risk Profile: "Balanced" (Score: 3.2)
     • Recommended Portfolio Name: "Core Diversification Fund"
     • Recommended Portfolio Description: "A diversified portfolio aiming for steady growth with a balanced approach to risk."
     • Key Asset Allocations: [{"assetClass": "Equities", "percentage": 50}, {"assetClass": "Fixed Income", "percentage": 40}, {"assetClass": "Cash", "percentage": 10}]
   • Rationale: Grounding the prompt with the user's specific risk profile and the portfolio's details enables Gemini to generate a highly relevant and personalized explanation, building trust and understanding.

3. Regulatory Compliance/Suitability Narrative (Backend Assist - Audit Trail):

   • Goal: Generate a concise, auditable statement confirming the suitability of the portfolio.
   • Prompt:

     As a regulatory compliance assistant for a financial firm, generate a 'Suitability Statement' for the following client and their recommended portfolio. The statement should articulate why the recommended portfolio aligns with the client's risk willingness, risk capacity, and investment objectives. Identify any notable deviations or points requiring human review. Keep it formal and objective.
     
     Client Profile:
     {{JSON_USER_DATA}} // E.g., {"age": 45, "income": "150k", "goals": ["retirement"], "riskProfile": "Moderate"}
     
     Recommended Portfolio:
     {{JSON_PORTFOLIO_DATA}} // E.g., {"name": "Balanced Growth", "assetAllocations": [...], "riskMetrics": {...}}
     
     Suitability Statement:
     

   • Rationale: This prompt is critical for internal compliance and audit trails. It requires a factual, objective assessment and identifies potential flags for human intervention, crucial for an advanced wealth management system.

Handling Hallucinations and Bias:

• Grounding: Always provide relevant factual data (e.g., model portfolio details) to minimize imaginative responses.
• Temperature Tuning: For critical tasks like risk scoring or suitability statements, use a very low temperature (e.g., 0.1-0.3) to encourage deterministic, less creative outputs. For personalized explanations, a slightly higher temperature (e.g., 0.5-0.7) can allow for more engaging prose without straying too far.
• Input Validation & Sanitization: Clean user inputs before sending to Gemini to prevent prompt injection or irrelevant noise.
• Post-processing & Human Review: Implement automated checks on Gemini's output (e.g., validate JSON schema, check for keyword presence/absence). For high-stakes decisions, human oversight or review of Gemini's justifications should be a final safeguard.
• Moderation API: Integrate Google's content moderation APIs to filter out any potentially harmful or inappropriate user inputs before they reach Gemini, and to check Gemini's outputs for compliance.

6. Deployment & Scaling

The deployment strategy will prioritize scalability, cost-efficiency, and operational simplicity, leveraging Google Cloud Platform's serverless and managed services.

Deployment Environment: Google Cloud Platform (GCP)

A. Frontend (Next.js Application):

• Service: Cloud Run
• Strategy:
  1. Containerize the Next.js application (including npm run build and npm start).
  2. Deploy the container image to Cloud Run.
  3. Cloud Run automatically scales instances up or down to zero based on traffic, providing excellent cost efficiency and handling traffic spikes effortlessly.
  4. Configure a custom domain mapping with Cloud Load Balancing (optional, but good for robust SSL and global traffic distribution).
  5. Utilize Cloud CDN for caching static assets and further improving global performance and reducing latency.
• CI/CD: Use Cloud Build to automate the build, containerization, and deployment process from a Git repository (e.g., Cloud Source Repositories, GitHub). A push to the main branch can trigger a full deployment.

B. Backend Services (API Endpoints for Scoring, Portfolio Matching, User Data):

• Service: Cloud Functions or Cloud Run
• Strategy:
  • Cloud Functions (Recommended for individual, stateless operations): Each API endpoint (e.g., calculateRiskScore, generatePortfolio) can be deployed as a separate Cloud Function. This provides fine-grained scaling, pay-per-invocation billing, and minimal operational overhead. Ideal for event-driven architectures.
  • Cloud Run (Alternative for more complex APIs or shared logic): If the backend services require more persistent connections, shared memory, or a full HTTP server abstraction, a single containerized application deployed to Cloud Run can host multiple API endpoints.
• CI/CD: Similar to the frontend, Cloud Build will automate deployments for these services.

C. Database (Firestore):

• Service: Cloud Firestore
• Strategy:
  1. Firestore is a fully managed, serverless NoSQL database that scales automatically. No manual provisioning or scaling configuration is required.
  2. Design data models carefully to ensure efficient queries and avoid hot spots. Utilize compound indexes for complex query patterns.
  3. Leverage Firestore's offline capabilities for potential future enhancements (e.g., pre-populating forms).
• Backup & Restore: Configure daily managed backups to Cloud Storage.

D. AI/ML Integration (Gemini API):

• Service: Gemini API
• Strategy:
  1. The Gemini API is a managed service by Google, inheriting its massive scalability and reliability.
  2. Access to Gemini API will be secured via API keys stored in Google Secret Manager, ensuring they are never hardcoded.
  3. Implement robust error handling and exponential backoff for API calls to handle transient issues and rate limits gracefully.
  4. Monitor Gemini API usage and costs via Cloud Monitoring.

E. Authentication & Authorization:

• Service: Firebase Authentication (Google Identity Platform)
• Strategy:
  1. Use Firebase Auth for secure user registration, login, and session management. It supports various providers (email/password, Google, etc.).
  2. Implement JWTs (JSON Web Tokens) for authenticating requests from the frontend to backend services.
  3. Utilize Google Cloud IAM (Identity and Access Management) to control permissions between GCP services (e.g., Cloud Function accessing Firestore, Cloud Run accessing Secret Manager). Define least-privilege roles.

F. Observability:

• Logging: Centralize all application and infrastructure logs in Cloud Logging. Ensure structured logging (JSON format) for easier querying and analysis.
• Monitoring: Use Cloud Monitoring to track key metrics:
  • Frontend: Latency, error rates, user traffic.
  • Backend (Cloud Run/Functions): Invocation count, execution time, memory/CPU usage, error rates.
  • Database: Read/write operations, latency, storage usage.
  • Gemini API: Call count, latency, error rates.
  • Set up custom dashboards and alerting (email, PagerDuty) for anomalies or critical thresholds.
• Tracing: Implement Cloud Trace for distributed tracing across frontend, backend, and Gemini API calls, crucial for debugging performance issues in a microservices architecture.

G. Security:

• Secrets Management: Store all sensitive credentials (API keys, database secrets) in Google Secret Manager. Access is granted via IAM roles.
• Network Security: Utilize VPC Service Controls to create a security perimeter around sensitive GCP resources, preventing data exfiltration.
• DDoS Protection & WAF: Implement Cloud Armor to protect against DDoS attacks and common web vulnerabilities (WAF capabilities).
• Code Scanning: Integrate static application security testing (SAST) and dynamic application security testing (DAST) into the CI/CD pipeline.
• Regular Audits: Conduct regular security audits and penetration testing.

H. Scaling Strategy:

• Horizontal Scaling: Cloud Run and Cloud Functions inherently provide horizontal scaling by automatically creating new instances to handle increased load.
• Database Scaling: Firestore scales automatically. Ensure efficient data model design to prevent query hotspots.
• CDN: Cloud CDN significantly reduces load on backend services by caching static content closer to users.
• Rate Limiting & Backoff: Implement rate limiting on backend APIs and exponential backoff/retry mechanisms for external API calls (e.g., Gemini API) to prevent overwhelming services and improve resilience.
• Regional Deployment: For a global user base, consider deploying the application across multiple GCP regions to minimize latency and improve fault tolerance.

By adhering to this blueprint, the "Robo-Advisor Onboarding" application will be built on a foundation that is robust, scalable, secure, and ready to deliver an advanced, intelligent onboarding experience in the dynamic wealth management sector.