PROJECT OVERVIEW:
The application is a "Code Cost Optimizer" SaaS designed for developers and development teams who heavily utilize AI coding assistants and Large Language Models (LLMs). The core problem it solves is the escalating and often unpredictable cost associated with API-based AI services like Claude, OpenAI, and others. Users often face limitations, fluctuating prices, and difficulty managing multiple API keys and billing cycles. The value proposition is to provide a centralized platform that offers intelligent cost management, flexible API routing, and transparent usage tracking, empowering developers to significantly reduce their AI spending while maintaining or improving their coding efficiency. It aims to be the single pane of glass for all AI coding-related expenses.
TECH STACK:
- Frontend: React.js (with Vite for fast development)
- Styling: Tailwind CSS (for rapid and utility-first UI development)
- State Management: Zustand (lightweight and efficient for global state)
- Routing: React Router DOM
- API Client: Axios (for making HTTP requests)
- Icons: lucide-react
- Form Handling: React Hook Form
- Validation: Zod
- Animation: Framer Motion
- Local Storage: Simple use for session tokens and user preferences.
- Backend (Conceptual for future expansion, not MVP): Node.js with Express.js or Next.js API Routes.
CORE FEATURES:
1. **API Key Management**:
* User Flow:
1. User navigates to the 'API Keys' section.
2. Clicks 'Add New API Key'.
3. Selects the provider (e.g., OpenAI, Anthropic, OpenRouter, Google AI).
4. Enters a descriptive name for the key (e.g., 'Claude Pro Key').
5. Pastes their actual API key into a secure input field.
6. Optionally, sets a monthly budget limit specifically for this key.
7. Clicks 'Save'. The key is stored securely (encrypted client-side or in a secure backend).
* Details: Input fields for provider, key name, API key (masked), and optional budget. Visual indicators for active/inactive keys.
2. **Intelligent Model Router/Selector**:
* User Flow:
1. User accesses the 'Routing Rules' or 'AI Assistant Settings'.
2. Defines a default provider/model for general coding tasks.
3. Creates custom rules based on task type (e.g., 'Code Generation', 'Debugging', 'Documentation') or complexity.
4. For each rule, selects preferred models/providers and sets priorities (e.g., 'Try OpenRouter first for GPT-3.5, then fall back to Claude Instant').
5. The system intercepts requests made through its integration (e.g., VS Code extension) and directs them based on these rules and real-time cost/availability data.
* Details: Rule creation interface with dropdowns for task type, provider, model. Option to set cost thresholds and fallback strategies. Ability to enable/disable rules.
3. **Usage & Cost Tracking Dashboard**:
* User Flow:
1. User lands on the main dashboard.
2. Sees an overview of total monthly AI spending.
3. Views a breakdown of spending by provider, by model, and by API key.
4. Examines usage metrics (e.g., tokens consumed, requests made) for each service.
5. Checks remaining budget against set limits (overall and per key).
6. Sees historical spending trends via charts.
* Details: Clean dashboard with cards for key metrics. Interactive charts (e.g., bar charts for provider breakdown, line charts for monthly trends). Tables for detailed data views. Real-time updates.
4. **Flexible Budget Management & Alerts**:
* User Flow:
1. User sets a global monthly budget in the 'Billing Settings'.
2. Receives notifications (in-app and optionally via email/Slack) when spending reaches predefined percentages (e.g., 50%, 80%, 100%) of the budget.
3. Can configure automatic actions, such as pausing all AI requests or switching to a cheaper model when the budget limit is hit.
4. Sets individual budgets for specific API keys.
* Details: Budget input field. Percentage-based alert triggers. Toggles for automatic actions. Clear display of budget status.
UI/UX DESIGN:
- **Layout**: Single Page Application (SPA) with a persistent sidebar navigation (Dashboard, API Keys, Routing Rules, Billing, Settings). Main content area displays the relevant section.
- **Color Palette**: Primary: A deep, professional blue (`#1A202C` - dark slate gray). Secondary: A vibrant accent color like teal (`#4FD1C5`) or a calming green (`#68D391`) for calls to action, highlights, and positive status indicators. Neutral: Shades of gray for backgrounds, borders, and text (`#F7FAFC` - light gray, `#A0AEC0` - medium gray, `#2D3748` - dark gray).
- **Typography**: A clean, modern sans-serif font like Inter or Manrope for readability. Use varying weights and sizes for hierarchy (e.g., H1 for page titles, H2 for section titles, standard text for body content).
- **Responsive Design**: Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content reflows into a single column. Use Tailwind CSS's responsive prefixes (sm:, md:, lg:) extensively. Ensure all interactive elements are easily tappable on touch devices.
- **Component Hierarchy**: A clear structure with reusable components (e.g., `Card`, `Button`, `Input`, `Table`, `Chart`, `ApiKeyForm`, `RuleEditor`).
COMPONENT BREAKDOWN:
- `App.jsx`: Main application wrapper, sets up routing.
- `Layout.jsx`: Contains the sidebar navigation and the main content outlet.
- `Sidebar.jsx`: Navigation links (Dashboard, API Keys, etc.).
- `Dashboard.jsx`: Main overview page. Renders `SpendingOverviewCard`, `ProviderBreakdownChart`, `UsageTable`.
- `SpendingOverviewCard.jsx`: Displays total monthly spend, budget remaining. Props: `totalSpend`, `budget`, `remaining`.
- `ProviderBreakdownChart.jsx`: Pie or bar chart showing spending per provider. Props: `data` (array of {provider: string, amount: number}).
- `UsageTable.jsx`: Table showing detailed usage per API key/provider. Props: `usageData` (array of objects).
- `ApiKeysPage.jsx`: Manages the API Keys section. Renders `ApiKeyList`, `ApiKeyFormModal`.
- `ApiKeyList.jsx`: Displays a list of saved API keys. Props: `apiKeys` (array). Handles delete/edit actions.
- `ApiKeyFormModal.jsx`: Modal for adding/editing API keys. Renders `ApiKeyForm`.
- `ApiKeyForm.jsx`: Form fields for API key details. Props: `onSubmit`, `initialData` (for editing).
- `RoutingRulesPage.jsx`: Manages AI routing rules. Renders `RuleList`, `RuleEditor`.
- `RuleList.jsx`: Displays existing routing rules. Props: `rules` (array). Handles enable/disable/delete.
- `RuleEditor.jsx`: Form for creating/editing a routing rule. Props: `providers`, `models`, `onSubmit`, `initialData`.
- `BillingSettings.jsx`: Page for setting global budget and alert preferences. Renders `BudgetForm`.
- `BudgetForm.jsx`: Input for global budget, alert thresholds, and automation toggles.
- `Button.jsx`: Reusable button component. Props: `children`, `onClick`, `variant`, `isLoading`.
- `Input.jsx`: Reusable input field. Props: `label`, `type`, `value`, `onChange`, `error`.
- `ChartComponent.jsx`: Wrapper for charting library (e.g., Recharts). Props: `chartType`, `data`, `options`.
DATA MODEL:
- **Global State (Zustand)**:
- `user`: { id, name, email }
- `apiKeys`: [ { id, provider, name, keyHash, budget, createdAt }, ... ]
- `routingRules`: [ { id, description, priority, conditions: { taskType }, actions: { provider, model, fallback }, enabled: boolean }, ... ]
- `billing`: { globalBudget, alertThresholds: [50, 80, 100], autoPauseEnabled: boolean }
- `usageData`: { overall: { totalSpend, requests }, perKey: [ { keyId, provider, model, spend, tokens, requests } ], perProvider: { provider1: { spend, tokens }, ... } }
- `settings`: { theme, notifications }
- **API Key Object**: `{ id: string, provider: 'openai' | 'anthropic' | 'openrouter' | 'google', name: string, key: string (stored encrypted or client-side hashed), budget: number | null, createdAt: string }`
- **Routing Rule Object**: `{ id: string, name: string, priority: number, enabled: boolean, conditions: { taskType?: string, promptKeywords?: string[] }, actions: { provider: string, model: string, fallbackStrategy: 'cheapest' | 'fastest' | 'sequential' } }`
- **Usage Data Object**: `{ date: string, provider: string, model: string, tokens_in: number, tokens_out: number, cost: number, apiKeyId: string }`
- **Mock Data Format**: Will be structured according to these objects, often arrays of these objects for lists and tables.
ANIMATIONS & INTERACTIONS:
- **Page Transitions**: Subtle fade-in/fade-out transitions between different sections using Framer Motion (`<AnimatePresence>`).
- **Button States**: Hover effects (slight scale-up or background color change). Active state feedback. Loading spinners within buttons when performing async actions (e.g., saving API key).
- **Input Fields**: Focus states with border highlighting. Error states with red borders and helper text.
- **Data Loading**: Skeleton loaders or spinners while fetching data for tables and charts.
- **Hover Effects**: Tooltips on chart data points or table rows for more information.
- **Toggles/Switches**: Smooth animations for enabling/disabling features or rules.
- **Key Input Masking**: Input for API keys should mask characters (e.g., show `••••••••••••••••••••••••` after typing).
EDGE CASES:
- **No API Keys Added**: Display a clear message and a prominent call to action to add the first API key on the API Keys page and dashboard.
- **No Routing Rules Created**: Similar to API Keys, guide the user to create their first rule.
- **API Errors**: Gracefully handle errors from the backend or API providers (e.g., invalid API key, rate limits exceeded). Display user-friendly error messages. Implement retry mechanisms where appropriate.
- **Validation**: Client-side validation for all forms (API key format, budget values, rule configurations) using Zod and React Hook Form. Server-side validation will be crucial for production.
- **Empty States**: Tables and lists should have empty state components (e.g., 'No API keys found. Add one to get started.').
- **Accessibility (a11y)**:
- Use semantic HTML elements.
- Ensure sufficient color contrast.
- Provide ARIA attributes where necessary (e.g., for custom form controls, modals).
- Ensure keyboard navigation is fully supported.
- Manage focus appropriately, especially within modals and dynamic content.
SAMPLE DATA:
1. **`apiKeys` Array**:
```json
[
{ "id": "key_abc123", "provider": "openai", "name": "GPT-4 Dev Key", "keyHash": "sk-••••••••••••••••••••••••••••••••••••••••", "budget": 50.00, "createdAt": "2023-10-26T10:00:00Z" },
{ "id": "key_def456", "provider": "anthropic", "name": "Claude 3 Opus", "keyHash": "sk-••••••••••••••••••••••••••••••••••••••••", "budget": null, "createdAt": "2023-10-27T11:30:00Z" },
{ "id": "key_ghi789", "provider": "openrouter", "name": "OpenRouter - Mixed Models", "keyHash": "sk-••••••••••••••••••••••••••••••••••••••••", "budget": 100.00, "createdAt": "2023-10-28T12:00:00Z" }
]
```
2. **`usageData.perProvider` Object**:
```json
{
"openai": { "spend": 25.50, "tokens": 150000 },
"anthropic": { "spend": 75.20, "tokens": 210000 },
"openrouter": { "spend": 90.00, "tokens": 300000 }
}
```
3. **`usageData.perKey` Array**:
```json
[
{ "keyId": "key_abc123", "provider": "openai", "model": "gpt-4", "spend": 25.50, "tokens": 150000 },
{ "keyId": "key_def456", "provider": "anthropic", "model": "claude-3-opus", "spend": 75.20, "tokens": 210000 }
]
```
4. **`routingRules` Array**:
```json
[
{ "id": "rule_001", "name": "Default Code Gen", "priority": 1, "enabled": true, "conditions": { "taskType": "Code Generation" }, "actions": { "provider": "openrouter", "model": "gpt-3.5-turbo", "fallbackStrategy": "cheapest" } },
{ "id": "rule_002", "name": "High Complexity Debugging", "priority": 2, "enabled": true, "conditions": { "taskType": "Debugging", "promptKeywords": ["complex", "difficult", "edge case"] }, "actions": { "provider": "anthropic", "model": "claude-3-opus", "fallbackStrategy": "sequential" } }
]
```
5. **`billing` Object**:
```json
{ "globalBudget": 200.00, "alertThresholds": [50, 80, 100], "autoPauseEnabled": true }
```
6. **`spendingOverviewCard` Mock Data**: `{ totalSpend: 190.70, budget: 200.00, remaining: 9.30 }`
7. **`providerBreakdownChart` Mock Data**: `[{"provider": "OpenAI", "amount": 25.50}, {"provider": "Anthropic", "amount": 75.20}, {"provider": "OpenRouter", "amount": 90.00}]`
8. **`dashboardStats` Mock Data**: `{ avgCostPerRequest: 0.0005, totalRequests: 500000, tokensConsumed: 660000 }`
DEPLOYMENT NOTES:
- **Build Tool**: Vite is recommended for its speed. `npm run build` will generate optimized static assets.
- **Environment Variables**: Use `.env` files for managing API keys (for backend services if used), base URLs, and other environment-specific configurations. Expose necessary variables to the frontend using `VITE_` prefix (e.g., `VITE_API_BASE_URL`). Sensitive keys should *never* be exposed to the frontend.
- **Performance Optimizations**:
- Code Splitting: Vite handles this automatically.
- Lazy Loading: Implement lazy loading for route components and non-critical components.
- Memoization: Use `React.memo`, `useMemo`, `useCallback` where necessary to prevent unnecessary re-renders, especially in lists and charts.
- Image Optimization: If images are used, optimize them.
- Bundle Analysis: Use tools like `vite-plugin-visualizer` to analyze bundle size and identify potential optimizations.
- **HTTPS**: Ensure deployment is over HTTPS.
- **CORS**: Configure CORS correctly if a separate backend is used.
- **Security**: Sanitize all user inputs. If storing API keys server-side, use robust encryption. Client-side key storage should ideally use Web Crypto API for encryption before storing in localStorage.
- **Scalability**: Design with stateless components where possible. If a backend is introduced, consider a scalable architecture (e.g., serverless functions, containerized services).