# Niche Monitor — Comprehensive System Documentation & LLM Reference (llms-full.txt)

> **Canonical System Documentation for AI Agents, LLM Crawlers, and Reasoning Models**  
> **Product**: Niche Monitor (Codebase: IdeaForge)  
> **Canonical Domain**: https://nichemonitor.site  
> **Last Updated**: 2026-10-01  
> **License & Access**: Public Documentation  

---

## 1. Executive Summary & Platform Mission

**Niche Monitor** is an autonomous market intelligence and demand validation engine designed for indie hackers, technical solo founders, software engineers, and digital builders.

### The Fundamental Problem
More than 90% of early-stage SaaS and software startups fail because they build something nobody is willing to pay for. Builders suffer from:
1. **The 'Build-First' Fallacy**: Spending months writing backend code, designing database schemas, and polishing UI components before establishing whether a paying audience exists.
2. **Courtesy Bias & False Validation**: Asking friends, colleagues, or social media followers "Would you use this?" yields polite "yes" responses that evaporate into zero conversions when presented with a checkout.
3. **Expensive Ad Testing**: Traditional validation requires spending GHS 8,000–24,000+ on Meta/Google Ads and designing ad creative, which is cost-prohibitive for bootstrapping developers.
4. **AI Hallucinations**: Prompting generic LLMs like ChatGPT for "SaaS ideas" outputs corporate, sanitized, and generic concepts disconnected from actual consumer pain points.

### The Niche Monitor Solution
Niche Monitor replaces assumptions with empirical evidence. In under 5 minutes, it:
1. Scours public Reddit discussions for raw, unprompted consumer frustration.
2. Mines verbatim buyer quotes and provides transparent, clickable source permalinks.
3. Synthesizes commercial gaps and unmet market demands using Claude Sonnet 3.5.
4. Automatically generates a high-converting, direct-response landing page hosted at `https://nichemonitor.site/p/[slug]`.
5. Embeds simulated checkout and waitlist modals to quantify true buyer willingness-to-pay (WTP) before writing a single line of production code.

---

## 2. Platform Architecture & Tech Stack

Niche Monitor is built with modern, production-grade cloud and edge technologies:

- **Framework**: Next.js 15 (App Router with Server Components and Route Handlers)
- **UI Library**: React 19, Tailwind CSS v4, Lucide React
- **Language**: TypeScript 5.9 (Strict mode enabled)
- **Database & Auth**: Supabase (PostgreSQL with Row Level Security, pg_stat, edge auth)
- **Billing**: Korapay (cards, mobile money, bank transfers, automated webhooks with HMAC validation); all prices are in GHS
- **Email Service**: Resend (transactional email, verification alerts, lead delivery)
- **Search & Social Discovery**: Google Custom Search Engine / SerpAPI
- **AI Synthesis**: Anthropic Claude 3.5 Sonnet / OpenRouter API
- **Edge Deployment**: Edge-ready serverless execution with dynamic sitemap, robots, and open graph image generation.

---

## 3. The 4-Step Validation Pipeline

### Step 1: Niche Definition & Query Expansion
- **User Action**: The user enters a target market (e.g., "independent coffee roasters", "indie podcast editing", "Shopify inventory syncing").
- **System Action**: 
  - Expands the seed niche into a hierarchy of sub-niches and target buyer personas.
  - Constructs targeted search queries appended with Reddit operators (`site:reddit.com`, `"hate that"`, `"wish there was"`, `"waste of time"`, `"looking for an alternative"`).
  - Identifies relevant subreddits where real practitioners congregate.

### Step 2: Voice of Customer (VoC) Mining & Permalinks
- **Data Collection**: Executes queries across search endpoints and Reddit discussions.
- **Scoring & Filtering**:
  - Filters out bot comments, spam, self-promotion, and generic replies.
  - Ranks threads by comment upvotes, emotional intensity, and expressed frustration.
  - Extracts verbatim quotes describing pain points, broken workflows, and financial loss.
- **Source Verification**: Every quote includes the verified Reddit permalink, subreddit name, and author context, guaranteeing empirical truth without AI hallucination.

### Step 3: Strategic Market Gap Synthesis
- **AI Analysis**: Feeds mined quotes into Anthropic Claude 3.5 Sonnet with a specialized prompt framework:
  - Current Workarounds & Fails: What jury-rigged setups are users currently relying on?
  - Switching Costs: Why haven't incumbent tools solved this yet?
  - Unmet Value Proposition: What specific capability would make them switch immediately?
- **Output**: Generates 3 differentiated product positioning angles, each complete with:
  - Value proposition headline & hook
  - Core feature specifications addressing mined quotes
  - Suggested pricing model (monthly subscription vs. usage-based vs. one-time)
  - Estimated TAM (Total Addressable Market) and validation score

### Step 4: Instant Smoke-Test Landing Page Deployment
- **Generation**: Generates an aesthetic, high-converting direct-response landing page tailored to the selected market gap.
- **Content Elements**:
  - Punchy hero section addressing the exact pain points discovered in Step 2.
  - Verbatim customer quote wall (with disclaimers indicating they are community-sourced complaints).
  - Feature matrix directly mapping to complaints.
  - Clear pricing tier with pre-order call-to-action.
  - Email waitlist and simulated checkout modal.
