> **Disclaimer:** This blueprint is provided by Fabrika42 for educational and > informational purposes. It describes architectural patterns and implementation > strategies based on our experience. Technology choices, pricing, and market > data are current as of the publish date and may change. Cost estimates are > approximations based on our usage patterns and may vary. This document does > not constitute financial, legal, or professional advice. All trademarks > mentioned belong to their respective owners. Published: April 2026. > **Domain Notice:** Tools built from this blueprint generate market-opportunity > analysis using AI. Output should be reviewed by the user and is not a substitute > for professional business, financial, or investment advice. Users are > responsible for verifying accuracy and suitability of any recommendations > before acting on them. Building or buying any iOS application requires > compliance with Apple Developer Program terms and applicable local regulations. > **Difficulty:** Intermediate · **Build time:** 3-5 weeks with AI assistance · **Monthly cost:** $35-55 · **Category:** AI Tool / SaaS ## How to Use This Blueprint **Who this is for:** Builders (coding themselves or directing an AI agent) who want to ship a market-intelligence SaaS for the iOS App Store, or apply the same pattern to any large public marketplace where solo operators need decision-grade signal. **What's inside:** 13 sections covering the full stack from architecture to agent build prompts. Sections 1-2 are public market context; Sections 3-13 are the technical buildout. **Two paths:** 1. **Read 1-12, build yourself.** Understand the architecture and decisions, then implement at your own pace. 2. **Skip to Section 13.** Copy the Agent Build Instructions into your AI coding agent (Claude Code, Cursor, Copilot CLI), let it scaffold, then refine. **Time estimate:** Reading time about 30 minutes. Build time with AI assistance: 3-5 weeks part-time or 7-10 days full-time. --- ## What an iOS App Opportunity Scanner Actually Does An iOS app opportunity scanner is a market-intelligence platform that takes the entire top of the US App Store, runs an AI analysis on every app, and produces a single decision-grade score (0-100) telling a solopreneur whether each app represents a viable opportunity for one person plus AI to compete with. Not "here is a wall of metrics", but "here is the score, here is why, build this or skip it." The user opens a category (Productivity, Health & Fitness, Finance, any of 27), sees the top 100 ranked apps with a Solopreneur Score badge next to each, clicks any app, and gets a structured analysis covering the apps unhappy reviews, missing features, monetization model, MVP complexity estimate, and explicit risks. The output is a decision, not a dashboard. **What you get when finished:** - Daily-refreshed catalog of about 20,000 US iOS apps across 27 categories and 3 ranking types (Top Free, Top Paid, Top Grossing) - AI-generated Solopreneur Score (0-100) per app, derived from a 7-dimension rubric (market validation, user satisfaction, competition, technical complexity, monetization, MVP feasibility, risk) - Per-app deep analysis: complaints from real reviews, feature gaps, MVP timeline estimate, recommended tech stack, monetization strategy, identified risks - Three-tier access model: public preview (3 categories), authenticated free (all 27 categories + rankings), Pro paid (AI scoring + exports) - Stripe-powered subscription billing - Admin panel: trigger fetcher runs, manage AI analysis queue, manage users, view system stats - Multi-provider AI layer with automatic fallback across free open-weight models (zero marginal AI cost) - Production-ready Docker Compose deploy on a single VPS **Who uses the finished product:** Wantrepreneurs and solo iOS developers hunting for their next app idea. They are non-technical or lightly technical, lean on AI to do the building, and need a way to choose a market without spending $25,000 a year on enterprise-grade analytics. ## Why iOS App Opportunity Scanning Is a Real Solopreneur Opportunity The US App Store ecosystem facilitated $406 billion in developer billings and sales in 2024, up from $142 billion in 2019, according to [Apple](https://www.apple.com/newsroom/2025/05/app-store-in-the-us-facilitated-406-billion-usd-in-developer-billings-and-sales-in-2024/). 557,000 new apps were submitted to the App Store in 2025, the first meaningful increase since 2016, per [Appfigures](https://appfigures.com/resources/insights/20251205?f=2). 783,729 publishers are active on the platform, per [Business of Apps](https://www.businessofapps.com/data/apple-app-store-statistics/). The standard tools for analyzing this market (Sensor Tower, data.ai, Apptopia, AppMagic) start at $25,000 to $200,000 per year on annual contracts, per aggregator data from [Vendr](https://www.vendr.com/marketplace/sensor-tower) and [RespectASO](https://respectaso.com/blog/aso-tool-pricing-true-cost-comparison/). They were configured for mobile growth teams at funded companies, not for solo operators with a credit card. The cheaper indie alternatives (Appfigures Connect at $9.99/month, AppWatch at €19/month) deliver raw data without the AI scoring layer that turns metrics into decisions. The new wave of AI-powered idea-validation tools that emerged in 2025-2026 (WorthBuild, IdeaProof, Validator AI, ProductGapHunt, ValidateMySaaS) all chose SaaS as the wedge market; none of them are tuned for iOS app builders, per [WorthBuild's own comparison](https://worthbuild.io/blog/best-startup-idea-validation-tools-2026-comparison). That leaves an empty quadrant: AI-driven opportunity scoring at indie pricing, built specifically for solopreneurs choosing what iOS app to build next. Combined with Apple's [Small Business Program](https://developer.apple.com/app-store/small-business-program/) (15% commission instead of 30% for developers earning under $1 million per year) and the collapse in frontier-AI cost via free-tier OpenRouter models, the unit economics for both the scanner and its users have never been better. **Unit economics of the scanner itself:** - Marginal AI cost per analysis: about $0 (free-tier model rotation across 7 providers with smart fallback) - Total infrastructure: $35-55 per month on a single VPS - Suggested Pro tier: $29 per month - Break-even: about 2 paying Pro subscribers Below is everything you need to build it. Architecture, complete database schema, every feature spec, deployment configs, the exact environment variables, common failure modes, and a copy-paste agent prompt. ## Architecture Overview **Plain-language summary:** Standard three-tier web app. SPA frontend (Angular) talks to a TypeScript API (Express) which talks to PostgreSQL. Two background workers run on cron: a fetcher that pulls Apple's iTunes RSS feeds and a scorer that runs AI analysis through OpenRouter (with Gemini as fallback). Redis handles sessions. Nothing exotic; the value is in the scoring methodology and the AI-cost economics, not the infrastructure. ``` [User Browser] | v [Cloudflare CDN/SSL] | v [nginx Reverse Proxy] | +-----------------+------------------+ | | v v [Angular SPA (static)] [Express API (Node.js)] | +----------------------------------------+----------------------------+ | | | | | v v v v v [PostgreSQL] [Redis] [iTunes RSS [OpenRouter [Stripe] (apps, users, (sessions, Fetcher cron] AI router + rankings, job queue) | Gemini fallback] AI analyses, v | subscriptions) [App Store (cron-driven Public Data] AI analysis) ``` **Major components:** - **Frontend (Angular SPA):** Static-built, serves marketing landing + authenticated dashboard + admin panel as one app. Communicates with backend via JSON API only. - **Backend API (Express + TypeScript):** Stateless REST API. JWT auth in httpOnly cookies. ~50 endpoints organized by access tier (public preview / authenticated free / Pro / admin). - **PostgreSQL:** Source of truth for all data (apps, rankings, reviews, AI analyses, users, subscriptions). - **Redis:** Session store and a lightweight in-process job queue for the AI worker. - **iTunes RSS Fetcher (cron worker):** Hits Apple's public iTunes RSS feeds for top 100 apps per category per ranking type. Refreshes daily. - **AI Scorer (cron worker):** Picks unscored or stale apps from the queue, sends app metadata + reviews to OpenRouter, parses the structured response, writes a Solopreneur Score and structured analysis row. - **Stripe:** Subscription billing for the Pro and Enterprise tiers. **Data flow (one full cycle):** 1. Fetcher cron triggers at a fixed time. It iterates the 27 App Store categories times 3 ranking types (81 feeds total) at a polite rate (1 second between feeds, 2 seconds between categories) and writes new ranking rows. 2. Newly seen apps are inserted into the catalog with metadata. 3. AI scorer cron picks apps that are either un-scored or whose last analysis is older than 6 months. 4. For each app, the scorer pulls the app metadata and recent reviews, formats them into a structured prompt, sends to OpenRouter (free-tier model with priority fallback chain), parses the JSON response. 5. Result is written to the AI analysis table. The Solopreneur Score is now visible in the API. 6. User opens the dashboard, hits the API, sees ranked apps with scores. Pro users can drill into the full per-app analysis. **Key architectural decisions:** - **Server-side everything except UI rendering.** All sorting, filtering, and pagination is done in the database. Client-side data manipulation breaks at any meaningful catalog size. - **AI provider abstraction layer.** The scorer does not know it is calling OpenRouter or Gemini; it calls a provider-agnostic interface. Swap providers in one file. This makes the free-tier rotation possible. - **No real-time streaming.** Analyses run on cron. Pro users see the result of yesterday's analysis run, not a live recompute. Real-time would 50x the cost without 50xing the user value. - **JWT in httpOnly cookies, not localStorage.** Cross-subdomain SSO is part of the planned platform; localStorage cannot do this securely. **What this architecture intentionally does NOT include:** - No user-uploaded data. Scope is tightly limited to public App Store data. - No team features, multi-seat billing, or RBAC beyond a 4-role model. Solopreneurs work alone; team complexity is feature creep. - No mobile app. The user does this research on a laptop, not a phone. - No event-streaming bus (Kafka/Pulsar). Cron writes to PostgreSQL; PostgreSQL is the bus. - No microservices. Single backend monolith. Splitting would multiply ops cost without benefit at this scale. ## Tech Stack and Decisions **Plain-language summary:** TypeScript everywhere except the database. Angular 17 SPA, Express + Postgres + Redis backend, OpenRouter for free-tier AI rotation with Gemini as fallback, Stripe for billing, Docker Compose on a Hetzner VPS behind Cloudflare. Total monthly stack cost: $35-55. | Layer | Choice | Version | Why | Alternatives Considered | |-------|--------|---------|-----|------------------------| | Frontend framework | Angular | 17.x (standalone components) | Robust SPA framework, strong typing, mature DI, good fit for admin-heavy apps | Next.js (better SSR/SEO but adds Node-server complexity for static SPA), SvelteKit (smaller ecosystem) | | UI library | Angular Material | 17.x | Free, accessible, integrates natively with Angular DI, no design budget needed | Tailwind + shadcn (more design effort), PrimeNG (less consistent) | | Backend runtime | Node.js | 20 LTS | TS support, mature ecosystem, single-language stack with frontend | Bun (newer, less proven for production), Deno (smaller ecosystem) | | API framework | Express | 4.18+ | Boring, stable, every middleware exists for it | Fastify (faster, but ecosystem cost), Hono (minimal, less battle-tested) | | ORM / DB layer | pg (raw queries) + custom service layer | pg 8.11+ | Full SQL control matters for ranking queries; ORMs hide cost | Drizzle (great TS types, fine alternative), Prisma (heavier, slower) | | Database | PostgreSQL | 14+ Alpine | Free, mature, JSON support, no managed-service lock-in | SQLite (insufficient for concurrent writes), MySQL (weaker JSON) | | Session store | Redis | 7-Alpine | Fast, mature, used for both sessions and lightweight job queue | In-memory (lost on restart), Memcached (no persistence) | | Auth | JWT + bcrypt + connect-redis | jsonwebtoken 9.x, bcrypt 5.x | httpOnly cookies, refresh-token rotation, cross-subdomain SSO ready | Auth0 / Clerk (cost + lock-in), Lucia (newer, smaller community) | | Validation | Joi | 17.11+ | Mature, declarative, integrates with Express | Zod (better TS inference, also fine), express-validator (less expressive) | | AI provider (primary) | OpenRouter | API as of April 2026 | Free-tier rotation across 7 frontier models with auto-fallback. Marginal cost approaches zero. | Direct Gemini (rate-limited heavily on free tier), direct DeepSeek (single-model risk), OpenAI (paid only) | | AI provider (fallback) | Google Gemini | gemini-2.5-flash-lite (1000 req/day free) | Backup when OpenRouter outage; pay nothing if traffic stays under quota | Anthropic API (paid only at scale), Mistral (less generous free tier) | | Payments | Stripe | 14.25+ | Industry standard, generous test mode, good webhooks | Lemonsqueezy (good for digital, fewer features), Paddle (merchant-of-record, higher fees) | | Email (transactional) | AWS SES | @aws-sdk 3.x | Cheapest at scale; alternative is Resend free tier (3K/month) | Resend (better DX, lower free tier), SendGrid (slower onboarding) | | Logging | Winston | 3.11+ | Standard Node logger, easy structured logs | pino (faster, slightly steeper learning curve) | | Hosting | Hetzner CX22 VPS | latest | $4.50/month for 2 vCPU/4GB RAM. Pricing/performance is unmatched in EU. | DigitalOcean (1.5x price for same specs), Fly.io (more complex pricing), AWS (10x at this scale) | | Containerization | Docker Compose | latest | Single-host orchestration, no Kubernetes overhead | Plain systemd (less reproducible), K8s/k3s (massive overkill) | | Reverse proxy | nginx | 1.25+ | Stable, well-known, free | Caddy (auto-SSL but less mature ecosystem), Traefik (Docker-native, more moving parts) | | SSL / CDN / DDoS | Cloudflare | (free tier) | Free SSL, DDoS protection, edge caching | Bring-your-own LE certs (no DDoS layer), AWS CloudFront (paid) | | CI/CD | GitHub Actions | latest | Free for public, generous private minutes, ubiquitous | GitLab CI (extra account), self-hosted Drone (ops cost) | | Process supervisor | Docker restart policies + healthchecks | n/a | Compose handles restart on failure; no PM2 needed inside container | PM2 (extra layer), systemd (host-coupled) | **Environment requirements:** - Node.js 20 LTS (use nvm to pin version) - Docker 24+ and Docker Compose v2 - PostgreSQL 14+ (containerized, no host install needed) - Redis 7+ (containerized) - Linux VPS with at least 2 vCPU and 4GB RAM (Hetzner CX22 is the minimum) **Required external accounts and API keys:** - **Hetzner Cloud:** [hetzner.com](https://www.hetzner.com/cloud) ($4.50/month CX22 instance) - **Cloudflare:** [cloudflare.com](https://www.cloudflare.com/) (free tier) - **Domain registrar of your choice** ($10-15/year) - **OpenRouter:** [openrouter.ai](https://openrouter.ai/) (free tier, no card required for free models) - **Google AI Studio (Gemini):** [aistudio.google.com](https://aistudio.google.com/) (free tier, optional fallback) - **Stripe:** [stripe.com](https://stripe.com/) (no monthly fee, pay per transaction) - **AWS account** (for SES) or **Resend** (free tier 3K/month) - **GitHub account** (for repo + Actions CI/CD) **Development tools:** - VS Code or Cursor with Angular Language Service + ESLint extensions - Postman or HTTPie for API testing - TablePlus or Postico for PostgreSQL inspection - Docker Desktop on local dev machine ## Data Model **Plain-language summary:** About 15 tables organized into four clusters: identity (users, sessions, refresh tokens), catalog (apps, app details, rankings, app metrics, reviews), intelligence (AI analyses, market opportunities, trending patterns, competitor groups), and billing (subscriptions, system config). The core relationship: an app has many rankings (one per day per ranking type per country), many reviews, and exactly one current AI analysis. A user has zero or one active subscription and zero or many sessions. **Note on JSONB shapes:** This product stores several flexible-schema fields as JSONB. The exact shapes are defined inline below. AI agents must implement these shapes precisely or downstream features will silently produce wrong results. ### Identity Cluster ``` users - id UUID PRIMARY KEY DEFAULT gen_random_uuid() - email VARCHAR(255) UNIQUE NOT NULL - password_hash VARCHAR(255) NOT NULL -- bcrypt cost factor 12 - name VARCHAR(255) NOT NULL - role VARCHAR(50) DEFAULT 'user' -- one of: 'user', 'pro', 'admin' - subscription_tier VARCHAR(50) DEFAULT 'free' -- 'free' | 'pro' | 'enterprise' - registration_source VARCHAR(255) -- which subdomain/campaign user came from - stripe_customer_id VARCHAR(255) - email_verified BOOLEAN DEFAULT false - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP - updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP refresh_tokens - id UUID PRIMARY KEY DEFAULT gen_random_uuid() - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE - token_hash VARCHAR(255) NOT NULL -- never store plain refresh tokens - expires_at TIMESTAMP NOT NULL - revoked BOOLEAN DEFAULT false - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP - INDEX (user_id, revoked, expires_at) email_verifications - id UUID PRIMARY KEY DEFAULT gen_random_uuid() - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE - token_hash VARCHAR(255) NOT NULL - expires_at TIMESTAMP NOT NULL - consumed_at TIMESTAMP ``` Sessions are stored in Redis via connect-redis, not in PostgreSQL. ### Catalog Cluster ``` apps - app_id VARCHAR(255) PRIMARY KEY -- Apple's iTunes app ID, e.g. "284882215" - name VARCHAR(255) - developer VARCHAR(255) - developer_id VARCHAR(255) - developer_url TEXT - category VARCHAR(100) -- one of 27 fixed categories, see Categories enum - platform VARCHAR(50) DEFAULT 'ios' - bundle_id VARCHAR(255) - summary TEXT - content_rating VARCHAR(50) - price DECIMAL(10,2) DEFAULT 0 - currency VARCHAR(10) DEFAULT 'USD' - app_url TEXT - icon_url TEXT - release_date DATE - title VARCHAR(500) - updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP - INDEX (category) app_details - app_id VARCHAR(255) PRIMARY KEY REFERENCES apps(app_id) ON DELETE CASCADE - current_version VARCHAR(20) - size_bytes BIGINT - minimum_os_version VARCHAR(20) - supported_devices TEXT -- JSON array of device identifiers - languages TEXT -- JSON array of language codes - age_rating VARCHAR(10) - has_in_app_purchases BOOLEAN DEFAULT false - in_app_purchase_data JSONB /* Shape: [ { "name": string, "price": string, "tier_id": string } ] */ - subscription_data JSONB /* Shape: [ { "name": string, "period": "weekly" | "monthly" | "yearly", "price": string, "free_trial_days": integer | null } ] */ - screenshots_data JSONB /* Shape: [ { "url": string, "device_type": string, "order": integer } ] */ - whats_new TEXT - version_date DATE - seller_name VARCHAR(255) - seller_url TEXT - privacy_policy_url TEXT - collected_date DATE DEFAULT CURRENT_DATE rankings - id BIGSERIAL PRIMARY KEY - app_id VARCHAR(255) NOT NULL REFERENCES apps(app_id) - country VARCHAR(10) NOT NULL -- 'US' for v1, structure supports more - rank_type VARCHAR(50) NOT NULL -- 'topfreeapplications' | 'toppaidapplications' | 'topgrossingapplications' - category VARCHAR(100) NOT NULL - rank INTEGER NOT NULL -- 1 to 100; rank 101 used as "dropped out" sentinel - date DATE NOT NULL - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP - UNIQUE (app_id, country, rank_type, category, date) - INDEX (date) - INDEX (app_id, country) - INDEX (rank_type) app_metrics - id BIGSERIAL PRIMARY KEY - app_id VARCHAR(255) NOT NULL REFERENCES apps(app_id) - date DATE NOT NULL - rating_average DECIMAL(2,1) -- 0.0 to 5.0 - rating_count INTEGER - review_count INTEGER - price DECIMAL(10,2) DEFAULT 0 - has_in_app_purchases BOOLEAN DEFAULT false - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP - UNIQUE (app_id, date) app_reviews - id BIGSERIAL PRIMARY KEY - app_id VARCHAR(255) REFERENCES apps(app_id) - review_id VARCHAR(255) UNIQUE -- Apple's review ID, dedupe key - author_label VARCHAR(255) -- store as label only, never PII - rating INTEGER CHECK (rating >= 1 AND rating <= 5) - title TEXT - content TEXT - version VARCHAR(20) - review_date DATE - helpful_count INTEGER DEFAULT 0 - sentiment VARCHAR(20) -- 'positive' | 'neutral' | 'negative' | null - collected_date DATE DEFAULT CURRENT_DATE - INDEX (app_id, review_date) ``` ### Intelligence Cluster ``` ai_analyses - id BIGSERIAL PRIMARY KEY - app_id VARCHAR(255) UNIQUE REFERENCES apps(app_id) ON DELETE CASCADE - analysis_version VARCHAR(20) NOT NULL -- bump when scoring rubric changes - analysis_timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP -- Solopreneur Score (the main output) - solopreneur_score INTEGER NOT NULL CHECK (solopreneur_score BETWEEN 0 AND 100) - score_confidence DECIMAL(3,2) -- 0.0 to 1.0, AI's self-reported confidence -- 7-dimension breakdown (each 0-100) - market_validation_score INTEGER - user_satisfaction_score INTEGER - competition_score INTEGER -- inverted: high score = low competition - technical_complexity_score INTEGER -- inverted: high score = low complexity - monetization_score INTEGER - mvp_feasibility_score INTEGER - risk_score INTEGER -- inverted: high score = low risk -- Structured analysis output (JSONB; shape defined in Section 6 / 7) - analysis_data JSONB NOT NULL /* Shape (every field required): { "core_purpose": string (1-2 sentences), "target_user": string (1 sentence), "common_complaints": [string, ...] (3-7 items, each 1 short sentence), "missing_features": [string, ...] (2-5 items), "monetization_model": "free" | "freemium" | "paid_app" | "subscription" | "iap_heavy" | "ad_supported", "estimated_mvp_weeks": integer (1-12), "estimated_mvp_investment_usd": integer (rounded to nearest 500), "tech_stack_recommendation": [string, ...] (3-6 items), "key_risks": [string, ...] (2-5 items), "competitive_advantage_required": string (1-2 sentences), "swiss_or_niche_opportunity": string | null } */ - INDEX (solopreneur_score) - INDEX (analysis_timestamp) market_opportunities - id BIGSERIAL PRIMARY KEY - app_id VARCHAR(255) NOT NULL REFERENCES apps(app_id) - opportunity_type VARCHAR(50) NOT NULL -- 'underperforming' | 'trending_up' | 'abandoned' | 'gap' - target_market VARCHAR(100) - opportunity_score DECIMAL(4,2) -- 0.0 to 100.0, finer-grained than solopreneur_score - description TEXT - discovered_date DATE NOT NULL - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP - INDEX (opportunity_type, discovered_date) trending_patterns - id BIGSERIAL PRIMARY KEY - pattern_name VARCHAR(255) NOT NULL - pattern_type VARCHAR(50) -- 'category' | 'feature' | 'monetization' | 'design' - app_count INTEGER - average_rank DECIMAL(6,2) - examples JSONB -- array of app_id strings, e.g. ["284882215", "..."] - date DATE NOT NULL competitor_groups - id BIGSERIAL PRIMARY KEY - group_name VARCHAR(255) NOT NULL - category VARCHAR(100) - app_ids JSONB -- array of app_id strings - common_features JSONB -- array of strings - market_gaps JSONB -- array of strings - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ``` ### Billing Cluster ``` subscriptions - id UUID PRIMARY KEY DEFAULT gen_random_uuid() - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE - stripe_subscription_id VARCHAR(255) UNIQUE - stripe_price_id VARCHAR(255) - tier VARCHAR(50) NOT NULL -- 'pro' | 'enterprise' - status VARCHAR(50) -- 'active' | 'past_due' | 'canceled' | 'incomplete' | 'trialing' - current_period_end TIMESTAMP - cancel_at_period_end BOOLEAN DEFAULT false - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP - updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP - INDEX (user_id, status) subscription_events - id BIGSERIAL PRIMARY KEY - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE - subscription_id UUID REFERENCES subscriptions(id) - event_type VARCHAR(100) NOT NULL -- mirrors Stripe webhook event names - payload JSONB - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP system_config - id SERIAL PRIMARY KEY - config_key VARCHAR(100) UNIQUE NOT NULL - config_value JSONB NOT NULL /* Examples of stored configs: - "ai_provider": "openrouter" | "gemini" - "openrouter_models": { "fallback_enabled": bool, "prioritized_models": [...] } - "gemini_models": { "prioritized_models": [...] } - "fetcher_schedule_cron": string */ - description TEXT - is_active BOOLEAN DEFAULT true - updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ai_provider_usage - id BIGSERIAL PRIMARY KEY - provider VARCHAR(50) NOT NULL -- 'openrouter' | 'gemini' - model_id VARCHAR(255) NOT NULL - date DATE NOT NULL DEFAULT CURRENT_DATE - requests_count INTEGER DEFAULT 0 - successful_requests INTEGER DEFAULT 0 - input_tokens BIGINT DEFAULT 0 - output_tokens BIGINT DEFAULT 0 - UNIQUE (provider, model_id, date) ``` **Categories enum (the 27 fixed categories):** Books, Business, Developer Tools, Education, Entertainment, Finance, Food & Drink, Games, Graphics & Design, Health & Fitness, Kids, Lifestyle, Magazines & Newspapers, Medical, Music, Navigation, News, Photo & Video, Productivity, Reference, Shopping, Social Networking, Sports, Travel, Utilities, Weather, Stickers. Public preview tier shows only 3 of these (default: Business, Travel, Productivity); free authenticated users see all 27; Pro adds AI scoring access. **Migration order (foreign-key safe):** users -> refresh_tokens, email_verifications -> apps -> app_details, rankings, app_metrics, app_reviews -> ai_analyses, market_opportunities -> subscriptions, subscription_events -> system_config, ai_provider_usage -> trending_patterns, competitor_groups (independent). ## Core Features Specification **Plain-language summary:** About 50 endpoints across 5 groups: Authentication (8), Catalog Browsing (10), AI Intelligence (Pro tier, 7), Billing (4), Admin (~21). The core product loop: user picks a category, sees the top-100 list with a Solopreneur Score next to each app, clicks an app to see the full AI analysis, decides whether to build it. **Standard API response envelope** (used by every endpoint): ``` Success: { "success": true, "data": } Error: { "success": false, "error": { "code": string, "message": string } } Paginated: { "success": true, "data": , "pagination": { "page": int, "page_size": int, "total": int, "total_pages": int } } ``` Standard error codes: `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `RATE_LIMITED`, `PAYMENT_REQUIRED`, `INTERNAL_ERROR`. **Standardized AI analysis output shape** (consumed by every Pro-tier feature; produced by the AI scorer; mirrors `ai_analyses.analysis_data` JSONB shape from Section 5): ```json { "core_purpose": "Daily habit tracking with streak gamification and reminders.", "target_user": "Productivity-minded individuals building personal habits.", "common_complaints": [ "Subscription unlocks core features after 7-day trial.", "iCloud sync fails silently between devices.", "Notifications often arrive late." ], "missing_features": ["Apple Watch complications", "Shareable streaks", "Habit templates"], "monetization_model": "freemium", "estimated_mvp_weeks": 4, "estimated_mvp_investment_usd": 2000, "tech_stack_recommendation": ["SwiftUI", "CloudKit", "RevenueCat", "SQLite"], "key_risks": [ "Category is crowded with 50+ established players.", "Retention drops sharply after 14 days for habit apps." ], "competitive_advantage_required": "Either differentiated UX or specific niche habit (e.g., recovery, fitness).", "swiss_or_niche_opportunity": "Underserved: German-speaking habit tracker with proper Apple-Watch support." } ``` ### Solopreneur Score Algorithm The Solopreneur Score is the single most important signal in the product. It must be deterministic given the same input. Define it precisely. **Output:** integer 0-100. Higher means better opportunity for one person plus AI to compete. **Inputs:** the app's metadata (category, price, IAP presence), recent rankings (last 30 days), recent reviews (last 100, balanced sample of ratings), and the AI's structured 7-dimension scores. **Computation:** ``` solopreneur_score = round( 0.20 * market_validation_score + 0.20 * user_satisfaction_inverted + 0.15 * competition_score + 0.15 * technical_complexity_score + 0.10 * monetization_score + 0.10 * mvp_feasibility_score + 0.10 * risk_score ) Where: - user_satisfaction_inverted = 100 - user_satisfaction_score (we WANT unhappy users; they signal opportunity to replace) - competition_score, technical_complexity_score, risk_score are returned by the AI on an inverted scale where high = good for us Penalties (subtract after weighted sum): - if app is in top-10 of category for 90+ consecutive days: -20 (entrenched incumbents are hard to displace) - if app rating >= 4.7 and review_count >= 1000: -25 (loved apps with mass adoption are wrong targets for replacement) - if technical_complexity_score < 30: -15 (extremely complex apps are not solopreneur-buildable) Floor at 0, cap at 100. Thresholds for UI labeling: - 0-39: "Skip" (red badge) - 40-59: "Maybe" (gray badge) - 60-79: "Worth Researching" (accent color) - 80-100: "High Opportunity" (gold/highlight) ``` The 7 dimension scores come directly from the AI; the weighting and penalties happen in the backend service layer, not in the AI prompt. This makes the rubric easy to tune without re-running every AI analysis. ### Group A: Authentication (8 endpoints) **Feature: User Registration** - **What it does:** Creates a new user account, sends email verification. - **User flow:** User submits email + password + name; backend validates, hashes password, creates user record with `email_verified=false`, sends verification email. - **Endpoint:** `POST /api/auth/register` - **Input:** `{ email: string, password: string (min 8, must include digit), name: string, registration_source?: string }` - **Processing:** Validate input -> check uniqueness -> bcrypt hash (cost 12) -> insert user -> generate verification token -> send email. - **Output:** `{ success: true, data: { user_id: uuid, email_verified: false } }` - **Edge cases:** Email already exists (return `VALIDATION_ERROR` with code `EMAIL_TAKEN`, never reveal if it's truly taken vs reserved). Email send failure (still return success, log for retry). - **Business logic:** Default tier is `free`. Default role is `user`. - **Dependencies:** Email service. **Feature: User Login** - **Endpoint:** `POST /api/auth/login` - **Input:** `{ email: string, password: string }` - **Processing:** Lookup user -> bcrypt compare -> issue access token (15 min) + refresh token (7 days) -> store refresh token hash -> set as httpOnly cookies. - **Output:** `{ success: true, data: { user: { id, email, name, role, subscription_tier } } }` - **Edge cases:** Bad credentials -> generic `UNAUTHORIZED` (never confirm if email exists). Lock account after 5 failed attempts in 15 minutes (rate-limit by email). - **Business logic:** Cookie domain: `.{your_root_domain}` for cross-subdomain SSO. **Feature: Token Refresh** - **Endpoint:** `POST /api/auth/refresh` - **Processing:** Read refresh cookie -> verify hash -> rotate (revoke old, issue new) -> reissue access token. - **Edge cases:** If refresh token is reused after revocation, revoke ALL the user's refresh tokens (token theft pattern). **Feature: Logout** - **Endpoint:** `POST /api/auth/logout` - **Processing:** Revoke current refresh token, clear cookies. **Feature: Email Verification** - **Endpoint:** `POST /api/auth/verify-email` - **Input:** `{ token: string }` (from emailed link) - **Processing:** Hash compare -> check expiry -> mark `email_verified=true` -> consume token. **Feature: Password Reset Request** - **Endpoint:** `POST /api/auth/forgot-password` - **Input:** `{ email: string }` - **Processing:** Lookup user -> issue reset token -> send email. Always return success (do not reveal if email exists). **Feature: Password Reset Confirm** - **Endpoint:** `POST /api/auth/reset-password` - **Input:** `{ token: string, new_password: string }` - **Processing:** Verify token -> bcrypt hash new password -> revoke all refresh tokens for that user. **Feature: Get Current User** - **Endpoint:** `GET /api/auth/me` - **Processing:** From JWT, return user profile + subscription state. ### Group B: Catalog Browsing (10 endpoints) **Feature: Public Category Preview** - **What it does:** Lists apps from 3 fixed public categories without login. - **Endpoint:** `GET /api/apps/public` - **Input:** `?category=Productivity&rank_type=topfreeapplications&page=1` - **Processing:** Validate category is in the 3 public categories -> query rankings for current date -> join apps -> return top 50. - **Output:** Paginated response with `data: [{ app_id, name, developer, icon_url, rank, category }, ...]`. - **Edge cases:** Category not in public set -> `FORBIDDEN`. No data for current date yet -> return previous date's data with a `data_freshness` field. **Feature: Authenticated Full Category Browse** - **Endpoint:** `GET /api/apps` - **Auth:** Required (any logged-in user) - **Input:** `?category=&rank_type=&min_rank=1&max_rank=100&search=&sort=&page=&page_size=` - **Processing:** Validate category is in the 27 enum -> query with all filters server-side -> return top 100 (or filtered subset). - **Output:** Paginated, includes `app_id, name, developer, category, icon_url, rank, current_rating, has_ai_analysis (boolean)`. - **Edge cases:** Search across name+developer with `ILIKE`. Sort whitelist (block SQL injection). - **Business logic:** `has_ai_analysis` indicates whether Pro users can drill in. **Feature: Get App Details** - **Endpoint:** `GET /api/apps/:app_id` - **Auth:** Required - **Output:** Joins `apps` + `app_details` + latest `app_metrics`. - **Edge cases:** Unknown app_id -> `NOT_FOUND`. **Feature: Get App Historical Rankings** - **Endpoint:** `GET /api/apps/:app_id/rankings?days=30` - **Output:** Time-series of rank per day. **Feature: Get App Reviews** - **Endpoint:** `GET /api/apps/:app_id/reviews?page=1&page_size=20` - **Output:** Paginated reviews. PII removed; `author_label` only. **Feature: List All Categories** - **Endpoint:** `GET /api/categories` (auth) or `/api/categories/public` (public, returns 3 only) - **Output:** Static list with translated labels. **Feature: Trending Apps** - **Endpoint:** `GET /api/apps/rankings/trending?category=` - **Processing:** Query the `v_trending_apps` view (rank improvement >= 50 over last 7 days). **Feature: New Top-100 Entrants** - **Endpoint:** `GET /api/apps/rankings/new-entries?days=7` - **Processing:** Apps that appeared in top-100 for the first time in the last N days. **Feature: Stats Overview (public)** - **Endpoint:** `GET /api/apps/stats/overview` - **Output:** Total apps, total categories, total AI analyses, last update date. **Feature: Get App Metadata Bundle** - **Endpoint:** `GET /api/apps/:app_id/metadata` - **Output:** Combined `app_details` + screenshots + IAP/subscription data. ### Group C: AI Intelligence (Pro tier, 7 endpoints) **Feature: List AI Opportunities** - **What it does:** Lists all apps with AI analysis, sortable/filterable by score and category. - **Endpoint:** `GET /api/ai/opportunities` - **Auth:** Pro subscription required - **Input:** `?min_score=60&category=&technical_complexity=&page=` - **Processing:** Query `v_solopreneur_opportunities` view with filters. - **Output:** Paginated. `data: [{ app_id, name, category, solopreneur_score, current_rank, mvp_weeks, monetization_model }, ...]` **Feature: Get Detailed AI Analysis for App** - **Endpoint:** `GET /api/ai/opportunities/:app_id` - **Auth:** Pro - **Output:** Full `ai_analyses.analysis_data` JSONB plus the dimension breakdown plus current ranking context. **Feature: Trigger New AI Analysis (force re-score)** - **Endpoint:** `POST /api/ai/analyze/:app_id` - **Auth:** Pro (rate-limited: 10 force-analyses per user per day) - **Processing:** Enqueue an analysis job in Redis. Return job ID. - **Output:** `{ success: true, data: { job_id: string, status: "queued" } }` **Feature: AI Stats** - **Endpoint:** `GET /api/ai/stats` - **Auth:** Pro - **Output:** Total analyses, average score, score distribution histogram. **Feature: Top Opportunities (cross-category)** - **Endpoint:** `GET /api/ai/top-opportunities?limit=20` - **Auth:** Pro - **Output:** Top N apps by solopreneur_score across all categories. **Feature: Analysis History for App** - **Endpoint:** `GET /api/ai/history/:app_id` - **Auth:** Pro - **Output:** All AI analyses for this app over time (when re-scored). **Feature: Analysis Queue Status** - **Endpoint:** `GET /api/ai/analysis/queue` - **Auth:** Pro - **Output:** `{ queued: int, in_progress: int, completed_last_24h: int }` ### Group D: Billing (4 endpoints) **Feature: Get Current Subscription** - **Endpoint:** `GET /api/subscriptions/current` - **Output:** User's active subscription state from local DB. **Feature: Create Stripe Checkout Session** - **Endpoint:** `POST /api/subscriptions/create-checkout` - **Input:** `{ tier: "pro" | "enterprise" }` - **Processing:** Look up Stripe price ID by tier -> create Checkout session -> return URL. - **Output:** `{ success: true, data: { checkout_url: string } }` **Feature: Stripe Webhook Handler** - **Endpoint:** `POST /api/subscriptions/webhook` - **Auth:** Verify Stripe signature header. - **Handles events:** `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed`. - **Processing:** Idempotent updates to `subscriptions` table. Append to `subscription_events`. **Feature: Cancel Subscription** - **Endpoint:** `POST /api/subscriptions/cancel` - **Processing:** Call Stripe to set `cancel_at_period_end=true`. Webhook will then update local state. ### Group E: Admin (~21 endpoints, role=admin only) Group these into: - **Fetcher control:** `GET /api/admin/fetcher/status`, `POST /api/admin/fetcher/start`, `POST /api/admin/fetcher/stop`, `GET /api/admin/fetcher/logs`, `POST /api/admin/fetcher/force-update` - **AI analyzer control:** `GET /api/admin/analysis/status`, `POST /api/admin/analysis/start`, `POST /api/admin/analysis/pause`, `POST /api/admin/analysis/resume`, `POST /api/admin/analysis/stop`, `POST /api/admin/analysis/force`, `GET /api/admin/analysis/queue`, `POST /api/admin/analysis/clear-queue` - **User management:** `GET /api/admin/users`, `GET /api/admin/users/:id`, `PUT /api/admin/users/:id/role`, `PUT /api/admin/users/:id/subscription`, `DELETE /api/admin/users/:id` - **System:** `GET /api/admin/stats`, `GET /api/admin/database/stats`, `POST /api/admin/backup/trigger` Each follows the same pattern: validate admin role -> perform action -> return state. Admin endpoints are rate-limited and audit-logged. ### Group F: GDPR (Required for any EU users; 3 endpoints) - `GET /api/gdpr/export` (returns the user's full data as JSON) - `POST /api/gdpr/request-deletion` (queues account+data deletion) - `GET /api/gdpr/deletion-status` (status of pending deletion) ## AI/LLM Integration Patterns **Plain-language summary:** All AI scoring runs through OpenRouter, which gives you free-tier access to seven frontier open-weight models with automatic fallback if any one rate-limits or fails. Gemini Flash-Lite is the secondary fallback. Marginal cost per analysis is essentially zero. The prompt pattern is: system role establishes the rubric, user message contains structured app data, output format is a strict JSON schema validated before persistence. **Provider strategy:** | Tier | Provider | Models | Cost (Apr 2026) | Failure response | |------|----------|--------|-----------------|------------------| | Primary | OpenRouter | NVIDIA Nemotron Nano 9B V2, Z.AI GLM 4.5 Air, DeepSeek V3.1, Qwen3 Coder 480B, DeepSeek R1, xAI Grok 4 Fast, Meituan LongCat Flash (all "free" tier) | $0 marginal | Fall through priority list, then to Gemini | | Secondary | Google Gemini | gemini-2.5-flash-lite (1000 req/day free) | $0 within quota | Queue retry next day | | Tertiary (paid, optional) | Gemini 1.5 Pro | gemini-1.5-pro | Paid per-token | Only enable if quality drops below threshold | The provider switch lives in `system_config.config_key='ai_provider'` (value: `"openrouter"` or `"gemini"`). The model priority list lives in `system_config.config_key='openrouter_models'` as a JSON array. Admins can re-order priorities or enable/disable models without redeploying. **Prompt structure (for the per-app analysis):** The prompt has three sections; the exact wording is left to the implementer (production prompts are proprietary). What each section accomplishes: 1. **System role:** Establishes the AI as an expert solopreneur opportunity analyst with the specific 7-dimension rubric. Instructs strictly to return JSON conforming to the schema. Emphasizes that scores must be defensible from the data provided, not invented. 2. **User message structure:** Injects three data blocks: - **App identity block:** name, developer, category, current rank, current rating, review count, price, IAP presence. - **Reviews sample block:** up to 30 reviews, balanced across rating buckets (some 1-star, some 5-star, some recent), each with rating + title + content (truncated to 500 chars per review). - **Comparative context block:** how this app's metrics compare to category averages (rank, rating, IAP presence). Computed by the backend before sending to the AI. 3. **Output format instruction:** Strict JSON schema. Each dimension score 0-100. Every required field. No additional fields. No prose before or after the JSON. **Expected response shape (validated before persistence):** ```json { "core_purpose": "string (1-2 sentences)", "target_user": "string (1 sentence)", "common_complaints": ["string", "..."], "missing_features": ["string", "..."], "monetization_model": "free|freemium|paid_app|subscription|iap_heavy|ad_supported", "estimated_mvp_weeks": 4, "estimated_mvp_investment_usd": 2000, "tech_stack_recommendation": ["string", "..."], "key_risks": ["string", "..."], "competitive_advantage_required": "string", "swiss_or_niche_opportunity": "string|null", "scores": { "market_validation": 75, "user_satisfaction": 35, "competition": 45, "technical_complexity": 60, "monetization": 70, "mvp_feasibility": 65, "risk": 55 }, "confidence": 0.78 } ``` **Output parsing flow:** 1. Receive raw text from the LLM API. 2. Strip code-fence markers (`json` or `\`\`\``) defensively. Some models wrap output in markdown despite being told not to. 3. Parse as JSON. If parse fails, retry with a clarifying re-prompt once. If still fails, mark the analysis as `parse_error` and skip persistence. 4. Validate against schema (use Joi or Zod). Reject if any required field is missing or wrongly typed. 5. Validate score ranges (0-100, integer) and the monetization_model enum. 6. If valid, compute the final `solopreneur_score` from the scores using the algorithm in Section 6. Persist. **Cost optimization:** - Cache by app_id + analysis_version. If the analysis_version constant has not changed and the analysis is less than 6 months old, do not re-score. (This alone saves 90%+ of would-be API calls during normal operation.) - Batch by category at fetcher run time. Send small batches with delays to avoid burst-rate limiting. - Track per-model success rate in `ai_provider_usage` table; auto-deprioritize models with success rate below 50%. - The free-tier cap on OpenRouter free models is per-model and per-API-key; rotating across 7 models multiplies your effective daily quota by ~7x without any cost. **Error handling:** | Error | Cause | Response | |-------|-------|----------| | 429 Rate Limited | Free-tier quota hit on current model | Fall through to next priority model. If all fail, requeue for next cron run. | | 5xx from provider | Provider outage | Fall through to next provider (OpenRouter -> Gemini). Log to `ai_provider_usage` as failed. | | Malformed JSON in response | Model didn't follow output instruction | Retry once with clarifying re-prompt. If still bad, log and skip. | | Refusal ("I cannot do this") | Safety filter triggered, often by app description content | Log, mark analysis as `refused`, do not retry. | | Schema validation failure | Model returned valid JSON but wrong shape | Same as malformed JSON: retry once, then skip. | **Quality assurance before showing scores to users:** - Pre-flight check: do the 7 dimension scores sum-and-weight to within 5 points of the AI's stated `confidence * 100`? If not, the AI's confidence and scores disagree; flag for review. - Floor on confidence: do not show scores with `confidence < 0.5` to users. Mark them as "Low-confidence analysis" or hide them. - Spot-check rate: every 100th analysis is sampled into an admin review queue. The admin manually reviews the AI output against the actual app for drift. ## Implementation Roadmap **Plain-language summary:** 4 phases over about 4 weeks part-time. Each phase has a testable milestone. Start with the data pipeline, then auth, then UI, then billing/launch. ### Phase 1: Foundation (Week 1) - [ ] Bootstrap repo with monorepo or two-project structure (`/backend`, `/frontend`) - [ ] Set up TypeScript, ESLint, Prettier, gitignore - [ ] Docker Compose for Postgres + Redis local dev - [ ] Database migration tool (node-pg-migrate or knex), apply initial schema (Section 5) - [ ] Backend skeleton: Express + middleware (helmet, cors, rate-limit, JSON body parsing, error handler) - [ ] Standard API response envelope helper (Section 6) - [ ] Logging setup (Winston, structured logs) - [ ] Health check endpoint (`GET /api/health`) - [ ] Basic Angular 17 standalone-components scaffold with shared library **Milestone:** Backend returns 200 from `/api/health`, frontend renders a placeholder dashboard, both connect to local Postgres + Redis via Docker Compose. ### Phase 2: Data Pipeline (Week 2) - [ ] Implement iTunes RSS fetcher service (`fetcher.service.ts`): hit each of 27 categories times 3 ranking types, polite rate-limit (1s between feeds, 2s between categories), upsert into `apps`, `app_details`, `rankings`, `app_metrics`. - [ ] Implement reviews fetcher: pull recent reviews per app, dedupe by `review_id`, store author label only (no PII). - [ ] Provider-agnostic AI service interface (`ai.service.ts`). - [ ] OpenRouter adapter (`openrouter.adapter.ts`) with priority-list fallback. - [ ] Gemini adapter (`gemini.adapter.ts`) as secondary. - [ ] AI scorer worker: pulls unscored apps from the queue, calls AI service, validates response, persists to `ai_analyses`. - [ ] Cron scheduler for fetcher (daily) and scorer (every 6 hours). - [ ] Solopreneur Score computation service (Section 6 algorithm). **Milestone:** Run the fetcher manually, see ~2,700 apps in Postgres after one full pass. Run the scorer manually on 10 apps, see valid `ai_analyses` rows with valid Solopreneur Scores. ### Phase 3: API + Frontend (Week 3) - [ ] Auth endpoints (Group A from Section 6): register, login, refresh, logout, verify email, password reset, get me. - [ ] JWT middleware, RBAC middleware (user/pro/admin role check). - [ ] Catalog endpoints (Group B): public preview, authenticated browse, app details, historical rankings, reviews. - [ ] AI endpoints (Group C): list opportunities, detailed analysis, force re-score, stats, top opportunities, history, queue. - [ ] Admin endpoints (Group E): fetcher control, analyzer control, user management. - [ ] Frontend pages: landing, login, register, dashboard (top-100 list with score badges), app detail (full AI analysis card), pricing, account. - [ ] Frontend admin panel: fetcher dashboard, AI queue dashboard, user list. **Milestone:** End-to-end: anonymous user lands on `/`, registers, logs in, sees the top-100 Productivity list with locked Pro scores, hits the upgrade page. ### Phase 4: Billing + Launch (Week 4) - [ ] Stripe integration (Group D from Section 6): checkout session creation, webhook handler, cancel. - [ ] Stripe webhook signature verification, idempotency on event processing. - [ ] Pro-tier gating in the frontend (lock score badges, show "Upgrade to see" CTA). - [ ] Email transactional setup (AWS SES or Resend) for: verification, password reset, subscription receipts. - [ ] GDPR endpoints (Group F): export, deletion request. - [ ] Production Docker Compose (`docker-compose.prod.yml`) with healthchecks and restart policies. - [ ] nginx reverse proxy config + Cloudflare DNS + SSL setup. - [ ] GitHub Actions CI: lint, test, build Docker images, push to GHCR, SSH-deploy to VPS. - [ ] Monitoring: Uptime Kuma for service health, Cloudflare analytics for traffic. - [ ] Backup script: daily `pg_dump` to Backblaze B2 or similar. - [ ] Pre-launch QA pass on the 4 user roles (guest, free, pro, admin). **Milestone:** Production deploy is live at your domain, a test user can sign up, upgrade to Pro via real Stripe checkout (test mode), and see AI scores. Webhooks process correctly. Daily backups confirmed. ## Deployment and Infrastructure **Plain-language summary:** Single Hetzner CX22 VPS ($4.50/month) running Docker Compose with Postgres + Redis + backend + nginx. Cloudflare in front for SSL/CDN/DDoS. GitHub Actions builds and SSH-deploys on push to main. Total infrastructure cost: $35-55/month. ### Hosting - **VPS:** Hetzner Cloud CX22 (2 vCPU, 4GB RAM, 40GB disk, 20TB traffic, $4.50/month). EU datacenter (Falkenstein or Helsinki). - **DNS / SSL / CDN:** Cloudflare free tier. Set DNS to proxy mode (orange cloud) for the production hostname; Full (strict) SSL. - **Block storage (optional):** Hetzner volume for additional space if catalog grows beyond 40GB. Add only when needed. - **Backup storage:** Backblaze B2 ($0.005/GB/month). For a full Postgres dump of about 1-3GB, costs less than $0.02/month. ### Docker Compose Structure (production) Services to run: - `postgres`: postgres:14-alpine, persistent volume mounted at `/var/lib/postgresql/data`, healthcheck `pg_isready`. - `redis`: redis:7-alpine with `--requirepass`, persistent volume. - `backend`: built from `./backend/Dockerfile` (node:20-alpine multi-stage build), depends on `postgres` and `redis`, exposes port 3000 internally. - `frontend-static`: nginx:alpine serving the prebuilt Angular SPA from `/usr/share/nginx/html`. - `nginx-reverse-proxy`: nginx:alpine, exposes 80 and 443, proxies `/api/*` to backend service and serves static frontend for everything else. Key Compose patterns: - Internal Docker network only; only nginx-reverse-proxy publishes ports to host. - Restart policy: `unless-stopped` on every service. - Healthchecks on all stateful services. - `init.sql` mounted read-only into postgres for schema bootstrap on first run. ### nginx Reverse Proxy Pattern (not literal config): - `server` block listening on 443 SSL with Cloudflare-issued origin certificates (or Let's Encrypt via certbot if not using Cloudflare proxy). - Server name: your production hostname. - `location /api/` -> `proxy_pass http://backend:3000/api/;` with standard proxy headers (X-Forwarded-For, Host, X-Real-IP). - `location /` -> serves static SPA, with try_files fallback to `/index.html` for client-side routing. - HTTP-to-HTTPS redirect on port 80. - Gzip compression for text/* and application/json. - HTTP security headers: HSTS (with preload), X-Content-Type-Options, X-Frame-Options DENY, Referrer-Policy strict-origin-when-cross-origin, Content-Security-Policy. - Rate limiting at nginx level for `/api/auth/*` (e.g., 10 requests per minute per IP). ### CI/CD Pipeline (GitHub Actions) Single workflow `.github/workflows/deploy.yml`: 1. **On push to main:** lint backend + frontend, run unit tests. 2. Build the backend Docker image, tag with `git-sha`, push to GHCR (GitHub Container Registry). 3. Build the frontend (`ng build --prod`), produce static bundle. 4. SSH to the VPS using a deploy key from GitHub Secrets. 5. On the VPS: `docker compose pull backend && docker compose up -d backend`, then sync the new frontend bundle to the static volume. 6. Run `docker compose exec backend node migrate.js` to apply any new migrations. 7. Health check the deployed `/api/health`. Roll back on failure (re-tag previous image as `latest`). ### Environment Variables (complete list) Group by service. **Never commit real values.** All values shown are example formats, not actual secrets. **General / process:** - `NODE_ENV` -> `production` | `development` - `PORT` -> `3000` **Database:** - `DB_HOST` -> `postgres` (Docker service name) - `DB_PORT` -> `5432` - `DB_NAME` -> `appscout_prod` - `DB_USER` -> `appscout_prod` - `DB_PASSWORD` -> 32+ char strong random string **Redis:** - `REDIS_HOST` -> `redis` - `REDIS_PORT` -> `6379` - `REDIS_PASSWORD` -> 32+ char strong random string - `REDIS_URL` -> `redis://default:@redis:6379` (some libs prefer URL form) **Auth / sessions:** - `JWT_SECRET` -> 64+ char strong random string - `JWT_ACCESS_TOKEN_EXPIRY_SECONDS` -> `900` (15 min) - `JWT_REFRESH_TOKEN_EXPIRY_SECONDS` -> `604800` (7 days) - `SESSION_SECRET` -> 32+ char strong random string - `COOKIE_DOMAIN` -> `.yourdomain.com` (note leading dot for cross-subdomain) - `COOKIE_SECURE` -> `true` in production - `BCRYPT_COST` -> `12` **AI providers:** - `OPENROUTER_API_KEY` -> `sk-or-v1-...` - `OPENROUTER_BASE_URL` -> `https://openrouter.ai/api/v1` - `GEMINI_API_KEY` -> `AIza...` - `AI_PROVIDER_DEFAULT` -> `openrouter` | `gemini` - `AI_REQUEST_TIMEOUT_MS` -> `60000` - `AI_MAX_RETRIES` -> `5` **Stripe:** - `STRIPE_SECRET_KEY` -> `sk_live_...` (or `sk_test_...` in dev) - `STRIPE_WEBHOOK_SECRET` -> `whsec_...` - `STRIPE_PRICE_ID_PRO_MONTHLY` -> `price_...` - `STRIPE_PRICE_ID_ENTERPRISE_MONTHLY` -> `price_...` - `STRIPE_SUCCESS_URL` -> `https://yourdomain.com/account/billing/success` - `STRIPE_CANCEL_URL` -> `https://yourdomain.com/account/billing/cancel` **Email (AWS SES):** - `AWS_REGION` -> `eu-central-1` - `AWS_ACCESS_KEY_ID` -> AWS IAM key - `AWS_SECRET_ACCESS_KEY` -> AWS IAM secret - `EMAIL_FROM` -> `noreply@yourdomain.com` (must be verified in SES) - `EMAIL_REPLY_TO` -> `support@yourdomain.com` **Email (alternative: Resend):** - `RESEND_API_KEY` -> `re_...` (use this OR the AWS vars, not both) **Cron schedules:** - `FETCHER_CRON` -> `0 4 * * *` (daily at 4am UTC) - `SCORER_CRON` -> `0 */6 * * *` (every 6 hours) - `BACKUP_CRON` -> `0 3 * * *` **Monitoring:** - `UPTIME_KUMA_PUSH_URL` -> webhook URL for backend heartbeat (optional) - `SENTRY_DSN` -> Sentry project DSN (optional, free tier 5K events/month) **Backup (Backblaze B2):** - `B2_ACCOUNT_ID` -> ... - `B2_APPLICATION_KEY` -> ... - `B2_BUCKET_NAME` -> `appscout-backups` ### Database Backup Strategy - Daily `pg_dump --format=custom` running in a sidecar container, output piped to `b2 upload-file`. - Retention: 30 daily, 12 monthly. - Restore drill: monthly automated test that restores into a throwaway container and runs schema validation. ### Monitoring Minimum viable stack (all free tier or self-hosted): - **Uptime Kuma** (self-hosted, ~50MB RAM): pings `/api/health` every minute, alerts to Telegram on failure. - **Cloudflare Analytics** (free): traffic, request counts, bot scores. - **Sentry** (free tier 5K events/month): error tracking from backend + frontend. Optional next-level (~750MB total RAM): - **Loki + Promtail + Grafana + Prometheus + CrowdSec + Fail2ban**: log aggregation, metrics, intrusion detection. ### Security Checklist - HTTPS enforced via Cloudflare + nginx redirect - HSTS with preload - Rate limiting at nginx (auth endpoints) AND in Express (per-route via express-rate-limit) - Login attempt lockout (5 fails per 15 min per email) - bcrypt cost factor 12 - JWTs in httpOnly + Secure + SameSite=Lax cookies - Refresh token rotation; reuse detection revokes all user tokens - All inputs validated with Joi/Zod schemas - Parameterized SQL only (pg with `$1, $2`) - helmet middleware enabled (sets standard security headers) - Stripe webhook signature verification on every webhook call - CORS allowlist (only your production domain + localhost in dev) - Database password and JWT secret regenerated for production (never use dev defaults) - API keys in env vars, never in code or commits - `.env*` in `.gitignore`; `.env.example` is the only env file in the repo - CSP headers set - Sensitive routes audit-logged (admin actions, payment events) ## Cost Breakdown **Plain-language summary:** Total monthly cost at low traffic is about $35-55. Per-AI-analysis cost is $0 marginal (free-tier rotation). Break-even on the suggested $29/month Pro tier is 2 paying subscribers. ### Monthly Infrastructure Costs | Service | Tier | Monthly Cost | Notes | |---------|------|-------------|-------| | Hetzner CX22 VPS | 2 vCPU, 4GB RAM | $4.50 | EU datacenter, includes 20TB traffic | | Domain name | .com or .io | ~$1 | $10-15/year amortized | | Cloudflare | Free tier | $0 | SSL, CDN, DDoS, analytics | | Backblaze B2 | Pay-as-you-go | ~$0.05 | 1-3GB Postgres backups | | AWS SES (email) | First 62K/month free | $0 | Beyond free: $0.10 per 1,000 emails | | OpenRouter (AI) | Free models | $0 | 7 free models with priority fallback | | Google Gemini (AI fallback) | Free tier | $0 | gemini-2.5-flash-lite, 1000 req/day | | Stripe | No fixed fee | $0 | 2.9% + $0.30 per transaction | | GitHub Actions | Free for public, 2000 min/mo private | $0 | Generous for low-traffic deploys | | Sentry (errors) | Free tier 5K events/month | $0 | | | Uptime Kuma | Self-hosted on VPS | $0 | | | **Subtotal (steady state)** | | **~$5/month** | | | **Total with buffer for usage spikes** | | **$35-55/month** | Includes occasional paid SES, optional paid Sentry, etc. | ### Per-Operation Costs | Operation | Cost | Notes | |-----------|------|-------| | Fetcher run (one full pass of 81 feeds) | $0 | Apple's iTunes RSS is public/free | | AI analysis (per app) | $0 marginal | OpenRouter free-tier model | | Stripe payment (Pro $29) | ~$1.14 | 2.9% + $0.30 | | Transactional email | $0 within SES free tier | $0.0001/email beyond | | Database backup | ~$0.0001/day | Backblaze B2 storage cost | ### Scaling Scenarios | Stage | Monthly Active Users | Pro Subscribers | AI Calls/Month | Infra Cost | Total Cost | Revenue (est.) | |------|---------------------|-----------------|----------------|------------|------------|----------------| | Early (free tier focus) | 100 | 0 | 5,000 (re-scoring catalog) | $5 | $5 | $0 | | Initial traction | 500 | 5 | 5,000 + 200 user-triggered | $5 | $7 | $145 | | Growth | 2,000 | 50 | 10,000 + 1,500 user-triggered | $5 | $25 (paid SES + Sentry) | $1,450 | | Scale | 10,000 | 250 | 50,000 + 10,000 user-triggered | $25 (CX32 upgrade) | $80 (paid Sentry + paid SES + buffer) | $7,250 | The cost structure is dominated by infrastructure that does not scale linearly with users. Revenue scales linearly. This is the SaaS economic shape every solopreneur wants. ### Revenue Model - **Free tier (anonymous):** 3 categories preview, top 50 apps each, no AI scores. - **Free tier (authenticated):** All 27 categories, top 100 each, no AI scores. - **Pro tier:** $29/month. Adds AI Solopreneur Scores, full per-app analysis, exports, force re-score (rate-limited). - **Enterprise tier:** $99/month. Adds API access (rate-limited), team seats (currently 3, expand on request). **Break-even:** With ~$50/month all-in operating cost, 2 paying Pro subscribers ($58/month) covers operating costs. Every subscriber after that is margin. ### Hidden Costs to Budget For - **Domain name:** $10-15/year (about $1/month). Renew on time or you lose it. - **AWS SES sending limits:** New accounts are sandboxed (200 emails/day). Request production access early; takes 24-48 hours. - **Stripe payout fees:** No fee for standard payouts. Instant payouts charge 1.5%. - **Sentry event spikes:** A buggy release can burn through 5K free events in hours. Set rate limiting in Sentry config. - **Cloudflare bandwidth:** Free tier is unlimited for HTTP traffic, but if you serve large files (e.g., screenshots), check Workers/R2 pricing. - **Backblaze egress:** Free up to 3x your storage per month. Plenty for backups; check if you ever restore frequently. - **GitHub Actions minutes:** Free is 2,000 min/month for private repos. A 5-minute build deploying 5 times/day uses 750 min/month. Comfortable. - **OpenRouter free-tier rate limits:** Per-model, per-API-key. Rotating across 7 models effectively multiplies your quota. If you hit ceilings consistently, the paid tier on OpenRouter is still 5-10x cheaper than direct OpenAI. ## Adaptation Guide **Plain-language summary:** The transferable formula is "public marketplace data + AI scoring rubric + decision-grade output + freemium gating." Anywhere a large public marketplace exists with mostly-public data and a long tail of underperforming entries, this pattern works. Below are 5 concrete adaptations across markets where solo operators have legit opportunities and no existing tool serves them at indie pricing. **The reusable formula:** 1. **Source:** A public marketplace with structured listings (apps, products, jobs, courses, listings, profiles). 2. **Pipeline:** Fetcher pulls listings + metadata + reviews/feedback on a schedule. 3. **AI scorer:** Per-entry analysis returning a single 0-100 opportunity score plus structured reasoning. 4. **Surface:** A category-browsing UI with score badges, drill-down to per-entry analysis. 5. **Monetization:** Free preview tier, free authenticated tier, paid AI-scoring tier, optional API/team tier. What stays the same across niches: auth, billing, deployment, the AI integration layer, the score-computation pattern, the freemium structure. What changes per niche: the fetcher (different source), the per-entry data shape, the AI prompt's domain knowledge, the dimensions in the scoring rubric, the niche-specific risk factors. ### Niche 1: Amazon Product Opportunity Scanner - **What it becomes:** A scanner that surfaces underperforming-but-validated Amazon products with high review velocity and identifiable improvement gaps. For e-commerce solopreneurs hunting for white-label or private-label opportunities. - **Input changes:** Replace the iTunes RSS feed with the Amazon Product Advertising API (or the Keepa/Helium 10 API as data source). Per-product data: ASIN, title, brand, category, BSR (Best Sellers Rank), price, review count, rating, recent review velocity, seller type (FBA/FBM). - **AI prompt changes:** System role becomes "Amazon private-label opportunity analyst." Inputs include BSR trend, review-snippet sample, price tier comparison. Output adds "estimated CPM for PPC campaigns" and "patent/IP risk." - **Output changes:** Per-product analysis includes: replacement opportunity (better photos, better copy, better packaging), niche white-space score, PPC competitive intensity estimate. - **Database changes:** Replace `apps`/`app_details` with `products`/`product_details`. Replace `rankings` with `bsr_history`. Reuse `reviews`, `ai_analyses`, `users`, `subscriptions` patterns. - **Market size:** Amazon catalog is approximately 350M-600M products globally per [aggregator estimates](https://redstagfulfillment.com/how-many-products-does-amazon-carry/), 9.7M sellers (~2.5M active per [Q1 2025 data](https://www.analyzer.tools/amazon-statistics/)). - **Unique consideration:** Amazon ToS restrictions on data scraping. Use official APIs (Product Advertising API, MWS) or licensed datasets (Keepa). Patent/trademark risk per product. - **Monetization angle:** Higher willingness to pay (e-commerce sellers compute ROI directly). $49-99/month tier is realistic. ### Niche 2: LinkedIn Job-Market Opportunity Scanner - **What it becomes:** A scanner identifying hiring patterns and market gaps from public job postings. For freelance specialists, recruiters, and career-pivot solopreneurs who want to spot rising skill demand before it peaks. - **Input changes:** Source: LinkedIn jobs API, or scraping (with care for ToS), or licensed dataset. Per-job data: title, company, location, posted date, applicant count, required skills (parsed), seniority level, salary range (where listed). - **AI prompt changes:** System role: "Labor market analyst for solopreneurs." Inputs: aggregated counts by skill+location+date. Output adds "skill velocity score" and "sub-niche opportunity." - **Output changes:** Aggregated dashboards rather than per-job analysis. "Roles trending up 50% in 30 days," "Skills with most postings + lowest applicant counts," "Company patterns suggesting upcoming demand." - **Database changes:** Heavier emphasis on time-series aggregations. Add `skill_demand_history` table. `ai_analyses` becomes per-niche/role rather than per-job. - **Market size:** LinkedIn lists 22M+ open jobs globally with ~4M posted monthly per [SalesSo](https://salesso.com/blog/linkedin-hiring-statistics/). - **Unique consideration:** LinkedIn ToS strictly limits scraping. Use the official Talent Insights API (paid) or partner with licensed data providers. Privacy: never store individual applicant data. - **Monetization angle:** Recruiters pay enterprise prices; solo career-pivoters pay indie prices. Tier cleanly: Personal $19/month, Recruiter $79/month, Agency $299/month. ### Niche 3: Etsy Niche Opportunity Scanner - **What it becomes:** A scanner surfacing low-competition + high-demand Etsy niches, with creator-friendly recommendations on what physical/digital products to make. For Etsy sellers and craft-business solopreneurs. - **Input changes:** Source: Etsy public API. Per-listing data: title, tags, price, shop name, favorites count, recent sales rate (where visible), category, materials. - **AI prompt changes:** System role: "Etsy niche opportunity analyst." Inputs: search trend per tag, listing density per category, average price points, visual style patterns from titles/descriptions. Output adds "production complexity score" (digital download vs physical hand-made vs print-on-demand). - **Output changes:** Niche-level scores rather than per-listing. "Wedding signage with X style: high demand, mid competition, digital-download viable." - **Database changes:** `listings`, `tags`, `tag_demand_history`, `ai_niche_analyses`. - **Market size:** Etsy has 120M+ active listings per [aggregator data](https://easyparser.com/blog/amazon-global-marketplaces-2025-complete-guide). - **Unique consideration:** Etsy API rate limits are strict (10K requests/day per app). Plan caching aggressively. - **Monetization angle:** Etsy sellers are price-sensitive. $19-29/month sweet spot. ### Niche 4: Shopify App Store Opportunity Scanner - **What it becomes:** A scanner of the Shopify App Store identifying underperforming apps that solopreneur developers could replace. Same model as AppScout but for Shopify's ecosystem. - **Input changes:** Source: Shopify App Store public listings. Per-app data: name, developer, install count (banded), rating, review count, price tier, category. - **AI prompt changes:** System role: "Shopify app opportunity analyst." Output adds "Shopify-specific complexity" (theme app vs admin app vs storefront app). - **Output changes:** Same shape as AppScout but with Shopify-specific tech stack recommendations (Liquid, Polaris, Hydrogen). - **Database changes:** Almost identical to AppScout; rename `apps` -> `shopify_apps`, adjust category enum to Shopify's categories. - **Market size:** Approximately 13K apps in the Shopify App Store, supporting 4.4M+ Shopify merchants globally (per Shopify's own annual reports). Smaller than iOS but very lucrative per-app for indie devs. - **Unique consideration:** Higher conversion-to-paid in this niche; merchants budget for tools. Required to be a Shopify Partner to publish apps. - **Monetization angle:** Higher tier pricing reasonable: $49-99/month. ### Niche 5: Chrome Web Store Extension Opportunity Scanner - **What it becomes:** A scanner of Chrome Web Store extensions surfacing extensions with thousands of users but low ratings or abandoned development. For solopreneur extension developers. - **Input changes:** Source: Chrome Web Store public listings (no official public API, scraping with caution). Per-extension data: name, developer, install count (banded), rating, review count, last updated date, permissions used. - **AI prompt changes:** System role: "Chrome extension opportunity analyst." Output adds "permissions risk" (extensions requesting too many permissions are often replaceable with leaner alternatives) and "manifest version" (V3 migration created replacement opportunities). - **Output changes:** Same shape as AppScout. Tech stack recommendation centers on Manifest V3 + TypeScript. - **Database changes:** Almost identical to AppScout; rename to `extensions`, drop categories that don't apply, add `permissions` array field. - **Market size:** Roughly 200,000 extensions in the Chrome Web Store. Smaller absolute market than iOS but lower competition for solopreneurs. - **Unique consideration:** Chrome Web Store doesn't expose download counts beyond ranges (1K+, 10K+, 100K+). Use rating velocity as a proxy. - **Monetization angle:** $19-29/month aligned with the indie-developer audience. ### What to Keep These components transfer directly to any niche above with zero or near-zero modification: - Authentication module (registration, login, refresh tokens, password reset, email verification, RBAC) - Stripe billing integration (just change tier price IDs) - Standard API response envelope and error code catalog - Provider-agnostic AI service interface with OpenRouter+Gemini fallback chain - Cron worker patterns for fetcher and scorer - Session management via Redis - Docker Compose production setup, nginx reverse proxy, Cloudflare frontend - Backup strategy - GDPR endpoints (export, deletion) - Admin panel pattern (fetcher control, scorer control, user management) ### What to Change - The fetcher (data source-specific) - The per-entry data shape (matches the marketplace's listing fields) - The AI prompt's domain knowledge (the role description and the dimensions of the scoring rubric) - The penalty rules in the score algorithm (different markets have different "skip" patterns) - The category enum - The price tiers (vary by niche willingness-to-pay) - The brand surface (landing page copy, tagline, positioning) ### Pricing Guidance per Adaptation | Niche | Suggested Free | Pro | Premium / Enterprise | |-------|---------------|-----|---------------------| | iOS App Store (this blueprint) | 3 categories, no AI | $29/mo | $99/mo | | Amazon Products | Daily 5 free analyses | $49/mo | $149/mo | | LinkedIn Jobs | 1 saved search free | $19 / $79 / $299 | tiered above | | Etsy Niches | 3 niches free | $29/mo | $79/mo | | Shopify Apps | View only, no AI | $49/mo | $149/mo | | Chrome Extensions | 5 categories, no AI | $19/mo | $49/mo | ## What Can Go Wrong This section is honest about the failure modes you will hit. Documenting them up-front is more valuable than pretending they do not exist. ### Technical: AI Returns Malformed JSON **Problem:** The AI returns valid English prose but invalid JSON, or includes the JSON inside a markdown code fence after being told not to, or omits a required field. **When it happens:** First few weeks of running any new model. More often with smaller models. Worse on long inputs. **How to prevent it:** Strict output-format instruction in the system prompt. Use JSON-mode if the provider supports it (OpenRouter does for some models). Keep input length manageable. **If it happens anyway:** Catch parse errors in the AI service. Re-prompt once with a clarifying instruction ("Return ONLY valid JSON matching this schema, no markdown, no commentary"). If still bad, log the raw response, mark the analysis as `parse_error`, and skip persistence. Do not show partial/invalid scores to users. ### Technical: All OpenRouter Free Models Rate-Limit Simultaneously **Problem:** Daily quota cap hit on every model in the priority list within the same hour. **When it happens:** Spike days (you ran a manual catalog re-score), or external traffic spikes from a launch, or OpenRouter platform-wide load. **How to prevent it:** Rate-limit your scorer worker (e.g., max 100 analyses per hour). Track per-model success-rate in `ai_provider_usage` and skip models with sub-50% success. **If it happens anyway:** Auto-fall through to Gemini fallback. If Gemini is also exhausted (1000 req/day cap on free tier), requeue the failed analyses for the next cron run. Notify admins via the monitoring webhook if queue depth exceeds threshold. ### Technical: PostgreSQL Bloat from Daily Ranking Inserts **Problem:** The `rankings` table grows by 8,100 rows per day (27 categories times 3 ranking types times 100 ranks). After 2 years that is about 6 million rows. Index bloat slows queries. **When it happens:** Slowly over months. Symptom: ranking queries get progressively slower. **How to prevent it:** Schedule monthly `VACUUM ANALYZE` on the rankings table. Set up partial indexes (e.g., `INDEX (category, date) WHERE date > now() - interval '90 days'` for the dashboard's hot path). **If it happens anyway:** Partition the rankings table by month. Drop or archive partitions older than 12 months. Or move historical data to a separate reporting database. ### Technical: Apple Changes the iTunes RSS Feed Format **Problem:** Apple deprecates or changes the public iTunes RSS feed schema. Your fetcher silently parses garbage or returns nothing. **When it happens:** Rarely (the feed has been stable for many years), but possible. Same risk as anyone in the App Store data category. **How to prevent it:** Schema-validate the parsed feed. Alert if a fetcher run returns more than 10% empty categories. **If it happens anyway:** Switch to the App Store Search API (also public) or to Apple's StoreKit. Worst case, license a third-party data feed (Appfigures, Sensor Tower) until Apple's change settles. ### Business: Failed Stripe Payment Mid-Cycle **Problem:** A Pro subscriber's card declines on renewal. Their access immediately drops, they email support angry. **When it happens:** Card expires, bank declines, charge fails for any reason. Stripe retries automatically (configurable) but the user loses access in the meantime. **How to prevent it:** Configure Stripe Smart Retries (up to 4 attempts over a week). In your webhook handler, on `invoice.payment_failed`, do NOT immediately downgrade. Mark subscription as `past_due` and grant a 3-day grace period before downgrading. **If it happens anyway:** Email user clearly explaining the issue and how to update card. Provide a self-service Stripe Customer Portal link (`stripe.billingPortal.sessions.create`). ### Business: Subscriber Cancels Mid-Cycle, Demands Refund **Problem:** User signs up, cancels day 4, asks for full refund. Your terms say no refund mid-cycle. **How to prevent it:** Show the terms clearly at checkout. Offer a 7-day money-back guarantee instead of strict no-refund (reduces support load and chargeback risk). **If it happens anyway:** Refund. Customer chargebacks cost more than the refund. Mark refund-rate users in your DB; if they sign up again later, do not auto-bill. ### Operational: Free-Tier Abusers Triggering Force-Analyze **Problem:** Someone signs up as Pro, force-analyzes hundreds of apps, then refunds. You burned AI quota and got nothing. **When it happens:** Within first month of public launch. **How to prevent it:** Rate-limit force-analyze to 10 per user per day even on Pro. Track abnormal usage (>50 force-analyzes in 7 days) and require email confirmation before continuing. **If it happens anyway:** Disable that user's force-analyze ability. Reassign their queued analyses to lower priority. ### Operational: Single VPS Outage **Problem:** Hetzner has an outage in your datacenter. Your single-VPS architecture has zero redundancy. Site is down for hours. **When it happens:** Maybe once a year. Hetzner's uptime is good but not perfect. **How to prevent it:** You cannot, with single-VPS architecture. The trade-off is intentional: $5/month vs the multi-AZ cost increase to about $50-100/month. Accept the trade-off until revenue justifies redundancy. **If it happens anyway:** Cloudflare Always Online may serve cached pages. Post status update on Twitter/your status page. When VPS recovers, Docker Compose auto-starts services, healthchecks confirm. ### Operational: Disk Fills Up **Problem:** PostgreSQL data directory grows past your VPS's 40GB disk. Database stops accepting writes. Site breaks. **When it happens:** Catalog grows + reviews accumulate + backups not pruned. **How to prevent it:** Monitor disk usage (Uptime Kuma can ping a small endpoint that reports disk%). Alert at 70%. Prune old reviews (keep last 100 per app). Rotate logs. **If it happens anyway:** Add a Hetzner volume (live attach), expand the postgres data volume. ### Security: Credentials Leak in a Git Push **Problem:** Someone commits `.env` instead of `.env.example`. API keys are now in your git history forever. **When it happens:** Almost everyone does this once. **How to prevent it:** Strict `.gitignore` from day one. Pre-commit hook with `gitleaks` or similar. `.env.example` is the only env file in the repo. **If it happens anyway:** Rotate every leaked credential immediately (Stripe, OpenRouter, Gemini, AWS, JWT secret). Force-push to remove from history (or use `git filter-repo`). Assume the keys are public the moment they hit GitHub. ## Agent Build Instructions Copy the entire block below and paste it into your AI coding agent (Claude Code, Cursor, GitHub Copilot CLI, etc.) to start building. --- [AGENT PROMPT START] I want to build an iOS App Store Opportunity Scanner SaaS application. Here is the complete specification. Follow these instructions in order. Make decisions and proceed; do not ask me to choose between options unless I have left a decision explicitly open. ## Stack (use these exact versions) - Frontend: Angular 17.x with standalone components, Angular Material 17.x - Backend: Node.js 20 LTS, Express 4.18+, TypeScript 5+ - Database: PostgreSQL 14 (Alpine container), `pg` 8.11+ for queries (no ORM) - Cache/Sessions: Redis 7 (Alpine container), connect-redis 7.x - Auth: JWT in httpOnly cookies (jsonwebtoken 9.x), bcrypt 5.x with cost 12 - Validation: Joi 17.11+ - Payments: Stripe 14.25+ (test mode for development) - Email: AWS SES via @aws-sdk/client-ses 3.x (or Resend if AWS not available) - Logging: Winston 3.11+ - AI primary: OpenRouter API (free models with priority fallback chain) - AI fallback: Google Gemini API (gemini-2.5-flash-lite free tier) - Containerization: Docker Compose v2 - CI/CD: GitHub Actions ## Project Structure ``` appscout/ backend/ src/ controllers/ # request handlers per route group routes/ # express route definitions (one file per group) services/ # business logic (auth, fetcher, scorer, ai, billing) middleware/ # auth, rate-limit, error handler, request logger validators/ # Joi schemas per endpoint db/ # query helpers, migrations types/ # shared TypeScript types utils/ # helpers main.ts # entrypoint Dockerfile package.json tsconfig.json frontend/ projects/ portal/ # main Angular app shared/ # shared components and services library angular.json package.json docker-compose.yml # dev docker-compose.prod.yml # prod nginx-prod.conf .env.example .github/workflows/deploy.yml README.md ``` ## Standard API Response Envelope ``` Success: { "success": true, "data": } Error: { "success": false, "error": { "code": , "message": } } Paginated: { "success": true, "data": , "pagination": { "page": int, "page_size": int, "total": int, "total_pages": int } } ``` Standard error codes: `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `RATE_LIMITED`, `PAYMENT_REQUIRED`, `INTERNAL_ERROR`. ## Database Schema (PostgreSQL) Create the following tables. Use `gen_random_uuid()` for UUID defaults. Use `BIGSERIAL` where listed. Use `JSONB` for fields marked JSONB. Add the indexes listed. ### Identity tables - `users(id UUID PK, email VARCHAR(255) UNIQUE NOT NULL, password_hash VARCHAR(255), name VARCHAR(255), role VARCHAR(50) DEFAULT 'user', subscription_tier VARCHAR(50) DEFAULT 'free', registration_source VARCHAR(255), stripe_customer_id VARCHAR(255), email_verified BOOLEAN DEFAULT false, created_at TIMESTAMP, updated_at TIMESTAMP)` - `refresh_tokens(id UUID PK, user_id UUID FK users.id ON DELETE CASCADE, token_hash VARCHAR(255), expires_at TIMESTAMP, revoked BOOLEAN DEFAULT false, created_at TIMESTAMP)` + INDEX (user_id, revoked, expires_at) - `email_verifications(id UUID PK, user_id UUID FK users.id ON DELETE CASCADE, token_hash VARCHAR(255), expires_at TIMESTAMP, consumed_at TIMESTAMP)` ### Catalog tables - `apps(app_id VARCHAR(255) PK, name VARCHAR(255), developer VARCHAR(255), developer_id VARCHAR(255), developer_url TEXT, category VARCHAR(100), platform VARCHAR(50) DEFAULT 'ios', bundle_id VARCHAR(255), summary TEXT, content_rating VARCHAR(50), price DECIMAL(10,2), currency VARCHAR(10), app_url TEXT, icon_url TEXT, release_date DATE, title VARCHAR(500), updated_at TIMESTAMP)` + INDEX (category) - `app_details(app_id VARCHAR(255) PK FK apps.app_id ON DELETE CASCADE, current_version VARCHAR(20), size_bytes BIGINT, minimum_os_version VARCHAR(20), supported_devices TEXT, languages TEXT, age_rating VARCHAR(10), has_in_app_purchases BOOLEAN, in_app_purchase_data JSONB, subscription_data JSONB, screenshots_data JSONB, whats_new TEXT, version_date DATE, seller_name VARCHAR(255), seller_url TEXT, privacy_policy_url TEXT, collected_date DATE)` - `rankings(id BIGSERIAL PK, app_id VARCHAR(255) FK apps.app_id, country VARCHAR(10), rank_type VARCHAR(50), category VARCHAR(100), rank INTEGER, date DATE, created_at TIMESTAMP, UNIQUE(app_id, country, rank_type, category, date))` + INDEX (date), INDEX (app_id, country), INDEX (rank_type) - `app_metrics(id BIGSERIAL PK, app_id VARCHAR(255) FK apps.app_id, date DATE, rating_average DECIMAL(2,1), rating_count INTEGER, review_count INTEGER, price DECIMAL(10,2), has_in_app_purchases BOOLEAN, created_at TIMESTAMP, UNIQUE(app_id, date))` - `app_reviews(id BIGSERIAL PK, app_id VARCHAR(255) FK apps.app_id, review_id VARCHAR(255) UNIQUE, author_label VARCHAR(255), rating INTEGER CHECK 1-5, title TEXT, content TEXT, version VARCHAR(20), review_date DATE, helpful_count INTEGER, sentiment VARCHAR(20), collected_date DATE)` + INDEX (app_id, review_date) ### Intelligence tables - `ai_analyses(id BIGSERIAL PK, app_id VARCHAR(255) UNIQUE FK apps.app_id ON DELETE CASCADE, analysis_version VARCHAR(20), analysis_timestamp TIMESTAMP, solopreneur_score INTEGER 0-100, score_confidence DECIMAL(3,2), market_validation_score INTEGER, user_satisfaction_score INTEGER, competition_score INTEGER, technical_complexity_score INTEGER, monetization_score INTEGER, mvp_feasibility_score INTEGER, risk_score INTEGER, analysis_data JSONB)` + INDEX (solopreneur_score), INDEX (analysis_timestamp). The `analysis_data` JSONB shape is in Section 6 of the blueprint. - `market_opportunities(id BIGSERIAL PK, app_id VARCHAR(255) FK apps.app_id, opportunity_type VARCHAR(50), target_market VARCHAR(100), opportunity_score DECIMAL(4,2), description TEXT, discovered_date DATE, created_at TIMESTAMP)` + INDEX (opportunity_type, discovered_date) - `trending_patterns(id BIGSERIAL PK, pattern_name VARCHAR(255), pattern_type VARCHAR(50), app_count INTEGER, average_rank DECIMAL(6,2), examples JSONB, date DATE)` - `competitor_groups(id BIGSERIAL PK, group_name VARCHAR(255), category VARCHAR(100), app_ids JSONB, common_features JSONB, market_gaps JSONB, created_at TIMESTAMP)` ### Billing tables - `subscriptions(id UUID PK, user_id UUID FK users.id ON DELETE CASCADE, stripe_subscription_id VARCHAR(255) UNIQUE, stripe_price_id VARCHAR(255), tier VARCHAR(50), status VARCHAR(50), current_period_end TIMESTAMP, cancel_at_period_end BOOLEAN, created_at TIMESTAMP, updated_at TIMESTAMP)` + INDEX (user_id, status) - `subscription_events(id BIGSERIAL PK, user_id UUID FK users.id ON DELETE CASCADE, subscription_id UUID FK subscriptions.id, event_type VARCHAR(100), payload JSONB, created_at TIMESTAMP)` - `system_config(id SERIAL PK, config_key VARCHAR(100) UNIQUE, config_value JSONB, description TEXT, is_active BOOLEAN, updated_at TIMESTAMP)` - `ai_provider_usage(id BIGSERIAL PK, provider VARCHAR(50), model_id VARCHAR(255), date DATE, requests_count INTEGER, successful_requests INTEGER, input_tokens BIGINT, output_tokens BIGINT, UNIQUE(provider, model_id, date))` ### Categories enum The 27 fixed categories: Books, Business, Developer Tools, Education, Entertainment, Finance, Food & Drink, Games, Graphics & Design, Health & Fitness, Kids, Lifestyle, Magazines & Newspapers, Medical, Music, Navigation, News, Photo & Video, Productivity, Reference, Shopping, Social Networking, Sports, Travel, Utilities, Weather, Stickers. Default 3 public-preview categories: Business, Travel, Productivity. ## Environment Variables The app needs these env vars. Create `.env.example` with example formats. Group by service. General: `NODE_ENV`, `PORT` Database: `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` Redis: `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_URL` Auth: `JWT_SECRET`, `JWT_ACCESS_TOKEN_EXPIRY_SECONDS`, `JWT_REFRESH_TOKEN_EXPIRY_SECONDS`, `SESSION_SECRET`, `COOKIE_DOMAIN`, `COOKIE_SECURE`, `BCRYPT_COST` AI: `OPENROUTER_API_KEY`, `OPENROUTER_BASE_URL`, `GEMINI_API_KEY`, `AI_PROVIDER_DEFAULT`, `AI_REQUEST_TIMEOUT_MS`, `AI_MAX_RETRIES` Stripe: `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_ID_PRO_MONTHLY`, `STRIPE_PRICE_ID_ENTERPRISE_MONTHLY`, `STRIPE_SUCCESS_URL`, `STRIPE_CANCEL_URL` Email: `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `EMAIL_FROM`, `EMAIL_REPLY_TO` (or `RESEND_API_KEY` if using Resend) Cron: `FETCHER_CRON`, `SCORER_CRON`, `BACKUP_CRON` Monitoring: `UPTIME_KUMA_PUSH_URL`, `SENTRY_DSN` Backup: `B2_ACCOUNT_ID`, `B2_APPLICATION_KEY`, `B2_BUCKET_NAME` ## Solopreneur Score Algorithm Compute in the backend, not in the AI prompt. The AI returns 7 dimension scores 0-100; the backend combines them. ``` weighted = 0.20*market_validation + 0.20*(100-user_satisfaction) + 0.15*competition_score + 0.15*technical_complexity_score + 0.10*monetization_score + 0.10*mvp_feasibility_score + 0.10*risk_score penalties: if entrenched_top_10_for_90_days: -20 if rating >= 4.7 AND review_count >= 1000: -25 if technical_complexity_score < 30: -15 solopreneur_score = clamp(0, 100, weighted - penalties) ``` UI thresholds: 0-39 Skip (red), 40-59 Maybe (gray), 60-79 Worth Researching (accent), 80-100 High Opportunity (gold). ## Phase 1: Foundation (build first) 1. Initialize repo with directory structure above. Add `.gitignore` excluding `.env*` (except `.env.example`), `node_modules`, `dist`, `.angular`, etc. 2. Set up `docker-compose.yml` for local dev with `postgres:14-alpine` and `redis:7-alpine`. Mount volumes for persistence. 3. Backend: TypeScript + Express scaffold. Set up middleware: helmet, cors (allowlist localhost in dev), express-rate-limit, JSON body parser, structured Winston logger, error handler that formats errors per the standard envelope. 4. Implement the standard API response helpers: `success(data)`, `error(code, message, status)`, `paginated(data, pagination)`. 5. DB migration tool: use `node-pg-migrate`. Write migrations creating all tables from the schema above. 6. Health endpoint: `GET /api/health` returns `{success:true, data:{status:"ok", db:"connected", redis:"connected"}}`. 7. Frontend: `ng new portal --standalone --routing` inside `frontend/projects/`. Add `shared` library project. Install Angular Material. Set up basic routing: `/`, `/login`, `/register`, `/dashboard`, `/account`, `/admin`. 8. Acceptance: `docker compose up` starts all services. Backend health check returns 200. Frontend renders an unstyled placeholder dashboard at `localhost:4200`. ## Phase 2: Data Pipeline 1. Implement `services/fetcher.service.ts`: function `fetchCategoryRanking(category, rankType, country='US')` that GETs from `https://itunes.apple.com//rss//limit=100/genre=/json`. Parse the response, upsert into `apps`, `app_details`, `rankings`, `app_metrics`. Apply 1-second delay between feed calls and 2-second delay between categories. 2. Implement `services/reviews.service.ts`: function `fetchAppReviews(appId, country='US')` that GETs `https://itunes.apple.com//rss/customerreviews/id=/json`. Dedupe by `review_id`, store with author_label only (truncate or hash). 3. Implement provider-agnostic AI service interface: `services/ai/ai.service.ts` with `analyzeApp(appId): Promise`. 4. Implement `services/ai/openrouter.adapter.ts`: reads model priority list from `system_config`, attempts each model in order on failure or rate-limit, records attempt to `ai_provider_usage`. 5. Implement `services/ai/gemini.adapter.ts` as fallback. 6. Implement `services/scorer.service.ts`: pulls a batch of apps from queue (apps with no `ai_analyses` row OR with `analysis_timestamp` older than 6 months), calls AI service, validates response with Joi against the analysis_data schema, computes solopreneur_score using the algorithm above, persists to `ai_analyses`. 7. Set up cron with `node-cron`: fetcher daily at 4 UTC, scorer every 6 hours. 8. Acceptance: manual fetcher run populates ~2,700 app rows in Postgres. Manual scorer run on 10 apps produces valid `ai_analyses` rows with realistic Solopreneur Scores (0-100 distribution, not all 50). ## Phase 3: API + Frontend 1. Auth endpoints (8): register, login, logout, refresh, verify-email, forgot-password, reset-password, me. JWT in httpOnly+Secure+SameSite=Lax cookies. Refresh token rotation with reuse-detection (revoke ALL user tokens on reuse). 2. Auth middleware: `requireAuth`, `requireRole('admin')`, `requireSubscription('pro')`. RBAC. 3. Catalog endpoints (10) per Section 6 Group B: public preview (3 categories), authenticated browse (all 27), app detail, historical rankings, reviews, categories, trending, new entries, stats overview, metadata bundle. 4. AI endpoints (7) per Group C, Pro tier required: list opportunities, detailed analysis, force re-score (rate-limited 10/day/user), AI stats, top opportunities, history, queue status. 5. Admin endpoints (~21) per Group E: fetcher control (5), scorer control (8), user management (5), system stats/backup (3). 6. GDPR endpoints (3) per Group F: export, request-deletion, deletion-status. 7. Frontend: implement landing page with 3-tier pricing display. Implement registration + login forms. Implement dashboard showing top-100 list with score badges (locked for non-Pro). Implement app-detail page with full analysis card. Implement account page with subscription state. Implement admin panel. 8. Acceptance: anonymous user can land, register, log in, see top-100 Productivity list with greyed-out scores, click upgrade. ## Phase 4: Billing + Launch 1. Stripe integration: create Pro and Enterprise products in Stripe Dashboard, get price IDs, add to env. Implement: create-checkout-session endpoint, webhook handler with signature verification, cancel endpoint. 2. Webhook handler: idempotent updates to `subscriptions` table on `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed`. Append every event to `subscription_events`. 3. Frontend Pro-tier gating: hide AI scores when subscription_tier != 'pro'/'enterprise'/'admin'. Show upgrade CTA. 4. Email: AWS SES (or Resend). Templates for: email verification, password reset, subscription receipt. From-address must be verified. 5. Production Docker Compose: postgres, redis, backend, frontend-static (nginx serving Angular bundle), nginx-reverse-proxy. Healthchecks, restart=unless-stopped. 6. nginx reverse proxy config: 80 -> 443 redirect, 443 SSL with Cloudflare-issued origin cert, /api/ proxied to backend, / serves SPA with try_files fallback to /index.html, gzip, security headers, rate-limit on /api/auth/. 7. GitHub Actions deploy workflow: lint+test, build backend Docker image to GHCR, build frontend bundle, SSH to VPS, pull image, restart backend, sync frontend bundle, run migrations, healthcheck, rollback on failure. 8. Cron container running daily backup: `pg_dump --format=custom` then `b2 upload-file` to Backblaze B2. 9. Monitoring: Uptime Kuma container pinging /api/health every minute, Telegram alert on failure. Sentry SDK in backend + frontend (optional). 10. Pre-launch QA: walk through all 4 roles (guest, free, pro, admin), confirm subscription upgrade end-to-end with Stripe test card, confirm webhook processes correctly, confirm one full backup cycle completes. Acceptance: Production deploy is live at the production domain. End-to-end signup -> upgrade -> see scores works. Admin can trigger fetcher and scorer runs from the admin panel. Daily backup confirmed in Backblaze. Status: ready to take real traffic. [AGENT PROMPT END] --- ## What to Do Next You just consumed a complete buildable spec for a category of product that does not currently exist at indie pricing. Three paths from here: 1. **Build it yourself.** Take Section 13's Agent Build Instructions, paste into Claude Code, Cursor, or your AI agent of choice, and let it scaffold the foundation. Estimated time with AI assistance: 3-5 weeks part-time, 7-10 days full-time. The architecture and decisions in Sections 3-12 are your reference manual when the agent needs context. 2. **Use the hosted version.** AppScout is live at the URL in the frontmatter. $29/month for AI Solopreneur Scoring across all 27 categories, exports, and force-rescore. Pay per use, no setup, immediate access. 3. **Adapt it for your niche.** Section 11 walks through five concrete adaptations (Amazon products, LinkedIn jobs, Etsy niches, Shopify apps, Chrome extensions). The pattern transfers cleanly anywhere a public marketplace + a long tail of underperforming entries exists. The pattern is simple: public marketplace data, AI scoring rubric, decision-grade output, freemium gating. The unit economics are the new part. With free-tier frontier AI and a $5/month VPS, the marginal cost of running this category of product approaches zero. The expensive enterprise incumbents have not adapted; the empty quadrant is yours to take.