# PROJECT OVERVIEW
**App Title:** CodeLens
**Concept:** This application aims to demystify the leaked source code of 'Claude Code' and similar advanced AI coding tools. It provides an interactive, visual guide and analysis platform to understand the inner workings, security vulnerabilities, and development processes of these AI coding tools. Users can gain a deeper insight into the coding capabilities and potential weaknesses of popular AI models, especially those derived from leaked or analyzed codebases.
**Problem Solved:** The rapid advancement of AI coding tools often leads to a 'black box' perception. When leaks like Claude Code's occur, the sheer volume and complexity of the code make it difficult for developers and researchers to understand its architecture, identify potential flaws, or learn from its implementation. CodeLens addresses this by providing a structured, visual, and analytical approach to dissecting such codebases.
**Value Proposition:** Empowering developers and researchers with clear, visual, and actionable insights into complex AI code. Enabling a better understanding of AI model behavior, security implications, and best practices in AI development through code analysis and community discussion synthesis.
# TECH STACK
- **Frontend Framework:** React (Next.js App Router)
- **Styling:** Tailwind CSS
- **ORM:** Drizzle ORM
- **Database:** PostgreSQL (recommended for Drizzle)
- **Authentication:** NextAuth.js (or Clerk for simpler integration)
- **UI Component Library:** shadcn/ui
- **State Management:** React Context API / Zustand (for global state)
- **Data Fetching:** React Server Components (RSC), Server Actions, Client Components with SWR or TanStack Query
- **Charting Library:** Recharts or Chart.js for visualizations
- **Markdown/MDX:** For rendering code snippets and potentially parsed documentation
- **AI Integration (Optional for MVP):** For summarizing discussions (e.g., using OpenAI API or a self-hosted model)
# DATABASE SCHEMA
We will use PostgreSQL with Drizzle ORM.
**1. `users` table:**
- `id` (uuid, primary key, default gen_random_uuid())
- `name` (text)
- `email` (text, unique)
- `emailVerified` (timestamp)
- `image` (text, optional)
- `createdAt` (timestamp, default now())
- `updatedAt` (timestamp, default now())
**2. `code_modules` table:**
- `id` (uuid, primary key, default gen_random_uuid())
- `name` (text, unique, indexed) - e.g., 'claude-core', 'utils', 'parser'
- `description` (text, optional)
- `filePath` (text, optional) - Relative path in the source code
- `createdAt` (timestamp, default now())
- `updatedAt` (timestamp, default now())
**3. `code_functions` table:**
- `id` (uuid, primary key, default gen_random_uuid())
- `moduleId` (uuid, foreign key to `code_modules.id`, indexed)
- `name` (text, indexed) - e.g., 'generateResponse', 'parseInput', 'encryptData'
- `signature` (text, optional) - Function signature
- `description` (text, optional)
- `filePath` (text, optional)
- `lineNumberStart` (integer, optional)
- `lineNumberEnd` (integer, optional)
- `createdAt` (timestamp, default now())
- `updatedAt` (timestamp, default now())
**4. `function_dependencies` table:**
- `callerFunctionId` (uuid, foreign key to `code_functions.id`, indexed)
- `calleeFunctionId` (uuid, foreign key to `code_functions.id`, indexed)
- `type` (text, optional) - e.g., 'direct call', 'indirect call'
- `createdAt` (timestamp, default now())
- PRIMARY KEY (`callerFunctionId`, `calleeFunctionId`)
**5. `discussions` table:**
- `id` (uuid, primary key, default gen_random_uuid())
- `source` (text, indexed) - e.g., 'Hacker News', 'GitHub Discussion'
- `sourceUrl` (text, unique, indexed)
- `title` (text)
- `content` (text, optional) - Full content or summary
- `upvotes` (integer, default 0)
- `commentsCount` (integer, default 0)
- `postedAt` (timestamp, optional)
- `processedSummary` (text, optional) - AI-generated summary
- `createdAt` (timestamp, default now())
- `updatedAt` (timestamp, default now())
**6. `analysis_reports` table:**
- `id` (uuid, primary key, default gen_random_uuid())
- `userId` (uuid, foreign key to `users.id`, indexed)
- `reportTitle` (text)
- `analysisType` (text) - e.g., 'module_overview', 'function_security', 'dependency_chain'
- `targetEntity` (text) - e.g., 'code_modules.id', 'code_functions.id'
- `generatedContent` (jsonb)
- `createdAt` (timestamp, default now())
**Relations:**
- `code_functions` has a many-to-one relationship with `code_modules`.
- `function_dependencies` defines a many-to-many relationship between `code_functions`.
- `analysis_reports` has a many-to-one relationship with `users`.
# CORE FEATURES & USER FLOW
**1. Interactive Code Visualizer**
- **Description:** Renders the structure of the leaked codebase (or a provided codebase) as an interactive graph. Users can navigate through modules and functions, see dependencies, and explore the code structure visually.
- **User Flow:**
1. User lands on the 'Code Explorer' page.
2. Application fetches `code_modules` and `code_functions` data (potentially paginated or filtered).
3. A graph visualization (e.g., using D3.js, React Flow) is rendered, showing modules as main nodes and functions within them. Arrows indicate dependencies between functions.
4. User can click on a module to expand/collapse its functions or view its details.
5. User can click on a function to view its signature, description, file path, line numbers, and related functions (callers/callees).
6. Search functionality allows users to find specific modules or functions by name.
7. Tooltips on hover provide quick info (function name, module).
**2. Discussion Analyzer & Summarizer**
- **Description:** Fetches and processes relevant online discussions (like Hacker News threads) related to the AI code leak. Uses AI to summarize key points, extract sentiment, and identify common themes.
- **User Flow:**
1. User navigates to the 'Discussions' page.
2. A list of related discussions (fetched from `discussions` table, ordered by date or relevance) is displayed.
3. Each discussion item shows title, source, upvotes, comment count, and a "View Summary" button.
4. Clicking "View Summary" (or automatically upon loading) triggers an API call to process the discussion content (if `processedSummary` is null).
5. The AI processing involves fetching content, cleaning it, and generating a concise summary. The summary is stored in `discussions.processedSummary`.
6. The summary is displayed to the user, highlighting key arguments, user concerns (e.g., "frustration regexes", "fake tools"), and potential security issues mentioned.
7. Users can click through to the original discussion source.
**3. Code Functionality Deep Dive**
- **Description:** Allows users to select specific functions or code blocks and get detailed analysis, potentially including visualizations of related logic or security implications.
- **User Flow:**
1. From the 'Code Explorer', a user clicks on a specific function.
2. A modal or dedicated view opens, showing the function's details (signature, description, parameters, return value if inferable).
3. Features might include:
- Displaying the call chain (who calls this function, which functions does it call).
- Highlighting known security patterns or anti-patterns within the function's logic (requires a rule engine or AI analysis).
- Linking to relevant discussion points that mention this function or its behavior.
- Displaying mock data examples relevant to this function's input/output.
**4. User Authentication & Profile**
- **Description:** Standard user authentication to allow saving analysis, preferences, and potentially creating custom reports.
- **User Flow:**
1. User clicks 'Sign In' / 'Sign Up'.
2. Redirected to authentication provider (e.g., Google, GitHub via NextAuth.js).
3. Upon successful login, user's session is managed. User dashboard/profile page is accessible.
4. Logged-in users can save specific functions/modules for later review, bookmark discussions, or generate custom `analysis_reports`.
# API & DATA FETCHING
- **Next.js App Router:** Utilize Server Components for initial data loading and Server Actions for mutations (e.g., saving reports, adding comments).
- **API Routes (if needed for specific services):**
- `GET /api/modules`: Fetch paginated list of modules.
- `GET /api/modules/:moduleId`: Fetch details of a specific module and its functions.
- `GET /api/functions/:functionId`: Fetch details of a specific function and its dependencies.
- `POST /api/discussions/summarize/:discussionId`: Trigger AI summarization for a discussion.
- `GET /api/discussions`: Fetch list of discussions.
- `POST /api/reports`: Create a new analysis report for a user.
- **Data Fetching in Components:**
- **Server Components:** Fetch data directly within the component using `async` functions and Drizzle queries. Example: `async function ModulesPage() { const modules = await db.query.codeModules.findMany(); return <ModuleList modules={modules} /> }`
- **Client Components:** Use libraries like `swr` or `tanstack-query` for client-side fetching, caching, and state synchronization, especially for interactive elements or data that updates frequently. Server Actions can be called directly from Client Components.
- **Response Bodies:** JSON format. Example for function details:
```json
{
"id": "uuid",
"name": "functionName",
"signature": "(arg1: type, arg2: type) => returnType",
"description": "...",
"filePath": "src/core/parser.js",
"lineNumberStart": 50,
"lineNumberEnd": 75,
"module": {
"id": "moduleUuid",
"name": "parser"
},
"dependencies": [
{ "functionId": "calleeUuid", "name": "calleeFunctionName" },
...
],
"callers": [
{ "functionId": "callerUuid", "name": "callerFunctionName" },
...
]
}
```
# COMPONENT BREAKDOWN (Next.js App Router)
- **`app/layout.tsx`:** Root layout (HTML, Head, Body, Global Providers, Tailwind CSS setup).
- **`app/page.tsx`:** Landing Page (Introduction to CodeLens, value proposition, call to action).
- **`app/(auth)/signin/page.tsx`:** Sign In page.
- **`app/(auth)/signup/page.tsx`:** Sign Up page.
- **`app/dashboard/page.tsx`:** User Dashboard (Overview of saved items, recent reports, quick links).
- **`app/explore/page.tsx`:** Code Explorer Home. Lists available codebases or initiates exploration.
- **`app/explore/[codebase]/page.tsx`:** Main Code Visualizer page for a specific codebase (e.g., 'claude-code'). Contains the graph component, search, module/function lists.
- **`app/explore/[codebase]/[module]/page.tsx`:** Module Detail View page.
- **`app/explore/[codebase]/[module]/[function]/page.tsx`:** Function Detail View page (showing signature, dependencies, callers, analysis tools).
- **`app/discussions/page.tsx`:** Lists summarized discussions.
- **`app/discussions/[discussionId]/page.tsx`:** Detailed view of a single discussion with its summary.
- **`app/profile/page.tsx`:** User Profile page (settings, saved items, past reports).
- **`app/admin/page.tsx` (Optional):** Admin interface for managing codebases, users, etc.
**Key UI Components:**
- **`components/ui/Navbar.tsx`:** Navigation bar with auth status.
- **`components/ui/Footer.tsx`:** Footer.
- **`components/GraphVisualizer.tsx`:** Interactive force-directed graph (e.g., using React Flow).
- **`components/ModuleNode.tsx`:** Represents a module in the graph.
- **`components/FunctionNode.tsx`:** Represents a function in the graph.
- **`components/FunctionDetailsModal.tsx`:** Modal for displaying function info.
- **`components/DiscussionListItem.tsx`:** Summary card for a discussion.
- **`components/SearchBar.tsx`:** For searching modules/functions.
- **`components/CodeViewer.tsx`:** For displaying code snippets (syntax highlighting).
- **`components/AuthButton.tsx`:** Button for sign-in/sign-out.
- **`components/DataTable.tsx`:** For displaying tables (e.g., user reports, discussions).
- **`components/Spinner.tsx`:** Loading indicator.
**State Management:**
- Global state (user auth, theme) via Context API or Zustand.
- Local component state for form inputs, UI toggles.
- Server state management (data fetching, caching) via RSC data fetching or client-side libraries like SWR/TanStack Query.
# UI/UX DESIGN & VISUAL IDENTITY
- **Design Style:** Modern, Tech-Focused, Clean with Dark Mode emphasis.
- **Color Palette:**
- Dark Background: `#121212` (Primary)
- Secondary Dark: `#1E1E1E`
- Accent Color (for links, buttons, highlights): A vibrant cyan or electric blue (`#00FFFF` or `#4D79FF`)
- Light Text: `#E0E0E0`
- Muted Text: `#A0A0A0`
- Error/Warning: `#FF6B6B`
- Success: `#4CAF50`
- **Typography:**
- Headings: Inter, Poppins, or similar sans-serif (e.g., `font-bold`)
- Body Text: Inter, Roboto, or similar sans-serif (e.g., `font-regular`)
- Code Font: Fira Code, JetBrains Mono (monospace)
- **Layout:**
- Sidebar navigation for main sections (Explore, Discussions, Dashboard, Profile).
- Main content area with clear hierarchy.
- Use of cards and containers with subtle borders or shadows against the dark background.
- Graph visualization should take a significant portion of the screen real estate in the explorer.
- **Visual Elements:**
- Subtle background gradients or patterns could be used sparingly.
- Clean icons from libraries like Lucide Icons.
- Use of `shadcn/ui` components for consistent styling.
- **Responsiveness:** Mobile-first approach. Sidebars collapse into hamburger menus on smaller screens. Grids and tables adapt gracefully. Graph visualization might need simplification or zooming/panning for mobile.
# ANIMATIONS
- **Page Transitions:** Subtle fade-in/fade-out using Next.js's built-in router or libraries like `Framer Motion` for more advanced effects.
- **Hover Effects:** Slight scale-up or color change on interactive elements (buttons, links, nodes).
- **Loading States:** Skeleton loaders or spinners (`components/Spinner.tsx`) when data is being fetched.
- **Graph Animations:** Smooth transitions when nodes are added/removed or when expanding/collapsing modules. Force-directed graph layout stabilization animation.
- **Micro-interactions:** Subtle animations on form submissions, notifications, or toggles.
# EDGE CASES
- **Authentication:**
- Handle guest users (view-only access).
- Secure session management using NextAuth.js or similar.
- Redirect unauthenticated users from protected pages.
- **Empty States:**
- No code modules loaded: Display a placeholder message and instructions.
- No discussions found: "No related discussions found."
- No saved reports: "You haven't saved any reports yet."
- **Error Handling:**
- Graceful error display for API failures (e.g., using SWR's `error` prop).
- Catching errors during AI summarization and providing fallback content or error messages.
- Proper HTTP status codes for API routes.
- **Data Validation:**
- Server-side validation for all mutations (Server Actions, API routes).
- Client-side validation for forms (e.g., using Zod with shadcn/ui form components).
- **Large Codebases:** Implement pagination, lazy loading, and efficient graph rendering techniques to handle potentially large numbers of modules and functions.
- **Codebase Updates:** Strategy for updating the analyzed codebase if new versions are released or found.
# SAMPLE/MOCK DATA
**1. Mock `code_modules`:**
```json
[
{"id": "mod-core-1", "name": "core", "filePath": "src/core"},
{"id": "mod-utils-1", "name": "utils", "filePath": "src/utils"},
{"id": "mod-api-1", "name": "api", "filePath": "src/api"}
]
```
**2. Mock `code_functions`:**
```json
[
{"id": "func-genresp-1", "moduleId": "mod-core-1", "name": "generateResponse", "signature": "(prompt: string, config: object) => string", "filePath": "src/core/generator.js", "lineNumberStart": 10, "lineNumberEnd": 55},
{"id": "func-parsein-1", "moduleId": "mod-core-1", "name": "parseInput", "signature": "(input: string) => object", "filePath": "src/core/parser.ts", "lineNumberStart": 20, "lineNumberEnd": 40},
{"id": "func-uuid-1", "moduleId": "mod-utils-1", "name": "generateUUID", "signature": "() => string", "filePath": "src/utils/helpers.js", "lineNumberStart": 5, "lineNumberEnd": 15}
]
```
**3. Mock `function_dependencies`:**
```json
[
{"callerFunctionId": "func-genresp-1", "calleeFunctionId": "func-parsein-1"},
{"callerFunctionId": "func-genresp-1", "calleeFunctionId": "func-uuid-1"}
]
```
**4. Mock `discussions` (from Hacker News thread 47584540):**
```json
{
"id": "disc-hn-1",
"source": "Hacker News",
"sourceUrl": "https://news.ycombinator.com/item?id=47584540",
"title": "Claude Code's source code has been leaked via a map file in their NPM registry",
"upvotes": 956,
"commentsCount": 956,
"postedAt": "2026-03-15T10:00:00Z",
"processedSummary": "Leaked map file revealed Claude Code source. Users express concerns about tool reliability ('fake tools'), complex regex usage, and 'undercover mode' functionality. Discussion highlights potential security risks and frustration with perceived tool limitations."
}
```
**5. Mock `analysis_reports`:**
```json
{
"id": "rep-user1-1",
"userId": "user-uuid-123",
"reportTitle": "Security Analysis of generateResponse Function",
"analysisType": "function_security",
"targetEntity": "func-genresp-1",
"generatedContent": {"vulnerabilities": ["Potential input sanitization issue"], "recommendations": ["Add input validation and sanitization"]},
"createdAt": "2024-05-20T14:30:00Z"
}
```
**6. Mock User Data:**
```json
{
"id": "user-uuid-123",
"name": "Alex",
"email": "alex@example.com",
"image": "/path/to/alex.jpg"
}
```
**7. Mock Function Details (for `app/explore/[codebase]/[module]/[function]/page.tsx`):**
```json
{
"id": "func-parsein-1",
"name": "parseInput",
"signature": "(input: string, options: {strict: boolean = false}) => object | null",
"description": "Parses raw user input string into a structured object. Handles basic formatting and validation.",
"filePath": "src/core/parser.ts",
"lineNumberStart": 20,
"lineNumberEnd": 40,
"module": {"id": "mod-core-1", "name": "core"},
"dependencies": [{"functionId": "func-uuid-1", "name": "generateUUID"}],
"callers": [{"functionId": "func-genresp-1", "name": "generateResponse"}]
}
```