You are an expert AI architect and full-stack developer tasked with building a fully functional, multi-page MVP of an AI SaaS application called 'CacheWise AI' using Next.js (App Router). The application's primary goal is to help developers optimize the Key-Value (KV) cache usage in Large Language Models (LLMs), thereby reducing memory consumption and improving inference speed. This MVP should be robust, visually appealing, and deployable.
PROJECT OVERVIEW:
CacheWise AI addresses the critical problem of excessive KV cache memory usage in LLMs, which is a major bottleneck for deploying and scaling AI applications, especially those involving long conversations or complex processing. The core value proposition is to provide developers with tools and insights to monitor, analyze, and optimize KV cache, leading to significant cost savings, improved performance, and the ability to run larger models or longer contexts on existing hardware. The MVP will focus on providing real-time monitoring, AI-driven optimization recommendations, and automated cache management features.
TECH STACK:
- Frontend Framework: Next.js 14 (App Router)
- Styling: Tailwind CSS v3
- UI Component Library: shadcn/ui (for accessible, reusable components)
- State Management: React Context API / Zustand (for global state, if needed)
- ORM: Drizzle ORM (for type-safe database interactions)
- Database: PostgreSQL (or any compatible SQL database supported by Drizzle)
- Authentication: NextAuth.js (for seamless user login/signup)
- Charting Library: Recharts (for data visualization)
- Animation Library: Framer Motion (for smooth UI animations)
- Form Handling: React Hook Form with Zod for validation
- Utilities: Axios (for API requests), date-fns (for date formatting)
DATABASE SCHEMA:
We will use Drizzle ORM with PostgreSQL. The schema will be defined in `src/db/schema.ts`.
1. `users` table:
- `id` (UUID, Primary Key, default: uuid_generate_v4())
- `name` (VARCHAR(255))
- `email` (VARCHAR(255), Unique)
- `emailVerified` (TIMESTAMP with time zone)
- `image` (TEXT)
- `createdAt` (TIMESTAMP with time zone, default: now())
- `updatedAt` (TIMESTAMP with time zone, default: now())
2. `accounts` table (for NextAuth.js):
- `id` (VARCHAR(255), Primary Key)
- `userId` (UUID, Foreign Key to `users.id`)
- `type` (VARCHAR(255))
- `provider` (VARCHAR(255))
- `providerAccountId` (VARCHAR(255))
- `refresh_token` (TEXT)
- `access_token` (TEXT)
- `expires_at` (BIGINT)
- `token_type` (VARCHAR(255))
- `scope` (VARCHAR(255))
- `id_token` (TEXT)
- `session_state` (VARCHAR(255))
3. `sessions` table (for NextAuth.js):
- `sessionToken` (VARCHAR(255), Primary Key)
- `userId` (UUID, Foreign Key to `users.id`)
- `expires` (TIMESTAMP with time zone)
4. `verificationTokens` table (for NextAuth.js):
- `identifier` (VARCHAR(255))
- `token` (VARCHAR(255))
- `expires` (TIMESTAMP with time zone)
- Primary Key (`identifier`, `token`)
5. `llm_projects` table:
- `id` (UUID, Primary Key, default: uuid_generate_v4())
- `userId` (UUID, Foreign Key to `users.id`)
- `projectName` (VARCHAR(255), Not Null)
- `modelName` (VARCHAR(255))
- `modelArchitecture` (VARCHAR(100))
- `createdAt` (TIMESTAMP with time zone, default: now())
- `updatedAt` (TIMESTAMP with time zone, default: now())
6. `cache_metrics` table:
- `id` (UUID, Primary Key, default: uuid_generate_v4())
- `projectId` (UUID, Foreign Key to `llm_projects.id`)
- `timestamp` (TIMESTAMP with time zone, default: now())
- `tokensProcessed` (BIGINT)
- `kvCacheSizeKB` (BIGINT)
- `memoryUsageGB` (DECIMAL(10, 2))
- `inferenceTimeMs` (BIGINT)
- `optimizationScore` (DECIMAL(5, 2))
- `processedData` (JSONB) // Optional: For raw data or specific metrics
CORE FEATURES & USER FLOW:
MVP 1: Real-time KV Cache Monitoring Dashboard
- User Flow:
1. User signs up/logs in via NextAuth.js (e.g., Google, email/password).
2. User creates a new LLM project, providing basic details (Project Name, Model Name, Architecture).
3. User integrates the CacheWise AI SDK/API into their LLM application.
4. Application starts sending real-time metrics (tokens processed, KV cache size, memory usage, inference time) to CacheWise AI backend via API.
5. The Dashboard page displays these metrics using charts (e.g., line charts for cache size over time, bar charts for inference time comparison) and key performance indicators (KPIs).
6. User can view metrics per project and overall.
MVP 2: AI-Driven Optimization Recommendations
- User Flow:
1. After sufficient data is collected on the dashboard (e.g., > 1 hour), the AI engine analyzes the metrics.
2. The engine identifies patterns indicating inefficient KV cache usage.
3. Recommendations are displayed on a dedicated 'Recommendations' tab/section within the project view. Examples: "Consider implementing KV cache quantization for model X", "Your current cache size suggests potential for significant reduction by using a sliding window approach", "Experiment with reducing cache granularity for long contexts."
4. Recommendations include estimated impact (e.g., "Potential memory saving: 30%", "Potential speed increase: 15%").
MVP 3: Automated Cache Management (Basic)
- User Flow:
1. User enables 'Automated Management' for a project.
2. User sets thresholds (e.g., maximum cache size percentage, maximum acceptable inference latency increase).
3. The system, based on AI recommendations and real-time data, can trigger actions like:
- Clearing least recently used cache entries if a threshold is breached.
- Adjusting cache chunk sizes dynamically.
4. A log of automated actions is available for user review.
API & DATA FETCHING:
- API Routes (Next.js App Router - `src/app/api/...`):
- `POST /api/projects`: Create a new LLM project.
- `POST /api/metrics`: Endpoint for the user's application to push real-time cache metrics. Requires authentication (API key or JWT).
- Request Body Example: `{ "projectId": "uuid", "timestamp": "iso_string", "tokensProcessed": 1500, "kvCacheSizeKB": 450000, "memoryUsageGB": 2.5, "inferenceTimeMs": 500 }`
- `GET /api/projects`: Get all projects for the logged-in user.
- `GET /api/projects/[projectId]`: Get details and metrics for a specific project.
- `GET /api/recommendations/[projectId]`: Get AI-driven optimization recommendations for a project.
- Data Fetching in Components:
- Server Components will fetch initial project lists and dashboard data directly from the database using Drizzle ORM.
- Client Components (e.g., Dashboard charts) will fetch time-series data via API routes or directly use server-fetched data passed as props.
- Use of `fetch` with caching/revalidation strategies in Next.js.
- `axios` for any client-side API calls if needed.
COMPONENT BREAKDOWN (Next.js App Router structure):
- `app/layout.tsx`: Root layout (includes providers, Tailwind setup, global styles).
- `app/page.tsx`: Landing Page (Marketing).
- `app/auth/...`: Authentication pages (Login, Sign Up, Forgot Password - handled by NextAuth.js).
- `app/(dashboard)/layout.tsx`: Dashboard layout (Sidebar, Header).
- `app/(dashboard)/dashboard/page.tsx`: Main overview dashboard showing all projects' high-level status.
- `app/(dashboard)/projects/page.tsx`: Page to list all user's projects and create new ones.
- `app/(dashboard)/projects/[projectId]/page.tsx`: Project Detail page. Contains tabs for:
- `Dashboard`: Real-time charts and KPIs for this project.
- Components: `MetricChart` (line, bar), `KpiCard`, `ProjectInfoPanel`.
- `Recommendations`: AI-generated optimization suggestions.
- Components: `RecommendationCard`.
- `Settings`: Project settings (model details, integration keys, automated management toggles).
- Components: `ProjectSettingsForm`.
- `MetricsLog`: Raw data log.
- Components: `DataTable` (using shadcn/ui's table component).
- `app/api/...`: API routes as described above.
- `components/ui/`: Reusable UI elements from shadcn/ui.
- `components/common/`: Custom shared components (e.g., `Sidebar`, `Header`, `GraphTooltip`, `LoadingSpinner`).
- `components/dashboard/`: Components specific to the dashboard pages (`MetricChart`, `KpiCard`).
- `components/projects/`: Components for project management (`ProjectForm`, `ProjectList`).
- `lib/`: Utility functions, database connection, API client setup.
- `hooks/`: Custom React hooks.
- `db/`: Drizzle ORM schema and migration files.
State Management:
- Global state (auth status, user info) via NextAuth.js context or Zustand.
- Local component state for forms, toggles etc.
- Server state fetched via server components or API routes, passed as props or cached.
UI/UX DESIGN & VISUAL IDENTITY:
- Style: Modern, Clean, Data-Driven, Professional.
- Color Palette:
- Primary: `#007AFF` (Vibrant Blue)
- Secondary: `#5AC8FA` (Lighter Blue)
- Accent: `#34C759` (Green for positive metrics/recommendations)
- Background: `#F2F2F7` (Light Gray)
- Card/Surface: `#FFFFFF` (White)
- Text (Primary): `#000000` (Black)
- Text (Secondary): `#8E8E93` (Gray)
- Warning/Alert: `#FF9500` (Orange)
- Danger: `#FF3B30` (Red)
- Typography:
- Font Family: Inter (sans-serif)
- Headings: Bold, varying weights (e.g., 700, 600)
- Body Text: Regular weight (400)
- Layout:
- Responsive design using Tailwind CSS utility classes and breakpoints.
- Dashboard: Sidebar navigation on larger screens, collapsible/off-canvas on smaller screens. Main content area with cards and charts.
- Forms: Clear labels, logical grouping, ample spacing.
- Visual Elements:
- Subtle gradients in charts or backgrounds.
- Clean icons (e.g., fromlucide-react).
- Use of shadcn/ui for consistent, accessible components.
ANIMATIONS:
- Page Transitions: Subtle fade-in/out using Framer Motion for route changes between pages.
- Element Transitions: Smooth transitions for chart updates (e.g., Recharts animation)
- Loading States: Skeleton loaders or subtle spinners (`@/components/ui/spinner`) while data is being fetched.
- Hover Effects: Slight scale-up or background color change on interactive elements (buttons, cards).
- Accordion/Collapse Animations: Smooth expansion/contraction for collapsible sections (e.g., in settings or detailed logs).
EDGE CASES:
- Authentication: Secure login/signup with NextAuth.js. Handling of expired sessions, role-based access if needed later.
- Authorization: Ensure users can only access their own projects and data.
- Empty States: Display user-friendly messages and clear calls-to-action when no projects exist, no metrics are recorded, or no recommendations are available.
- Validation: Robust form validation using React Hook Form and Zod for all user inputs (project names, thresholds, API keys).
- API Error Handling: Graceful handling of API errors (e.g., rate limiting, server errors) with user feedback.
- Data Inconsistencies: Implement checks for missing or invalid metric data pushed via API.
- Zero/Low Data Scenarios: Ensure charts and recommendations are handled gracefully when minimal data is available.
SAMPLE DATA (for frontend development and initial DB seeding):
1. User:
```json
{
"id": "user-1", "name": "Alice", "email": "alice@example.com"
}
```
2. LLM Project (User: user-1):
```json
{
"id": "proj-abc", "userId": "user-1", "projectName": "Chatbot v2", "modelName": "GPT-4", "modelArchitecture": "Decoder-only Transformer"
}
```
3. LLM Project (User: user-1):
```json
{
"id": "proj-def", "userId": "user-1", "projectName": "Code Gen API", "modelName": "CodeLlama 7B", "modelArchitecture": "Decoder-only Transformer"
}
```
4. Cache Metrics (Project: proj-abc, 2024-01-15 10:00:00 UTC):
```json
{
"timestamp": "2024-01-15T10:00:00Z", "tokensProcessed": 1250, "kvCacheSizeKB": 480000, "memoryUsageGB": 2.7, "inferenceTimeMs": 550, "optimizationScore": 75.5
}
```
5. Cache Metrics (Project: proj-abc, 2024-01-15 10:05:00 UTC):
```json
{
"timestamp": "2024-01-15T10:05:00Z", "tokensProcessed": 1300, "kvCacheSizeKB": 495000, "memoryUsageGB": 2.8, "inferenceTimeMs": 560, "optimizationScore": 74.0
}
```
6. Cache Metrics (Project: proj-def, 2024-01-15 10:00:00 UTC):
```json
{
"timestamp": "2024-01-15T10:00:00Z", "tokensProcessed": 800, "kvCacheSizeKB": 300000, "memoryUsageGB": 1.5, "inferenceTimeMs": 300, "optimizationScore": 88.2
}
```
7. Recommendation (Project: proj-abc):
```json
{
"id": "rec-xyz", "projectId": "proj-abc", "generatedAt": "2024-01-15T11:00:00Z", "title": "KV Cache Quantization Recommended", "description": "Model GPT-4 shows high KV cache usage. Implementing 8-bit quantization could reduce cache size by approx. 30% without significant performance degradation.", "impactEstimate": {"memorySavingPercent": 30, "speedIncreasePercent": 5}, "status": "pending"
}
```
8. Automated Action Log (Project: proj-abc):
```json
{
"id": "action-123", "projectId": "proj-abc", "timestamp": "2024-01-15T11:30:00Z", "actionType": "Cache Pruning", "details": "Cleared 50 LFU cache entries due to exceeding 90% memory threshold.", "status": "success"
}
```
9. User (Another user for testing auth):
```json
{
"id": "user-2", "name": "Bob", "email": "bob@example.com"
}
```
10. LLM Project (User: user-2):
```json
{
"id": "proj-ghi", "userId": "user-2", "projectName": "Image Captioning", "modelName": "BLIP-2", "modelArchitecture": "Encoder-Decoder Transformer"
}
```
TURKISH TRANSLATIONS (for UI elements):
- CacheWise AI: CacheWise AI
- Dashboard: Kontrol Paneli
- Projects: Projeler
- New Project: Yeni Proje
- Project Name: Proje Adı
- Model Name: Model Adı
- Model Architecture: Model Mimarisi
- Settings: Ayarlar
- Metrics: Metrikler
- Recommendations: Öneriler
- Real-time Metrics: Gerçek Zamanlı Metrikler
- KV Cache Size: KV Cache Boyutu
- Tokens Processed: İşlenen Tokenlar
- Memory Usage: Bellek Kullanımı
- Inference Time: Çıkarım Süresi
- Optimization Score: Optimizasyon Skoru
- See Details: Detayları Gör
- Add Project: Proje Ekle
- Save Changes: Değişiklikleri Kaydet
- Enable Automated Management: Otomatik Yönetimi Etkinleştir
- Max Cache Size: Maks. Cache Boyutu
- Edit: Düzenle
- Delete: Sil
- Log Out: Çıkış Yap
- Sign In: Giriş Yap
- Sign Up: Kayıt Ol
- Email: E-posta
- Password: Şifre
- Apply Recommendation: Öneriyi Uygula
- Pending: Bekliyor
- Action Log: Eylem Kaydı
- Timestamp: Zaman Damgası
- Action Type: Eylem Türü
- Details: Detaylar
- Success: Başarılı
- Error: Hata
- Estimated Memory Saving: Tahmini Bellek Tasarrufu
- Estimated Speed Increase: Tahmini Hız Artışı
- No projects yet. Create one! : Henüz proje yok. Bir tane oluştur!
- No metrics available for this project. : Bu proje için henüz metrik yok.
- No recommendations available at this time. : Şu anda uygun öneri bulunmamaktadır.
- Fetching data...: Veri yükleniyor...
- Model Name is required.: Model adı zorunludur.
- Project Name is required.: Proje adı zorunludur.
- Please enter a valid number.: Lütfen geçerli bir sayı girin.
- Optimization Strategies: Optimizasyon Stratejileri
- Monitor KV Cache Usage: KV Cache Kullanımını İzleyin
- Analyze LLM Performance: LLM Performansını Analiz Edin
- Reduce Costs, Increase Speed: Maliyetleri Düşürün, Hızı Artırın
- Get Started for Free: Ücretsiz Başlayın
- Sign in to your account: Hesabınıza giriş yapın
- Welcome back!: Tekrar hoş geldiniz!
- Create your first project to start monitoring.: İzlemeye başlamak için ilk projenizi oluşturun.
- View All Projects: Tüm Projeleri Görüntüle
- Add New Project: Yeni Proje Ekle