React Component

Never mix the two for the same data type. Dashboard = Recharts. Stock detail price history = lightweight-charts.

TanStack Query v5 Hook Pattern

Every data hook must follow this exact structure — no useEffect + useState for server data:

import { useQuery } from '@tanstack/react-query';
import { stockApi } from '../services/api';

export function useStockSummary(ticker: string) {
  return useQuery({
    queryKey: ['stock', ticker, 'summary'],   // always an array, most specific last
    queryFn: () => stockApi.getSummary(ticker),
    staleTime: 4 * 60 * 1000,                // see staleTime table below
    refetchInterval: 5 * 60 * 1000,          // omit for slow-changing data
    enabled: !!ticker,                        // guard against empty params
    retry: 2,
  });
}

staleTime Reference (must match backend TTL tiers)

Component Guard Pattern

Always guard loading and error at the TOP of the component body, before any rendering or hooks that depend on data:

export function MyComponent({ ticker }: { ticker: string }) {
  const { data, isLoading, error } = useStockSummary(ticker);

  if (isLoading) return <LoadingSpinner />;
  if (error || !data) return <p className="text-red-400 text-sm">Failed to load data.</p>;

  // safe to use data here
  return <div>...</div>;
}

Shared Components — Use These, Don't Reinvent

TypeScript Rules

• All interfaces live in frontend/src/types/index.ts. Never define inline interface or type inside a component file.
• All API return types are already imported in frontend/src/services/api.ts — import from there, not re-declared.
• When adding a new endpoint, add the interface to types/index.ts first, then use it in the hook and api service.

Tailwind Conventions Observed in This Codebase

• Dark background: bg-gray-900, bg-gray-800, bg-gray-950
• Card surface: bg-gray-800 rounded-xl p-4
• Positive change: text-green-400
• Negative change: text-red-400
• Neutral/label: text-gray-400 text-sm
• Primary value: text-white font-semibold

File Placement