## AI Master Prompt for CodeGuardian MVP
**1. PROJECT OVERVIEW:**
CodeGuardian is a cutting-edge SaaS platform designed to protect intellectual property and ensure legal compliance within the software development ecosystem. It addresses the critical problem of open-source license violations and unauthorized code forking, exemplified by incidents like the one involving Delve. The platform automates the detection of open-source libraries used in a project, verifies their license compliance, and scans for potential unauthorized copying or "forking" of existing codebases. CodeGuardian provides developers and companies with a robust tool to maintain legal integrity, build trust within the open-source community, and safeguard their valuable software assets. The core value proposition lies in providing proactive, automated, and reliable compliance monitoring, preventing costly legal disputes and reputational damage.
**2. TECH STACK:**
- **Framework:** Next.js (App Router)
- **Language:** TypeScript
- **Styling:** Tailwind CSS
- **ORM:** Drizzle ORM (PostgreSQL compatible)
- **Database:** PostgreSQL
- **Authentication:** NextAuth.js (e.g., with GitHub, Google, Email providers)
- **UI Components:** shadcn/ui (leveraging Radix UI and Tailwind CSS)
- **State Management:** React Context API / Zustand (for global state), local component state
- **Form Handling:** React Hook Form + Zod (for validation)
- **API Communication:** Server Actions (for mutations/actions), Fetch API / React Query (for queries)
- **Background Jobs/Queues:** (Optional for MVP, but consider for scaling) e.g., `node-cron` or a dedicated service like Resend/Queue
- **Code Scanning:** Integrate with a static analysis tool or develop custom AST parsing logic (e.g., using `esprima` or similar libraries).
- **Deployment:** Vercel (recommended for Next.js)
**3. DATABASE SCHEMA (Drizzle ORM - PostgreSQL):**
```typescript
// Schema definitions would go in a separate file, e.g., schema.ts
import { pgTable, serial, varchar, text, timestamp, boolean, integer, jsonb, pgEnum } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';
import { createId } from '@paralleldrive/cuid2'; // For unique IDs
// User Authentication
export const users = pgTable('users', {
id: varchar('id', { length: 128 }).primaryKey().$default(() => createId()),
name: varchar('name'),
email: varchar('email', { length: 255 }).notNull().unique(),
emailVerified: timestamp('emailVerified', { mode: 'date' }),
image: varchar('image', { length: 255 }),
createdAt: timestamp('createdAt').defaultNow(),
updatedAt: timestamp('updatedAt').defaultNow(),
});
export const accounts = pgTable('accounts', {
id: serial('id').primaryKey(),
userId: varchar('userId', { length: 128 }).notNull().references(() => users.id, { onDelete: 'cascade' }),
type: varchar('type', { length: 255 }).$type<AccountType>(),
provider: varchar('provider', { length: 255 }).notNull(),
providerAccountId: varchar('providerAccountId', { length: 255 }).notNull(),
refresh_token: text('refresh_token'),
access_token: text('access_token'),
expires_at: integer('expires_at'),
token_type: varchar('token_type'),
scope: varchar('scope'),
id_token: text('id_token'),
session_state: varchar('session_state'),
});
export const sessions = pgTable('sessions', {
sessionToken: varchar('sessionToken', { length: 255 }).primaryKey(),
userId: varchar('userId', { length: 128 }).notNull().references(() => users.id, { onDelete: 'cascade' }),
expires: timestamp('expires', { mode: 'date' }).notNull(),
});
export const verificationTokens = pgTable('verificationTokens', {
identifier: varchar('identifier', { length: 255 }).notNull(),
token: varchar('token', { length: 255 }).notNull(),
expires: timestamp('expires', { mode: 'date' }).notNull(),
}).primaryKey(identifier, token);
// Application Specific Tables
export const projects = pgTable('projects', {
id: varchar('id', { length: 128 }).primaryKey().$default(() => createId()),
userId: varchar('userId', { length: 128 }).notNull().references(() => users.id, { onDelete: 'cascade' }),
name: varchar('name', { length: 255 }).notNull(),
repoUrl: varchar('repoUrl', { length: 1024 }),
projectType: pgEnum('projectType', ['github', 'gitlab', 'local', 'other']),
status: pgEnum('status', ['processing', 'completed', 'error']),
createdAt: timestamp('createdAt').defaultNow(),
updatedAt: timestamp('updatedAt').defaultNow(),
});
export const dependencies = pgTable('dependencies', {
id: varchar('id', { length: 128 }).primaryKey().$default(() => createId()),
projectId: varchar('projectId', { length: 128 }).notNull().references(() => projects.id, { onDelete: 'cascade' }),
name: varchar('name', { length: 255 }).notNull(),
version: varchar('version', { length: 50 }),
license: varchar('license', { length: 100 }),
source: varchar('source', { length: 255 }), // e.g., package.json, requirements.txt
isVulnerable: boolean('isVulnerable').default(false),
complianceStatus: pgEnum('complianceStatus', ['compliant', 'non_compliant', 'unknown', 'pending']),
createdAt: timestamp('createdAt').defaultNow(),
updatedAt: timestamp('updatedAt').defaultNow(),
});
export const complianceIssues = pgTable('complianceIssues', {
id: varchar('id', { length: 128 }).primaryKey().$default(() => createId()),
dependencyId: varchar('dependencyId', { length: 128 }).notNull().references(() => dependencies.id, { onDelete: 'cascade' }),
projectId: varchar('projectId', { length: 128 }).notNull().references(() => projects.id, { onDelete: 'cascade' }),
issueType: pgEnum('issueType', ['missing_attribution', 'non_approved_license', 'possible_fork', 'vulnerability']),
details: text('details'),
severity: pgEnum('severity', ['low', 'medium', 'high', 'critical']),
resolved: boolean('resolved').default(false),
resolvedAt: timestamp('resolvedAt', { mode: 'date' }),
createdAt: timestamp('createdAt').defaultNow(),
});
// Relations (Example)
export const userRelations = relations(users, ({ many }) => ({
projects: many(projects),
}));
export const projectRelations = relations(projects, ({ one, many }) => ({
user: one(users),
dependencies: many(dependencies),
complianceIssues: many(complianceIssues),
}));
export const dependencyRelations = relations(dependencies, ({ one, many }) => ({
project: one(projects),
complianceIssues: many(complianceIssues),
}));
export const complianceIssueRelations = relations(complianceIssues, ({ one }) => ({
dependency: one(dependencies),
project: one(projects),
}));
// Type definitions for enums and other types would be here
type AccountType = 'oauth' | 'email';
```
**4. CORE FEATURES & USER FLOW:**
* **User Authentication (OAuth & Email):**
* **Flow:** User lands on the homepage -> Clicks 'Sign Up' or 'Login' -> Selects OAuth provider (GitHub, Google) OR enters email/password -> If OAuth, redirects to provider for auth, then back to app with user info -> If Email/Password, validates credentials, logs user in -> Creates user record in DB if new.
* **Edge Case:** Invalid credentials, OAuth callback errors, email already exists.
* **Project Onboarding:**
* **Flow:** Logged-in user navigates to 'Projects' page -> Clicks 'Add New Project' -> Enters Project Name, Repository URL (e.g., GitHub) -> Selects Project Type (GitHub initially for MVP) -> Clicks 'Scan Project' -> Project status set to 'processing'.
* **Edge Case:** Invalid URL, private repository without auth token, unsupported repository type.
* **Dependency Scanning & License Verification:**
* **Flow:** Triggered after project onboarding or manually. Backend service fetches the repository -> Parses relevant manifest files (e.g., `package.json` for Node.js, `pyproject.toml` for Python, `pom.xml` for Java) -> Extracts dependency names and versions -> For each dependency: Fetches license information from sources like SPDX, GitHub API, or package registries -> Stores dependencies in the `dependencies` table with their license and `complianceStatus` (initially 'pending'). Sets status to 'compliant', 'non_compliant', or 'unknown' based on validation rules.
* **Edge Case:** Manifest file not found, ambiguous/missing license info, rate limiting on external APIs.
* **Potential Fork/Code Similarity Detection:**
* **Flow:** After dependency scanning, or as a separate background process. The system analyzes the project's codebase (or key files). It compares code segments against a database of known open-source projects (initially focusing on the dependencies found). Uses techniques like hashing, Abstract Syntax Tree (AST) comparison, or fuzzy matching to identify significant similarities. If a high degree of similarity is found without proper attribution or license compatibility, an issue of type `possible_fork` is logged.
* **Edge Case:** Minor code similarities (e.g., common algorithms, boilerplate), detecting forks of forks, large codebases impacting performance.
* **Compliance Issue Reporting:**
* **Flow:** Identified non-compliance or potential forks generate records in the `complianceIssues` table. Issues are categorized by `issueType` and `severity`. Users can view these issues on their project's dashboard or a dedicated 'Issues' page. Users can mark issues as 'resolved'.
* **Edge Case:** False positives/negatives, outdated issue status.
* **Dashboard Overview:**
* **Flow:** Logged-in user navigates to the Dashboard. Displays a summary of all projects, number of open issues, overall compliance status (e.g., percentage compliant). Provides quick links to view project details and issues. Shows recent scan activity.
* **Edge Case:** No projects added yet (empty state).
**5. API & DATA FETCHING:**
* **Server Actions (Next.js App Router):** Primarily for mutations (creating projects, adding dependencies manually, marking issues as resolved).
* `POST /api/projects`: Create a new project (Server Action).
* `PUT /api/projects/:id`: Update project details (Server Action).
* `DELETE /api/projects/:id`: Delete a project (Server Action).
* `POST /api/issues/:id/resolve`: Mark an issue as resolved (Server Action).
* **API Routes (for background processing/external triggers if needed):**
* `POST /api/scan/:projectId`: Trigger a manual scan for a specific project (initiates background job).
* **Data Fetching (Server Components / Client Components):**
* Use `fetch` within Server Components for initial page loads.
* Use Server Actions for form submissions and mutations.
* For real-time updates or more complex client-side data needs, consider Zustand or Context API combined with Server Actions.
* **Expected Request/Response Bodies:**
* **Project Creation:** `{ name: string, repoUrl: string }` -> `{ id: string, status: 'processing' | 'completed' | 'error', ... }`
* **Scan Trigger:** `{ projectId: string }` -> `{ message: string }`
* **Issue Data:** `{ id: string, projectId: string, dependencyId: string | null, issueType: IssueType, details: string, severity: Severity, resolved: boolean, createdAt: string }`
**6. COMPONENT BREAKDOWN (Next.js App Router Structure):**
```
app/
├── (auth)/ // Authentication routes (login, signup)
│ ├── login/page.tsx
│ └── signup/page.tsx
├── (dashboard)/ // Authenticated user routes
│ ├── layout.tsx // Dashboard layout (sidebar, header)
│ ├── page.tsx // Dashboard overview (summary cards, recent activity)
│ ├── projects/
│ │ ├── page.tsx // List of all projects
│ │ └── [projectId]/
│ │ ├── page.tsx // Project detail page (dependencies, issues)
│ │ └── loading.tsx // Project detail loading state
│ ├── issues/
│ │ └── page.tsx // All compliance issues across projects
│ └── settings/
│ └── page.tsx // User settings (profile, API keys, integrations)
├── api/
│ ├── auth/[...nextauth]/route.ts // NextAuth.js handler
│ └── scan/
│ └── [projectId]/route.ts // Trigger scan API route
├── components/
│ ├── ui/
│ │ ├── button.tsx
│ │ ├── card.tsx
│ │ ├── input.tsx
│ │ ├── label.tsx
│ │ ├── table.tsx // Reusable table component
│ │ ├── dropdown.tsx
│ │ ├── badge.tsx
│ │ └── ... (shadcn/ui components)
│ ├── layout/
│ │ ├── Sidebar.tsx
│ │ ├── Header.tsx
│ │ └── Footer.tsx
│ ├── ProjectCard.tsx
│ ├── DependencyTable.tsx
│ ├── ComplianceIssueRow.tsx
│ ├── ScanProgressBar.tsx
│ ├── AuthButtons.tsx
│ └── ...
├── lib/
│ ├── db.ts // Drizzle ORM setup
│ ├── auth.ts // NextAuth.js options
│ ├── utils.ts // Helper functions
│ └── validators.ts // Zod validation schemas
├── providers/
│ └── QueryProvider.tsx // If using React Query
├── styles/
│ └── globals.css
├── .env
├── next.config.js
├── postcss.config.js
├── tailwind.config.ts
└── tsconfig.json
```
* **Pages:** `page.tsx` files in `app/(dashboard)` and `app/(auth)` folders.
* **Layouts:** `layout.tsx` files for nested routing and shared UI structure.
* **Server Components:** Default for pages and data fetching.
* **Client Components:** Use `'use client';` directive for interactive elements (forms, buttons with state, dynamic UI).
* **State Management:** Local state for UI elements, Context/Zustand for shared global state like user auth status or theme.
**7. UI/UX DESIGN & VISUAL IDENTITY:**
* **Design Style:** "Minimalist Clean" with subtle "Tech Gradient" accents.
* **Color Palette:**
* Primary (Dark Background): `#0D1117` (Dark Gray/Near Black)
* Secondary (Accent): `#161B22` (Slightly Lighter Dark Gray)
* Primary Accent (Gradient): Linear gradient from `#38BDF8` (Sky Blue) to `#818CF8` (Slate Blue) for buttons, highlights.
* Text (Primary): `#C9D1D9` (Light Gray)
* Text (Secondary): `#8B949E` (Muted Gray)
* Success: `#238636` (Green)
* Warning: `#A82F2F` (Red)
* Info: `#0969DA` (Blue)
* **Typography:**
* Headings: Inter (Variable Font, Bold)
* Body Text: Inter (Variable Font, Regular)
* Code/Monospace: Fira Code or Source Code Pro
* **Layout:** Focus on clear information hierarchy. Sidebar for navigation, main content area. Use cards for summaries. Ample whitespace. Responsive design adapting to mobile, tablet, and desktop.
* **Elements:** Use shadcn/ui components for consistency. Subtle hover effects on interactive elements. Clear loading indicators (spinners, skeleton loaders).
* **Responsive Rules:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Ensure readability and usability across all device sizes.
**8. SAMPLE/MOCK DATA:**
* **User:**
```json
{
"id": "user_abc123",
"name": "Alice Developer",
"email": "alice@example.com",
"image": "https://example.com/avatar.jpg"
}
```
* **Project (Processing):**
```json
{
"id": "proj_xyz789",
"userId": "user_abc123",
"name": "Awesome App",
"repoUrl": "https://github.com/alice/awesome-app",
"status": "processing",
"createdAt": "2023-10-27T10:00:00Z"
}
```
* **Project (Completed with Issues):**
```json
{
"id": "proj_def456",
"userId": "user_abc123",
"name": "Utility Library",
"repoUrl": "https://github.com/alice/utility-lib",
"status": "completed",
"createdAt": "2023-10-26T12:00:00Z"
}
```
* **Dependency (Non-Compliant):**
```json
{
"id": "dep_ghi012",
"projectId": "proj_def456",
"name": "LegacyLogger",
"version": "1.0.2",
"license": "GPL-2.0",
"source": "package.json",
"complianceStatus": "non_compliant"
}
```
* **Dependency (Compliant):**
```json
{
"id": "dep_jkl345",
"projectId": "proj_def456",
"name": "React",
"version": "18.2.0",
"license": "MIT",
"source": "package.json",
"complianceStatus": "compliant"
}
```
* **Compliance Issue (Possible Fork):**
```json
{
"id": "issue_mno678",
"dependencyId": null,
"projectId": "proj_def456",
"issueType": "possible_fork",
"details": "Significant code similarity detected with 'SimStudio v0.8.1' without proper attribution. Consider reviewing original license.",
"severity": "high",
"resolved": false,
"createdAt": "2023-10-27T11:00:00Z"
}
```
* **Compliance Issue (Missing Attribution):**
```json
{
"id": "issue_pqr901",
"dependencyId": "dep_ghi012",
"projectId": "proj_def456",
"issueType": "missing_attribution",
"details": "GPL-2.0 licensed dependency 'LegacyLogger' is missing required attribution notices in source code.",
"severity": "medium",
"resolved": false,
"createdAt": "2023-10-27T11:05:00Z"
}
```
**9. TURKISH TRANSLATIONS:**
* **App Title:** Kod Koruyucu
* **Navigation:** Projeler, Sorunlar, Ayarlar, Gösterge Paneli
* **Buttons:** Yeni Proje Ekle, Tara, Kaydet, Çözüldü Olarak İşaretle, Giriş Yap, Kaydol
* **Labels:** Proje Adı, Depo URL'si, Tarama Durumu, Lisans, Sürüm, Sorun Türü, Ciddiyet
* **Titles:** Proje Detayları, Lisans Uyumluluk Raporu, Tespit Edilen Sorunlar
* **Status:** İşleniyor, Tamamlandı, Hata, Uygun, Uygun Değil, Bilinmiyor, Beklemede
* **Issue Types:** Eksik Atıf, Onaylanmamış Lisans, Olası Kopyalama, Güvenlik Açığı
* **Placeholders:** GitHub Depo URL'sini Girin...
* **Empty States:** Henüz proje eklenmedi. İlk projenizi taramaya başlayın!
**10. ANIMATIONS:**
* **Page Transitions:** Subtle fade-in/out using Next.js `AnimatePresence` (if using Framer Motion) or CSS transitions on route changes.
* **Hover Effects:** Slight scale-up or color change on buttons and interactive cards.
* **Loading States:** Use shadcn/ui's `Skeleton` component or a simple CSS spinner (`@keyframes spin`) for data loading. Indicate processing with subtle progress bars or spinners.
* **Background Gradient:** Subtle, slow-moving background gradient animation on the landing page or login screens.
**11. EDGE CASES & VALIDATION:**
* **Authentication:** Handle expired sessions, invalid tokens, unauthorized access attempts gracefully (redirects, error messages).
* **Repository Access:** Implement robust error handling for private repositories (prompt for access token), non-existent URLs, network errors during cloning/fetching.
* **License Parsing:** Handle cases with multiple licenses, custom licenses, or missing `LICENSE` files. Default to 'unknown' or 'non_compliant' with clear warnings.
* **Code Similarity:** Implement thresholds for similarity detection to minimize false positives. Allow users to dismiss false positives.
* **Empty States:** Design informative empty states for the dashboard, project list, and issues pages when no data is available.
* **Rate Limiting:** Respect API rate limits of external services (GitHub API, npm registry). Implement exponential backoff or queuing strategies.
* **Form Validation:** Use Zod with React Hook Form for client-side and server-side validation of all user inputs (project names, URLs, settings).
* **Error Handling:** Global error handling mechanism (e.g., using Error Boundaries in React) and specific error messages for API failures or processing errors.