Architecture D

The Brands page is where you manage all brand profiles in the system. Each brand card shows its current lifecycle status and key information extracted during onboarding.

Brand Lifecycle

Status transitions automatically based on pipeline progress: setup when created, onboarding when GTM extraction begins, and active once Phase 0 knowledge assets are generated.

Brand Detail

Each brand detail page displays the full profile populated from GTM extraction: category, target audience, key ingredients, and product claims. Quick Actions let you jump directly to onboarding, editing, or cloning a brand.

Architecture D provides a zero-friction onboarding pipeline: upload a GTM Master Guidebook (PDF or DOCX), and the system automatically extracts Brand DNA, creates knowledge assets, and populates the brand profile.

Step 1: Upload GTM Guidebook

Navigate to Onboard Brand in the sidebar. Drop your GTM Master Guidebook — the system creates a brand record from the filename and begins processing.

Step 2: Extract Brand DNA

The extraction pipeline processes your document chunk by chunk, extracting all Brand DNA sections. The Pipeline Timeline shows every event with cost, duration, and model used. Extraction Completeness tracks which sections have been populated.

Step 3: Import into Architecture D

Once extraction is complete, import the data into Architecture D models. You can choose:

Extraction Models

You can select which LLM model performs the extraction. DeepSeek V3 is the default (cost-optimized at ~$0.65 per full extraction). Sonnet, Haiku, and Opus are available for comparison. Model benchmark results are documented in GTM-EXTRACTION-MODEL-ANALYSIS.md.

The Knowledge Layer page manages the four foundational knowledge assets that every specialist consumes. These must be built before any specialist can run — this is Phase 0.

The Four Knowledge Assets

Viewing Asset Content

Click View content on any asset to inspect the full JSON structure. Each relation type contains terms with typicality classifications (dominant vs. secondary) that govern how the specialists prioritize language.

Refresh Cadence

Each asset shows its age and next refresh due date. The system tracks whether assets are Fresh or overdue. When an asset is refreshed, downstream specialist runs are automatically flagged as stale.

Use Run Phase 0 to generate assets for the first time, or Force Regenerate to refresh them.

The Workflow Pipeline runs all six COSMO-governed specialists in the correct dependency order for a selected brand. This is the primary execution interface for generating complete brand content.

Execution Order

Each step shows its execution time, cost, and age. Steps 4 (Backend Terms & Competitive) and Step 5 (A+ Content) are marked Parallel — they run simultaneously since they don't depend on each other. Use Re-run to regenerate any individual step, or History to view past runs.

The Specialists page lets you run individual discipline specialists against a brand's knowledge layer. This is useful for targeted regeneration or testing specific disciplines.

The Six Specialists

Specialist Output

Each specialist result shows validation gates (Layer 2 automated checks), a formatted output view, and raw JSON. Relation-type tags (e.g., xWant, capable_of, used_for_func) are annotated on every content element so you can verify COSMO coverage.

The Prompt Modules page manages the two-tier prompt system — the core intellectual property of Architecture D.

Two-Tier Architecture

Tier 1 Foundation (~23K tokens) encodes the COSMO knowledge layer: identity & mandate, semantic gap principle, 15-relation taxonomy, typicality filter, regulatory compliance, Masters Operational Doctrine, desire-language framework, specificity standards, and the 7-gate self-validation protocol. This module is inherited in full by every Tier 2 specialist — never abridged.

Tier 2 Disciplines (10K–16K tokens each) add domain expertise: ASIN Optimization (Sections 10-19), Store Architecture (Sections 10-20), Operational Architecture (Sections 10-19), PPC Strategy (Sections 10-19), A+ Content (Sections 10-20), Backend & Competitive (Sections 10-18).

Version Management

Each module has independent versioning with changelog tracking. The Tier 1 module shows version history (v1 → v2 with change description). At runtime, the system assembles the system prompt by concatenating: Tier 1 + transition block + Tier 2 discipline.

The Human Review Gate implements Layer 3 of the validation architecture — structured quality assessment across 6 dimensions derived from the COSMO knowledge layer.

Review Interface

The 6 Quality Dimensions

Verdict

After scoring each dimension, select an overall verdict: Pass, Conditional, or Fail. The verdict is auto-suggested from dimension scores but can be overridden. Add notes for specific observations or prompt revision recommendations.

The Feedback Loop implements Domain 7 of the deployment specification — a closed-circuit system where execution performance data feeds back into the knowledge layer.

Six Data Sources

The system accepts feedback data from six categories:

Four-Category Term Routing

When Search Term Report data is processed, each term is automatically classified into one of four categories with differentiated handling:

Pipeline: Ingest → Extract → Apply

Upload CSV data or add manual entries. The system uses LLM intelligence extraction with COSMO annotations. When applied, knowledge assets are versioned and downstream specialist runs are flagged as stale.

The Settings page configures LLM providers, specialist model assignments, RAG parameters, feature toggles, and team access.

LLM Providers

All models route through OpenRouter during development. The native Anthropic SDK is available for production deployment — switching is a configuration change (API key + endpoint). New models from tracked providers are auto-detected with pricing.

Specialist Model Assignment

Each specialist is assigned to a model tier based on output complexity. Opus handles the highest-stakes creative output; Sonnet handles structured analytical work. Assignments are visible but configured in the backend (prompt_assembly.py).

