System Requirements Document for orbitspy

1. Introduction

The project "AdSpyZero: Competitor Ad Monitor" is a production-ready, single-tenant micro-SaaS application designed to monitor competitor advertisements. The application is optimized for low code footprints to ensure it can be built successfully within 10 credits. It leverages an opinionated stack, including Next.js, Tailwind CSS, Lucide Icons, and SQLite, to deliver a seamless user experience with a deep space/black hole aesthetic.

2. System Overview

AdSpyZero is designed for a single SaaS operator who needs to track competitor websites and monitor captured ad creatives. The application provides a live, self-serve view of competitor ad activity without manual research. It includes a mock infrastructure to simulate ad scraping and populates the database with realistic competitor ad mock data. The system is built with a focus on a pristine, functional UI and bulletproof local mock-data persistence.

2a. Product Interpretation and Delivery Boundary

The application is a single-tenant micro-SaaS, meaning it is designed for use by one operator at a time. It must be built within 10 credits, emphasizing a low code footprint. The backend endpoints are consolidated within Next.js API routes, and the database is managed using SQLite via Prisma or native Node-sqlite. The application includes a mock scraper service to simulate ad data collection, and payment is managed through a mock success trigger toggle.

2b. Source Content Inventory

Not applicable as no content_source directive was provided.

2c. Page Content and Component Coverage

Landing

• Information/State: Introduction to AdSpyZero, explaining its purpose and features.
• Primary Actions: Navigate to the Landing / Auth Page.
• Components: Hero section with a real-time WebGL event-horizon ring, headline, and status ticker.

Landing / Auth Page

• Information/State: Login and signup forms.
• Primary Actions: User authentication (email/password).
• Components: Translucent login/signup card, violet glow button.

Dashboard Overview Page

• Information/State: Overview of tracked competitors and ads.
• Primary Actions: Add competitor URL, view alerts.
• Components: Cosmic Stat Cards, "Pull Competitor URL" Input, Singularity Alerts Feed.

Tracked Competitors

• Information/State: List of tracked competitors.
• Primary Actions: Manage competitor records, delete competitors.
• Components: Competitor list, delete action.

Competitor Detail View

• Information/State: Detailed view of a competitor's ad creatives.
• Primary Actions: View ad details.
• Components: Ad creative grid, Supernova Performance badges.

Ad Archive

• Information/State: Archive of all tracked ads.
• Primary Actions: Browse ads, filter by platform.
• Components: Ad list, platform filter.

Billing

• Information/State: Subscription details.
• Primary Actions: Manage subscription.
• Components: Tier selection, mock payment success toggle.

3. Functional Requirements

1. As a Solo SaaS Operator, I should be able to authenticate using email and password to access the dashboard, competitor, archive, and billing states. (required_inference)
2. As a Solo SaaS Operator, I should be able to add a competitor URL to trigger the mock scraper service, generating ad creatives for immediate dashboard updates. (required_inference)
3. As a Solo SaaS Operator, I should be able to view a dashboard overview with cosmic stat cards, a URL input for competitor tracking, and a Singularity Alerts Feed. (explicit)
4. As a Solo SaaS Operator, I should be able to manage tracked competitors by adding, viewing, and deleting them, with cascading ad deletion. (explicit)
5. As a Solo SaaS Operator, I should be able to view detailed competitor ad creatives with performance badges. (explicit)
6. As a Solo SaaS Operator, I should be able to browse an ad archive with sorting and filtering capabilities. (explicit)
7. As a Solo SaaS Operator, I should be able to manage my subscription through a billing page with a mock payment success toggle. (required_inference)

4. User Personas

Solo SaaS Operator

• Product Context: The single-tenant operator who uses AdSpyZero to monitor competitor ads.
• Primary Goal: To gain insights into competitor advertising strategies without manual research.
• Responsibilities: Adding competitor URLs, reviewing dashboard stats, inspecting ad creatives, managing subscription.
• Interactions: Engages with the dashboard, competitor detail view, and billing page.
• Observable Success: A live, updated view of competitor ad activity.

5. Core User Flows

1. Authentication Flow

   • Start: User accesses the Landing / Auth Page.
   • Action: User enters email and password.
   • Result: User is authenticated and redirected to the Dashboard Overview Page.

2. Competitor URL Submission Flow

   • Start: User is on the Dashboard Overview Page.
   • Action: User enters a competitor URL in the "Pull Competitor URL" input.
   • Result: Mock scraper service generates ad creatives, updating the dashboard stats and alerts.

3. Competitor Management Flow

   • Start: User accesses the Tracked Competitors page.
   • Action: User adds or deletes a competitor.
   • Result: Competitor list is updated, and associated ads are managed accordingly.

4. Ad Creative Inspection Flow

   • Start: User clicks on a competitor in the Tracked Competitors page.
   • Action: User views the Competitor Detail View.
   • Result: User inspects ad creatives and performance badges.

5. Subscription Management Flow

   • Start: User accesses the Billing page.
   • Action: User toggles the mock payment success.
   • Result: Subscription state is updated.

6. Visuals Colors and Theme

• Muse: Gleb Kuznetsov
• Palette:
  • Background: #050508
  • Surface: #0d0e15
  • Text: #e8e9f2
  • Primary: #8b5cf6
  • Accent: #06b6d4
  • Muted: #1e2235
• Typography:
  • Headings: Space Grotesk
  • Body: IBM Plex Sans
  • Numbers: JetBrains Mono
• Shape Language: Soft-edged glass, thin luminous strokes.
• Layout: Fixed left control rail, 12-col grid content column.

7. Signature Design Concept

The public entry page features a real-time WebGL event-horizon ring as the hero element, creating an immersive deep-space experience. The headline "Pull Your Competitors' Strategies into the Event Horizon" is prominently displayed, with a status ticker providing live updates. The translucent auth card is positioned to overlap the ring, enhancing the cinematic effect.

8. Interaction Model & Motion Direction

• Interaction Model: Animated
• Motion Tempo: Cinematic
• Hero Dimensionality: WebGL
• Landing Hero Motion Brief: The event-horizon ring rotates slowly, with particle streaks brightening as the URL field is focused. The headline animates into view, and the status ticker updates dynamically.

9. Non-Functional Requirements

• Performance: The application must be optimized for low code footprints to ensure it builds successfully within 10 credits.
• Scalability: The system should support the single-tenant model efficiently.
• Usability: The UI must be intuitive and align with the deep space/black hole aesthetic.

10. Tech Stack

• Frontend: Next.js (App Router), Tailwind CSS, Lucide Icons
• Backend: Next.js API routes
• Database: SQLite (via Prisma or native Node-sqlite)
• Mock Infrastructure: Internal simulated worker service for ad scraping

11. Assumptions and Constraints

• The application is single-tenant and must be built within 10 credits.
• Backend endpoints are consolidated within Next.js API routes.
• The database is managed using SQLite.
• Ad scraping is simulated through a mock service.
• Payment is managed through a mock success trigger toggle.

12. Glossary

• AdCreative: A model representing an advertisement's details.
• Competitor: A model representing a competitor being tracked.
• Mock Scraper Service: A simulated service that generates ad data.
• Single-Tenant: An application designed for use by one operator at a time.