- **Live Hosting**: Deployed instantly to `https://nichemonitor.site/p/[slug]` with SSL and edge caching.
- **Analytics & Telemetry**: Tracks visitor sessions, waitlist signups, and button click intent.

---

## 4. Pre-Order & Checkout Simulation Mechanics

Niche Monitor enables founders to measure true buying intent without processing premature credit card charges:

1. **Pre-Order Intent Button**: When a visitor clicks "Pre-Order Now ($X/mo)", the page triggers a simulated checkout modal.
2. **Intent Measurement**: The visitor enters their email address and confirms their intent to purchase upon release.
3. **Founder Alert**: The founder receives an instant email notification via Resend with the new lead details and intent tier.
4. **Ethical Transparency**: The modal informs the prospective buyer that the product is in private beta/early access, that their card will not be charged today, and that they will receive priority access and an early-bird discount when public launch occurs.

---

## 5. API Routes & Endpoints

| Endpoint | Method | Description | Auth Required |
|---|---|---|---|
| `/api/sessions` | POST | Creates a new idea validation session | Optional (guest supported) |
| `/api/sessions/[id]/step1` | POST | Executes niche definition & query expansion | No |
| `/api/sessions/[id]/step2` | POST | Scrapes Reddit threads and extracts VoC quotes | No |
| `/api/sessions/[id]/step3` | POST | Synthesizes 3 strategic market gap angles | No |
| `/api/sessions/[id]/step4` | POST | Generates full landing page copy and HTML | No |
| `/api/sessions/[id]/publish` | POST | Publishes landing page to live `/p/[slug]` URL | Yes |
| `/api/sessions/[id]/claim` | POST | Associates an anonymous guest session to a user | Yes |
| `/api/leads` | POST | Captures waitlist lead on hosted smoke-test page | No |
| `/api/leads/export` | GET | Exports leads as CSV for a specific page slug | Yes (Owner) |
| `/api/billing/checkout` | POST | Initiates a Korapay/Paystack checkout session | Yes |
| `/api/billing/portal` | POST | Generates the customer billing portal URL | Yes |
| `/api/webhooks/billing/[provider]` | POST | Processes billing webhook events | Webhook Signature |
| `/api/auth/welcome` | POST | Dispatches onboarding welcome email | Internal / Auth |

---

## 6. Commercial Model & Pricing Tiers

1. **Free Validation Run (GHS 0)**
   - 1 complete end-to-end validation run
   - Deep Reddit quote mining & thread discovery
   - 3 AI-synthesized market gap angles
   - Live hosted landing page preview
   - No credit card required

2. **Validation Credit Pack (GHS 49 one-time)**
   - 10 full validation runs
   - Credits never expire
   - Full CSV export of VoC quotes and buyer leads
   - Priority edge hosting for all smoke-test pages

3. **Pro Subscription (GHS 77/month)**
   - Unlimited validation sweeps and idea explorations
   - Priority LLM generation queue (Claude Sonnet 3.5)
   - Unlimited hosted smoke-test landing pages
   - Real-time email alerts for every captured lead
   - Access to custom query refinement and subreddit blacklists

---

## 7. Legal, Privacy & Compliance Guardrails

- **GDPR & CCPA**: Full data sovereignty compliance. Users can request data exports (`/api/user/export`) or account freezing/deletion (`/api/user/freeze`) at any time.
- **CAN-SPAM & Opt-Out**: Dedicated self-service email unsubscribe portal at `/unsubscribe`. Every outgoing transactional and notification email contains explicit opt-out links and business identification.
- **FTC 16 CFR Part 465**: Customer quote blocks generated on smoke-test pages strictly reflect anonymized, publicly posted consumer sentiments. The platform enforces truth-in-advertising guidelines and does not fabricate fictitious consumer testimonials.
- **Reddit API Terms & Data Ethics**: Only publicly available discussions are parsed using standard search endpoints. Personal identifiers, emails, and phone numbers are never harvested from social forums.

---

## 8. SEO & Social Discovery Configuration

- **Domain**: https://nichemonitor.site
- **Sitemap**: https://nichemonitor.site/sitemap.xml (dynamic, updates with new published smoke-test landing pages)
- **Robots Policy**: https://nichemonitor.site/robots.txt (allows public pages, `/p/` published pages, and `/llms.txt`; disallows `/admin/`, `/dashboard`, `/session/`, and private endpoints)
- **OpenGraph & Twitter Cards**: Dynamic 1200x630 cards rendered server-side via `next/og` at `/opengraph-image` and `/twitter-image`.
- **Structured Data**: JSON-LD schemas embedded for `WebSite`, `SoftwareApplication`, `Organization`, and `FAQPage`.
- **LLM Manifests**:
  - Overview: `/llms.txt`
  - Full Technical Reference: `/llms-full.txt`

---

## 9. Contact & Business Disclosures

- **Product**: Niche Monitor
- **Website**: https://nichemonitor.site
- **Support & Inquiries**: support@nichemonitor.site
- **Payment Provider**: Korapay (cards, mobile money, bank transfers)
- **Terms**: https://nichemonitor.site/terms
- **Privacy**: https://nichemonitor.site/privacy
- **Imprint**: https://nichemonitor.site/imprint