RAG Configuration

RAG parameters are tunable from the settings page:

Additional RAG parameters configured in the backend: similarity threshold (0.7 minimum cosine), retrieval budget (4,000 token cap), and embedding model (text-embedding-3-large, 3072 dimensions).

Feature Toggles

QA Review — automatic quality review on every agent output. Memory Extraction — extract reusable style rules from user corrections. QA Timeout — configurable wait time (default 45s).

The Publish pages push a brand's DNA-derived product listing into external marketplaces. Every publish (including dry-runs) lands a row in the external_publishes audit table, so the operator has full history + rollback context. The first two channels are Shopify and Google Shopping; additional channels (Amazon, Walmart, TikTok Shop) follow the same operator flow with channel-specific fields.

What's shared across channels

Both pages are admin/manager-only. Each starts with a brand picker (any brand the operator is a member of), then a SKU picker when the brand has multiple asin_listings in its DNA. The flow ends with Preview (dry-run) → review the payload that would go out → Publish. The expandable history panel at the bottom shows the last 25 publishes with status, error, and full payload/response JSON.

Image-ref format (Shopify + Google)

The images textarea accepts one entry per line in the format <src> | <alt> (the | alt suffix is optional). Three src shapes are accepted:

• https://... — fully public URL, passed through verbatim. http:// is rejected.
• /api/v1/uploads/serve/uploads/<user>/<hash>.<ext> — the signed proxy URL returned by the file uploader. The publisher strips the signature suffix and presigns a fresh S3 GET URL when sending to the channel.
• uploads/<user>/<hash>.<ext> — the raw S3 key (same as the key field returned by the uploader). Same presign behavior.

You can only reference uploads you created (the publisher enforces this against the current user's ID — audit H-3 fix from 2026-05-16). Max 10 images per Shopify publish; max 11 (1 main + 10 additional) per Google publish. The persisted audit row stores the operator-supplied refs verbatim; presigned URLs are generated only at HTTP-call time, so the idempotency key stays stable across retries.

Shopify (/archd/publish/shopify)

What the publisher does: maps the brand's latest DNA into a Shopify ProductCreateInput / ProductUpdateInput (rich HTML description from dna.amazon.asin_listings[0], FDA disclaimer pulled from dna.regulatory.disclaimers, ingredients metafield from dna.product_science.ingredients, tags from backend_search_terms). Product status is always DRAFT — the operator promotes manually in Shopify Admin.

Operator inputs: price (USD, optional — sets variant.price via a follow-up productVariantsBulkUpdate), images (optional).

Action: Publish uses Shopify's upsert semantics — if a prior successful publish exists for this brand + SKU on the same store, it routes to productUpdate on the existing GID; otherwise productCreate. Per-SKU scoping (audit slice-4 fix from 2026-05-16) means listing-1's upsert never accidentally resolves to listing-0's product. When the update path runs with images, the existing media gallery is cleared first so re-publishes don't duplicate entries.

Sandbox: the BrandRevUP dev store (brandrevup.myshopify.com) is the default SHOPIFY_SHOP_URL. Products land as DRAFT so they never show in the storefront until manually published.

Google Shopping (/archd/publish/google)

What the publisher does: maps the brand's DNA into a Google Merchant API productInputs.insert call. Description is plain-text (HTML stripped from the DNA prose). Price uses Google's amountMicros scalar. Insert is upsert-by-offerId — re-publishing the same SKU updates the existing Merchant Center listing in place.

Operator inputs (required for live publish):

• Destination URL — public product page (e.g. the Shopify storefront URL). Must match the domain you verified in Merchant Center. Google rejects placeholder URLs at the validation layer.
• Price + currency (defaults USD).
• At least one image — first line is the MAIN image (attributes.imageLink); subsequent lines populate additionalImageLinks.

Optional inputs: GTIN (8/12/13/14 digits) and/or MPN. If both are blank, the publisher sets identifierExists=false so the listing isn't rejected — but products without identifiers are less discoverable in Shopping search. Availability + condition default to in_stock + new. Google product category can be overridden with either a numeric category ID or the full text path; otherwise falls back to the Brand row's category.

Configuration required to flip live: GOOGLE_MERCHANT_ACCOUNT_ID, GOOGLE_DATA_SOURCE_ID, GOOGLE_SERVICE_ACCOUNT_JSON (path to the GCP service-account key file on disk). Without them, action='insert' records a clean failed row with the missing-config error message; action='dryrun' works end-to-end without any GCP setup.

Audit + history

Every publish writes to external_publishes — channel, surface, action, target store, operator-shaped payload, Shopify/Google response, error message, idempotency key. The history panel on each publish page lists the most recent 25 rows for the selected brand and channel, with expandable JSON view and a deep-link to the listing in the channel admin (Shopify Admin product page; Merchant Center item view). Failed rows are flagged red and inline the error string.

Restricted-products review (Google)

Supplements + health products go through Google's automated "Restricted products" review when first published. Most pass automatically; ingredient compliance (FDA disclaimer text, no disease-claim language) matters. The Shopify-side description already injects the FDA disclaimer; the Google-side description is the same DNA prose stripped to plaintext, so the compliance signal carries across. Expect new products to sit in "Pending review" for 24–72 hours before going live.