{"id":30182823,"url":"https://github.com/thehackerfrommars/wealth_pulse_dashboard","last_synced_at":"2026-04-04T22:31:43.172Z","repository":{"id":308920645,"uuid":"1034576945","full_name":"TheHackerFromMars/Wealth_Pulse_Dashboard","owner":"TheHackerFromMars","description":"Stock Portfolio Analytics Dashboard","archived":false,"fork":false,"pushed_at":"2025-08-08T16:11:41.000Z","size":222,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-08T18:25:00.173Z","etag":null,"topics":["fastapi","javascript","portfolio-analytics","python","react","stock-market","typescript"],"latest_commit_sha":null,"homepage":"https://wealth-pulse-dash-tau.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheHackerFromMars.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-08T16:04:48.000Z","updated_at":"2025-08-08T16:11:45.000Z","dependencies_parsed_at":"2025-08-08T18:25:02.396Z","dependency_job_id":"25eec707-f42c-4464-a174-04d52683d973","html_url":"https://github.com/TheHackerFromMars/Wealth_Pulse_Dashboard","commit_stats":null,"previous_names":["thehackerfrommars/wealth_pulse_dashboard"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/TheHackerFromMars/Wealth_Pulse_Dashboard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheHackerFromMars%2FWealth_Pulse_Dashboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheHackerFromMars%2FWealth_Pulse_Dashboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheHackerFromMars%2FWealth_Pulse_Dashboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheHackerFromMars%2FWealth_Pulse_Dashboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheHackerFromMars","download_url":"https://codeload.github.com/TheHackerFromMars/Wealth_Pulse_Dashboard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheHackerFromMars%2FWealth_Pulse_Dashboard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31416770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","javascript","portfolio-analytics","python","react","stock-market","typescript"],"created_at":"2025-08-12T10:17:13.893Z","updated_at":"2026-04-04T22:31:43.128Z","avatar_url":"https://github.com/TheHackerFromMars.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Portfolio Analytics Dashboard\n\n\u003cimg width=\"1898\" height=\"950\" alt=\"image\" src=\"https://github.com/user-attachments/assets/124a3809-cccd-47e1-b005-a6303fd94f88\" /\u003e\n\u003cimg width=\"1901\" height=\"949\" alt=\"image\" src=\"https://github.com/user-attachments/assets/195b60db-3df2-44a2-b6e2-f9763724b58b\" /\u003e\n\n\n\nA full-stack portfolio analytics application with a **React TypeScript frontend** and **Python FastAPI backend**.\n\n## 🚀 Features\n\n### Frontend (React + TypeScript)\n- **Portfolio Overview Cards** - Total value, gains/losses, holdings count, risk level\n- **Asset Allocation Charts** - Interactive pie charts for sector and market cap distribution  \n- **Holdings Table** - Sortable, searchable table with all portfolio positions\n- **Performance Chart** - Timeline comparison vs Nifty 50 and Gold benchmarks\n- **Top Performers** - Best and worst performing stocks with insights\n\n### Backend (Python FastAPI)\n- **4 REST API Endpoints** matching the assignment requirements exactly\n- **Excel Data Integration** - Reads portfolio data from provided Excel file\n- **Real-time Calculations** - Gain/loss, percentages, allocations computed on-the-fly\n- **Type Safety** - Pydantic models for request/response validation\n- **Auto-generated API Docs** - Interactive Swagger UI at `/docs`\n\n## 📊 API Endpoints\n\n| Endpoint | Description | Returns |\n|----------|-------------|---------|\n| `GET /api/portfolio/holdings` | Complete holdings with calculations | List of enriched stock positions |\n| `GET /api/portfolio/allocation` | Sector \u0026 market cap distribution | Percentage breakdowns with counts |\n| `GET /api/portfolio/performance` | Historical timeline vs benchmarks | Performance data with returns |\n| `GET /api/portfolio/summary` | Key portfolio metrics | Overview with top/worst performers |\n\n## 🛠️ Technology Stack\n\n### Frontend\n- **React 18** with **TypeScript** for type safety\n- **Vite** for fast development and building\n- **Shadcn/ui** + **Tailwind CSS** for modern, responsive design\n- **Recharts** for interactive data visualizations\n- **TanStack Query** for efficient API state management\n- **React Router** for navigation\n\n### Backend  \n- **Python 3.12** with **FastAPI** for high-performance APIs\n- **JSON-based data pipeline** for optimal performance (Excel → JSON → API)\n- **Automatic data import** from Excel with timestamped backups\n- **In-memory caching** for sub-millisecond API responses\n- **Pydantic** for data validation and serialization\n- **Uvicorn** as ASGI server with auto-reload\n\n## 🚦 Quick Start\n\n### Prerequisites\n- **Node.js 18+** (for frontend)\n- **Python 3.12+** (for backend)\n\n### 1. Setup \u0026 Run Backend (Python FastAPI)\n\n```bash\n# Navigate to backend directory\ncd backend\n\n# Install Python dependencies (virtual environment already configured)\npip install -r requirements.txt\n\n# Import Excel data to JSON (first time or after Excel updates)\npython import_data.py\n\n# Start the API server\npython run.py\n```\n\nBackend will run on: **http://localhost:8000**\n- API Documentation: **http://localhost:8000/docs**\n- Alternative docs: **http://localhost:8000/redoc**\n\n### 2. Setup \u0026 Run Frontend (React)\n\n```bash\n# Navigate to frontend directory\ncd frontend\n\n# Install frontend dependencies\nnpm install\n\n# Start the development server  \nnpm run dev\n```\n\nFrontend will run on: **http://localhost:8080**\n\n### 3. Test Integration\n\n```bash\n# Run the integration test script\nchmod +x test-integration.sh\n./test-integration.sh\n```\n\n### 4. Update Data (When Excel File Changes)\n\n```bash\n# Complete data update workflow\ncd backend\n./update_data.sh\n```\n\nThis will:\n1. Import latest Excel data to JSON\n2. Reload API server cache\n3. Validate all endpoints\n\n## 📁 Project Structure\n\n```\nwealth-pulse-dash/\n├── frontend/                    # React TypeScript Frontend\n│   ├── src/\n│   │   ├── components/dashboard/    # Dashboard components\n│   │   ├── api/portfolio.ts         # API client\n│   │   ├── pages/Index.tsx          # Main dashboard page\n│   │   └── ...\n│   ├── package.json\n│   └── vite.config.ts\n├── backend/                     # Python FastAPI Backend\n│   ├── app/\n│   │   ├── main.py                  # FastAPI application\n│   │   ├── models.py                # Pydantic models\n│   │   ├── data_service.py          # JSON processing logic\n│   │   └── __init__.py\n│   ├── data/\n│   │   ├── portfolio_data.json      # Generated JSON cache\n│   │   ├── Sample Portfolio Dataset for Assignment.xlsx\n│   │   └── backups/                 # Timestamped backups\n│   ├── requirements.txt\n│   ├── run.py                       # Server startup\n│   └── README.md\n└── start-dev.sh                     # Development startup script\n```\n\n## 📈 Data Source\n\nThe application reads portfolio data from **`Sample Portfolio Dataset for Assignment.xlsx`** with the following sheets:\n\n- **Holdings** - Stock positions with quantities, prices, sectors\n- **Historical_Performance** - Timeline data for performance charts  \n- **Summary** - Portfolio overview metrics\n- **Sector_Allocation** - Sector distribution data\n- **Market_Cap** - Market cap allocation data\n- **Top_Performers** - Best/worst performing stocks\n\n## 🔧 Development\n\n### Frontend Development\n```bash\ncd frontend\nnpm run dev     # Start with hot reload\nnpm run build   # Production build\nnpm run preview # Preview production build\n```\n\n### Backend Development\n```bash\npython run.py   # Start with auto-reload\n# API will automatically restart when code changes\n```\n\n### Adding New Features\n1. **Backend**: Add new endpoints in `backend/app/main.py`, models in `backend/app/models.py`\n2. **Frontend**: Add API calls in `frontend/src/api/portfolio.ts`, components in `frontend/src/components/`\n\n## 🌟 Key Features Implemented\n\n### ✅ Backend Requirements Met\n- [x] All 4 required API endpoints implemented exactly as specified\n- [x] Data calculations (gain/loss, percentages) working correctly\n- [x] Error handling with proper HTTP status codes\n- [x] CORS enabled for frontend integration\n- [x] Clean, documented code structure\n\n### ✅ Frontend Requirements Met  \n- [x] Portfolio overview cards with color-coded gains/losses\n- [x] Interactive asset allocation visualizations\n- [x] Sortable, searchable holdings table\n- [x] Performance comparison charts with hover effects\n- [x] Top performers section with insights\n- [x] Responsive design for mobile/desktop\n- [x] Loading states and error handling\n\n## 🚀 Deployment Ready\n\nThe application is architected for easy deployment:\n\n- **Backend**: Can be deployed to any platform supporting Python (Heroku, Railway, DigitalOcean, etc.)\n- **Frontend**: Can be deployed to static hosting (Vercel, Netlify, GitHub Pages, etc.)\n- **Environment Variables**: Backend URL configurable via frontend environment\n\n## 🧪 Testing\n\n- Integration test script validates all API endpoints\n- Frontend automatically handles API failures gracefully\n- Type safety ensures data consistency between frontend/backend\n\n---\n\n**Portfolio Analytics Dashboard** - Built with modern web technologies for optimal performance and user experience.\n- Edit files directly within the Codespace and commit and push your changes once you're done.\n\n## What technologies are used for this project?\n\nThis project is built with:\n\n- Vite\n- TypeScript\n- React\n- shadcn-ui\n- Tailwind CSS\n  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthehackerfrommars%2Fwealth_pulse_dashboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthehackerfrommars%2Fwealth_pulse_dashboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthehackerfrommars%2Fwealth_pulse_dashboard/lists"}