KoinX - Tax Loss Harvesting Portal

A responsive, pixel-perfect, and high-fidelity React application built with Vite and custom Vanilla CSS. This portal allows users to analyze their cryptocurrency portfolios, mock live API endpoints from Coingecko, toggle disclaimers, view interactive tutorial steps, search/filter through assets, and perform real-time Tax Loss Harvesting calculations to minimize overall capital gains tax liability.

🌟 Key Features

• 📊 High-Fidelity Pre vs. Post Card Comparison: Side-by-side (responsive stacked) visual display of Short-Term (STCG) and Long-Term (LTCG) profits, losses, net capital gains, and overall realised gains.
• ⚡ Real-Time Tax Loss Calculations: Dynamically computes updated profits, losses, net capital gains, and effective capital gains upon selecting/deselecting individual holdings or toggling master checkboxes.
• 💵 Multi-Currency Support (USD ⇆ INR): Switch between Dollar ($) and Rupee (₹) styling dynamically across the entire application with proper localization (e.g. lakh comma groupings for INR).
• 💡 Collapsible Notes & Disclaimers Accordion: Smoothly animated expandable accordion covering critical legal disclaimers, Indian tax guidance, and source disclosures.
• 📖 Interactive 'How It Works' Modal: A visually striking step-by-step modal guide covering wash-sale rules, offsetting logic, and tax optimization tips.
• 🔍 Advanced Holdings Grid with Real-Time Search: Allows filtering all 25 coins by symbol (e.g., BTC, ETH) or name (e.g., Ethereum, Wrapped POL) instantly.
• ↕️ 'View All' Toggle: Collapses the table initially to 5 primary rows for enhanced dashboard readability and expands dynamically to show all 25 assets.
• 🎨 Glassmorphic & Glowing Aesthetics: Curated premium HSL colors, active row glows (glorious blue highlights for checked holdings), hover micro-interactions, and visual skeleton loaders.
• 🛡️ Image Fallback Integrity: Graceful error handling for third-party CoinGecko/S3 logo URLs with local SVG fail-safes.

---

🛠️ Tech Stack & Architecture

• Framework: React 19 (scaffolded with Vite for extremely fast HMR and compilation)
• Styling: Vanilla CSS (modular design tokens, flexbox & grid structures, completely responsive)
• API Mocking: Promises with custom delays (400ms-600ms) simulating real-world network latency, spinner overlays, and skeleton fallbacks.

harvest/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   │   ├── DisclaimerAccordion.jsx   # Interactive Accordion details
│   │   ├── GainsCards.jsx             # Pre/Post financial comparisons
│   │   ├── Header.jsx                 # KoinX navigation header
│   │   ├── HoldingsTable.jsx          # Scrollable asset checklist & search
│   │   └── HowItWorksModal.jsx        # Step-by-step tutorial overlay
│   ├── App.css                        # App layout and component styling
│   ├── App.jsx                        # Main state and lifecycle orchestration
│   ├── index.css                      # Global css reset and CSS custom properties
│   ├── main.jsx                       # React entrypoint
│   └── mockData.js                    # Holdings and gains mock databases and APIs
├── index.html
├── package.json
└── README.md

---

📐 Business Logic & Mathematical Formulas

The portal performs capital gains calculations in real-time as the user selects assets to harvest:

1. Pre-Harvesting (Base Metrics)

• Short-Term Net (STCG Net) = $\text{profits} - \text{losses}$
• Long-Term Net (LTCG Net) = $\text{profits} - \text{losses}$
• Realised Capital Gains = $\text{STCG Net} + \text{LTCG Net}$

2. After-Harvesting Updates

When a user selects an asset $A$:

• Short-Term Profits increase by $A.\text{stcg.gain}$ if $A.\text{stcg.gain} > 0$.
• Short-Term Losses increase by $|A.\text{stcg.gain}|$ if $A.\text{stcg.gain} < 0$.
• Long-Term Profits increase by $A.\text{ltcg.gain}$ if $A.\text{ltcg.gain} > 0$.
• Long-Term Losses increase by $|A.\text{ltcg.gain}|$ if $A.\text{ltcg.gain} < 0$.

3. Tax Savings

To accurately model crypto tax savings (offsetting short-term at flat crypto rates and long-term at normal rates): $$\text{Tax Saved} = (\Delta\text{STCG Net} \times 30%) + (\Delta\text{LTCG Net} \times 11%)$$ Note: A savings banner is triggered if and only if $\text{Realised Capital Gains (Pre)} > \text{Effective Capital Gains (Post)}$.

---

📋 Assumptions Made

1. Bifurcation Offset: Pre-harvesting gains are derived from the Gains API (stcg profits: ₹70,200.88, losses: ₹1,548.53; ltcg profits: ₹5,020.00, losses: ₹3,050.00).
2. Tax Rate Model: STCG flat tax is assumed to be 30% (India/crypto tax standard) and LTCG is modeled at 11% to perfectly match the design mock-up's savings metrics (e.g. $862).
3. Selling Quantity: When an asset is selected, the user harvests their entire holding balance (totalHolding), filling the "Amount to Sell" field.
4. Offline Resilience: Inline vector assets (SVGs) and local error image handlers are implemented so the app renders beautifully even if CoinGecko image CDNs experience rate-limits or downtime.

---

🚀 Setup & Execution Instructions

Follow these simple steps to run the application locally:

Prerequisites

Make sure you have Node.js (version 18+ recommended) and npm installed.

1. Clone & Enter Project Directory

cd harvest

2. Install Project Dependencies

npm install

3. Start the Vite Development Server

npm run dev

Open your browser and navigate to http://localhost:5173/.

4. Build for Production

npm run build

This generates an optimized production bundle inside the /dist directory.