{"id":31070124,"url":"https://github.com/aryaminus/virtual-energy-trader","last_synced_at":"2025-09-15T22:59:03.827Z","repository":{"id":314752768,"uuid":"998538062","full_name":"aryaminus/virtual-energy-trader","owner":"aryaminus","description":"A comprehensive energy trading simulation platform.","archived":false,"fork":false,"pushed_at":"2025-09-14T14:05:54.000Z","size":312,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T16:12:22.220Z","etag":null,"topics":["dashboard","edge-service","energy-monitor","llm","netlify","serverless","trading"],"latest_commit_sha":null,"homepage":"https://fabulous-llama-19a021.netlify.app/","language":"JavaScript","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/aryaminus.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-08T20:25:19.000Z","updated_at":"2025-09-14T14:07:13.000Z","dependencies_parsed_at":"2025-09-14T16:12:29.280Z","dependency_job_id":"eed77849-f22f-4e99-9fa2-725bffb8f5cb","html_url":"https://github.com/aryaminus/virtual-energy-trader","commit_stats":null,"previous_names":["aryaminus/virtual-energy-trader"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aryaminus/virtual-energy-trader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryaminus%2Fvirtual-energy-trader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryaminus%2Fvirtual-energy-trader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryaminus%2Fvirtual-energy-trader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryaminus%2Fvirtual-energy-trader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aryaminus","download_url":"https://codeload.github.com/aryaminus/virtual-energy-trader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryaminus%2Fvirtual-energy-trader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275333312,"owners_count":25446100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["dashboard","edge-service","energy-monitor","llm","netlify","serverless","trading"],"created_at":"2025-09-15T22:59:01.359Z","updated_at":"2025-09-15T22:59:03.811Z","avatar_url":"https://github.com/aryaminus.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Virtual Energy Trader\n\nA comprehensive energy trading simulation platform that allows users to experience CAISO electricity market dynamics through historical data analysis and bid placement simulation.\n\n## Production Deployment\n\n### Full-Stack Deployment on Netlify\n\nThe application is deployed as a full-stack application on Netlify using Netlify Functions to run the Express.js backend as serverless functions.\n\n**Live Demo**: [https://fabulous-llama-19a021.netlify.app](https://fabulous-llama-19a021.netlify.app)\n\n**API Health Check**: [https://fabulous-llama-19a021.netlify.app/api/health](https://fabulous-llama-19a021.netlify.app/api/health)\n\n### Environment Variables Required\n\nTo enable full functionality, configure these environment variables in your Netlify deployment:\n\n**Required:**\n\n- `GRIDSTATUS_API_KEY` - Your GridStatus.io API key for real market data\n\n**Optional (for AI Analysis features):**\n\n- `OPENAI_API_KEY` - OpenAI API key for GPT models\n- `ANTHROPIC_API_KEY` - Anthropic API key for Claude models  \n- `GOOGLE_API_KEY` - Google API key for Gemini models\n- `TOGETHER_API_KEY` - Together AI API key for open-source models\n\n### Deployment Architecture\n\n- **Frontend**: React SPA served from Netlify CDN\n- **Backend**: Express.js API running as Netlify Functions (serverless)\n- **Data**: Real-time fetching from GridStatus.io API with intelligent caching\n- **AI**: Optional LangChain integration with multiple LLM providers\n\n## Installation \u0026 Setup\n\n### Prerequisites\n\n1. **GridStatus.io API Key**: Sign up at [gridstatus.io](https://www.gridstatus.io/) for a free API key\n2. **Node.js**: Version 18 or higher\n\n### Setup Instructions\n\n```bash\n# Install dependencies\nnpm install\n\n# Configure environment variables\ncp .env.example .env\n# Edit .env and add your GridStatus.io API key:\n# GRIDSTATUS_API_KEY=your_api_key_here\n\n# Start the development server (runs both frontend and backend)\nnpm run dev\n```\n\nThe application will be available at `http://localhost:5173` with the API server running on `http://localhost:3001`.\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```env\n# GridStatus.io API Configuration\nGRIDSTATUS_API_KEY=your_api_key_here\nGRIDSTATUS_BASE_URL=https://api.gridstatus.io\n\n# Server Configuration\nPORT=3001\nNODE_ENV=development\n```\n\n## How to Use\n\n1. **Select a Date**: Choose a historical date for simulation (yesterday or earlier)\n2. **Analyze Market Data**: Review day-ahead and real-time price patterns in the Dashboard\n3. **Place Bids**: Switch to Trading Interface and place strategic bids for different hours\n4. **Run Simulation**: Execute your trading strategy and see results\n5. **Analyze Performance**: Review detailed profit/loss calculations and trading metrics\n\n## Features\n\n### Market Data Dashboard\n\n- **Historical Price Visualization**: Interactive charts displaying day-ahead and real-time electricity prices\n- **Market Statistics**: Real-time calculation of average prices, spreads, and volatility metrics\n- **Date Selection**: Choose any historical date for market analysis\n- **Price Comparison**: Side-by-side visualization of day-ahead vs real-time pricing\n\n### Trading Interface\n\n- **Bid Placement**: Place up to 10 buy/sell bids per hour across 24-hour periods\n- **Smart Execution**: Automatic bid execution based on historical day-ahead prices\n- **Profit Calculation**: Real-time profit/loss calculation using actual market outcomes\n- **Performance Analytics**: Detailed trading results with execution rates and profitability metrics\n\n### Simulation Engine\n\n- **Historical Accuracy**: Uses CAISO market data from gridstatus.io for realistic simulation\n- **Risk Management**: Calculates position offsetting in real-time markets\n- **Portfolio Analysis**: Hourly and total profit/loss tracking\n- **Market Education**: Learn energy trading concepts through hands-on experience\n\n## Trading Logic\n\n### Bid Execution Rules\n\n- **Buy Bids**: Execute when bid price ≥ day-ahead price\n- **Sell Bids**: Execute when bid price ≤ day-ahead price\n- **Settlement**: All executed positions offset at average real-time price\n\n### Profit Calculation\n\n- **Long Position**: Profit = (RT_avg - DA_price) × quantity\n- **Short Position**: Profit = (DA_price - RT_avg) × quantity\n\n## Development Notes\n\n### Comprehensive Documentation\n\nEach major directory contains detailed README files explaining the architecture and patterns:\n\n**Backend Documentation:**\n\n- `server/README.md` - Main backend architecture overview\n- `server/config/README.md` - Service initialization and configuration\n- `server/controllers/README.md` - Business logic layer patterns\n- `server/middleware/README.md` - Request processing layer\n- `server/routes/README.md` - API endpoint definitions\n- `server/services/README.md` - Core business services\n- `server/utils/README.md` - Helper functions and utilities\n\n**Frontend Documentation:**\n\n- `src/README.md` - Frontend architecture overview\n- `src/components/README.md` - Component organization and patterns\n- `src/contexts/README.md` - Global state management\n- `src/hooks/README.md` - Custom React hooks\n- `src/lib/README.md` - Utility libraries and API client\n- `src/pages/README.md` - Top-level page components\n\n**Component Subdirectories:**\n\n- `src/components/analysis/README.md` - AI analysis components\n- `src/components/dashboard/README.md` - Market data components\n- `src/components/trading/README.md` - Trading interface components\n- `src/components/common/README.md` - Shared components\n- `src/components/layout/README.md` - Layout components\n- `src/components/ui/README.md` - Base UI primitives\n\n### API Integration\n\n- Uses the official GridStatus.io API for real historical market data\n- Implements intelligent caching to respect rate limits\n- Graceful error handling when data is unavailable\n\n### Performance Optimization\n\n- Data caching reduces API calls and improves response times\n- Efficient state management in React components\n- Optimized chart rendering for large datasets\n\n### Error Handling\n\n- Comprehensive error handling for API failures\n- User-friendly error messages and retry options\n- Logging for debugging and monitoring\n\n## Built for Bolt Hackathon 2025\n\nThis project demonstrates modern web development practices while providing educational value in energy markets. The application showcases:\n\n- Full-stack development with React and Node.js\n- Real-time data visualization\n- Complex business logic implementation\n- Professional UI/UX design\n- Educational technology applications\n- Integration with real-world energy market APIs\n\n**⚡ Built on Bolt** - Showcasing the power of modern web development for energy market education.\n\n## Educational Value\n\nThis simulator provides hands-on experience with:\n\n- Energy market fundamentals\n- Price volatility and risk management\n- Arbitrage opportunities between day-ahead and real-time markets\n- Portfolio optimization strategies\n- Market timing and bid placement strategies\n\n## License\n\nThis project is developed for educational purposes and the Bolt Hackathon 2025.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faryaminus%2Fvirtual-energy-trader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faryaminus%2Fvirtual-energy-trader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faryaminus%2Fvirtual-energy-trader/lists"}