Industries
Edit Industry
Industry Information
AI Industry Scaffold
Generate categories, project types, and industry-level defaults using AI. You review and edit everything before applying.
Industry Categories
Define the primary product/service categories for this industry.
Project Types
Define the types of research projects available in this industry.
Industry Defaults
Default configuration inherited by ALL templates in this industry. Templates and categories can override individual settings.
Category Defaults (per-category themes + guidance)
Each category has its own themes and AI guidance. These override industry defaults and provide the base for scoped templates.
Template Matrix
Each cell represents a scoped template for a specific (Category × Project Type) combination. Click a cell to create or edit the template.
Edit Template
AI Template Scaffold
Generate project-type-specific overrides. Only produces the delta from category/industry defaults.
Industry Templates
Edit Template
General Information
AI Template Scaffold
Once you've set the industry and added categories, AI can research and generate the entire template: UI labels, survey fields, phases, project types, report sections, and category guidance — all tailored to your industry. You review and edit everything before applying.
Categories (industry-specific classification groups)
Define the primary classification categories for this industry template.
Category Theme Templates (per-category strength/friction keywords)
Define keyword templates for auto-generating strength and friction themes per category. Use AI to research and suggest industry-relevant keywords, then review and edit before applying.
Or click the AI button on individual categories below
Category Prompt Guidance (per-category AI guidance)
Per-category guidance paragraphs that are injected into AI prompts to help the LLM understand the specific characteristics of each category. Use "AI Suggest All" on the Cat. Themes tab to generate guidance alongside themes.
Project Types
Define the distribution or methodology types for this industry.
Verbatim Fields
Define which response fields exist for respondents in this industry. Field keys must match CSV column mappings.
UI Labels
Customize all user-facing labels. These replace default terminology with your industry's language.
Phase Configuration
Define the phases used in flow/pacing/journey analysis. Default: Beginning / Middle / Climax / Ending.
Default Dashboard Cards
Select which stat cards appear by default in the generated dashboard.
Verbatim Section
Quant Section
Default AI Agent System Prompts
These defaults are baked into generated admin files. Users can still override them per-project.
Report Sections
Define the sections of the AI-generated research report.
Admin Registry
Base Template Files
Manage versioned admin.html and master_template.html variants per industry. Stored in R2 with local IDB cache.
Generate Admin File
Create a new standalone admin.html from a template. The generated file has all template values baked in.
Factory
Initial Admin User
Create the first admin user for this portal. They'll use this PIN to log in. You can add more users after launching.
Permissions
Output filename:
Operations Dashboard
Loading platform stats…
Recent Projects (30 days)
Admin Portal Health
Storage Usage
Settings
File System
Manage directory handles for template storage and admin file generation.
AI Configuration
Configure LLM backends for AI-powered template suggestions. Super Admin shares API keys with the admin if stored in the same localStorage domain.
Data Management
Cloud Sync (D1)
Push all local data (industries, templates, registry) to D1 so it's available from any origin. Requires Cloud Settings to be configured.
Cloud Settings
Workers API Connection
Connect to your Cloudflare Workers API. This same API key is used in admin.html for cloud sync.
Data Sync
Push all local data (industries, templates, registry) to D1 cloud database. This makes your data available across all browser origins.
Client Organizations
Cloud API not configured. Organization management requires a cloud backend. Go to Cloud Settings to configure your API URL and key.
Each organization in Clerk maps to a client. Client users log into the portal and see only their org's projects.
No organizations
Configure cloud settings first, then create organizations.
Client Details
Assigned Templates
Admin Portals for this Client
Projects
Organization Members
Credit Balance & History
Client Users
Manage client portal users. Users are invited to an organization and can access that org's projects.
No users
Configure cloud settings first, then invite users.
Credit Pricing Tiers
Define credit packs that clients can purchase. Each pack needs a corresponding Stripe Price ID.
No pricing tiers
Create credit packs for clients to purchase.
Credit Management
Per-client credit balances, purchase history, and usage reporting. Toggle test mode for unlimited credits during development.
Loading...
Fetching client credit data.
Client Portal
Access the Client Portal to test, manage, and troubleshoot the client experience. Use this to verify projects, files, credits, and organisation access from the client's perspective.
Quick Launch
Open the Client Portal in a new window. You will need to sign in with a Clerk account that belongs to a client organisation.
Troubleshooting Checklist
1. Clerk Configuration — Verify the Clerk publishable key is set in Cloud Settings and matches the Client Portal's key.
2. Organisation Exists — Check Client Orgs to ensure the client's organisation is created and active.
3. User Invited — Verify the user has been invited to the organisation via Client Users with the correct role.
4. API Connectivity — Confirm the Workers API URL in Cloud Settings is correct and the API is responding (check
/api/health).5. Credits Available — Check Credit Management to verify the client's organisation has credits remaining.
6. Files Published — Ensure generated dashboard files have been uploaded to the cloud via the Admin Portal.
7. PIN Access — If files are PIN-protected, confirm the correct PIN has been communicated to the client.
Portal Status
Portal URL
—
API Endpoint
—
Help & Documentation
Getting Started — Complete Workflow
End-to-end: from blank system to a client running a research project
1.Configure Cloud Settings — Go to Cloud Settings and enter your Workers API URL and Admin API Key. This enables D1 sync, Clerk management, and credit operations.
2.Set up an Industry — Go to Industries. The platform ships with 10 pre-configured industries (Pharma, Media, FMCG, etc.). Click an industry to edit its categories, project types, and defaults. Use Scaffold Industry with AI to auto-generate configuration.
3.Add Category Themes — Inside the industry editor, go to Category Defaults tab. Click the brain icon on each category to generate unique themes with AI, or click AI Suggest All Categories to generate all at once.
4.Create Scoped Templates — Click Template Matrix to see the category × project type grid. Click "+" in a cell to create a template for that combination. Use Scaffold Overrides with AI to auto-generate project-type-specific fields, themes, and prompts.
5.Create a Client Organization — Go to Client Orgs and create a Clerk organization for your client. Assign templates to the org using the template checkboxes in the creation modal.
6.Invite Client Users — Go to Client Users and invite team members via email. Use Bulk Invite (CSV) for multiple users at once.
7.Generate an Admin Portal — Go to Generate Admin. Select the industry, project type, and categories. Add an initial admin user with a login PIN. Click Generate Admin File to create a standalone HTML admin portal.
8.Launch & Share — Go to Admin Registry. Click Launch to open the admin portal. Share the auto-generated password and user PIN with the client team.
9.Client Self-Service — Clients log into the Client Portal with Clerk auth. They select a template, fill in project details, and a project is created with a credit deduction.
10.Monitor Operations — Use the Operations dashboard to track projects, credits, storage, and admin portal health across all clients.
Industries
Industries are the top-level organizational unit. Each industry contains categories (product segments), project types (study types), and default configuration inherited by all templates within it.
Pre-configured: 10 industries ship out of the box — Pharma, Media & Broadcasting, Consumer Goods, Financial Services, Technology, Retail, Automotive, Food & Beverage, Telecom, Tourism & Hospitality.
Create new: Click New Industry, optionally clone from an existing one.
Edit: Click the pencil icon to open the 5-tab editor: General, Categories, Project Types, Industry Defaults, Category Defaults.
Industry Defaults: These are inherited by ALL templates in the industry — UI labels, survey fields, experience phases, dashboard cards, AI prompts, and report sections.
AI Scaffold: On the General tab, click Scaffold Industry with AI to auto-generate categories, project types, labels, fields, and prompts for any industry.
Create new: Click New Industry, optionally clone from an existing one.
Edit: Click the pencil icon to open the 5-tab editor: General, Categories, Project Types, Industry Defaults, Category Defaults.
Industry Defaults: These are inherited by ALL templates in the industry — UI labels, survey fields, experience phases, dashboard cards, AI prompts, and report sections.
AI Scaffold: On the General tab, click Scaffold Industry with AI to auto-generate categories, project types, labels, fields, and prompts for any industry.
Category Themes & Guidance
Each category within an industry has its own set of strength and friction keyword themes that drive the audience signal detection engine. Themes should be unique to each category — not generic industry themes.
Category Defaults tab: Shows a card for each category with theme bucket counts and guidance status.
AI Suggest (single): Click the brain icon on a category card to generate themes specific to that category. The AI is instructed to differentiate from other categories in the same industry.
AI Suggest All: Click AI Suggest All Categories to generate themes for every category at once. The AI ensures no two categories share generic bucket names.
Edit manually: Click the pencil icon on a category card to expand the inline editor with bucket name + keywords inputs for strength and friction, plus a guidance textarea.
Guidance: A paragraph instructing the AI analyst what to look for when analysing feedback in this category. This is injected into the admin portal's analysis pipeline.
AI Suggest (single): Click the brain icon on a category card to generate themes specific to that category. The AI is instructed to differentiate from other categories in the same industry.
AI Suggest All: Click AI Suggest All Categories to generate themes for every category at once. The AI ensures no two categories share generic bucket names.
Edit manually: Click the pencil icon on a category card to expand the inline editor with bucket name + keywords inputs for strength and friction, plus a guidance textarea.
Guidance: A paragraph instructing the AI analyst what to look for when analysing feedback in this category. This is injected into the admin portal's analysis pipeline.
Template Matrix
The Template Matrix shows a grid of categories (rows) × project types (columns). Each cell can hold a scoped template — a project-type-specific configuration that overrides the category and industry defaults.
Open: Click Template Matrix button in the Industry Editor or the grid icon on an industry row.
Create template: Click "+" in an empty cell. The template starts with empty overrides (inherits everything from category/industry defaults).
Edit template: Click "Edit" in a filled cell. The scoped editor shows scope badges (Industry → Category → Project Type) and only stores what's different from defaults.
AI Scaffold: In the scoped template editor, click Scaffold Overrides with AI to generate project-type-specific themes, guidance, survey fields, report sections, and agent prompts. The AI only generates the DELTA — not everything from scratch.
Contextual fields: The AI scaffold adds 1-3 survey fields specific to the study type (e.g., "Taste Profile" for sensory studies, "Eco Perception" for sustainability studies).
Bulk scaffold: Click Scaffold All Empty Cells to AI-generate templates for every empty cell in the matrix.
Create template: Click "+" in an empty cell. The template starts with empty overrides (inherits everything from category/industry defaults).
Edit template: Click "Edit" in a filled cell. The scoped editor shows scope badges (Industry → Category → Project Type) and only stores what's different from defaults.
AI Scaffold: In the scoped template editor, click Scaffold Overrides with AI to generate project-type-specific themes, guidance, survey fields, report sections, and agent prompts. The AI only generates the DELTA — not everything from scratch.
Contextual fields: The AI scaffold adds 1-3 survey fields specific to the study type (e.g., "Taste Profile" for sensory studies, "Eco Perception" for sustainability studies).
Bulk scaffold: Click Scaffold All Empty Cells to AI-generate templates for every empty cell in the matrix.
Generate Admin Portal
Create standalone admin portals for clients. Each generated admin has its template configuration baked in and is completely self-contained — no server required to use it.
Step 1 — Select scope: Choose an Industry, then a Project Type, then check which Categories to include. You can include 1, some, or all categories — themes and fields for each are merged into one admin.
Step 2 — Admin details: Enter a name (used as filename) and client name.
Step 3 — Initial admin user: Create the first user who can log into this admin portal. Provide their name, email, role (Super Admin/Admin/Analyst), and a login PIN (min 4 characters). More users can be added after launching.
Step 4 — Permissions: Toggle which features the admin portal can access (AI pipeline, CSV import, theme editing, etc.).
Step 5 — Lock mode: Locked portals are read-only (clients can view but not change configuration).
Step 6 — Generate: Click Generate Admin File. The system auto-generates a random admin password, injects all template config, and saves the file.
Password: Displayed in the Admin Registry. Share this with the client — it's the global admin PIN for the portal.
Step 2 — Admin details: Enter a name (used as filename) and client name.
Step 3 — Initial admin user: Create the first user who can log into this admin portal. Provide their name, email, role (Super Admin/Admin/Analyst), and a login PIN (min 4 characters). More users can be added after launching.
Step 4 — Permissions: Toggle which features the admin portal can access (AI pipeline, CSV import, theme editing, etc.).
Step 5 — Lock mode: Locked portals are read-only (clients can view but not change configuration).
Step 6 — Generate: Click Generate Admin File. The system auto-generates a random admin password, injects all template config, and saves the file.
Password: Displayed in the Admin Registry. Share this with the client — it's the global admin PIN for the portal.
Admin Registry
Tracks all generated admin portals with their passwords, users, permissions, and status.
Launch: Opens the admin portal in a new tab. Pre-injects a valid session so you're auto-logged in. The initial user is written to the admin's user database.
Regenerate: Click the 🔄 icon to re-open the Factory pre-filled with the original settings. Modify and regenerate to update the admin.
Lock/Unlock: Toggle read-only mode for a portal.
Permissions: Click the permission count badge to edit which features are enabled.
Password & User: Each entry displays the auto-generated password and initial user details (name, role, email). Share these credentials with the client team.
Archive: Mark completed projects as archived. Filter by status using the dropdown.
Regenerate: Click the 🔄 icon to re-open the Factory pre-filled with the original settings. Modify and regenerate to update the admin.
Lock/Unlock: Toggle read-only mode for a portal.
Permissions: Click the permission count badge to edit which features are enabled.
Password & User: Each entry displays the auto-generated password and initial user details (name, role, email). Share these credentials with the client team.
Archive: Mark completed projects as archived. Filter by status using the dropdown.
Operations Dashboard
Platform-wide operational visibility. Requires Cloud Settings to be configured.
Stat cards: Client orgs, total projects (active/draft/archived), total respondents, scoped templates, admin portals (active/locked), credit balance (available/purchased/used), generated files + storage, AI feedback (👍/👎).
Recent projects: Table of projects created in the last 30 days with client name, status, and respondent count.
Admin health: Table of all admin portals with user count and status.
Storage: R2 usage by file type + cleanup recommendations for files older than 90 days.
Recent projects: Table of projects created in the last 30 days with client name, status, and respondent count.
Admin health: Table of all admin portals with user count and status.
Storage: R2 usage by file type + cleanup recommendations for files older than 90 days.
Client Organizations
Manage Clerk organizations that represent your client companies. Each org can be assigned specific templates that their users can access via the Client Portal.
Create Org: Provide name, slug, short code, and accent colour. Use the template checkboxes to assign which templates this org's users can use for project creation.
Template assignment: Templates are grouped by industry in the creation modal. Check the ones this client needs access to.
Requires: Cloud Settings must be configured (API URL + Key). The amber warning banner tells you if it's not.
Template assignment: Templates are grouped by industry in the creation modal. Check the ones this client needs access to.
Requires: Cloud Settings must be configured (API URL + Key). The amber warning banner tells you if it's not.
Client Users
Manage client portal users. Users are invited to a Clerk organization and can access that org's projects and templates.
Invite: Click Invite User — provide email, select org, and assign a role (member or admin).
Bulk Invite: Click Bulk Invite (CSV) — upload a CSV file with columns:
Bulk Invite: Click Bulk Invite (CSV) — upload a CSV file with columns:
org_id, email, role (optional, defaults to org:member). One row per user. The system sends Clerk invitations for all rows at once.
Cloud Sync & Data Migration
All Super Admin data (industries, templates, registry) syncs to the D1 cloud database automatically. This ensures data is available regardless of which browser or origin you use.
Automatic sync: Every save (industry, template, registry entry) pushes to D1 after a 2-second debounce. On page load, data is pulled from D1.
Manual sync: Go to Settings → Cloud Sync (D1). Click Migrate All to Cloud to push everything, or Pull from Cloud to refresh from D1.
Why it matters: localStorage is scoped by origin. Opening
Cloud badge: The header shows "● Cloud" (green) when connected, "● Offline" (amber) when the API is unreachable.
Recommendation: Always use
Manual sync: Go to Settings → Cloud Sync (D1). Click Migrate All to Cloud to push everything, or Pull from Cloud to refresh from D1.
Why it matters: localStorage is scoped by origin. Opening
file:///super_admin.html and http://localhost:8899/super_admin.html creates two separate data stores. D1 sync solves this — both origins read from the same database.Cloud badge: The header shows "● Cloud" (green) when connected, "● Offline" (amber) when the API is unreachable.
Recommendation: Always use
http://localhost:8899 for full functionality. file:// blocks API calls due to browser security.
Cloud Settings
Configure the connection to the Cloudflare Workers API. Required for D1 sync, Clerk management, credit operations, and the Operations dashboard.
API URL: Your Workers API endpoint (e.g.,
Admin API Key: The shared secret set as a Cloudflare Worker secret (
Clerk Keys: Publishable key for client portal authentication. Secret key is stored as a Worker secret and never exposed client-side.
Test: Click Test Connection to verify the API is reachable.
https://piaza-api.syed-332.workers.dev).Admin API Key: The shared secret set as a Cloudflare Worker secret (
ADMIN_API_KEY). Used for all authenticated API calls.Clerk Keys: Publishable key for client portal authentication. Secret key is stored as a Worker secret and never exposed client-side.
Test: Click Test Connection to verify the API is reachable.
Client Portal
The Client Portal is a separate app where authenticated clients can create projects, view dashboards, and manage their credits.
How clients create projects:
1. Client logs in via Clerk (Google or email).
2. Clicks "New Project" — sees templates assigned to their org.
3. Selects a template, fills in project name and details (labels adapt to the template's industry terminology).
4. Confirms — a credit is deducted and the project is created in D1.
Troubleshooting checklist: Verify Clerk config, org exists, user invited, API connectivity, credits available, files published, PINs communicated.
1. Client logs in via Clerk (Google or email).
2. Clicks "New Project" — sees templates assigned to their org.
3. Selects a template, fills in project name and details (labels adapt to the template's industry terminology).
4. Confirms — a credit is deducted and the project is created in D1.
Troubleshooting checklist: Verify Clerk config, org exists, user invited, API connectivity, credits available, files published, PINs communicated.
Credits & Billing
Credits gate project creation. Clients purchase credit packs via Stripe; each project creation consumes one credit.
Credit Prices: Define pack tiers (e.g., 10 credits for $500). Each needs a Stripe Price ID.
Credit Management: View per-client balances, purchase history, and usage log. Toggle test mode for development.
Consumption: Automatic on project creation via Client Portal. Can also be consumed manually via the API.
Credit Management: View per-client balances, purchase history, and usage log. Toggle test mode for development.
Consumption: Automatic on project creation via Client Portal. Can also be consumed manually via the API.
Settings
Portal-level settings for file system, AI backends, data management, and cloud sync.
File System: Set the templates directory (for file-based template loading) and the base admin.html file (used by the Factory to generate new portals).
AI Configuration: Configure Ollama URL/model, OpenAI key, Claude key, and primary backend for AI scaffold operations.
Data Management: Export/import the admin registry as JSON. Clear all data (destructive).
Cloud Sync: Migrate all local data to D1 or pull latest from cloud.
AI Configuration: Configure Ollama URL/model, OpenAI key, Claude key, and primary backend for AI scaffold operations.
Data Management: Export/import the admin registry as JSON. Clear all data (destructive).
Cloud Sync: Migrate all local data to D1 or pull latest from cloud.