Files
webb/management/README.md

164 lines
6.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Management — Content Source of Truth
This folder is the **single source of truth** for all editable content, media, and configuration.
Developers and content managers should edit files here — **never hardcode content in TypeScript/React source files**.
---
## Directory Structure
```
management/
├── README.md ← This file
│
├── apps/ ← Per-app media & promotional assets
│ ├── art-studio-app/
│ │ └── media/ ← Screenshots, icons, feature graphics
│ ├── bg-cleaner-app/
│ │ └── media/
│ ├── photo-enhancer-pro/
│ │ └── media/
│ └── portrait-app/
│ └── media/
│
├── pages/ ← Per-page layout config & media
│ │
│ ├── home/ ← Homepage (/)
│ │ ├── page.config.json ← Section order, props, copy, SEO
│ │ ├── media/ ← Global homepage media assets
│ │ │ ├── hero/ ← Hero section images / videos
│ │ │ ├── reel/ ← Transformation reel media
│ │ │ ├── showcase/ ← Showcase grid images
│ │ │ └── our-tools/ ← Per-tool images for the grid
│ │ │ └── {tool-slug}/
│ │ └── sections/ ← Per-section override media
│ │ ├── hero/media/
│ │ ├── how-it-works/media/
│ │ ├── our-tools/ ← Tool thumbnails per grid slot
│ │ ├── community-reviews/
│ │ └── trendy-bento/
│ │
│ ├── apps/ ← Apps listing page (/apps)
│ │ └── media/
│ │
│ ├── tools/ ← Tools index + per-tool pages
│ │ ├── page.config.json ← /tools index page section config
│ │ └── {tool-slug}/ ← One directory per published tool
│ │ ├── tool.config.json ← Tool-level page overrides (optional)
│ │ └── media/ ← Before/after comparison images
│ │ ├── before.jpg
│ │ └── after.jpg
│ │
│ └── trust/ ← Trust & Privacy page (/trust)
│ ├── page.config.json
│ └── media/
│
└── templates/ ← Blank JSON templates for new content
├── app.json ← Starter for a new app entry
└── tool.json ← Starter for a new tool entry
```
---
## Content Files vs Management Files
| Data type | Location | Purpose |
|-----------|----------|---------|
| Site-wide config | `content/site.config.json` | Nav, footer, theme, features, SEO, org schema |
| Tool metadata | `content/collections/tools/*.json` | Tool data, tryIt config, SEO, schema |
| App metadata | `content/collections/apps/*.json` | App data, store links, features |
| Category data | `content/collections/categories/*.json` | Category labels and slugs |
| Homepage layout | `management/pages/home/page.config.json` | Section order, all copy, CTAs |
| Tool page layout | `management/pages/tools/{slug}/tool.config.json` | Per-tool page overrides |
| Media / images | `management/pages/{page}/media/` | Before/after, hero, reel images |
| Feature configs | `content/features/*.json` | Auto-mask, rate-limits, cookies, reviews |
| Localisation | `content/locales/*.json` | Translated strings per locale |
---
## Feature Configs (`content/features/`)
| File | Controls |
|------|---------|
| `auto-mask.config.json` | Auto-mask ellipse size, resolution (512×512), subject/background RGBA |
| `rate-limits.config.json` | Per-visitor/IP/daily API quota limits and dev overrides |
| `cookie.config.json` | Visitor cookie max-age (days) and session cookie max-age |
| `api-proxy.config.json` | Max upload size (MB), request timeout (ms), max image dimension |
| `reviews.json` | Community review cards shown in the marquee on the homepage |
---
## Workflow: Editing Homepage Content
1. Open `management/pages/home/page.config.json`
2. Find the section to edit by its `type` field (e.g. `hero`, `faq`, `reviewsMarquee`)
3. Edit the `props` object — all copy, CTAs, and configuration live here
4. For images: drop files in the matching `media/` subdirectory and update the path in `props`
5. Run `npm run dev` to preview — **no code changes required**
---
## Workflow: Editing Community Reviews
1. Open `content/features/reviews.json`
2. Add, edit, or remove entries in the `reviews` array
3. Each entry needs: `name`, `role`, `location`, `avatarInitials`, `avatarColor`, `body`, `tool`, `stars`
4. The homepage marquee automatically picks up the new data on next page load
---
## Workflow: Adding a New Tool
1. Copy `management/templates/tool.json` → `content/collections/tools/{slug}.json`
2. Create `management/pages/tools/{slug}/` directory
3. Add before/after images to `management/pages/tools/{slug}/media/`
4. Register the endpoint in `content/api.catalog.json`
5. The tool appears automatically on `/tools` and `/tools/{slug}` — no code changes
---
## Workflow: Adding a New App
1. Copy `management/templates/app.json` → `content/collections/apps/{slug}.json`
2. Create `management/apps/{slug}/media/` directory
3. Add app media (icon, screenshots, feature graphic) to that directory
4. The app appears automatically on `/apps` and `/apps/{slug}` — no code changes
---
## Workflow: Adjusting Rate Limits
1. Open `content/features/rate-limits.config.json`
2. Update `perVisitorPerDay`, `perIpPerHour`, or `dailyBudgetCalls`
3. Dev overrides (loopback only) are in `devOverrides`
4. Restart the server to pick up the new values (cached at startup)
---
## Conventions
> [!IMPORTANT]
> **Never hardcode** strings, URLs, or image paths in `.tsx`/`.ts` source files.
| What | Where |
|------|-------|
| Copy / labels / CTAs | `page.config.json` props or `content/` JSON |
| Images / videos | `management/` directories, referenced by path in JSON |
| Feature toggles | `content/site.config.json` → `features` block |
| API secrets / keys | `.env.local` only — **never** in JSON files |
| Org schema data | `content/site.config.json` → `organization` block |
| Rate limits | `content/features/rate-limits.config.json` |
| Cookie expiry | `content/features/cookie.config.json` |
| Auto-mask params | `content/features/auto-mask.config.json` |
---
## Schema Versions
| File | `schemaVersion` | Last updated |
|------|-----------------|--------------|
| `content/site.config.json` | 1.0 | 2026-11 |
| `content/collections/tools/*.json` | (per file) | varies |
| `content/collections/apps/*.json` | (per file) | varies |
| `management/pages/home/page.config.json` | (implicit) | 2026-11 |