From 9af2d3ab6263f4ab26cd0451b8c19b643b2de022 Mon Sep 17 00:00:00 2001 From: root Date: Sat, 25 Jul 2026 14:13:47 -0400 Subject: [PATCH] =?UTF-8?q?feat:=20Super=20Search=20for=20Business=20?= =?UTF-8?q?=E2=80=94=20project=20inception?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Product spec, architecture diagram, README, CHANGELOG. Multi-tenant competitive intelligence SaaS built on Super Search v2. Pricing: Starter 99/mo, Pro 99/mo, Enterprise ,499+/mo. --- CHANGELOG.md | 31 ++ README.md | 99 ++++++ docs/super-search-business-architecture.html | 343 +++++++++++++++++++ docs/super-search-business-spec.md | 214 ++++++++++++ 4 files changed, 687 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 README.md create mode 100644 docs/super-search-business-architecture.html create mode 100644 docs/super-search-business-spec.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b142d06 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,31 @@ +# CHANGELOG — Super Search for Business + +--- + +## 2026-07-25 — Project Inception + +**Decision:** Build a commercial competitive intelligence SaaS product on top of existing Super Search v2 and OSINT infrastructure. + +**Deliverables created:** +- Product specification (`docs/super-search-business-spec.md`) +- Architecture diagram (`docs/super-search-business-architecture.html`) +- Project README with deployment, recovery, and URL planning + +**Key architectural decision:** The product is an 80/20 build — 80% already exists (Super Search v2, OSINT enrichment, 7 search providers with fallback chains, MCP protocol) and 20% needs building (multi-tenant REST API, React portal, Stripe billing, PostgreSQL schema). + +**Naming candidates evaluated (30+ domains checked):** +- IntelSight (intelsight.io — available) +- ScopeIntel (scopeintel.io — available) +- BrandSleuth (brandsleuth.io — available) +- RivalEye (rivaleye.io — available) +- BizScope (bizscope.io — available) + +**Structural decision:** Product should have its own brand and domain, listed as an IT Pro Partner product (same model as VoIPSimplicity). Footer: "A product of IT Pro Partner." + +**Pricing model:** Three tiers — Starter ($199/mo), Pro ($499/mo), Enterprise ($1,499+/mo). 93-95% gross margins. + +**Open decisions:** +- Final product name +- Hosting target (app1 shared vs. dedicated VPS) +- Data retention policy +- Rate limit definition for Starter tier diff --git a/README.md b/README.md new file mode 100644 index 0000000..9922d83 --- /dev/null +++ b/README.md @@ -0,0 +1,99 @@ +# Super Search for Business + +> **Product codename:** IntelSight (pending brand confirmation) +> **Status:** Specification & Architecture — pre-MVP +> **Started:** July 25, 2026 + +Multi-tenant competitive intelligence and OSINT search platform sold as SaaS. Companies subscribe for continuous visibility into competitors, customer sentiment, market trends, and public records intelligence. + +--- + +## Architecture + +See [`docs/super-search-business-architecture.html`](docs/super-search-business-architecture.html) for the full visual diagram. + +### Stack + +| Layer | Technology | Status | +|-------|-----------|--------| +| Search Engine | Super Search v2 (FastMCP, 7 providers) | ✅ Built | +| OSINT Enrichment | osint-person MCP server | ✅ Built | +| API Gateway | Caddy reverse proxy | ✅ Running | +| Portal Frontend | React + TypeScript | 🔨 To build | +| REST API | FastAPI wrapping MCP tools | 🔨 To build | +| Multi-tenant DB | PostgreSQL | 🔨 To build | +| Auth | OAuth/SSO (pattern from Ops Portal) | 🔨 Adapt | +| Billing | Stripe subscriptions | 🔨 Integrate | +| Reports | Markdown → PDF (pandoc/weasyprint) | 🔨 To build | +| Scheduler | Hermes cron → report generation | 🔨 Configure | + +### Providers (Super Search v2) + +SearXNG → Exa → OpenCorporates → CourtListener → DuckDuckGo → Wikipedia → Firecrawl + +All with circuit breakers, health checks, and fallback chains. Additional: Browserless Chrome for screenshots. + +--- + +## Deployment + +**Target:** app1 (152.53.36.131, Hetzner) or dedicated netcup VPS — TBD. + +**Domains (planned):** +- `intelsight.io` (or chosen brand) — marketing site + customer portal +- `api.intelsight.io` — REST API +- Listed under Products on `itpropartner.com` + +**Backup:** Follows standard ITPP backup cadence (daily + 15-min database sync to S3). + +--- + +## Recovery + +Standard ITPP recovery procedure: +1. Restore PostgreSQL from latest S3 backup +2. Redeploy FastAPI + React containers +3. Re-establish Caddy routes and LE certificates +4. Verify Stripe webhook endpoint + +Full DR plan to be drafted post-MVP. + +--- + +## Pricing + +| Tier | Price | Key Features | +|------|-------|-------------| +| Starter | $199/mo | 50 searches, basic reports, 1 user | +| Pro | $499/mo | Unlimited searches, weekly reports, OSINT dossiers, white-label | +| Enterprise | $1,499+/mo | API access, custom dashboards, dedicated analyst | + +14-day free trial on all plans. + +--- + +## Key URLs (planned) + +| Purpose | URL | +|---------|-----| +| Marketing + Portal | intelsight.io | +| API | api.intelsight.io | +| ITPP product listing | itpropartner.com/products/intelsight | + +--- + +## Related Repos + +- `itpp-infrastructure` — server architecture, DNS records +- Super Search MCP server (`/opt/super-search/` on app1) +- osint-person MCP server + +--- + +## Open Decisions + +- [ ] Product name (IntelSight, ScopeIntel, BrandSleuth, RivalEye, BizScope) +- [ ] Hosting: app1 shared or dedicated VPS +- [ ] Data retention policy (GDPR/CCPA) +- [ ] Rate limit definition for Starter tier +- [ ] LLM choice for report generation (deepseek-v4-pro vs Claude) diff --git a/docs/super-search-business-architecture.html b/docs/super-search-business-architecture.html new file mode 100644 index 0000000..be213d0 --- /dev/null +++ b/docs/super-search-business-architecture.html @@ -0,0 +1,343 @@ + + + + + + Super Search for Business — Architecture + + + + +
+
+
+
+

