PROJECT OVERVIEW:
Develop a single-page Single Page Application (SPA) frontend for 'Miasma', a novel defense tool designed to protect websites from AI web scrapers. AI companies continuously scrape the internet at an enormous scale, ingesting public content for training data. Miasma aims to empower website owners to fight back by deploying a server that traps malicious AI scrapers in an endless loop. It achieves this by serving poisoned training data and self-referential links, effectively wasting the scraper's resources and polluting their datasets. The core value proposition is to provide an accessible, efficient, and resource-light solution for website owners to defend their content against unauthorized AI data harvesting, without incurring significant computational overhead.
TECH STACK:
- Frontend Framework: React.js (using Vite for fast development server and build process)
- Styling: Tailwind CSS for rapid UI development and utility-first styling.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for client-side navigation (though for a single-page app, initial focus might be on components rather than complex routing).
- Icons: Heroicons or similar for clean, functional icons.
- Utilities: Axios for potential future API interactions, date-fns for any date formatting needs.
CORE FEATURES & USER FLOWS:
1. **Dashboard:**
* **User Flow:** Upon loading the application, the user sees a clear overview of Miasma's status. Key metrics like 'Scraper Traps Active', 'Data Poisoned Today', and 'Estimated Scraper Resources Wasted' are prominently displayed. A status indicator (e.g., 'Running', 'Stopped') is visible.
* **Description:** This serves as the main control panel and informational hub. It provides immediate feedback on the system's operation and its effectiveness.
2. **Configuration Panel:**
* **User Flow:** Users navigate to the 'Configuration' section. They can adjust settings such as the target path for trap redirection (e.g., '/bots'), the type and volume of poisoned data to serve, the complexity of self-referential link generation, and the response codes for trapped scrapers (e.g., 200 OK with fake data, 403 Forbidden, 418 I'm a teapot). They can also input specific IP ranges or user-agent strings to target.
* **Description:** This section allows users to customize Miasma's behavior to suit their specific website structure and threat model. It's crucial for fine-tuning the trapping mechanism.
3. **Installation/Setup Guide:**
* **User Flow:** A dedicated section provides clear, step-by-step instructions for installing Miasma. This includes commands for `cargo install miasma` and instructions for downloading pre-built binaries. It also details how to configure a reverse proxy (like Nginx) to point malicious traffic to the Miasma server.
* **Description:** Simplifies the initial setup process, making Miasma accessible even to users with moderate technical expertise. Visual aids like code snippets and diagrams are essential here.
4. **Status & Logs:**
* **User Flow:** Users can view real-time logs of Miasma's activity. This includes information about detected scraper attempts, actions taken (e.g., 'Sent poisoned data to scraper IP x.x.x.x'), and any encountered errors.
* **Description:** Provides transparency and helps users troubleshoot or verify that Miasma is functioning correctly and effectively trapping scrapers.
5. **Quick Start / Test Trap:**
* **User Flow:** A simple button or command is available to quickly activate Miasma with default settings or to run a quick test to simulate trapping a scraper.
* **Description:** Enables users to get started immediately or test the core functionality without deep configuration.
UI/UX DESIGN:
- **Layout:** Single-page application layout. A persistent sidebar navigation (collapsible on smaller screens) will provide access to Dashboard, Configuration, Logs, and Setup Guide. The main content area will display the relevant information or forms for the selected section.
- **Color Palette:** Dark theme primarily, evoking a sense of security and 'underground' operation. Primary colors: Deep charcoal (#121212), dark slate gray (#2c3e50). Accent colors: Electric green (#39FF14) or vibrant purple (#8A2BE2) for active states, warnings, and calls to action. Neutral grays for text and borders.
- **Typography:** Clean, modern sans-serif font like 'Inter' or 'Poppins'. Clear hierarchy using font weights and sizes. Headings should be bold and prominent, body text legible and well-spaced.
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on small screens. Content sections reflow and adapt. Ensure readability and usability across devices from mobile phones to large desktops.
- **Interactivity:** Subtle hover effects on buttons and links. Smooth transitions for sidebar collapse/expand and content area loading.
COMPONENT BREAKDOWN:
1. `App.jsx`: Main application component, sets up routing (if needed) and main layout.
* Props: None
* Responsibility: Renders the overall application structure, including sidebar and main content area.
2. `Sidebar.jsx`:
* Props: `activeTab` (string), `onTabChange` (function)
* Responsibility: Displays navigation links (Dashboard, Config, Logs, Setup) and handles tab changes.
3. `Dashboard.jsx`:
* Props: None (fetches data via Zustand store)
* Responsibility: Displays key status metrics and an overview of Miasma's performance.
4. `StatusCard.jsx`:
* Props: `title` (string), `value` (string | number), `icon` (ReactNode), `isLoading` (boolean)
* Responsibility: Reusable component to display individual metrics (e.g., 'Active Traps', 'Data Poisoned').
5. `Configuration.jsx`:
* Props: None (manages state internally or via Zustand)
* Responsibility: Renders the configuration form elements.
6. `ConfigInput.jsx`:
* Props: `label` (string), `type` (string), `value` (string | number), `onChange` (function), `placeholder` (string), `description` (string, optional)
* Responsibility: Reusable input field component for configuration settings.
7. `Logs.jsx`:
* Props: None (fetches log data)
* Responsibility: Displays a list of recent activity logs.
8. `LogEntry.jsx`:
* Props: `timestamp` (string), `message` (string), `level` (string - e.g., 'INFO', 'WARN', 'ERROR')
* Responsibility: Renders a single log entry.
9. `SetupGuide.jsx`:
* Props: None
* Responsibility: Displays installation and setup instructions, including code snippets.
10. `CodeBlock.jsx`:
* Props: `language` (string), `code` (string)
* Responsibility: Renders formatted code snippets, potentially with copy-to-clipboard functionality.
DATA MODEL (Zustand Store):
- `store.js` (using Zustand):
```javascript
import { create } from 'zustand';
const useMiasmaStore = create((set) => ({
// Dashboard State
status: 'Stopped', // 'Running', 'Stopped', 'Error'
activeTraps: 0,
dataPoisoned: 0,
estimatedWastedResources: '0 MB',
// Configuration State
trapPath: '/bots',
poisonDataLevel: 'medium', // 'low', 'medium', 'high'
linkStrategy: 'hidden', // 'hidden', 'obfuscated'
responseCode: 200,
targetIps: '',
targetUserAgents: '',
// Logs State
logs: [],
// Actions
setStatus: (newStatus) => set({ status: newStatus }),
updateMetrics: (metrics) => set(metrics), // e.g., updateMetrics({ activeTraps: 5, dataPoisoned: 1024 })
updateConfiguration: (config) => set(config),
addLog: (logEntry) => set((state) => ({ logs: [logEntry, ...state.logs].slice(0, 100) })), // Keep last 100 logs
// Mock Fetch Functions (replace with actual API calls later)
fetchDashboardStats: async () => {
// Simulate API call
await new Promise(resolve => setTimeout(resolve, 1000));
const mockStats = {
activeTraps: Math.floor(Math.random() * 10),
dataPoisoned: Math.floor(Math.random() * 5000),
estimatedWastedResources: `${Math.floor(Math.random() * 200)} MB`
};
set(mockStats);
set({ status: 'Running' }); // Assume running after fetch
},
fetchLogs: async () => {
// Simulate API call
await new Promise(resolve => setTimeout(resolve, 800));
set({
logs: [
{ timestamp: new Date().toISOString(), message: 'Miasma started successfully.', level: 'INFO' },
...get().logs.slice(0, 98) // Keep logs consistent
]
});
}
}));
export default useMiasmaStore;
```
- **Mock Data Formats:**
* `LogEntry`: `{ timestamp: string, message: string, level: 'INFO' | 'WARN' | 'ERROR' }`
* `Configuration`: `{ trapPath: string, poisonDataLevel: string, linkStrategy: string, responseCode: number, targetIps: string, targetUserAgents: string }`
ANIMATIONS & INTERACTIONS:
- **Sidebar Toggle:** Smooth slide animation when the sidebar collapses or expands.
- **Page Transitions:** Subtle fade-in/fade-out effect when switching between sections (Dashboard, Config, etc.).
- **Button Hovers:** Slight scale or background color change on interactive elements.
- **Loading States:** Use skeleton loaders or spinners (e.g., using `react-spinners`) when fetching data for the dashboard or logs. The `isLoading` prop in `StatusCard` will manage this.
- **Form Feedback:** Subtle animations on input focus and validation errors (e.g., a slight shake or border color change).
- **Status Indicator:** A pulsating animation for the 'Running' status indicator to draw attention.
EDGE CASES:
- **Initial State:** When the app first loads, all metrics should show zero or placeholder values, and the status should indicate 'Stopped'. Loading indicators should be visible.
- **Error Handling:** Network errors during data fetching should display user-friendly error messages (e.g., 'Could not load status. Please check your connection or try again later.'). Specific error logs should appear in the Logs section.
- **Validation:** Configuration inputs should have basic validation (e.g., response code must be a number, path cannot be empty). Display clear error messages next to invalid fields.
- **Empty Logs:** If no logs are available, display a message like 'No activity recorded yet.'
- **Accessibility (a11y):** Use semantic HTML elements. Ensure keyboard navigation is possible for all interactive elements. Provide appropriate ARIA attributes (e.g., `aria-label` for icon buttons). Ensure sufficient color contrast.
- **No Backend:** The initial frontend version simulates all backend interactions (stats updates, log generation) using `setTimeout` and Zustand's state management. The prompt clearly states this is a frontend SPA simulation.
SAMPLE DATA:
1. **Dashboard Metrics (Mock):**
* `status`: 'Running'
* `activeTraps`: 7
* `dataPoisoned`: 3456
* `estimatedWastedResources`: '75 MB'
2. **Log Entries (Array):**
* `{ timestamp: '2023-10-27T10:00:00Z', message: 'Scraper detected from IP 198.51.100.10. Redirected to /bots.', level: 'INFO' }`
* `{ timestamp: '2023-10-27T10:01:15Z', message: 'Serving poisoned data. Response Code: 200', level: 'INFO' }`
* `{ timestamp: '2023-10-27T10:02:30Z', message: 'Configuration updated: Trap Path changed to /trapzone.', level: 'WARN' }`
* `{ timestamp: '2023-10-27T09:59:50Z', message: 'Miasma service started.', level: 'INFO' }`
* `{ timestamp: '2023-10-26T23:55:00Z', message: 'Failed to resolve DNS for scraper. IP: 203.0.113.5', level: 'ERROR' }`
3. **Configuration (Default State):**
* `trapPath`: '/bots'
* `poisonDataLevel`: 'medium'
* `linkStrategy`: 'hidden'
* `responseCode`: 200
* `targetIps`: ''
* `targetUserAgents`: 'python-requests,curl,Go-http-client'
4. **Configuration (Updated State Example):**
* `trapPath`: '/ai-feed'
* `poisonDataLevel`: 'high'
* `linkStrategy`: 'obfuscated'
* `responseCode`: 418
* `targetIps`: '192.0.2.0/24'
* `targetUserAgents`: ''
5. **Setup Guide Snippets:**
* Cargo Install: `cargo install miasma`
* Nginx Config Snippet:
```nginx
location /bots {
proxy_pass http://localhost:8080; # Assuming Miasma runs on port 8080
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
```
DEPLOYMENT NOTES:
- **Build Tool:** Vite is recommended for its speed. Run `npm run build` (or `yarn build`) to generate optimized static assets in the `dist` folder.
- **Environment Variables:** Use `.env` files for managing different configurations (e.g., API endpoints if Miasma later connects to a backend service). For this initial frontend-only version, environment variables are less critical but can be set up for future expansion (e.g., `VITE_API_BASE_URL`).
- **Performance:** Tailwind CSS purging should be enabled in the build process to remove unused styles. Code splitting (handled by Vite) will ensure initial load times are minimized. Optimize image assets if any are introduced.
- **Hosting:** The generated static files can be hosted on any static hosting provider (Netlify, Vercel, GitHub Pages, AWS S3).
- **CORS:** If Miasma were to interact with a separate backend API, CORS configuration on the backend would be crucial.
- **Security:** While Miasma itself is a security tool, ensure the hosting environment is secure. For the SPA, focus on secure development practices within React and dependency management.