Skip to content

SETUP.md

Latest commit

 

History

History
408 lines (312 loc) · 8.95 KB

SETUP.md

File metadata and controls

408 lines (312 loc) · 8.95 KB
Raw

🚀 SETUP GUIDE - FinGuard

Complete installation and deployment guide for judges and developers.

📋 Prerequisites

  • Node.js 18+ (Download)
  • npm 9+ (comes with Node.js)
  • Git (optional, for version control)

Check your versions:

node --version    # Should be 18.0.0 or higher
npm --version     # Should be 9.0.0 or higher

⚡ Quick Start (5 minutes)

1. Install Dependencies

# Install root dependencies
npm install

# Install all workspace dependencies (frontend + backend)
npm run install:all

2. Start Development Servers

# Start both frontend and backend concurrently
npm run dev

This will start:

3. Open in Browser

Navigate to http://localhost:5173 and you'll see the FinGuard dashboard!

📦 Manual Installation (if needed)

Frontend Only

cd frontend
npm install
npm run dev

Frontend runs on: http://localhost:5173

Backend Only

cd backend
npm install
npm run dev

Backend runs on: http://localhost:3000

🏗️ Build for Production

Build Frontend

npm run build

Output will be in frontend/dist/

Serve Production Build

cd frontend
npm run preview

🧪 Testing the Application

1. Dashboard (Screen 1)

  • Open http://localhost:5173
  • Check:
    • ✓ Total net worth displayed
    • ✓ Risk meter showing score
    • ✓ Asset allocation donut chart
    • ✓ Sector allocation bars
    • ✓ Portfolio alerts

2. Crash Simulator (Screen 3)

  • Click "Crash Simulator" tab
  • Select a scenario (e.g., "2008-Style Financial Crisis")
  • Click "Simulate Market Crash"
  • Check:
    • ✓ Red overlay appears
    • ✓ Portfolio value drops
    • ✓ Drawdown percentage shown
    • ✓ Hardest hit assets displayed

3. Auto-Rebalancing (Screen 4)

  • Click "Auto-Rebalance" tab
  • Select risk profile (Conservative/Moderate/Aggressive)
  • Adjust rebalance intensity slider
  • Click "Auto-Rebalance Portfolio"
  • Check:
    • ✓ Before/after comparison
    • ✓ Risk score improvement
    • ✓ Volatility reduction
    • ✓ Summary metrics

4. Action Plan (Screen 5)

  • Click "Action Plan" tab
  • Check:
    • ✓ Phased execution plan (3 phases)
    • ✓ Buy/sell recommendations
    • ✓ Reasons for each action
    • ✓ Priority badges

🎯 Demo Flow for Judges

Scenario 1: High-Risk Portfolio Analysis

  1. Start at Dashboard

    • Point out: Red risk score (70+)
    • Show: Concentrated holdings
    • Highlight: Portfolio alerts

  2. Simulate Market Crash

    • Navigate to Crash Simulator
    • Select "2008-Style Financial Crisis"
    • Click simulate
    • Show: -35% to -45% drawdown
    • Emphasize: Educational value

  3. Fix the Portfolio

    • Navigate to Rebalancing
    • Select "Moderate" risk profile
    • Set intensity to 40%
    • Click rebalance
    • Show: Risk score drops from 70 → 45
    • Show: Volatility reduces by 30%

  4. Review Action Plan

    • Navigate to Action Plan
    • Walk through Phase 1 recommendations
    • Explain: Why each buy/sell makes sense
    • Highlight: Clear explanations, not black box

Scenario 2: Crash Comparison

  1. Go to Crash Simulator
  2. Note current portfolio value
  3. Simulate crash → Show -40% drop
  4. Reset simulation
  5. Go to Rebalancing → Rebalance portfolio
  6. Go back to Crash Simulator
  7. Simulate same crash on rebalanced portfolio → Show only -25% drop
  8. Key message: Diversification reduced crash impact by 15%!

📁 Project Structure