Super Search for Business — Architecture

+
+

Multi-tenant competitive intelligence & OSINT search platform · IT Pro Partner

+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + IT Pro Partner Infrastructure (netcup VPS / app1) + + + + Search & Enrichment Providers + + + + + + Customer A + Browser / Mobile + + + Customer B + insights.cust.com + + + Customer C + API Integration + + + + + + Auth Service + OAuth / SSO / MFA + + + + API Gateway (Caddy) + Rate Limiting · Key Validation · Routing + + + + + + Multi-Tenant Portal + React + TypeScript + portal.itpropartner.com + + + + REST API + FastAPI · Python 3.13 + api.itpropartner.com/v1 + + + + Super Search Engine v2 + 7 Providers · Circuit Breakers + MCP Server :8899 + + + + OSINT Enrichment + Identity · Courts · Sentiment + Dossier Reports + + + + + + PostgreSQL + Tenants · Users · History · Reports + + + + Report Scheduler + Cron · Recurring · Alerts + + + + Report Generator + Markdown · PDF · Email + + + + Stripe Billing + Subscriptions · Invoicing + + + + + SearXNG + Meta Search + + + Exa + Premium Search + + + OpenCorporates + Business Records + + + CourtListener + Legal Records + + + DuckDuckGo + Web + Instant + + + Wikipedia + Encyclopedic + + + Firecrawl + Web Extraction + + + + Browserless + Screenshots + + + + + + + + + + + + + + + + + + + + + + + + REST + + + + JSON + + + + MCP + + + + dossier + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Legend + + Frontend / Portal + + Backend / Engine + + Database / Storage + + Security / Gateway + + External / Billing + + 3rd-Party Provider + + Auth Flow + +
+ + +
+
+
+
+

Customer Features

+
+
    +
  • • Competitive landscape reports
    • +
  • • Customer review sentiment analysis
    • +
  • • Market trend monitoring & alerts
    • +
  • • White-label dashboard (own domain)
    • +
  • • API access for internal tooling
    • +
+
+
+
+
+

Search Capabilities

+
+
    +
  • • 7-provider fallback chain with circuit breakers
    • +
  • • OSINT person/business deep dossiers
    • +
  • • Court records, corporate filings, skip tracing
    • +
  • • Web screenshots via browserless Chrome
    • +
  • • Academic, news, and image search
    • +
+
+
+
+
+

Pricing Tiers

+
+
    +
  • • Starter: $199/mo — 50 searches, basic reports
    • +
  • • Pro: $499/mo — unlimited searches, weekly reports
    • +
  • • Enterprise: $1,499+/mo — API access, OSINT, custom dashboards
    • +
  • • All plans: 14-day free trial, no CC required
    • +
+
+
+ +

Super Search for Business · IT Pro Partner · Architecture v1.0 · July 2026

