You are an expert AI assistant tasked with building a fully functional Next.js MVP application called 'Code Insights'. This application will analyze GitHub repositories to identify and evaluate code generated by AI tools like Claude. The goal is to provide developers and project managers with insights into AI-generated code adoption, quality, and impact.
**1. PROJECT OVERVIEW:**
- **App Name:** Code Insights (Kod İçgörüleri)
- **Problem Solved:** Developers and project managers lack clear visibility into the adoption, quality, and effectiveness of AI-generated code within their projects. It's difficult to track which AI tools are used, where they are used, and what impact they have on project health (e.g., repository star count, activity levels).
- **Value Proposition:** Code Insights provides actionable data and visualizations to understand AI code generation trends, identify high-impact AI usage, and optimize development workflows by leveraging AI tools more effectively. It helps answer questions like: 'Which AI tools are most prevalent in low-star repositories?' or 'What percentage of commits in active TypeScript projects use AI assistance?'
**2. TECH STACK:**
- **Framework:** Next.js (App Router)
- **Language:** TypeScript
- **Styling:** Tailwind CSS
- **ORM:** Drizzle ORM (PostgreSQL compatible)
- **Database:** PostgreSQL (or a compatible SQL database)
- **UI Library:** shadcn/ui for accessible, composable components.
- **Authentication:** NextAuth.js (or Clerk for easier integration)
- **Data Fetching:** React Server Components (RSC), Server Actions, and client-side fetching as needed.
- **State Management:** Zustand or Jotai for global client-side state, React Context for local state.
- **Charting:** Recharts or Chart.js for data visualization.
- **API Interaction:** GitHub API (using libraries like Octokit or direct fetch requests).
- **Deployment:** Vercel (recommended)
**3. DATABASE SCHEMA:**
```sql
-- Users table for authentication
CREATE TABLE users (
id TEXT PRIMARY KEY,
name TEXT,
email TEXT UNIQUE NOT NULL,
emailVerified TIMESTAMP WITH TIME ZONE,
image TEXT
);
-- Accounts table for OAuth providers
CREATE TABLE accounts (
id TEXT PRIMARY KEY,
userId TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
type TEXT NOT NULL,
provider TEXT NOT NULL,
providerAccountId TEXT NOT NULL,
refresh_token TEXT,
access_token TEXT,
expires_at BIGINT,
token_type TEXT,
scope TEXT,
id_token TEXT,
session_state TEXT
);
CREATE UNIQUE INDEX accounts_provider_providerAccountId_idx ON accounts (provider, providerAccountId);
-- Sessions table for user sessions
CREATE TABLE sessions (
id TEXT PRIMARY KEY,
sessionToken TEXT UNIQUE NOT NULL,
userId TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
expires TIMESTAMP WITH TIME ZONE NOT NULL
);
-- Verification tokens for email verification
CREATE TABLE verification_tokens (
identifier TEXT NOT NULL,
token TEXT NOT NULL,
expires TIMESTAMP WITH TIME ZONE NOT NULL
);
CREATE UNIQUE INDEX verification_tokens_identifier_token_idx ON verification_tokens (identifier, token);
-- Repositories table to store analyzed repository data
CREATE TABLE repositories (
id SERIAL PRIMARY KEY,
github_repo_id BIGINT UNIQUE NOT NULL,
owner_login TEXT NOT NULL,
name TEXT NOT NULL,
full_name TEXT UNIQUE NOT NULL,
html_url TEXT NOT NULL,
description TEXT,
stargazers_count INTEGER DEFAULT 0,
watchers_count INTEGER DEFAULT 0,
forks_count INTEGER DEFAULT 0,
language TEXT,
last_analyzed_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
ai_commits_count INTEGER DEFAULT 0,
total_commits_count INTEGER DEFAULT 0,
percentage_ai_commits REAL DEFAULT 0.0
);
CREATE INDEX idx_repositories_stargazers ON repositories (stargazers_count);
CREATE INDEX idx_repositories_language ON repositories (language);
-- AI Tools table to define known AI tools
CREATE TABLE ai_tools (
id SERIAL PRIMARY KEY,
name TEXT UNIQUE NOT NULL,
detection_method TEXT NOT NULL -- e.g., 'Co-Authored-By: Claude', 'Generated by ChatGPT'
);
-- Analysis Results table to store detailed analysis for each repo
CREATE TABLE analysis_results (
id SERIAL PRIMARY KEY,
repository_id INTEGER NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
analysis_date TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
detected_ai_tool_id INTEGER REFERENCES ai_tools(id),
commit_hash TEXT NOT NULL,
commit_message TEXT,
author_name TEXT,
is_ai_generated BOOLEAN NOT NULL DEFAULT FALSE,
-- Add other relevant commit details if needed
UNIQUE (repository_id, commit_hash) -- Prevent duplicate analysis for the same commit
);
CREATE INDEX idx_analysis_results_repo ON analysis_results (repository_id);
CREATE INDEX idx_analysis_results_ai_tool ON analysis_results (detected_ai_tool_id);
```
**Initial AI Tools Seed Data:**
- { name: 'Claude', detection_method: 'Co-Authored-By: Claude' }
- { name: 'ChatGPT', detection_method: 'Generated by ChatGPT' }
- { name: 'GitHub Copilot', detection_method: 'Copilot' } (Note: Copilot detection might require heuristics or different metadata analysis if explicit markers aren't consistently present)
**4. CORE FEATURES & USER FLOW:**
**a. User Authentication:**
- Flow: User signs up/logs in via GitHub OAuth or email/password.
- Pages: `/auth/signin`, `/auth/signup`.
- Components: Sign-in form, OAuth buttons.
- Auth Handling: Utilize NextAuth.js middleware for protected routes and session management.
**b. Repository Connection & Analysis Trigger:**
- Flow: Authenticated user navigates to 'Add Repository' page. Enters GitHub repository URL (e.g., `owner/repo-name`). Upon submission, a server action or API route is triggered.
- Action: The system attempts to fetch repository data from GitHub API (star count, forks, language, description). If successful, it's added to the `repositories` table or marked for deeper analysis.
- Triggering Deeper Analysis: A background job (or a manual trigger via an 'Analyze' button on the dashboard) initiates the commit-level analysis.
- Components: Repository input form, loading indicator.
**c. Deep Code Analysis (Commit Level):**
- Flow: For a selected repository, the system fetches recent commits via GitHub API.
- Logic: Each commit's message and potentially the diff (if feasible and necessary for advanced detection) are scanned for known AI tool indicators (e.g., 'Co-Authored-By: Claude', specific patterns). Results are stored in `analysis_results`.
- Data Update: `repositories` table is updated with aggregate data (AI commit count, total commits, percentage AI). This can be a scheduled task or triggered on demand.
- Edge Cases: Rate limiting by GitHub API, large number of commits, repos without AI indicators.
**d. Dashboard & Visualization:**
- Flow: Authenticated user lands on the dashboard. Displays a list of connected/analyzed repositories and key metrics.
- Content: Summary cards (Total Repos Analyzed, Overall AI Commit %).
- Visualizations:
- Bar chart: AI Commit % by Language.
- Scatter plot: Star Count vs. AI Commit % (to identify potential correlations).
- Table: List of analyzed repositories with columns for Name, Stars, Language, AI Commit %, Last Analyzed.
- Interactivity: Clicking a repository name navigates to its detailed view.
- Components: Repository list (DataTable), Summary Cards, Charts.
**e. Repository Detail View:**
- Flow: User clicks on a specific repository from the dashboard.
- Content: Detailed repository information (description, URL, stats). A breakdown of AI-generated commits (list of commits, author, message, AI tool detected). Line chart showing AI commit activity over time.
- Components: Repository stats section, Commit log table, Time-series chart.
**5. API & DATA FETCHING:**
- **GitHub API Integration:** Primarily use server-side fetching within Server Actions or Route Handlers to avoid exposing API tokens and manage rate limits.
- `GET /api/github/repo/:owner/:name` (Fetch basic repo info - stars, forks, language)
- `GET /api/github/repo/:owner/:name/commits` (Fetch recent commits, potentially paginated)
- **Internal API (Next.js Route Handlers / Server Actions):**
- `POST /api/repositories` (Add a new repository for analysis)
- `GET /api/repositories` (Fetch list of analyzed repositories for the dashboard)
- `GET /api/repositories/:id` (Fetch details for a single repository)
- `POST /api/repositories/:id/analyze` (Trigger a deep analysis for a specific repository)
- **Data Flow:**
- UI requests data from Next.js API routes or uses Server Actions.
- Server-side code interacts with the Database (Drizzle ORM) and GitHub API.
- Data is returned to the client and displayed using React components, potentially with charting libraries.
- Use RSC for initial data loading where possible, client-side fetching (e.g., using `swr` or `useEffect`) for dynamic or interactive data.
**6. COMPONENT BREAKDOWN (Next.js App Router Structure):**
- **`app/`**
- **`(auth)/` (Auth Routes)**
- `signin/page.tsx` (Sign-in page)
- `signup/page.tsx` (Sign-up page)
- **`(app)/` (Authenticated Routes)**
- **`layout.tsx`** (Main app layout with sidebar/header)
- **`dashboard/page.tsx`** (Main dashboard with overview stats and repository list)
- Components: `DashboardHeader`, `StatsGrid`, `RepositoryTable`, `AddRepositoryForm` (modal or separate section).
- **`repositories/[owner]/[name]/page.tsx`** (Detailed view for a single repository)
- Components: `RepoDetailsCard`, `CommitAnalysisChart`, `CommitLogTable`.
- **`settings/page.tsx`** (User settings, connected accounts, etc.)
- Components: `ProfileForm`, `ApiKeysManager`.
- **`layout.tsx`** (Root layout)
- **`page.tsx`** (Landing Page - marketing, features, call to action)
- **`components/`**
- **`ui/`** (Re-export from shadcn/ui: `Button`, `Input`, `Card`, `Table`, `Sheet`, `Dialog`, `Tooltip`, `Avatar`, `Spinner`, etc.)
- **`charts/`**: `LanguageCommitChart`, `StarVsAiCommitChart`, `CommitActivityChart`
- **`layout/`**: `AppLayout`, `Header`, `Sidebar`, `Footer`
- **`forms/`**: `AddRepositoryForm`, `SignInForm`, `SettingsForm`
- **`tables/`**: `RepositoryTable`, `CommitLogTable` (using shadcn/ui Table component)
- **`general/`**: `Logo`, `PageTitle`
- **`lib/`** (Utility functions, GitHub API client, DB client with Drizzle)
- **`hooks/`** (Custom React hooks, e.g., `useFetchRepositories`, `useChartData`)
- **`server/`** (Server Actions, Route Handlers - can be co-located with pages or in a separate folder)
**7. UI/UX DESIGN & VISUAL IDENTITY:**
- **Design Style:** Minimalist Clean with a touch of modern tech. Focus on clarity, data readability, and intuitive navigation.
- **Color Palette:**
- Primary: `#4F46E5` (Indigo-500) - For key actions, active states.
- Secondary: `#6366F1` (Indigo-600) - Accents, secondary buttons.
- Background: `#FFFFFF` (White) or a very light gray `#F9FAFB` for main content area.
- Text: `#111827` (Dark Gray-800)
- Subtle Backgrounds/Borders: `#E5E7EB` (Gray-200)
- Chart Colors: A pleasant, distinct set (e.g., Teal, Blue, Purple, Orange).
- **Typography:** Inter or Tailwind's default sans-serif font (e.g., `font-sans`). Clear hierarchy using font weights and sizes.
- **Layout:** Use a sidebar for navigation within the authenticated app section. Main content area is clean with clear sections. Use cards for summarizing information.
- **Responsiveness:** Mobile-first approach. Sidebar might collapse into a hamburger menu on smaller screens. Tables should be responsive (e.g., horizontal scroll or collapsing columns).
- **Visual Elements:** Subtle use of gradients in headers or key cards. Clean icons from shadcn/ui or an icon library like Lucide React.
**8. SAMPLE/MOCK DATA:**
- **`repositories` Table:**
1. `{ github_repo_id: 123456, owner_login: 'moinmir', name: 'ClashOfCans', full_name: 'moinmir/ClashOfCans', html_url: 'https://github.com/moinmir/ClashOfCans', description: 'Change initial game setup...', stargazers_count: 5, watchers_count: 10, forks_count: 2, language: 'Python', ai_commits_count: 2, total_commits_count: 15, percentage_ai_commits: 13.33 }
2. `{ github_repo_id: 789012, owner_login: 'standardbeagle', name: 'agnt', full_name: 'standardbeagle/agnt', html_url: 'https://github.com/standardbeagle/agnt', description: 'Agent framework with AI...', stargazers_count: 250, watchers_count: 300, forks_count: 50, language: 'TypeScript', ai_commits_count: 15, total_commits_count: 200, percentage_ai_commits: 7.5 }
3. `{ github_repo_id: 345678, owner_login: 'openai', name: 'gpt-3', full_name: 'openai/gpt-3', html_url: 'https://github.com/openai/gpt-3', description: 'Official repo for GPT-3', stargazers_count: 15000, watchers_count: 16000, forks_count: 3000, language: 'Python', ai_commits_count: 5, total_commits_count: 1000, percentage_ai_commits: 0.5 }
4. `{ github_repo_id: 901234, owner_login: 'vercel', name: 'next.js', full_name: 'vercel/next.js', html_url: 'https://github.com/vercel/next.js', description: 'The React Framework...', stargazers_count: 120000, watchers_count: 125000, forks_count: 25000, language: 'JavaScript', ai_commits_count: 100, total_commits_count: 15000, percentage_ai_commits: 0.67 }
5. `{ github_repo_id: 567890, owner_login: 'google', name: 'model-garden', full_name: 'google/model-garden', html_url: 'https://github.com/google/model-garden', description: 'Collection of models and tools...', stargazers_count: 5000, watchers_count: 5500, forks_count: 800, language: 'Python', ai_commits_count: 80, total_commits_count: 500, percentage_ai_commits: 16.0 }
- **`analysis_results` Table (Example for repo ID 1):**
1. `{ repository_id: 1, commit_hash: 'moinmir-commit-1', commit_message: 'Refactor game logic', author_name: 'moinmir', is_ai_generated: false }
2. `{ repository_id: 1, commit_hash: 'moinmir-commit-2', commit_message: 'Fix initial can placement bug #12', author_name: 'Claude', is_ai_generated: true, detected_ai_tool_id: 1 }` (Assuming Claude is tool ID 1)
3. `{ repository_id: 1, commit_hash: 'moinmir-commit-3', commit_message: 'Add tests for placement logic', author_name: 'moinmir', is_ai_generated: false }
4. `{ repository_id: 1, commit_hash: 'moinmir-commit-4', commit_message: 'Co-Authored-By: Claude <[email protected]>
Update game loop', author_name: 'moinmir', is_ai_generated: true, detected_ai_tool_id: 1 }
5. `{ repository_id: 1, commit_hash: 'moinmir-commit-5', commit_message: 'Improve starting condition consistency', author_name: 'Claude', is_ai_generated: true, detected_ai_tool_id: 1 }`
**9. TURKISH TRANSLATIONS:**
- **App Title:** Kod İçgörüleri
- **Dashboard:** Gösterge Paneli
- **Repositories:** Depolar
- **Add Repository:** Depo Ekle
- **Analyze:** Analiz Et
- **Repository Name:** Depo Adı
- **Stars:** Yıldızlar
- **Language:** Dil
- **AI Commit %:** YZ Yorum Yüzdesi
- **Last Analyzed:** Son Analiz
- **Details:** Detaylar
- **Commits:** Yorumlar
- **AI Generated:** YZ Tarafından Üretildi
- **Settings:** Ayarlar
- **Sign In:** Giriş Yap
- **Sign Up:** Kayıt Ol
- **Connect GitHub:** GitHub Bağla
- **Search/Filter:** Ara/Filtrele
- **No data available:** Veri mevcut değil
- **Loading...:** Yükleniyor...
- **An error occurred:** Bir hata oluştu.
- **Analysis triggered successfully:** Analiz başarıyla başlatıldı.
- **Repository added successfully:** Depo başarıyla eklendi.
- **Invalid repository URL:** Geçersiz depo URL'si.
**10. ANIMATIONS:**
- **Page Transitions:** Subtle fade-in/slide-in animations using Next.js `AnimatePresence` and Framer Motion, or simple CSS transitions.
- **Hover Effects:** Slight scale-up or background color change on interactive elements like buttons, table rows, and cards.
- **Loading States:** Use spinners (`shadcn/ui Spinner`) with skeleton loaders for data fetching. Animate chart loading states.
- **Micro-interactions:** Smooth transitions on chart elements, subtle hover effects on data points.
**11. EDGE CASES:**
- **Authentication:** Handle expired sessions, token refresh, unauthorized access attempts gracefully (redirect to login).
- **GitHub API:** Implement robust error handling for rate limits, private repository access errors, and invalid repository names. Use exponential backoff for retries on rate limits.
- **Empty States:** Design clear UI states for when no repositories are added, no commits are found, or no AI code is detected. Provide helpful messages and calls to action.
- **Data Validation:** Validate all user inputs (repository URLs, form data) on both client and server sides.
- **Large Repositories:** Implement pagination for commit lists and potentially use background jobs for analyzing repositories with a very high number of commits to avoid long-running requests.
- **AI Detection Accuracy:** Acknowledge that AI detection might not be 100% accurate. The 'detection_method' should be clearly defined and potentially user-configurable or expandable.
- **Database Migrations:** Use Drizzle Kit or a similar tool for managing database schema changes.