DU Hacks/
├── frontend/                 # React + Vite app
│   ├── src/
│   │   ├── components/       # Reusable UI components
│   │   │   ├── ui/          # Basic components (Card, Button, etc.)
│   │   │   ├── RiskMeter.jsx
│   │   │   ├── AssetAllocationChart.jsx
│   │   │   └── SectorAllocationChart.jsx
│   │   ├── lib/             # Core business logic
│   │   │   ├── portfolioNormalizer.js   # Data normalization
│   │   │   ├── riskEngine.js            # Risk calculations
│   │   │   ├── crashSimulator.js        # Market crash logic
│   │   │   ├── rebalancer.js            # Rebalancing algorithm
│   │   │   └── utils.js                 # Helper functions
│   │   ├── pages/           # Main screens
│   │   │   ├── Dashboard.jsx
│   │   │   ├── CrashSimulator.jsx
│   │   │   ├── Rebalancing.jsx
│   │   │   └── ActionPlan.jsx
│   │   ├── data/
│   │   │   └── mockData.js  # Demo portfolio data
│   │   ├── App.jsx          # Main app component
│   │   ├── main.jsx         # Entry point
│   │   └── index.css        # Global styles
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
│
├── backend/                  # Express API (minimal)
│   ├── server.js            # Backend server
│   ├── package.json
│   └── README.md
│
├── package.json             # Root workspace config
├── README.md                # Project overview
└── SETUP.md                 # This file

🔧 Troubleshooting

Port Already in Use

Frontend (5173):

# Kill process on port 5173 (Windows)
netstat -ano | findstr :5173
taskkill /PID <PID> /F

# Then restart
npm run dev:frontend

Backend (3000):

# Kill process on port 3000 (Windows)
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# Then restart
npm run dev:backend

Module Not Found

# Clean install
rm -rf node_modules frontend/node_modules backend/node_modules
rm package-lock.json frontend/package-lock.json backend/package-lock.json
npm run install:all

Vite Build Errors

cd frontend
rm -rf node_modules dist
npm install
npm run build

🎨 Customization

Change Mock Portfolio

Edit frontend/src/data/mockData.js:

export const MOCK_PORTFOLIO_CONCENTRATED = [
  {
    symbol: 'YOUR_STOCK',
    name: 'Your Company Name',
    type: 'EQUITY',
    value: 100000,
    quantity: 40,
    currentPrice: 2500,
  },
  // Add more assets...
];

Adjust Risk Thresholds

Edit frontend/src/lib/rebalancer.js:

export const RISK_PROFILES = {
  CONSERVATIVE: {
    maxStockWeight: 0.15,    // Change to 0.10 for 10% max
    maxSectorWeight: 0.25,   // Change as needed
    // ...
  },
};

Modify Crash Scenarios

Edit frontend/src/lib/crashSimulator.js:

FINANCIAL_CRISIS: {
  name: '2008-Style Financial Crisis',
  impacts: {
    [ASSET_TYPES.EQUITY]: { min: -0.45, max: -0.35 },  // Adjust impact
    // ...
  },
}

📊 Tech Stack Reference

Layer Technology Purpose
Frontend Framework React 18 UI components & state management
Build Tool Vite Fast development & optimized builds
Styling Tailwind CSS Utility-first styling
Charts Recharts Data visualization
Icons Lucide React Beautiful icons
Backend Express.js API server (minimal)
Language JavaScript (ES6+) Modern JavaScript features

🎓 For Judges: Key Technical Points

1. Mathematical Rigor

  • HHI calculation: Σ(wi²) for concentration
  • Portfolio volatility: σp = √(wᵀΣw)
  • Risk score: Weighted composite (45% vol + 35% conc + 20% top)

2. Privacy-First Architecture

  • Zero server-side storage: All calculations client-side
  • No API calls needed: Fully functional offline
  • Data never leaves browser: True privacy

3. Educational Focus

  • Every metric is explained
  • Clear reasons for recommendations
  • Transparent algorithms (no black box)
  • Historical crash data (2008, 2020)

4. Production-Ready Code

  • Modular architecture
  • Reusable components
  • Type-safe utilities
  • Error handling
  • Responsive design

🚀 Deployment Options

Option 1: Vercel (Recommended for Frontend)

cd frontend
npm install -g vercel
vercel

Option 2: Netlify

cd frontend
npm run build
# Upload dist/ folder to Netlify

Option 3: Docker (Full Stack)

# Coming soon - Dockerfile included in production version

📞 Support

For issues during judging:

  1. Check troubleshooting section above
  2. Ensure Node.js 18+ is installed
  3. Try clean reinstall: npm run install:all

Remember: This is a client-side app. Backend is optional!

✅ Verification Checklist

Before presenting:

  • Frontend runs on port 5173
  • Dashboard loads successfully
  • Risk meter displays correctly
  • Charts render properly
  • Crash simulation works
  • Rebalancing shows before/after
  • Action plan displays recommendations
  • No console errors
  • Responsive on different screen sizes

Built with ❤️ for DU Hacks 2026

🛡️ FinGuard - "We don't predict markets. We prepare portfolios to survive them."