+
+ + diff --git a/docs/super-search-business-spec.md b/docs/super-search-business-spec.md new file mode 100644 index 0000000..a42e0be --- /dev/null +++ b/docs/super-search-business-spec.md @@ -0,0 +1,214 @@ +# Super Search for Business — Product Specification + +> **Status:** Draft v1.0 · July 25, 2026 +> **Author:** Sho'Nuff (Hermes Agent) for Germaine Brown / IT Pro Partner + +--- + +## 1. Product Overview + +Super Search for Business is a multi-tenant competitive intelligence and OSINT search platform sold as a SaaS subscription. Companies subscribe to gain continuous visibility into their competitive landscape: who their competitors are, what customers say about them, what the market is looking for, and actionable intelligence from public records. + +**What it is:** A business search engine that does the work of a competitive intelligence analyst — for $199-1,499/mo instead of $5k+/mo. + +**What it isn't:** SEO keyword research (Semrush), web traffic estimation (SimilarWeb), or a generic search tool. This is investigative business intelligence. + +### Core value proposition + +> "Know everything the public internet knows about your competitors, your reputation, and your market — continuously, automatically, and without hiring an analyst." + +--- + +## 2. Target Market + +### Primary +- SMB service businesses (legal, medical, trades, agencies) who can't afford a dedicated analyst +- Small consulting firms doing competitive research for clients +- Debt recovery / skip tracing firms (existing DRE workflow) + +### Secondary +- Mid-market companies wanting continuous market monitoring +- Franchise operators tracking local competitive dynamics +- Law firms doing due diligence research + +### Buyer persona +**"Mike"** — Operations director at a 50-person HVAC company. He knows there are 4 competitors in his market but has no systematic way to track their pricing, reviews, hiring, or expansion. He'd pay $199/mo to get a monthly report instead of spending 4 hours Googling. + +--- + +## 3. Feature Matrix by Tier + +| Feature | Starter ($199) | Pro ($499) | Enterprise ($1,499+) | +|---------|:---:|:---:|:---:| +| Competitive search queries | 50/mo | Unlimited | Unlimited | +| Web extraction (full pages) | 25/mo | 100/mo | Unlimited | +| News monitoring | ✓ | ✓ | ✓ | +| Sentiment analysis (reviews) | Basic | Advanced | Custom models | +| Saved searches | 5 | 25 | Unlimited | +| Scheduled reports | Monthly | Weekly | Daily + real-time alerts | +| Report export | PDF | PDF + CSV | PDF + CSV + API | +| OSINT person/business dossier | — | 5/mo | Unlimited | +| Court records search | — | ✓ | ✓ | +| Skip tracing | — | — | ✓ | +| White-label domain | — | ✓ | ✓ | +| API access | — | — | ✓ | +| Custom dashboard | — | — | ✓ | +| Multi-user accounts | 1 | 3 | Unlimited | +| Dedicated analyst summary | — | — | ✓ | + +--- + +## 4. Technical Architecture + +See `super-search-business-architecture.html` for the visual diagram. + +### Stack + +| Layer | Technology | Status | +|-------|-----------|--------| +| Search engine | Super Search v2 (FastMCP, 7 providers) | ✅ Built | +| OSINT enrichment | osint-person MCP server | ✅ Built | +| API gateway | Caddy reverse proxy | ✅ Running | +| Portal frontend | React + TypeScript (new) | 🔨 To build | +| REST API | FastAPI wrapping MCP tools | 🔨 To build | +| Multi-tenant DB | PostgreSQL (new schema) | 🔨 To build | +| Auth | OAuth/SSO (existing pattern from Ops Portal) | 🔨 Adapt | +| Billing | Stripe subscriptions | 🔨 Integrate | +| Hosting | app1 (Hetzner) or netcup VPS | 🔨 Deploy | +| Reports | Markdown → PDF pipeline (pandoc/weasyprint) | 🔨 To build | +| Scheduler | Hermes cron → report generation | 🔨 Configure | + +### What's already built (80%) + +Super Search v2 already has: +- 7 providers with circuit breakers and health checks +- Web extraction (single + batch) +- Racing search (fastest provider wins) +- Premium search (Exa API) +- Academic, news, image search +- Web lookups (DuckDuckGo Instant + Wikipedia) +- Screenshot capture (browserless Chrome) +- OSINT person search with identity clustering, source scoring, dossier reports +- All accessible via MCP protocol on `:8899` + +### What needs building (20%) + +| Component | Effort | Priority | +|-----------|--------|----------| +| Multi-tenant REST API wrapper | 2-3 days | P0 | +| Customer portal (React) | 3-5 days | P0 | +| PostgreSQL schema (tenants, users, history) | 1 day | P0 | +| Stripe integration | 2 days | P1 | +| Auth (OAuth + API keys) | 1 day | P1 | +| Report generation pipeline | 2 days | P1 | +| White-label domain routing | 1 day | P2 | +| Scheduled search/monitoring | 2 days | P2 | + +--- + +## 5. Implementation Phases + +### Phase 1: MVP (2 weeks) +- REST API wrapping Super Search MCP tools +- Single-tenant portal (validate the concept with 1-2 beta customers) +- Manual billing (Stripe invoice links, no integration) +- Basic report generation (markdown → email) + +### Phase 2: Multi-Tenant Launch (2 weeks) +- PostgreSQL schema with tenant isolation +- Stripe subscription integration +- Customer signup flow (14-day trial) +- White-label domain support +- Saved searches + history + +### Phase 3: Advanced Features (ongoing) +- Scheduled monitoring with alerts +- Sentiment analysis pipeline +- OSINT dossier automation +- API access for Enterprise tier +- Custom dashboard builder + +--- + +## 6. Pricing & Unit Economics + +### Subscription Pricing + +| Tier | Monthly | Annual (2 mo free) | Target CAC | +|------|---------|---------------------|------------| +| Starter | $199 | $1,990 | < $200 | +| Pro | $499 | $4,990 | < $500 | +| Enterprise | $1,499+ | Custom | < $1,000 | + +### Cost Structure (per customer, estimated) + +| Cost Driver | Starter | Pro | Enterprise | +|-------------|---------|-----|------------| +| Exa API (premium search) | ~$5/mo | ~$15/mo | ~$50/mo | +| Firecrawl (web extraction) | ~$3/mo | ~$10/mo | ~$30/mo | +| Server compute (netcup VPS) | Shared | Shared | Dedicated | +| Report generation (LLM) | ~$2/mo | ~$5/mo | ~$20/mo | +| **Total marginal cost** | **~$10/mo** | **~$30/mo** | **~$100/mo** | +| **Gross margin** | **95%** | **94%** | **93%** | + +### Break-even +- 10 Starter customers = $1,990/mo revenue vs. ~$200/mo infra cost +- Infrastructure already paid for (Hermes, app1) — marginal cost only + +--- + +## 7. Competitive Landscape + +| Competitor | What they do | Our advantage | +|------------|-------------|---------------| +| Semrush | SEO keyword + domain analytics | We do actual competitive intelligence, not SEO metrics | +| SimilarWeb | Traffic estimation | We pull from court records, corporate filings, reviews | +| Crayon | Enterprise competitive intel ($20k+) | Same capability at 1/10th the price | +| Klue | Competitive enablement | We're self-serve, not sales-enablement | +| Custom analyst | $5-15k/mo for one analyst | We're automated, always-on, $199/mo | + +**Positioning:** "Competitive intelligence" tools exist — they're just either SEO tools mislabeled, or $20k+/yr enterprise suites. The SMB market is completely unserved. + +--- + +## 8. Go-to-Market + +### Channel 1: Existing ITPP customers +- Liberty Tire, Forefront Wireless, DRE — existing relationships +- Offer them free beta access in exchange for testimonials + +### Channel 2: Content marketing +- Publish sample competitive reports for well-known industries (HVAC, legal, dental) +- "We analyzed the top 5 HVAC companies in Savannah — here's what we found" +- LinkedIn + industry subreddits + +### Channel 3: Partnerships +- Business coaches / consultants who resell to their clients +- MSPs who want to offer competitive intel as a value-add + +### Launch sequence +1. Build MVP (2 weeks) +2. Beta with Liberty Tire + 1-2 others (free, 30 days) +3. Collect testimonials + refine based on feedback +4. Public launch with 3 tiers +5. Target: 10 paying customers by month 3 + +--- + +## 9. Open Questions + +1. **Product name:** "Super Search for Business" is functional but not marketable. Options: IntelSight, MarketPulse, BizScope, CompassIntel? +2. **Hosting:** Share app1 resources or deploy to a dedicated VPS? +3. **Data retention:** How long do we keep search history per tenant? (GDPR/CCPA implications) +4. **Rate limiting:** What's a "search" in the Starter tier? One query = one provider call, or one "session" with multiple providers? +5. **LLM for reports:** Use deepseek-v4-pro (cheap) or Claude (better summaries)? Both? + +--- + +## 10. Next Steps + +- [ ] Germaine approves spec and picks a product name +- [ ] Architect the PostgreSQL multi-tenant schema +- [ ] Scaffold the FastAPI REST wrapper around Super Search MCP +- [ ] Build the React portal shell with auth +- [ ] Deploy to staging and invite beta customers