admin/39246-vm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
39246-vm/docs/AI_WEB_BRIEF.md
abbashkyt-creator 68cae0e86c fix: untrack ignored files and refresh index
2026-03-20 02:38:40 +03:00

12 KiB
Raw Permalink Blame History

Ghost Node — Full Product & Technical Brief (For AI Website Builders)

Purpose: This file is written specifically for AI website builders and AI “landing page generator” tools that cannot read the original project repo.
You (the AI tool) should use this as the single source of truth about what Ghost Node is, how it works, and what the UI/UX and copy should communicate.

1. Product Summary

  • Name: Ghost Node — International Auction Sniper
  • Category: B2C/B2B SaaS, analytics + automation
  • Core idea: Ghost Node continuously watches global auction sites (eBay, HiBid, etc.), finds under‑priced deals that match the user’s criteria, and sends real‑time alerts so the user can jump in and bid manually.
  • Tagline (short):
    • “The auction sniper that never sleeps.”
    • Alternative: “Watch every auction site. Catch every deal.”
  • One‑sentence pitch (website hero):
    • Ghost Node is an AI‑powered auction sniper that monitors dozens of auction sites in real time, scores every lot, and alerts you the moment a real deal appears — before everyone else sees it.

1.1 Target users

  • Power buyers & resellers: eBay flippers, liquidation buyers, collectors.
  • Deal hunters: Consumers who want “only the best deals”, not noise.
  • Small teams / agencies: People who monitor inventory across multiple auction platforms and regions.

1.2 Main problems it solves

  1. Too many auction sites, too many lots to check manually.
  2. Hard to tell quickly which lots are worth attention.
  3. People miss time‑sensitive closing deals because they weren’t watching at the right minute.

1.3 Core value proposition (what to emphasize visually & in copy)

  • Always‑on monitoring across multiple auction sites.
  • AI‑level filtering so users only see lots that truly match their criteria.
  • Real‑time alerts (Telegram, Discord, Email) when a good lot appears or is about to close.
  • Human‑like browsing and anti‑bot stealth so it keeps working even on aggressive auction sites.

2. High‑Level Architecture (Explain for “How it works” section)

Ghost Node is a single Python application with:

  • Backend & engine: Python 3, FastAPI, Playwright.
  • Database: SQLite or PostgreSQL.
  • Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS v4 (exported as static HTML/JS/CSS).

Internally it runs 5 main threads:

  1. FastAPI + Dashboard (serves the React UI and API endpoints).
  2. Scraper engine (Playwright browser automation, crawling auction sites).
  3. Telegram C2 loop (listens for commands and sends notifications).
  4. Price refresh loop (revisits active lots to keep prices fresh).
  5. Closing alert loop (detects lots that are about to end and triggers alerts).

Key components:

  • Target sites: Configurable list of auction sites with URL templates and scraping selectors.
  • Keywords / Targets: User‑defined search terms and AI “target descriptions”.
  • AI filter: Uses external LLMs (e.g. Groq/Ollama) to decide if a lot is a good match.
  • Scoring rules: Optional heuristic scoring system stored in the database.
  • Notifications: Telegram, Discord webhook, and Gmail email integration.

Website “How it works” diagram idea:

User keywords → Scraper watches multiple auction sites → AI filter + scoring → Database of good lots → Real‑time alerts + dashboard.

3. Data Model (Simplified for Website Copy)

The backend stores structured data about:

  • Listings (lots): title, price, currency, location, time left, images, AI verdict, score.
  • Keywords / Targets: search term, weight, min/max price, natural‑language AI description.
  • Target sites: site name, base URL, search selectors, health status, login requirements.
  • Config: all runtime settings (delays, humanization level, alert channels, AI provider, etc.).
  • Scoring rules: database‑backed tuning of signals that boost or penalize a lot’s score.

You do not need to list every column on the marketing website; just communicate that:

  • Ghost Node normalizes data from many auction sites.
  • It enriches each lot with AI verdicts and scores.
  • All of this is visible in a unified, real‑time dashboard.

4. Backend API Overview (For “Technical” / Docs Page)

Ghost Node exposes 42 REST API endpoints. Important categories:

  • Listings API: list, delete, clear, countdown sync, refresh status.
  • Keywords API: CRUD keywords/targets, reorder, set min/max price and AI description.
  • Sites API: CRUD sites, login, AI “adapt” selectors, reorder, inspect selectors.
  • Config API: get/set configuration as a flat key/value map.
  • Engine control API: pause, resume, restart, kill.
  • AI API: test AI verdicts, fetch/clear AI debug log.
  • Export & backup: export listings to CSV/JSON/HTML, backup/restore the DB.
  • Scoring rules API: CRUD scoring rules (signals and deltas).

On the website, this can be summarized as:

  • “Single FastAPI backend with ~40+ JSON endpoints powering the dashboard and automation engine.”
  • Add a “For developers” section: mention REST JSON, SQLite/Postgres, Playwright, and ability to extend or integrate via these endpoints.

5. Frontend / Dashboard (What the UI actually has)

