## AI Master Prompt for SecureScan MVP Development
**PROJECT OVERVIEW:**
SecureScan is a proactive cybersecurity SaaS platform designed to protect individuals and organizations from sophisticated digital threats, inspired by real-world incidents like the Iran-linked breach of the FBI director's personal email. The application provides a continuous monitoring service for digital assets, identifies potential security vulnerabilities, detects suspicious activities, and alerts users in real-time. Its core value proposition is to offer peace of mind by providing a robust, intelligent, and user-friendly shield against evolving cyber threats, minimizing the risk of data breaches and unauthorized access. SecureScan aims to democratize advanced cybersecurity by making it accessible and actionable for a wider audience.
**TECH STACK:**
- **Framework:** Next.js (App Router)
- **Language:** TypeScript
- **Styling:** Tailwind CSS
- **ORM:** Drizzle ORM (PostgreSQL compatible)
- **Database:** PostgreSQL
- **Authentication:** NextAuth.js (with PostgreSQL adapter)
- **UI Components:** shadcn/ui (built on Radix UI and Tailwind CSS)
- **State Management:** React Context API / Zustand (for global state)
- **Form Handling:** React Hook Form + Zod for validation
- **API Layer:** Next.js API Routes (Server Actions for mutations)
- **Deployment:** Vercel (recommended)
- **Other:** Axios (for external API calls if needed), React-Icons, Date-fns
**DATABASE SCHEMA (PostgreSQL with Drizzle ORM):**
1. **`users` Table:**
* `id` (UUID, Primary Key)
* `name` (VARCHAR(255))
* `email` (VARCHAR(255), Unique, Not Null)
* `emailVerified` (TIMESTAMP WITH TIME ZONE)
* `image` (VARCHAR(255))
* `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
* `updatedAt` (TIMESTAMP WITH TIME ZONE, Default: now())
2. **`accounts` Table (for NextAuth.js):**
* `id` (BIGSERIAL, Primary Key)
* `userId` (UUID, Foreign Key to `users.id`)
* `type` (VARCHAR(255) NOT NULL)
* `provider` (VARCHAR(255) NOT NULL)
* `providerAccountId` (VARCHAR(255) NOT NULL)
* `refresh_token` (TEXT)
* `access_token` (TEXT)
* `expires_at` (BIGINT)
* `token_type` (VARCHAR(255))
* `scope` (VARCHAR(255))
* `id_token` (TEXT)
* `session_state` (VARCHAR(255))
* `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
* `updatedAt` (TIMESTAMP WITH TIME ZONE, Default: now())
* **Unique Constraint:** (`provider`, `providerAccountId`)
3. **`sessions` Table (for NextAuth.js):**
* `sessionToken` (VARCHAR(255), Primary Key)
* `userId` (UUID, Foreign Key to `users.id`)
* `expires` (TIMESTAMP WITH TIME ZONE, Not Null)
* `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
* `updatedAt` (TIMESTAMP WITH TIME ZONE, Default: now())
4. **`verificationTokens` Table (for NextAuth.js):**
* `identifier` (VARCHAR(255), Not Null)
* `token` (VARCHAR(255), Primary Key)
* `expires` (TIMESTAMP WITH TIME ZONE, Not Null)
* `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
5. **`monitored_assets` Table:**
* `id` (UUID, Primary Key)
* `userId` (UUID, Foreign Key to `users.id`, Not Null)
* `assetType` (VARCHAR(50) NOT NULL, e.g., 'email', 'domain', 'social_profile')
* `assetIdentifier` (VARCHAR(255) NOT NULL, e.g., 'user@example.com', 'example.com')
* `status` (VARCHAR(50) Default: 'active')
* `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
* `updatedAt` (TIMESTAMP WITH TIME ZONE, Default: now())
* **Unique Constraint:** (`userId`, `assetType`, `assetIdentifier`)
6. **`security_alerts` Table:**
* `id` (UUID, Primary Key)
* `userId` (UUID, Foreign Key to `users.id`, Not Null)
* `assetId` (UUID, Foreign Key to `monitored_assets.id`)
* `alertType` (VARCHAR(100) NOT NULL, e.g., 'suspicious_login', 'data_breach_detected', 'vulnerability_found', 'phishing_attempt')
* `description` (TEXT NOT NULL)
* `severity` (VARCHAR(20) NOT NULL, e.g., 'low', 'medium', 'high', 'critical')
* `source` (VARCHAR(255))
* `timestamp` (TIMESTAMP WITH TIME ZONE, Not Null, Default: now())
* `isRead` (BOOLEAN, Default: false)
* `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
7. **`risk_reports` Table:**
* `id` (UUID, Primary Key)
* `userId` (UUID, Foreign Key to `users.id`, Not Null)
* `reportDate` (DATE, Not Null)
* `overallScore` (INTEGER)
* `summary` (TEXT)
* `details` (JSONB)
* `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
**CORE FEATURES & USER FLOW:**
1. **User Authentication:**
* **Flow:** User lands on the homepage. Clicks 'Sign Up' or 'Login'. Presented with options: Email/Password, Google OAuth, GitHub OAuth. Upon successful authentication via chosen method, user is redirected to the dashboard. If new user, an initial onboarding process might start (e.g., adding first asset to monitor).
* **Details:** Utilize NextAuth.js with a database adapter for secure session management. Email/Password requires robust validation and hashing. OAuth flows must handle callback URLs and state parameters securely.
2. **Asset Onboarding:**
* **Flow:** Authenticated user navigates to 'My Assets' or a dedicated 'Add Asset' section. Selects asset type (e.g., Email Address). Enters the identifier (e.g., `user@example.com`). The system validates the input format and adds it to the `monitored_assets` table associated with the user.
* **Details:** For email monitoring, this might involve instructing the user to set up forwarding or API access (with clear security warnings). For domain monitoring, DNS verification might be needed. For this MVP, focus on email and potentially domain monitoring.
3. **Security Monitoring & Alerting:**
* **Flow:** Background processes (or scheduled serverless functions/cron jobs) periodically scan monitored assets for threats.
* **Email:** Check against known breach databases (e.g., Have I Been Pwned API), analyze login patterns (if integrated with provider APIs or using logs), detect suspicious email headers/links (requires external service integration or pattern matching).
* **Dark Web Monitoring:** Scan breach data for user's email/identifiers.
* **Vulnerability Scanning:** Basic checks for exposed ports or known CVEs associated with services linked to the user's domain (if applicable).
* **Detection:** If a threat is detected (e.g., email found in a data breach, suspicious login attempt detected via IP/timing analysis), a new entry is created in the `security_alerts` table.
* **Notification:** The system sends an in-app notification (and potentially email notification if configured) to the user about the new alert. Alerts have severity levels (low, medium, high, critical).
4. **Alert Management:**
* **Flow:** User navigates to the 'Alerts' page. Sees a list of all triggered alerts, sortable/filterable by date, severity, type, and read status. User can click on an alert to view full details (description, source, timestamp). User can mark alerts as 'Read'.
* **Details:** Frontend displays alerts fetched from the `security_alerts` table. Implement pagination for long lists. Filtering and sorting logic handled client-side or server-side depending on performance needs.
5. **Risk Report Generation:**
* **Flow:** User can request a 'Security Risk Report' from their dashboard or settings. The system compiles data from monitored assets and recent alerts. Generates a score and a summary. Report is stored in `risk_reports` table and presented to the user. The report might include: number of monitored assets, number of critical alerts, data breach count, overall risk score.
* **Details:** This feature involves aggregating data. For MVP, a simplified calculation based on the number and severity of active alerts and detected breaches is sufficient.
**API & DATA FETCHING:**
- **Next.js API Routes / Server Actions:** Used for all backend logic.
- **Authentication:** Handled by NextAuth.js, provides `session` object available on both client and server.
- **CRUD Operations:** Server Actions (recommended for mutations) or API routes for:
* `POST /api/assets`: Add a new monitored asset.
* `DELETE /api/assets/[id]`: Remove a monitored asset.
* `GET /api/assets`: Fetch all monitored assets for the user.
* `GET /api/alerts`: Fetch alerts for the user (with filtering/pagination params).
* `PUT /api/alerts/[id]`: Mark an alert as read.
* `POST /api/reports`: Trigger generation of a risk report.
* `GET /api/reports`: Fetch user's risk reports.
- **Data Fetching (Client):** Use `fetch` within Server Components (for static rendering or dynamic rendering with caching) or `useEffect` with `fetch`/Axios in Client Components (for dynamic data). Utilize SWR or React Query for client-side caching and revalidation if complex state management is needed.
- **Request/Response:** Standard JSON payloads. Use Zod for request validation on API routes and Server Actions.
**COMPONENT BREAKDOWN (Next.js App Router):**
- **`app/layout.tsx`:** Root layout, includes HTML head, body, global providers (e.g., ThemeProvider, QueryClientProvider if using SWR/RQ), Tailwind CSS setup, global styles.
- **`app/page.tsx`:** Landing Page. Hero section, features overview, call to action (CTA).
- **`app/(auth)/login/page.tsx`:** Login page with email/password and OAuth options.
- **`app/(auth)/signup/page.tsx`:** Sign up page.
- **`app/(auth)/layout.tsx`:** Auth layout wrapper (e.g., centered card).
- **`app/dashboard/layout.tsx`:** Main application layout wrapper, including Sidebar, Header/Navbar, Content area.
- **`app/dashboard/page.tsx`:** Dashboard Overview. Summary cards (active alerts, recent activity, risk score), quick links to add assets or view alerts.
- **`app/dashboard/assets/page.tsx`:** My Assets Page. List of monitored assets, ability to add/remove. Each asset might show its current status or last scan time.
* **Components:** `AssetList`, `AssetCard`, `AddAssetForm`.
- **`app/dashboard/alerts/page.tsx`:** Alerts Page. Detailed list of security alerts.
* **Components:** `AlertList`, `AlertTable`, `AlertDetailModal`.
- **`app/dashboard/reports/page.tsx`:** Risk Reports Page. List of generated reports, option to generate a new one.
* **Components:** `ReportList`, `ReportViewer`, `GenerateReportButton`.
- **`app/dashboard/settings/page.tsx`:** User Settings. Profile management, notification preferences, security settings, account management (linked accounts).
* **Components:** `ProfileForm`, `NotificationSettingsForm`.
- **`app/components/ui/`:** Re-usable shadcn/ui components (Button, Input, Card, Table, Sheet, Dialog, etc.).
- **`app/components/`:** Custom application components (e.g., `Sidebar`, `Navbar`, `DashboardCard`, `ChartComponent` for future enhancements).
- **`app/api/auth/[...nextauth]/route.ts`:** NextAuth.js route handler.
- **`app/lib/`:** Utility functions, database access layer (Drizzle), validation schemas (Zod).
**UI/UX DESIGN & VISUAL IDENTITY:**
- **Design Style:** Modern Minimalist with a focus on clarity and trust. Dark theme primarily, with an optional light theme. Use of subtle gradients and clean lines.
- **Color Palette:**
* Primary (Dark Mode): `#1E1E1E` (Background), `#FAFAFA` (Text)
* Primary (Light Mode): `#FFFFFF` (Background), `#121212` (Text)
* Accent/Brand: `#3498DB` (Primary Blue - for CTAs, active states, links)
* Secondary Accent: `#2ECC71` (Green - for success, positive indicators)
* Warning/Alert: `#E74C3C` (Red - for critical alerts, errors)
* Info/Neutral: `#F39C12` (Orange - for medium severity, warnings)
* Subtle Backgrounds/Borders: `#2C2C2E` (Dark Mode), `#F0F0F0` (Light Mode)
- **Typography:** A clean, sans-serif font family. 'Inter' or 'Poppins'.
* Headings: Bold, larger sizes (e.g., `font-bold text-3xl`)
* Body Text: Regular weight, standard sizes (e.g., `text-base`)
- **Layout:**
* **Dashboard:** Sidebar navigation on the left, main content area on the right. Use of cards for summarizing information.
* **Responsive:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content reflows gracefully. Use of CSS Grid and Flexbox extensively.
* **Spacing:** Consistent use of Tailwind's spacing scale (e.g., `p-4`, `m-2`, `space-y-4`).
- **Visual Elements:** Subtle use of icons (e.g., from Lucide React/Heroicons) to denote actions and information types. Loading spinners and skeleton loaders for data fetching.
**ANIMATIONS:**
- **Page Transitions:** Subtle fade-in/fade-out transitions between pages using Next.js `Layout Router` and a library like `Framer Motion` or CSS transitions.
- **Hover Effects:** Slight scale-up or background color change on interactive elements (buttons, links, cards).
- **Loading States:** Skeleton loaders on components while data is being fetched. Spinner indicators for asynchronous actions (e.g., submitting forms, generating reports).
- **Micro-interactions:** Smooth transitions for dropdowns, modals, and slide-in panels.
**EDGE CASES:**
- **Authentication:** Handling expired sessions, failed login attempts (rate limiting), invalid credentials, OAuth errors.
- **Empty States:** Displaying user-friendly messages and clear calls to action when lists are empty (e.g., 'No assets monitored yet. Add your first asset!', 'No alerts found. Stay vigilant!').
- **Data Validation:** Implementing robust server-side and client-side validation for all user inputs (forms, API requests) using Zod.
- **Error Handling:** Graceful error handling on both frontend (displaying user-friendly error messages) and backend (logging errors, returning appropriate HTTP status codes). Implement a global error boundary component.
- **API Rate Limiting:** Protect backend endpoints from abuse.
- **Data Integrity:** Ensure data consistency, especially during concurrent operations or updates.
- **Permissions:** Ensure users can only access their own data.
**SAMPLE/MOCK DATA:**
1. **User:**
```json
{
"id": "uuid-user-1",
"name": "Ahmet Yilmaz",
"email": "ahmet.yilmaz@example.com",
"emailVerified": "2023-10-26T10:00:00Z",
"image": "/images/avatars/ahmet.png"
}
```
2. **Monitored Asset (Email):**
```json
{
"id": "uuid-asset-email-1",
"userId": "uuid-user-1",
"assetType": "email",
"assetIdentifier": "ahmet.yilmaz@example.com",
"status": "active",
"createdAt": "2024-01-15T08:30:00Z"
}
```
3. **Monitored Asset (Domain - Future potential):**
```json
{
"id": "uuid-asset-domain-1",
"userId": "uuid-user-1",
"assetType": "domain",
"assetIdentifier": "yilmazcorp.com",
"status": "active",
"createdAt": "2024-01-15T08:35:00Z"
}
```
4. **Security Alert (High Severity):**
```json
{
"id": "uuid-alert-1",
"userId": "uuid-user-1",
"assetId": "uuid-asset-email-1",
"alertType": "data_breach_detected",
"description": "Your email address was found in a data breach containing passwords and personal information from 'ExampleBreach.com' (10M records).",
"severity": "high",
"source": "Have I Been Pwned API",
"timestamp": "2024-01-20T14:05:00Z",
"isRead": false
}
```
5. **Security Alert (Medium Severity):**
```json
{
"id": "uuid-alert-2",
"userId": "uuid-user-1",
"assetId": "uuid-asset-email-1",
"alertType": "suspicious_login",
"description": "Unusual login attempt detected from IP address 198.51.100.1 (Location: Unknown). Timing is atypical for your usual activity.",
"severity": "medium",
"source": "Email Provider Logs (Simulated)",
"timestamp": "2024-01-19T23:15:00Z",
"isRead": false
}
```
6. **Risk Report:**
```json
{
"id": "uuid-report-1",
"userId": "uuid-user-1",
"reportDate": "2024-01-20",
"overallScore": 65, // Scale of 0-100
"summary": "Your digital security posture is moderate. Several data breaches have been detected involving your email address. Increased vigilance is recommended.",
"details": {
"breachCount": 2,
"suspiciousLogins": 1,
"criticalAlerts": 0,
"mediumAlerts": 1,
"lowAlerts": 0
}
}
```
7. **User (Another User for testing):**
```json
{
"id": "uuid-user-2",
"name": "Ayse Demir",
"email": "ayse.demir@company.com",
"emailVerified": "2023-11-01T09:00:00Z",
"image": null
}
```
8. **Security Alert (Low Severity):**
```json
{
"id": "uuid-alert-3",
"userId": "uuid-user-1",
"assetId": null, // General alert
"alertType": "phishing_attempt_detected",
"description": "A known phishing email was detected in your inbox targeting financial information. Consider marking it as spam.",
"severity": "low",
"source": "Email Provider Filter",
"timestamp": "2024-01-21T09:00:00Z",
"isRead": false
}
```
**TURKISH TRANSLATIONS (Key UI Elements):**
* **App Title:** Güvenli Tarama (Secure Scan)
* **Dashboard:** Kontrol Paneli
* **My Assets:** Varlıklarım
* **Alerts:** Uyarılar
* **Reports:** Raporlar
* **Settings:** Ayarlar
* **Login:** Giriş Yap
* **Sign Up:** Kayıt Ol
* **Add Asset:** Varlık Ekle
* **Email Address:** E-posta Adresi
* **Domain:** Alan Adı
* **Status:** Durum
* **Active:** Aktif
* **Severity:** Önem Derecesi
* **Low:** Düşük
* **Medium:** Orta
* **High:** Yüksek
* **Critical:** Kritik
* **View Details:** Detayları Gör
* **Mark as Read:** Okundu Olarak İşaretle
* **Generate Report:** Rapor Oluştur
* **No data available:** Veri mevcut değil
* **Loading...:** Yükleniyor...
* **Suspicious Login:** Şüpheli Giriş
* **Data Breach Detected:** Veri Sızıntısı Tespit Edildi
* **Vulnerability Found:** Zafiyet Bulundu
* **Phishing Attempt:** Oltalama Girişimi Algılandı
* **Save Changes:** Değişiklikleri Kaydet
* **Notification Preferences:** Bildirim Tercihleri
* **Account Management:** Hesap Yönetimi
* **Sign Out:** Çıkış Yap
* **Hero Title:** Dijital Varlıklarınızı Güvence Altına Alın
* **Hero Subtitle:** Siber tehditlere karşı proaktif koruma ve gerçek zamanlı uyarılar. Güvenliğinizi bugün sağlayın.