{"id":50717013,"url":"https://github.com/msmygit/ibmcloud_usage_cost","last_synced_at":"2026-06-09T19:02:06.604Z","repository":{"id":355951454,"uuid":"1229972311","full_name":"msmygit/ibmcloud_usage_cost","owner":"msmygit","description":"IBM cloud usage cost by creator and by resource groups","archived":false,"fork":false,"pushed_at":"2026-06-02T02:44:14.000Z","size":380,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T04:21:08.919Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/msmygit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2026-05-05T14:55:39.000Z","updated_at":"2026-06-02T02:44:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/msmygit/ibmcloud_usage_cost","commit_stats":null,"previous_names":["msmygit/ibmcloud_usage_cost"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/msmygit/ibmcloud_usage_cost","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msmygit%2Fibmcloud_usage_cost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msmygit%2Fibmcloud_usage_cost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msmygit%2Fibmcloud_usage_cost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msmygit%2Fibmcloud_usage_cost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msmygit","download_url":"https://codeload.github.com/msmygit/ibmcloud_usage_cost/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msmygit%2Fibmcloud_usage_cost/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34121022,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"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":[],"created_at":"2026-06-09T19:02:05.310Z","updated_at":"2026-06-09T19:02:06.599Z","avatar_url":"https://github.com/msmygit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IBM Cloud Cost Analytics Application\n\nA full-stack application for analyzing and visualizing IBM Cloud costs with real-time data, interactive dashboards, and comprehensive reporting capabilities.\n\n## Features\n\n### Core Functionality\n\n- **Account Management**: Automatically fetch and manage multiple IBM Cloud accounts\n- **Dashboard**: Real-time cost overview with key metrics (Total Cost, Resource Groups, Active Users)\n- **User Spending Analysis**: Detailed breakdown of costs by user with interactive charts\n- **Resource Group Costs**: Visualize spending across different resource groups\n- **Date Range Selection**: Flexible date range picker with presets (last 7/30 days, last month, 3/6/12 months, custom)\n- **Export Capabilities**: Download charts as images (PNG/JPEG) and data as CSV/Excel/JSON\n- **Report Generation**: Create comprehensive cost reports with WebSocket progress tracking\n\n### Technical Highlights\n\n- **IBM Cloud API Integration**: Strict conformance to official IBM Cloud APIs\n  - [Resource Controller API](https://cloud.ibm.com/apidocs/resource-controller/resource-controller#list-resource-instances)\n  - [Usage Reports API](https://cloud.ibm.com/apidocs/metering-reporting#get-resource-group-usage)\n- **Real-time Updates**: WebSocket support for live progress tracking\n- **Caching**: Multi-layer caching (memory + file) for optimal performance\n- **Type Safety**: Full TypeScript implementation across frontend and backend\n- **Error Handling**: Comprehensive error handling with user-friendly messages\n\n## Prerequisites\n\n- **Node.js**: v18 or higher\n- **pnpm**: v8 or higher (recommended) or npm\n- **IBM Cloud Account**: With appropriate permissions\n- **IBM Cloud API Key**: Required for authentication\n\n## Quick Start\n\n### 1. Clone the Repository\n\n```bash\ngit clone \u003crepository-url\u003e\ncd ibmcloud_usage_cost\n```\n\n### 2. Install Dependencies\n\n```bash\npnpm install\n```\n\n### 3. Configure Backend\n\nCreate a `.env` file in the `backend` directory:\n\n```bash\ncd backend\ncp .env.example .env\n```\n\nEdit `backend/.env` and add your IBM Cloud credentials:\n\n```env\n# REQUIRED: IBM Cloud API Key\nIBM_CLOUD_API_KEY=your_ibm_cloud_api_key_here\n\n# OPTIONAL: Default account ID (pre-selects this account in the UI)\nIBM_CLOUD_ACCOUNT_ID=your_account_id_here\n\n# Server Configuration\nNODE_ENV=development\nPORT=3000\nHOST=localhost\n\n# CORS Configuration\nCORS_ORIGIN=http://localhost:5173\n```\n\n#### Getting Your IBM Cloud API Key\n\n1. Go to [IBM Cloud IAM API Keys](https://cloud.ibm.com/iam/apikeys)\n2. Click \"Create an IBM Cloud API key\"\n3. Give it a descriptive name (e.g., \"Cost Analytics App\")\n4. Copy the API key immediately (you won't be able to see it again)\n5. Paste it into your `.env` file\n\n### 4. Configure Frontend (Optional)\n\nCreate a `.env` file in the `frontend` directory if you need to customize the API URL:\n\n```bash\ncd frontend\ncp .env.example .env\n```\n\nEdit `frontend/.env`:\n\n```env\nVITE_API_BASE_URL=http://localhost:3000\n```\n\n### 5. Start the Application\n\n#### Development Mode\n\nStart both backend and frontend in development mode:\n\n```bash\n# From the root directory\npnpm dev\n```\n\nOr start them separately:\n\n```bash\n# Terminal 1 - Backend\ncd backend\npnpm dev\n\n# Terminal 2 - Frontend\ncd frontend\npnpm dev\n```\n\nThe application will be available at:\n- **Frontend**: http://localhost:5173\n- **Backend API**: http://localhost:3000\n\n#### Production Mode\n\n```bash\n# Build both frontend and backend\npnpm build\n\n# Start production server\npnpm start\n```\n\n## Application Structure\n\n```\nibmcloud_usage_cost/\n├── backend/                 # Node.js/Express backend\n│   ├── src/\n│   │   ├── api/            # API routes and controllers\n│   │   ├── clients/        # IBM Cloud API clients\n│   │   ├── config/         # Configuration management\n│   │   ├── services/       # Business logic\n│   │   ├── types/          # TypeScript type definitions\n│   │   └── utils/          # Utility functions\n│   └── tests/              # Backend tests\n├── frontend/               # React/TypeScript frontend\n│   ├── src/\n│   │   ├── components/     # React components\n│   │   ├── contexts/       # React contexts\n│   │   ├── hooks/          # Custom React hooks\n│   │   ├── pages/          # Page components\n│   │   ├── services/       # API and export services\n│   │   ├── types/          # TypeScript type definitions\n│   │   └── utils/          # Utility functions\n│   └── public/             # Static assets\n└── docs/                   # Documentation\n```\n\n## Usage Guide\n\n### Dashboard\n\nThe landing page displays:\n- **Total Cost**: Aggregate cost for the selected date range\n- **Total Resource Groups**: Number of resource groups in the account\n- **Active Users**: Count of unique users who created resources\n- **Cost Trend Chart**: Monthly cost progression\n- **Top Services Chart**: Distribution of costs by service\n\n### User Spending Page\n\nAnalyze costs by individual users:\n- View total spending per user\n- See resource and service counts\n- Filter users by email\n- Export data as CSV, Excel, or JSON\n- Download charts as images\n\n### Resource Group Costs Page\n\nVisualize spending across resource groups:\n- Total cost per resource group\n- Resource and service counts\n- Monthly cost trends\n- Top 5 resource groups by cost\n- Export capabilities for charts and data\n\n### Date Range Selection\n\nAll pages support flexible date range selection:\n- **Presets**: Last 7 days (default), 30 days, last month, 3/6/12 months\n- **Custom Range**: Select any start and end date\n- Date range applies globally across all views\n\n### Account Selection\n\n- Accounts are automatically discovered using your API key\n- Select different accounts from the dropdown in the header\n- If `IBM_CLOUD_ACCOUNT_ID` is set in `.env`, that account is pre-selected\n- Manual account entry is available if auto-discovery fails\n\n## API Endpoints\n\n### Accounts\n- `GET /api/accounts` - List accessible accounts\n- `GET /api/accounts/test` - Test IBM Cloud connection\n\n### Resources\n- `GET /api/resources` - Get resource instances\n\n### Usage\n- `GET /api/usage` - Get usage data for date range\n\n### Reports\n- `POST /api/reports/user-spending` - Generate user spending report\n- `POST /api/reports/team-spending` - Generate team spending report\n- `GET /api/reports/:id` - Get report by ID\n- `DELETE /api/reports/:id` - Cancel report generation\n\n### Cache\n- `GET /api/cache/stats` - Get cache statistics\n- `DELETE /api/cache` - Clear cache\n- `POST /api/cache/warm` - Warm cache for account\n\n## Environment Variables\n\n### Backend\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `IBM_CLOUD_API_KEY` | **Yes** | - | IBM Cloud API key for authentication |\n| `IBM_CLOUD_ACCOUNT_ID` | No | - | Default account ID to pre-select |\n| `NODE_ENV` | No | `development` | Environment mode |\n| `PORT` | No | `3000` | Server port |\n| `HOST` | No | `localhost` | Server host |\n| `CORS_ORIGIN` | No | `http://localhost:5173` | Allowed CORS origins |\n| `CACHE_ENABLED` | No | `true` | Enable caching |\n| `CACHE_TTL_RESOURCES` | No | `3600` | Resource cache TTL (seconds) |\n| `CACHE_TTL_USAGE` | No | `1800` | Usage cache TTL (seconds) |\n| `LOG_LEVEL` | No | `info` | Logging level |\n| `WEBSOCKET_ENABLED` | No | `true` | Enable WebSocket support |\n\n### Frontend\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `VITE_API_BASE_URL` | No | `http://localhost:3000` | Backend API URL |\n\n## Error Handling\n\n### Missing API Key\n\nIf `IBM_CLOUD_API_KEY` is not configured, the application will display a clear error screen with:\n- Explanation of the issue\n- Step-by-step instructions to obtain an API key\n- Configuration guidance\n- Link to IBM Cloud IAM console\n\n### API Errors\n\nThe application handles various API errors gracefully:\n- Network errors\n- Authentication failures\n- Rate limiting\n- Invalid account IDs\n- Missing permissions\n\n## Performance Optimization\n\n### Caching Strategy\n\nThe application implements a multi-layer caching system:\n1. **Memory Cache**: Fast in-memory storage for frequently accessed data\n2. **File Cache**: Persistent storage for larger datasets\n3. **Configurable TTLs**: Different cache durations for different data types\n\n### Rate Limiting\n\nBuilt-in rate limiting protects against API abuse:\n- Default: 100 requests per 15 minutes\n- Configurable via environment variables\n\n## Development\n\n### Running Tests\n\n```bash\n# Backend tests\ncd backend\npnpm test\n\n# Frontend tests\ncd frontend\npnpm test\n```\n\n### Linting\n\n```bash\n# Lint all code\npnpm lint\n\n# Fix linting issues\npnpm lint:fix\n```\n\n### Type Checking\n\n```bash\n# Check TypeScript types\npnpm type-check\n```\n\n## Troubleshooting\n\n### Backend won't start\n\n1. Verify `IBM_CLOUD_API_KEY` is set in `backend/.env`\n2. Check that the API key is valid (at least 40 characters)\n3. Ensure Node.js version is 18 or higher\n4. Check port 3000 is not already in use\n\n### Frontend can't connect to backend\n\n1. Verify backend is running on port 3000\n2. Check `VITE_API_BASE_URL` in `frontend/.env`\n3. Ensure CORS is properly configured in `backend/.env`\n\n### No accounts showing up\n\n1. Verify your API key has proper permissions\n2. Check that you have access to at least one IBM Cloud account\n3. Try setting `IBM_CLOUD_ACCOUNT_ID` manually in `backend/.env`\n\n### Charts not exporting\n\n1. Ensure you have a modern browser (Chrome, Firefox, Safari, Edge)\n2. Check browser console for errors\n3. Try a different export format\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor issues, questions, or contributions, please open an issue on the GitHub repository.\n\n## Acknowledgments\n\n- Built with [React](https://react.dev/), [TypeScript](https://www.typescriptlang.org/), and [Express](https://expressjs.com/)\n- Charts powered by [Recharts](https://recharts.org/)\n- UI components styled with [Tailwind CSS](https://tailwindcss.com/)\n- IBM Cloud integration via official SDKs","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsmygit%2Fibmcloud_usage_cost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsmygit%2Fibmcloud_usage_cost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsmygit%2Fibmcloud_usage_cost/lists"}