Files

137 lines
7.2 KiB
Markdown
Raw Permalink Normal View History

# 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`.
>
2026-11-06 18:47:51 +05:30
> 📘 **Home PC Setup Guide (What to do after clone):** See [SETUP_README.md](./SETUP_README.md).
> 📘 **Multi-Location Sync & Branching Guide:** See [GIT_README.md](./GIT_README.md).
---
## 🌟 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
```bash
cd /home/creserver/Desktop/WEBB
npm install
```
### 2. Run Test Suite
```bash
npm test
```
Runs 14 unit tests across catalogue normalization, binding interpolation, rate limiting, and config integrity.
### 3. Build & Run
```bash
# 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` |