134 lines
7.0 KiB
Markdown
134 lines
7.0 KiB
Markdown
# Ekagni PhotoAI — 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
|
|
```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` |
|