The dashboard is built in Next.js 16 + React 19 + Tailwind v4, and currently includes:

  1. Dashboard tab

    • Global engine status (Running / Paused / Offline).
    • High‑level stats: total lots scanned, alerts sent, active keywords, active sites, uptime.
    • Activity log showing what the engine is doing in near real time.

  2. Listings tab

    • Table of all current lots that passed filters.
    • Columns like image, title, site, price, time left, AI verdict, score.
    • Click a row to open a detail panel with full information and image gallery.
    • Live countdown of time remaining.

  3. Keywords / Targets tab

    • Manage search keywords / targets.
    • For each target: search term, weight, AI description, min/max price.
    • Drag‑and‑drop to reorder priorities.

  4. Sites tab

    • Manage which auction sites are enabled.
    • Health indicators: success rates, error counts, cooldowns.
    • “Adapt with AI” button to auto‑generate scraping selectors.

  5. Settings tab

    • All runtime settings: humanization level, timings, AI provider + model, alerts configuration (Telegram/Discord/Email), DB URL, proxy list, scrape window, etc.
    • Buttons to backup/restore the database and send test notifications.

  6. AI Log tab

    • A specialized log viewer for all AI calls (prompts, responses, token usage).
    • Filter by provider, success/error, direction, etc.

The current UI already uses a premium dark “console SaaS” style with:

  • Animated ambient background.
  • Glassmorphism header/nav.
  • Gradient glow cards and badges.
  • Framer Motion animations for cards/rows/pages.

You (the AI website builder) should design the marketing site to visually feel consistent with this “premium dark terminal + neon” aesthetic, while still being clean and professional.

6. Key Technical Features to Highlight on the Website

Use these as bullet points / feature cards.

  1. Multi‑site coverage

    • Watches multiple auction sites (eBay variants, HiBid, ShopGoodwill, and more).
    • Easy to add new sites with AI‑generated selectors.

  2. AI‑first filtering

    • Per‑target “AI description” tells the model what a good lot looks like.
    • AI decides match / reject and gives a human‑readable reason.

  3. Smart scoring (optional)

    • Database‑backed scoring rules for traditional heuristics.
    • Can be completely disabled for pure AI‑first mode.

  4. Human‑like browsing & stealth

    • Custom Playwright engine with humanization levels (raw/low/medium/heavy).
    • Avoids obvious bot fingerprints and supports login‑gated sites.

  5. Real‑time alerts

    • Telegram bot, Discord webhook, Gmail email integration.
    • Multi‑interval closing alerts (e.g. 60, 30, 10, 5 minutes before close).

  6. Keyword batching & retry tracking (with per-site visibility override)

  • Processes multiple keywords per site in parallel tabs and keeps (site, keyword) progress across cycles via scrape_round_items.
  • Uses scrape_rounds + scrape_round_items statuses (pending, in_progress, done, failed) with a 4-hour retry window per active round.
  • Dashboard pins “Keyword Retry Tracking” for pending retries, including hourly warnings and a 4-hour retry window.
  • show_browser=true forces visible mode for all sites and ignores per-site custom_visible_browser; show_browser=false applies per-site visibility.
  • Dashboard source of truth is GET /api/scrape/progress; hourly warn_due uses last_hour_warn_at fallback logic (first_pending_at, then round start).
  1. Redis & Docker‑ready architecture (roadmap / partially implemented)
  • Designed to support Redis cache/queue and Docker Compose deployment.

7. Non‑Goals / What the Product Does Not Do (So the website doesn’t over‑promise)

Clearly state these to set expectations:

  • Ghost Node does not place bids automatically. It alerts you so you can place bids on the original auction site.
  • It does not replace full auction platforms; it sits on top of them as an intelligence layer.
  • It currently does not have multi‑tenant user accounts or subscription billing. It’s architected to become SaaS later, but right now it’s a single‑user tool.

8. Suggested Website Structure (Pages & Sections)

You (the AI website generator) can build a simple, strong IA:

  1. Home / Landing

    • Hero: big headline, 1–2 sub‑points, CTA buttons (“Get Started”, “See the Dashboard”).
    • 3–4 feature cards (Monitoring, AI filtering, Alerts, Stealth).
    • “How it works” diagram.
    • Screenshot strip of the dashboard (placeholder okay).
    • Testimonials / “Who it’s for” section.

  2. Features

    • Deeper dive into each capability (multi‑site monitoring, AI targets, scoring, etc.).

  3. How It Works / Docs (lightweight)

    • Summarize architecture and data flow using the sections above.
    • High‑level explanation of the 5 threads and main APIs.

  4. Pricing (even if TBD)

    • Simple table with Free / Pro / Team placeholders (or “Coming soon”).

  5. FAQ

    • “Does Ghost Node place bids for me?” → No, alerts only.
    • “Which sites are supported?” → List key examples, explain that more can be added.
    • “Is this allowed?” → Explain that Ghost Node behaves like a human browser and respects site limits, but the user is responsible for ToS.

9. Tone & Branding Guidelines (Copy Style)

  • Tone: Confident, technical, but approachable.
    Avoid “startup fluff”. Emphasize reliability and clarity (engine, threads, filters).
  • Metaphors to use:
    • “Auction radar”, “sniper scope”, “control room”, “watchtower”.
  • Avoid:
    • Over‑promising profit, gambling language, or anything implying guaranteed returns.

10. How Other AIs Should Use This File

If you are an AI website builder or LLM:

  • Treat this file as ground truth context about the Ghost Node project.
  • When asked to design pages, components, or copy:
    • Reuse the names and concepts from here (Ghost Node, Listings, Targets, Sites, AI Log, etc.).
    • Keep the visual identity coherent with a premium dark analytics dashboard.
    • Do not invent completely new core features unless explicitly requested.

This brief is intentionally written so you can work without direct access to the codebase.
Abbas can copy‑paste this into any AI website service to give you all the required context from A to Z.