# PROJECT OVERVIEW
BotGuard Pro is a SaaS platform designed to protect websites and online services from aggressive bot traffic and web scraping attacks. Inspired by systems like Hacker News's Anubis, it leverages an AI-enhanced, user-friendly Proof-of-Work (PoW) mechanism to deter malicious bots while minimizing friction for legitimate users. The core value proposition is to provide robust, automated bot mitigation and security without requiring deep technical expertise, offering real-time threat analysis, detailed reporting, and seamless integration with popular web platforms.
# TECH STACK
- **Frontend:** React with Next.js (App Router)
- **Styling:** Tailwind CSS
- **ORM:** Drizzle ORM (PostgreSQL)
- **UI Components:** shadcn/ui
- **Authentication:** NextAuth.js (or Clerk for simplicity)
- **State Management:** Zustand or React Context API
- **API Layer:** Next.js API Routes (or tRPC for type safety)
- **Database:** PostgreSQL
- **Deployment:** Vercel (recommended)
- **Additional Packages:** `axios` (for external API calls if needed), `react-hook-form` (for forms), `zod` (for validation), `date-fns` (for date manipulation), `chart.js` or `recharts` (for dashboards).
# DATABASE SCHEMA
## 1. `users` Table
- `id` (UUID, Primary Key)
- `email` (VARCHAR, Unique, Not Null)
- `hashedPassword` (VARCHAR, Nullable - for email/password auth)
- `name` (VARCHAR, Nullable)
- `avatarUrl` (VARCHAR, Nullable)
- `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
- `updatedAt` (TIMESTAMP WITH TIME ZONE, Default: now())
- `stripeCustomerId` (VARCHAR, Nullable, Unique) - For payment integration
## 2. `accounts` Table (for NextAuth.js)
- `id` (VARCHAR, Primary Key)
- `userId` (UUID, Foreign Key to users.id, Not Null)
- `type` (VARCHAR, Not Null) - e.g., 'oauth', 'email'
- `provider` (VARCHAR, Not Null)
- `providerAccountId` (VARCHAR, Not Null)
- `refresh_token` (TEXT, Nullable)
- `access_token` (TEXT, Nullable)
- `expires_at` (TIMESTAMP WITH TIME ZONE, Nullable)
- `token_type` (VARCHAR, Nullable)
- `scope` (VARCHAR, Nullable)
- `id_token` (TEXT, Nullable)
- `session_token` (VARCHAR, Unique, Not Null)
## 3. `sessions` Table (for NextAuth.js)
- `sessionToken` (VARCHAR, Primary Key)
- `userId` (UUID, Foreign Key to users.id, Not Null)
- `expires` (TIMESTAMP WITH TIME ZONE, Not Null)
## 4. `verificationTokens` Table (for NextAuth.js)
- `identifier` (VARCHAR, Not Null)
- `token` (VARCHAR, Not Null)
- `expires` (TIMESTAMP WITH TIME ZONE, Not Null)
## 5. `websites` Table
- `id` (UUID, Primary Key)
- `userId` (UUID, Foreign Key to users.id, Not Null)
- `url` (VARCHAR, Not Null)
- `name` (VARCHAR, Not Null) - User-friendly name for the website
- `protectionLevel` (VARCHAR, Default: 'medium') - e.g., 'low', 'medium', 'high'
- `status` (VARCHAR, Default: 'active') - e.g., 'active', 'paused', 'deleted'
- `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
- `updatedAt` (TIMESTAMP WITH TIME ZONE, Default: now())
## 6. `botEvents` Table
- `id` (UUID, Primary Key)
- `websiteId` (UUID, Foreign Key to websites.id, Not Null)
- `timestamp` (TIMESTAMP WITH TIME ZONE, Default: now())
- `ipAddress` (VARCHAR, Not Null)
- `userAgent` (TEXT, Nullable)
- `eventType` (VARCHAR, Not Null) - e.g., 'blocked_pow', 'detected_scraping', 'malicious_request'
- `details` (JSONB, Nullable) - Further details about the event
## 7. `plans` Table
- `id` (VARCHAR, Primary Key) - e.g., 'free', 'pro', 'enterprise'
- `name` (VARCHAR, Not Null)
- `priceId` (VARCHAR, Nullable) - Stripe Price ID
- `priceMonthly` (INTEGER, Not Null) - Price in cents
- `maxWebsites` (INTEGER, Not Null)
- `maxBandwidthGB` (INTEGER, Not Null)
- `advancedReporting` (BOOLEAN, Default: false)
- `prioritySupport` (BOOLEAN, Default: false)
## 8. `subscriptions` Table
- `id` (UUID, Primary Key)
- `userId` (UUID, Foreign Key to users.id, Not Null)
- `planId` (VARCHAR, Foreign Key to plans.id, Not Null)
- `stripeSubscriptionId` (VARCHAR, Nullable, Unique)
- `status` (VARCHAR, Not Null) - e.g., 'active', 'canceled', 'past_due'
- `currentPeriodEnd` (TIMESTAMP WITH TIME ZONE, Nullable)
- `createdAt` (TIMESTAMP WITH TIME ZONE, Default: now())
- `updatedAt` (TIMESTAMP WITH TIME ZONE, Default: now())
**Relationships:**
- `users` 1:N `websites`
- `users` 1:N `subscriptions`
- `websites` 1:N `botEvents`
- `plans` N:1 `subscriptions`
- `users` 1:N `accounts` (via NextAuth)
- `users` 1:1 `sessions` (via NextAuth)
# CORE FEATURES & USER FLOW
## 1. User Authentication & Onboarding
- **Flow:**
1. User signs up via email/password or OAuth (Google/GitHub).
2. Upon first login, user is prompted to add their first website.
3. User enters website URL and a friendly name.
4. System generates a unique JavaScript snippet (or a server-side configuration for specific platforms).
5. User is guided on how to integrate the snippet/configuration into their website (e.g., via `<head>` tag, theme file, or plugin settings).
6. User's website is added to their dashboard with 'pending verification' status.
7. Once the snippet is detected, the status changes to 'active'.
- **Edge Cases:** Invalid URL, failed snippet verification, OAuth connection errors.
## 2. Bot Protection (Proof-of-Work Challenge)
- **Flow:**
1. A new, unverified visitor arrives at the protected website.
2. The BotGuard Pro JS snippet on the website initiates a client-side Proof-of-Work (PoW) calculation (e.g., hashing a complex string with a nonce until a target difficulty is met).
3. Upon successful completion, the browser sends a token to the backend API.
4. Backend verifies the token and the PoW solution.
5. If valid, the visitor is marked as 'human' (or 'verified bot' if applicable) for a certain session duration, and their request is allowed to proceed to the website.
6. If the PoW fails or times out, the request is blocked, and a `botEvent` is logged.
- **Customization:** Users can configure the PoW difficulty (influencing calculation time vs. bot deterrence) and duration of the 'verified' status.
- **Edge Cases:** JavaScript disabled in browser, slow client devices, high PoW difficulty, invalid token submission.
## 3. Threat Analysis & Reporting Dashboard
- **Flow:**
1. User logs into their BotGuard Pro dashboard.
2. Dashboard displays an overview: total threats blocked, current active threats, website status, subscription info.
3. A dedicated 'Reports' or 'Logs' section shows a chronological list of `botEvents`.
4. Users can filter events by date range, website, event type (blocked PoW, detected scraping patterns, etc.), and IP address.
5. Visualizations (charts) show trends over time, top offending IPs, and bot types.
6. Users can view detailed information for each event, including IP, User-Agent (if available), timestamp, and specific details.
- **Edge Cases:** No events logged yet (empty state), large datasets requiring pagination and efficient querying.
## 4. Website Management
- **Flow:**
1. User navigates to the 'Websites' section.
2. User can add new websites, view existing ones, edit their names or protection levels, pause/resume protection, or delete them.
3. For each website, the current status (active, inactive, verification pending) and the associated protection level are displayed.
- **Edge Cases:** User trying to delete a website with active subscription, managing limits based on subscription plan.
## 5. Subscription Management
- **Flow:**
1. User navigates to the 'Billing' or 'Subscription' section.
2. User can view their current plan, upgrade/downgrade, or cancel their subscription.
3. Integration with Stripe for secure payment processing.
4. Display usage relative to plan limits (e.g., number of websites protected).
- **Edge Cases:** Payment failures, subscription renewals, Stripe webhooks for status updates.
# API & DATA FETCHING
- **API Routes (Next.js App Router structure):**
- `POST /api/websites`: Add a new website.
- `GET /api/websites`: Get list of user's websites.
- `PUT /api/websites/[id]`: Update a website's settings (name, protection level).
- `DELETE /api/websites/[id]`: Delete a website.
- `POST /api/verify-pow`: Endpoint for website visitors to submit PoW results.
- `GET /api/events`: Get bot event logs (with filtering/pagination).
- `GET /api/dashboard/summary`: Get aggregated data for the main dashboard.
- `POST /api/webhooks/stripe`: Handle Stripe payment events.
- **Data Fetching:**
- Frontend components will use server components where possible for initial data load (e.g., dashboard summary, website list).
- Client components will fetch dynamic data (e.g., event logs, real-time updates) using `fetch` or libraries like `swr` or `react-query` within `useEffect` or event handlers.
- API routes will interact with Drizzle ORM to query/mutate the PostgreSQL database.
- **Request/Response Examples:**
- `POST /api/verify-pow`:
- Request Body: `{ websiteId: string, token: string, nonce: string }`
- Response (Success): `{ success: true, message: 'Verified', sessionId: string }`
- Response (Error): `{ success: false, message: 'Invalid token' }`
- `GET /api/events?websiteId=...&startDate=...`:
- Response: `{ events: BotEvent[], pagination: { nextPage: number | null, totalPages: number } }`
# COMPONENT BREAKDOWN (Next.js App Router)
- **`app/page.tsx` (Landing Page):** Public facing marketing page. (Note: This is NOT the main app interface).
- **`app/layout.tsx`:** Root layout, includes global styles, providers (e.g., ThemeProvider, AuthProvider).
- **`app/(auth)/layout.tsx`:** Layout for auth pages (login, signup).
- **`app/(auth)/login/page.tsx`:** Login form component.
- **`app/(auth)/signup/page.tsx`:** Signup form component.
- **`app/(app)/layout.tsx`:** Main application layout (authenticated users).
- **`app/(app)/dashboard/page.tsx`:** Main dashboard. Fetches summary data. Uses `ChartComponent`, `StatsCardComponent`.
- **`app/(app)/websites/page.tsx`:** Manages user's websites. Uses `WebsiteList`, `AddWebsiteForm`, `WebsiteListItem`.
- **`app/(app)/websites/[id]/page.tsx`:** Detail page for a specific website. Shows stats, events, settings for that site. Uses `WebsiteStatsChart`, `EventLogTable`.
- **`app/(app)/billing/page.tsx`:** Subscription and payment management. Uses `PlanSelector`, `BillingDetails`, `StripePaymentForm`.
- **`app/(app)/settings/page.tsx`:** User profile and account settings. Uses `ProfileForm`, `AccountSecurity`.
- **`components/ui/`:** Re-usable shadcn/ui components (Button, Card, Input, Table, Dialog, etc.).
- **`components/layout/`:** `Navbar`, `Sidebar`, `Footer` components.
- **`components/charts/`:** `ChartComponent` (using Recharts or Chart.js).
- **`components/forms/`:** `AddWebsiteForm`, `ProfileForm`, `LoginForm`.
- **`components/table/`:** `EventLogTable` (with sorting, filtering, pagination).
- **`components/providers/`:** `AuthProvider`, `ThemeProvider`.
- **`lib/`:** Utility functions, API clients, ORM configuration.
- **`hooks/`:** Custom React hooks (e.g., `usePoW`, `useFetch`).
**State Management:**
- Global state (auth status, user profile) via AuthProvider/Zustand.
- UI state (form inputs, modal open/closed) managed locally within components.
- Server/API state (dashboard data, event logs) fetched and managed via `useSWR` or similar, or directly in Server Components.
# UI/UX DESIGN & VISUAL IDENTITY
- **Design Style:** Minimalist Clean with a touch of futuristic/tech aesthetic. Focus on clarity, usability, and trust.
- **Color Palette:**
- Primary: Deep Blue (`#1E3A8A` - slate-800)
- Secondary: Cyan/Teal accent (`#06B6D4` - cyan-400)
- Background: Dark Grey (`#1F2937` - gray-800)
- Surface/Card Background: Slightly lighter Dark Grey (`#374151` - gray-700)
- Text (Primary): Light Grey/Off-white (`#E5E7EB` - gray-300)
- Text (Secondary): Muted Grey (`#9CA3AF` - gray-400)
- Success: Green (`#10B981` - green-500)
- Warning/Error: Red (`#EF4444` - red-500)
- **Typography:** Sans-serif font like Inter or Roboto. Clear hierarchy using font weights and sizes.
- Headings: Inter Bold (e.g., 2rem, 1.5rem, 1.25rem)
- Body Text: Inter Regular (e.g., 1rem)
- **Layout:**
- Dashboard uses a sidebar for navigation and a main content area.
- Consistent spacing and padding using Tailwind's spacing scale.
- Use of cards to group related information.
- Responsive design: Mobile-first approach, adapting layout for tablets and desktops.
- **Visual Elements:** Clean icons, subtle gradients on accent elements, clear data visualizations (charts).
# ANIMATIONS
- **Page Transitions:** Subtle fade-in/out transitions between pages using Next.js `transition` utilities or a library like `Framer Motion`.
- **Component Mount/Unmount:** Fade-in animations for elements like cards, table rows, or modals appearing.
- **Loading States:** Skeleton loaders or subtle spinners (`lucide-react` icons) while data is being fetched. Use Tailwind's `animate-spin`.
- **Hover Effects:** Subtle background color changes or slight scaling on buttons and interactive elements.
- **Form Validation:** Inline error messages appear with a quick fade-in animation.
# EDGE CASES
- **Authentication:** Handle expired sessions, OAuth errors, password reset flows.
- **Authorization:** Ensure users can only access their own websites and data (using middleware and checks in API routes/Server Components).
- **Empty States:** Display user-friendly messages and calls to action when lists are empty (e.g., "No websites added yet. Add your first website!", "No bot events recorded.").
- **Error Handling:** Graceful error handling for API failures, displaying user-friendly error messages. Use `try...catch` blocks extensively. Implement global error boundary.
- **Validation:** Robust server-side and client-side validation for all user inputs (website URLs, form fields) using Zod.
- **Rate Limiting:** Implement rate limiting on API routes to prevent abuse.
- **Scalability:** Design database queries and API logic to be efficient, considering potential high traffic.
- **JavaScript Disabled:** Provide a fallback message or basic functionality warning if a user's browser has JavaScript disabled, explaining that bot protection may not work optimally.
# SAMPLE/MOCK DATA
**1. User Data:**
```json
{
"id": "d3f4a5b1-e6c8-4a9d-8f1e-2b3c4d5e6f7a",
"email": "user@example.com",
"name": "Jane Doe",
"stripeCustomerId": "cus_abcdef123456",
"plan": "pro"
}
```
**2. Website Data:**
```json
{
"id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"userId": "d3f4a5b1-e6c8-4a9d-8f1e-2b3c4d5e6f7a",
"url": "https://example-shop.com",
"name": "My Awesome Shop",
"protectionLevel": "high",
"status": "active"
}
```
**3. Bot Event Data (Blocked PoW):**
```json
{
"id": "f1e2d3c4-b5a6-7c8d-9e0f-1a2b3c4d5e6f",
"websiteId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"timestamp": "2024-07-28T10:30:00Z",
"ipAddress": "192.168.1.101",
"userAgent": "Mozilla/5.0 (compatible; BadBot/1.0; +http://badbot.com/info)",
"eventType": "blocked_pow",
"details": {"difficulty": 100000}
}
```
**4. Bot Event Data (Detected Scraping):**
```json
{
"id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f",
"websiteId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"timestamp": "2024-07-28T11:00:00Z",
"ipAddress": "203.0.113.45",
"userAgent": "Python-urllib/3.9",
"eventType": "detected_scraping",
"details": {"pattern": "repeated_high_frequency_requests"}
}
```
**5. Dashboard Summary Data:**
```json
{
"totalThreatsBlocked": 1578,
"activeThreats": 23,
"websitesProtected": 5,
"currentPlan": "pro"
}
```
**6. Subscription Data:**
```json
{
"id": "g1h2i3j4-k5l6-7m8n-9o0p-1q2r3s4t5u6v",
"userId": "d3f4a5b1-e6c8-4a9d-8f1e-2b3c4d5e6f7a",
"planId": "pro",
"status": "active",
"currentPeriodEnd": "2025-07-28T00:00:00Z"
}
```
**7. Plan Data:**
```json
{
"id": "pro",
"name": "Professional",
"priceMonthly": 2900, // $29.00
"maxWebsites": 10,
"maxBandwidthGB": 50,
"advancedReporting": true,
"prioritySupport": false
}
```
**8. User Data (OAuth):**
```json
{
"id": "xyz789abc-1234-5678-9def-0123456789ab",
"email": "oauthuser@gmail.com",
"name": "OAuth User",
"stripeCustomerId": null, // Might be populated later
"plan": "free"
}
```
**9. Website Data (Inactive):**
```json
{
"id": "b7c8d9e0-f1a2-3b4c-5d6e-7f8a9b0c1d2e",
"userId": "d3f4a5b1-e6c8-4a9d-8f1e-2b3c4d5e6f7a",
"url": "https://my-blog.net",
"name": "My Personal Blog",
"protectionLevel": "medium",
"status": "inactive" // e.g., snippet not verified yet
}
```
**10. Bot Event Data (Malicious Request):**
```json
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"websiteId": "b7c8d9e0-f1a2-3b4c-5d6e-7f8a9b0c1d2e",
"timestamp": "2024-07-29T08:15:00Z",
"ipAddress": "198.51.100.77",
"userAgent": "curl/7.68.0",
"eventType": "malicious_request",
"details": {"reason": "unusual_request_pattern"}
}
```