Skip to content

PROJECT_CONTEXT.md

Latest commit

 

History

History
103 lines (73 loc) · 6.09 KB

PROJECT_CONTEXT.md

File metadata and controls

103 lines (73 loc) · 6.09 KB
Raw

Project Context

Product Summary

This project is an interactive personal stock portfolio dashboard for beginner Indonesian investors. It converts manually entered holdings and cash into accurate summaries, clean visualizations, scenario simulations, and transparent educational insights.

The product is not a trading agent, brokerage platform, price predictor, or buy/sell recommendation system.

Target User and Experience

The primary user is a beginner investor who wants to understand portfolio value, return, allocation, concentration, and cash exposure without professional trading software.

The user interface is written in English. It should feel like a premium private-banking dashboard: calm, spacious, elegant, and easy to scan. Use off-white, cream, charcoal, gray, and restrained gold rather than neon purple or bright blue-led styling.

MVP Capabilities

  • Add, edit, and remove holdings with a stock name or ticker, lot quantity, average purchase price, and current price.
  • Enter a cash balance and optionally refresh IDX current prices from Yahoo Finance.
  • Calculate invested capital, current holdings value, total portfolio value, floating profit or loss, and return percentage.
  • Visualize allocation across holdings and cash.
  • Score portfolio health from diversification, concentration, cash allocation, and performance factors.
  • Visualize equity sector allocation using a documented ticker map with an Other fallback.
  • Simulate bearish, neutral, bullish, or custom percentage changes without mutating the saved portfolio.
  • Generate deterministic insights using documented thresholds and visible trigger values.
  • Show a three-symbol educational Daily Market Watch ranked from Yahoo OHLCV momentum and volatility, never order-book claims or trade recommendations.
  • Export a client-generated PDF summary with totals, holdings, allocation, notes, and scenario output.
  • Save portfolio inputs to browser localStorage and provide a reset action.
  • Ship responsive behavior, accessible labels, deterministic tests, a polished README, and Vercel-ready configuration.

Financial Model

Version 1 uses Indonesian rupiah (IDR). One Indonesian stock lot equals 100 shares.

For each holding:

  • shares = lots * 100
  • investedCapital = shares * averageBuyPrice
  • currentValue = shares * currentPrice
  • floatingProfitLoss = currentValue - investedCapital
  • returnPercentage = investedCapital > 0 ? floatingProfitLoss / investedCapital * 100 : 0

For the portfolio:

  • totalInvestedCapital = sum(holding.investedCapital)
  • totalHoldingsValue = sum(holding.currentValue)
  • totalPortfolioValue = totalHoldingsValue + cashBalance
  • portfolioFloatingProfitLoss = totalHoldingsValue - totalInvestedCapital
  • portfolioReturnPercentage = totalInvestedCapital > 0 ? portfolioFloatingProfitLoss / totalInvestedCapital * 100 : 0
  • allocationPercentage = assetValue / totalPortfolioValue * 100, or 0 when the total value is zero

Cash is included in portfolio value and allocation, but excluded from stock investment return calculations.

Data and Application Flow

  1. Capture and validate holdings and cash in the browser.
  2. Normalize lots, prices, and cash into a typed domain model.
  3. Save only validated domain data to versioned localStorage state.
  4. Calculate summaries through framework-independent pure functions.
  5. Derive scenario values and transparent insights from calculated results.
  6. Map derived data into cards, tables, and Recharts visualizations.
  7. Keep calculations out of presentation components. Only ticker symbols may leave the device during an explicit market-price refresh.

If saved data is missing, malformed, or from an unsupported schema version, the application must fall back safely to demo or empty state without crashing.

Transparent Insight Policy

Insights are deterministic and descriptive. Every insight must show the relevant percentage or condition and must not recommend a transaction.

Initial thresholds:

  • A holding at or above 40% of total portfolio value is identified as a high concentration.
  • Cash at or above 30% of total portfolio value is identified as high cash exposure.
  • Cash below 5% is identified as low cash exposure.
  • Positive, negative, and flat portfolio returns use neutral gain, loss, and unchanged language.

These thresholds are educational defaults, not universal investment rules. Display that qualification wherever threshold-based insights appear.

Technical Architecture

  • Next.js App Router with TypeScript
  • Tailwind CSS and shadcn/ui-compatible reusable primitives
  • Recharts for allocation visualization
  • jsPDF and jsPDF-AutoTable for private, client-side report generation
  • React client state hydrated from localStorage
  • Pure domain utilities for calculations, scenarios, formatting, validation, and insight generation
  • Unit tests for domain logic and component tests for critical user flows
  • Vercel deployment through a GitHub-connected project

No authentication, database, brokerage integration, server-side portfolio storage, or LLM is part of the MVP. Server routes may fetch best-effort Yahoo Finance prices and OHLCV history for normalized .JK tickers; the UI must show source, methodology, possible delay, manual fallback where applicable, and non-advisory language.

Delivery Sequence

  1. Scaffold the application, local Git repository, tooling, design tokens, and test runner.
  2. Implement domain types, validation, calculations, scenarios, persistence, and tests.
  3. Build the dashboard input workflow and responsive information hierarchy.
  4. Add allocation chart, scenario controls, and transparent insight cards.
  5. Verify accessibility, edge cases, production build, and browser preview.
  6. Complete README and continuous integration.
  7. Push to GitHub and connect the repository to Vercel for preview and production deployments.

Definition of Done

The MVP is complete when a user can manage a portfolio, refresh without losing valid inputs, understand all calculated outputs, run scenarios, reset local data, and use the dashboard on mobile and desktop. Linting, type checking, tests, and the production build must pass, and the deployed URL must be documented.