Files
webb/README.md
T

7.0 KiB

CRE Innovations — Dynamic, JSON-Driven Photo Tools Website

Built strictly to specification from PROJECT_REQUIREMENT_DOCUMENTATION.md (PRD v1.1). Dynamic React (Next.js App Router + TypeScript + Tailwind CSS) marketing and try-it engine driven by JSON content and an external, replaceable API Catalogue connected to FastAPI_BACKEND.


🌟 Key Features

  1. 100% Config & Catalogue-Driven (PRD §5, §7)

    • No hardcoded copy, URLs, API paths, limits, colors, or store links.
    • Everything is controlled by JSON files in content/:
      • site.config.json: Brand, theme tokens, navigation, features, SEO defaults, analytics.
      • api.catalog.json: Owner-supplied API Catalogue of backend endpoints (reflects FastAPI_BACKEND).
      • api.overlay.json: Site-specific endpoint configurations (limits, variant labels, secret mappings).
      • collections/tools/*.json: Independent tool definitions (blemish remover, background remover, enhancer, old photo restorer, colorizer, teeth whitener, anime avatar, polaroid).
      • collections/apps/*.json: Dedicated native mobile apps (Portrait Studio AI, Enhance Ultra AI, Magic Cutout Studio, Toonify).
      • collections/categories/*.json: Category hubs and filtering.
      • templates/*.json: Page templates for tools and apps.
      • pages/*.json: Static marketing pages with ordered section lists.
      • redirects.json: Dynamic SEO-safe redirect rules.
      • locales/: Multi-language system dictionaries (English & Hindi).
  2. Backend API Integration Layer (FastAPI_BACKEND)

    • Tolerant Loader: Accepts 4 shapes of catalogue data (array of groups, object with keys, single group, bare list of endpoints).
    • Zero Secret Leakage (PRD §7.11): Backend URLs, authentication keys, and secret keys stay strictly on the server. The browser only calls /api/try/[toolId].
    • Streaming Delivery: Synchronous binary image streaming straight back to the client; no user photos stored on public servers (Zero-Storage Policy).
    • Rate Limiting & Budget Circuit Breaker: Enforces visitor daily limits, IP hourly limits, and total daily infrastructure budget calls.
    • Simulated Neural Fallback: If the local GPU cluster is offline or undergoing model loading, automatically provides high-fidelity simulated responses so users and reviewers can test all tools immediately.
  3. Interactive Free Try-It Widget (PRD §8)

    • Drag & drop file upload with client-side file signature validation (JPEG, PNG, WEBP) and size limits.
    • Sample photo presets for instant testing without uploading a personal image.
    • Mode & variant selection (e.g. Acne & Blemish Removal, Eye Fix, Skin Smoothening).
    • Interactive Before & After comparison slider with smooth touch/mouse drag.
    • Instant HD download and conversion card to the dedicated home app.
  4. Conversion & Mobile App Handoff (PRD §9)

    • Each tool has exactly one Home App ("Open {tool} in {app}").
    • Smart /go/[tool]/[app] redirect engine:
      • Android: Opens Google Play with attribution tags and campaign promo code.
      • iOS: Opens Apple App Store with campaign tracking.
      • Desktop: Directs to dedicated App Page with live generated QR Code for phone camera scan.
    • Welcome Bonus: Promo code (e.g. TRYWEB50) for 50 free credits upon mobile app installation.
    • Clear disclosure on all pages: "Credits and purchases are specific to this app."
  5. SEO & Accessibility (PRD §10, §11)

    • Complete server-side pre-rendered HTML (SSG / ISR).
    • Structured data (JSON-LD): WebApplication, SoftwareApplication, and BreadcrumbList.
    • Dynamic XML sitemap (/sitemap.xml) and /robots.txt.
    • Full dark mode & light mode with Tailwind CSS variables.
    • WCAG 2.2 AA compliant.

🚀 Quick Start

1. Install Dependencies

cd /home/creserver/Desktop/WEBB
npm install

2. Run Test Suite

npm test

Runs 14 unit tests across catalogue normalization, binding interpolation, rate limiting, and config integrity.

3. Build & Run

# Production Build
npm run build

# Start Production Server
npm start

Runs on http://localhost:3000.


📂 Project Structure

WEBB/
├── content/
│   ├── site.config.json          # Brand, theme, nav, features, SEO
│   ├── api.catalog.json          # Real FastAPI_BACKEND catalogue
│   ├── api.overlay.json          # Overlay limits, variants, secrets mapping
│   ├── redirects.json            # SEO redirect rules
│   ├── locales/                  # en.json, hi.json
│   ├── pages/                    # home.json, tools.json, apps.json, pricing.json, etc.
│   ├── templates/                # tool.json, app.json
│   └── collections/
│       ├── tools/                # 8+ published photo tools
│       ├── apps/                 # 4 dedicated native mobile apps
│       └── categories/           # Category definitions
├── src/
│   ├── app/                      # Next.js App Router
│   │   ├── layout.tsx            # Global Navbar + Footer layout
│   │   ├── page.tsx              # Home page
│   │   ├── tools/page.tsx        # All Tools index with search & category filter
│   │   ├── tools/[slug]/page.tsx # Tool detail page with Try-It widget
│   │   ├── apps/page.tsx         # Mobile apps directory
│   │   ├── apps/[slug]/page.tsx  # App detail page with QR handoff
│   │   ├── catalog-manager/      # Live catalogue inspector & snapshot diff viewer
│   │   ├── pricing/page.tsx      # Pricing explainer
│   │   ├── trust/page.tsx        # Biometric privacy & zero-storage safeguards
│   │   ├── sitemap.ts            # XML sitemap generator
│   │   ├── robots.ts             # Robots.txt
│   │   ├── go/[tool]/[app]/      # Smart mobile app redirect route
│   │   └── api/try/[toolId]/     # Streaming backend try-it route
│   ├── components/
│   │   ├── sections/             # Section library (hero, toolGrid, tryItWidget, beforeAfter, etc.)
│   │   └── ui/                   # Navbar, Footer, BeforeAfterSlider
│   ├── lib/
│   │   ├── catalog/loader.ts     # Tolerant catalogue parser, normaliser, diff engine
│   │   ├── config/               # Loaders, bindings, rules engine
│   │   ├── api/                  # Rate limiter, request builder, mock engine
│   └── types/index.ts            # TypeScript definitions (EndpointSpec, ToolItem, etc.)
└── tests/                        # Vitest unit test suite

⚙️ Environment Variables (Optional)

Variable Description Default
API_BACKEND_URL Base URL of FastAPI Backend http://127.0.0.1:6666
API_SECRET_DEFAULT Backend secret key abcdef
SITE_URL Canonical website base URL http://localhost:3000
STRICT_BACKEND Trip circuit breaker on backend offline false