architecture · supabase_json
AD SEO Agent architecture
architecture artifact · for AD SEO Agent · status draft
data model
tables
| id | rls | name | columns | indexes | purpose |
|---|---|---|---|---|---|
| TABLE-001 | Future RLS by client_id and role; Monday seed may be read-only. | seo_company_profiles | - id: Primary key. - client_id: Client/tenant scope, e.g. dreamborn. - company_name: Analyzed company name. - domain: Canonical analyzed domain. - vertical: Business vertical or distributor category. - categories: Product/category context used in recommendations. - competitors: Configured competitor domains/labels for analysis. - white_label: Brand/network packaging context. - created_at: Creation timestamp. | - item: reason: string, unique: boolean, columns: object | Stores company/domain/vertical/competitor and white-label context for an AD SEO Agent account or demo company. |
| TABLE-002 | Scoped through company profile client_id. | seo_analysis_runs | - id: Primary key. - company_profile_id: Analyzed company profile. - source_mode: seeded, live, or hybrid. - status: queued, running, complete, failed, blocked. - summary: Run-level summary metrics and caveats. - started_at: Run start time. - completed_at: Run completion time. | - item: reason: string, unique: boolean, columns: object | Represents one analysis pass over a CompanyProfile. |
| TABLE-003 | Scoped through analysis run company profile. | seo_agent_steps | - id: Primary key. - analysis_run_id: Parent analysis run. - agent_slug: Agent or role name. - step_type: crawler, competitor_analysis, gap_analysis, backlink_analysis, recommendation_planning, review, publish_waiting. - status: waiting, running, complete, blocked. - payload: Evidence refs, output summary, cost, duration, handoff. - created_at: Event creation time. | - item: reason: string, unique: boolean, columns: object | Agent activity and audit trail for an AnalysisRun. |
| TABLE-004 | Scoped through analysis run company profile. | seo_recommendations | - id: Primary key. - analysis_run_id: Parent analysis run. - title: Recommendation headline. - recommendation_type: content, technical, internal_link, outreach, strategy. - rank: Display ranking within the run. - reasoning: Plain-language AI reasoning for why this matters now. - expected_value: Estimated monetary or weighted value. - confidence: 0-1 confidence score. - risk_level: low, medium, high. - governance_tier: autonomous, approval_required, strategy_required. - owner_agent: Agent responsible for preparing/executing next action. - status: ready, invalid, approved, returned, deferred, ex | - item: reason: string, unique: boolean, columns: object - item: reason: string, unique: boolean, columns: object | Central AI-first product object: ranked recommendation with value, risk, confidence, action, governance, owner agent, and evidence. |
| TABLE-005 | Scoped through recommendation analysis run. | seo_evidence | - id: Primary key. - recommendation_id: Parent recommendation. - source_type: seed, crawl, provider, manual, agent. - source_label: Human-readable source label. - source_url: Optional source URL. - freshness: Freshness/currency note. - facts: Extracted facts supporting the recommendation. - confidence: 0-1 confidence for this evidence item. - caveats: Known caveats and assumptions. | - item: reason: string, unique: boolean, columns: object | Structured evidence attached to recommendations. |
| TABLE-006 | Scoped through recommendation analysis run. | seo_actions | - id: Primary key. - recommendation_id: Parent recommendation. - action_type: content_brief, technical_fix, internal_link_plan, outreach_draft, strategy_decision. - payload: Structured brief/fix/draft/decision payload. - status: prepared, approval_required, approved, returned, executing, complete. | - item: reason: string, unique: boolean, columns: object | Executable action associated with a Recommendation. |
| TABLE-007 | Production: approver/admin write; viewer read. | seo_approval_decisions | - id: Primary key. - action_id: Action being decided. - decision: approved, rejected, returned, deferred, edited. - decided_by: Human/user id or demo approver label. - reason: Reason or return instruction. - edits: Structured edits to action or constraints. - created_at: Decision timestamp. | - item: reason: string, unique: boolean, columns: object | Human governance decisions for Actions. |
| TABLE-008 | Production: operator/approver/admin write; viewer read. | seo_constraints | - id: Primary key. - company_profile_id: Company profile receiving constraints. - constraint_type: budget, risk, brand, competitor, category, approval_policy, roi_assumption. - value: Constraint payload. - updated_at: Last update time. | - item: reason: string, unique: boolean, columns: object | User/business constraints that shape recommendation ranking and governance. |
| TABLE-009 | Scoped through company profile. | seo_outcome_metrics | - id: Primary key. - company_profile_id: Company profile this metric belongs to. - recommendation_id: Optional recommendation linked to metric. - metric_type: spend_baseline, savings, traffic_value, pipeline_impact, payback, ranking_delta. - value: Numeric metric value when applicable. - unit: Currency, percent, days, rank, etc. - assumption: Whether the metric is seeded/assumption-based. - metadata: Calculation inputs, caveats, display labels. | - item: reason: string, unique: boolean, columns: object | ROI and post-action outcome metrics. |
migrations
| id | path | purpose | depends on |
|---|---|---|---|
| MIG-001 | supabase/migrations/ad_seo_agent/001_ai_first_object_model.sql | Create AD SEO Agent AI-first object model tables. | |
| MIG-002 | supabase/seed/ad_seo_agent/001_hubbard_seed.sql | Seed Hubbard CompanyProfile, AnalysisRun, AgentSteps, Recommendations, Evidence, Actions, Constraints, and OutcomeMetrics. | - MIG-001 |
risks
| id | severity | mitigation | description |
|---|---|---|---|
| RISK-001 | high | Build around Recommendation, Evidence, Action, ApprovalDecision, and AgentStep objects first. | If implementation starts from keyword tables, it will regress to a conventional SEO dashboard. |
| RISK-002 | medium | Label source mode and seed assumptions in Command Center and System/Data. | Seeded data may be perceived as fake if assumptions and source mode are hidden. |
| RISK-003 | high | Provider adapters are optional for Monday; seeded dataset is required and must be complete. | Monday production target leaves little room for live provider integration instability. |
| RISK-004 | medium | Allow read-only unauthenticated pilot; gate real writes behind route protection or server-side demo approver until auth is decided. | Approval persistence requires auth decisions that may not be resolved for demo route. |
open questions
| id | owner | blocks | status | question | resolution |
|---|---|---|---|---|---|
| OQ-ARCH-001 | atlas | No longer blocks decomposition; build planning must follow client project Cloudflare conventions. | answered | Which repo/app root should host the Monday production pilot? | client project app: C:/Users/jstnk/Downloads/cc/projects/seo-studio, canonical route /seo, optional /products/seo redirect. |
| OQ-ARCH-002 | atlas | Approval write behavior only; does not block read-only product route or decomposition. | deferred | Should Monday approval decisions persist to Supabase Projects/Demo immediately or remain demo-local/read-only until auth/policy is finalized? |
Agent Handoff
Start Here
architecture artifact · for AD SEO Agent · status draft
Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Risks
- RISK-001: If implementation starts from keyword tables, it will regress to a conventional SEO dashboard.
- RISK-002: Seeded data may be perceived as fake if assumptions and source mode are hidden.
- RISK-003: Monday production target leaves little room for live provider integration instability.
- RISK-004: Approval persistence requires auth decisions that may not be resolved for demo route.
Open Questions
- OQ-ARCH-001: id: string, owner: string, blocks: string, status: string, question: string, resolution: string
- OQ-ARCH-002: id: string, owner: string, blocks: string, status: string, question: string
Structured Payload
Machine-readable source fields
api
endpoints
| id | path | method | request | responses | feature ids |
|---|---|---|---|---|---|
| API-001 | /api/ad-seo-agent/company/:companyId/summary | GET | - body: - query: include: string - params: companyId: string | - 200: body: object, status: number, condition: string - 404: body: object, status: number, condition: string | - F-01 - F-02 - F-04 - F-06 - F-07 |
| API-002 | /api/ad-seo-agent/company/:companyId/recommendations | GET | - body: - query: type: string, status: string, governance_tier: string - params: companyId: string | - 200: body: object, status: number, condition: string | - F-03 |
| API-003 | /api/ad-seo-agent/recommendations/:id | GET | - body: - query: include: string - params: id: string | - 200: body: object, status: number, condition: string | - F-03 - F-04 - F-05 |
| API-004 | /api/ad-seo-agent/actions/:id/decision | POST | - body: edits: string, reason: string, decision: string - query: - params: id: string | - 200: body: object, status: number, condition: string - 403: body: object, status: number, condition: string | - F-02 - F-05 - F-06 |
| API-005 | /api/ad-seo-agent/runs/:runId/steps | GET | - body: - query: - params: runId: string | - 200: body: object, status: number, condition: string | - F-04 - F-07 |
error envelope
{ ok: false, error: { code, message, details } }auth
roles
- viewer
- operator
- approver
- admin
policies
| id | rule | resource |
|---|---|---|
| POL-001 | Only approver/admin roles may create final approve/reject decisions in production. | ApprovalDecision |
| POL-002 | Operator/approver/admin roles may edit constraints; viewer is read-only. | Constraint |
| POL-003 | Seeded estimates must be labeled as seeded/configurable and never represented as audited live data. | Seeded analysis data |
session model
Unauthenticated read-only pilot is acceptable if route is private; approval persistence should require operator/approver auth once exposed beyond demo.
identity model
Monday pilot may be public or protected at route/deploy layer; object model includes tenant/client_id for future auth.
tenant isolation
All records include client_id and company_profile_id. Future production uses RLS by client_id and role.
risks
| id | severity | mitigation | description |
|---|---|---|---|
| RISK-001 | high | Build around Recommendation, Evidence, Action, ApprovalDecision, and AgentStep objects first. | If implementation starts from keyword tables, it will regress to a conventional SEO dashboard. |
| RISK-002 | medium | Label source mode and seed assumptions in Command Center and System/Data. | Seeded data may be perceived as fake if assumptions and source mode are hidden. |
| RISK-003 | high | Provider adapters are optional for Monday; seeded dataset is required and must be complete. | Monday production target leaves little room for live provider integration instability. |
| RISK-004 | medium | Allow read-only unauthenticated pilot; gate real writes behind route protection or server-side demo approver until auth is decided. | Approval persistence requires auth decisions that may not be resolved for demo route. |
status
approved
handoff
notes for zara
- Architecture supports UX object model directly; seeded and live data share shapes.
- ApprovalGate state can be persisted or demo-local depending on hosting/auth decision, but UI should not change.
- AD SEO Agent is a buyer-facing client project route; do not inherit Dev Studio internal shell or desktop-only guard.
notes for decomp
- Use C:/Users/jstnk/Downloads/cc/projects/seo-studio for product implementation at /seo; treat C:/Users/jstnk/Downloads/cc/projects/seo-studio as prototype context only.
- First module should create object model and Hubbard seed data.
- Second module should implement Blanc-based Command Center and OpportunityBoard.
- Third module should implement EvidenceDrawer, AgentActivityRail, ApprovalGate, and System/Data status.
- Implement against C:/Users/jstnk/Downloads/cc/projects/seo-studio
/seoCloudflare route; treat seo-studio repo as prototype context only. - Ask Vikram or use Vikram architecture context for Cloudflare/Supabase Projects/Demo decisions before generic app assumptions.
blocking question ids
No items captured.
ready for coherence review
true
project
id
ad-seo-agent
name
AD SEO Agent for Affiliated Distributor Networks
client id
ad
requirements ref
docs/projects/ad-seo-agent/artifacts/REQUIREMENTS.json
platform project id
0.0.8832348
platform project title
AD SEO Agent
env vars
| name | scope | default | example | required | description |
|---|---|---|---|---|---|
| NEXT_PUBLIC_AD_SEO_AGENT_SOURCE_MODE | client | seeded-bundled | seeded-bundled | false | Displays seeded/hybrid/live source mode label in the Next client bundle. Client code must default missing value to seeded-bundled and must never branch trust/security behavior on this display value. |
| SEO_STUDIO_SEED_PATH | server | appsad-seo-agent/data/hubbard-seed.json | false | Local/dev-only optional path to versioned Hubbard seed JSON/SQL. Cloudflare production must use bundled static imports or Supabase, not runtime filesystem reads. | |
| SEMRUSH_API_KEY | server | false | Optional future live SEO provider credential. | ||
| AHREFS_API_KEY | server | false | Optional future live SEO provider credential. | ||
| GOOGLE_SEARCH_CONSOLE_CLIENT_ID | server | false | Optional future GSC integration credential. | ||
| NEXT_PUBLIC_SUPABASE_URL | client | https://<project>.supabase.co | false | Supabase project URL for client project reads from Projects/Demo/product data. Required only when AD SEO Agent runtime source mode uses Supabase/live data; not required for the bundled-fixture Monday pilot path. | |
| NEXT_PUBLIC_SUPABASE_ANON_KEY | client | false | Supabase anon key for browser-safe reads/writes allowed by RLS/policies. Required only when AD SEO Agent runtime source mode uses Supabase/live data; not required for the bundled-fixture Monday pilot path. | ||
| SEO_STUDIO_CANONICAL_ROUTE | build | /seo | false | Canonical suite route for AD SEO Agent product links and metadata. | |
| CF_IMAGES_ACCOUNT_HASH | build | false | Cloudflare Images account hash for optional product media assets. |
services
| id | auth | name | purpose | feature ids | failure behavior |
|---|---|---|---|---|---|
| SVC-001 | Server-side only; no secrets required. | Hubbard Seed Dataset Loader / Supabase Demo Dataset | Loads versioned production seed records for Monday pilot, preferably from Supabase Projects/Demo or a bundled fixture that mirrors that shape. | - F-01 - F-02 - F-03 - F-04 - F-05 - F-06 - F-07 | Block the pilot with explicit seeded dataset missing state. Do not fall back to generic examples. |
| SVC-002 | Server-side provider credentials only. | SEO Provider Adapter Boundary | Future adapter for live SEO data while preserving seeded object shape. | - F-03 - F-07 | Return provider_unavailable and continue rendering seeded/hybrid data with visible status. |
| SVC-003 | Server-side RedKey credentials. | RedKey/agent infrastructure Agent Event Adapter | Future live source for AgentStep events from task lifecycle/HCS materialization. | - F-04 - F-07 | Render seeded AgentStep records and mark live stream unavailable. |
| SVC-004 | Public CSS/package asset. | Blanc Design System | Provides product patterns and core components for the pilot UI. | - F-01 - F-02 - F-03 - F-04 - F-05 - F-06 - F-07 | Build should fail if required product styles are unavailable; do not ship an unstyled fallback. For the client project route, integrate Blanc patterns through suite-compatible CSS/assets. |
| SVC-005 | Deploy credentials stay outside browser/runtime bundle. | Cloudflare Pages | Hosts the client project and AD SEO Agent product route at /seo. | - F-01 - F-02 - F-03 - F-04 - F-05 - F-06 - F-07 | Deployment failure blocks release; route should not point to stale or unrelated product surface. |
| SVC-006 | Server-side environment variables/secrets only; no provider keys in client bundle. | Cloudflare Workers / Pages Functions | Server-side product actions, provider adapters, approval persistence, and secret-bearing calls when needed. | - F-03 - F-04 - F-05 - F-07 | Return structured unavailable/error states and keep seeded read-only demo available. |
| SVC-007 | Upload/admin credentials stay server-side or build-time only. | Cloudflare Images / Stream | Optional product media, screenshots, demo visuals, or future explainer video assets for the AD SEO Agent suite product route. | - F-06 - F-07 | Media failure must not block core product route; show text/product UI first. |
data model
tables
| id | rls | name | columns | indexes | purpose |
|---|---|---|---|---|---|
| TABLE-001 | Future RLS by client_id and role; Monday seed may be read-only. | seo_company_profiles | - id: Primary key. - client_id: Client/tenant scope, e.g. dreamborn. - company_name: Analyzed company name. - domain: Canonical analyzed domain. - vertical: Business vertical or distributor category. - categories: Product/category context used in recommendations. - competitors: Configured competitor domains/labels for analysis. - white_label: Brand/network packaging context. - created_at: Creation timestamp. | - item: reason: string, unique: boolean, columns: object | Stores company/domain/vertical/competitor and white-label context for an AD SEO Agent account or demo company. |
| TABLE-002 | Scoped through company profile client_id. | seo_analysis_runs | - id: Primary key. - company_profile_id: Analyzed company profile. - source_mode: seeded, live, or hybrid. - status: queued, running, complete, failed, blocked. - summary: Run-level summary metrics and caveats. - started_at: Run start time. - completed_at: Run completion time. | - item: reason: string, unique: boolean, columns: object | Represents one analysis pass over a CompanyProfile. |
| TABLE-003 | Scoped through analysis run company profile. | seo_agent_steps | - id: Primary key. - analysis_run_id: Parent analysis run. - agent_slug: Agent or role name. - step_type: crawler, competitor_analysis, gap_analysis, backlink_analysis, recommendation_planning, review, publish_waiting. - status: waiting, running, complete, blocked. - payload: Evidence refs, output summary, cost, duration, handoff. - created_at: Event creation time. | - item: reason: string, unique: boolean, columns: object | Agent activity and audit trail for an AnalysisRun. |
| TABLE-004 | Scoped through analysis run company profile. | seo_recommendations | - id: Primary key. - analysis_run_id: Parent analysis run. - title: Recommendation headline. - recommendation_type: content, technical, internal_link, outreach, strategy. - rank: Display ranking within the run. - reasoning: Plain-language AI reasoning for why this matters now. - expected_value: Estimated monetary or weighted value. - confidence: 0-1 confidence score. - risk_level: low, medium, high. - governance_tier: autonomous, approval_required, strategy_required. - owner_agent: Agent responsible for preparing/executing next action. - status: ready, invalid, approved, returned, deferred, ex | - item: reason: string, unique: boolean, columns: object - item: reason: string, unique: boolean, columns: object | Central AI-first product object: ranked recommendation with value, risk, confidence, action, governance, owner agent, and evidence. |
| TABLE-005 | Scoped through recommendation analysis run. | seo_evidence | - id: Primary key. - recommendation_id: Parent recommendation. - source_type: seed, crawl, provider, manual, agent. - source_label: Human-readable source label. - source_url: Optional source URL. - freshness: Freshness/currency note. - facts: Extracted facts supporting the recommendation. - confidence: 0-1 confidence for this evidence item. - caveats: Known caveats and assumptions. | - item: reason: string, unique: boolean, columns: object | Structured evidence attached to recommendations. |
| TABLE-006 | Scoped through recommendation analysis run. | seo_actions | - id: Primary key. - recommendation_id: Parent recommendation. - action_type: content_brief, technical_fix, internal_link_plan, outreach_draft, strategy_decision. - payload: Structured brief/fix/draft/decision payload. - status: prepared, approval_required, approved, returned, executing, complete. | - item: reason: string, unique: boolean, columns: object | Executable action associated with a Recommendation. |
| TABLE-007 | Production: approver/admin write; viewer read. | seo_approval_decisions | - id: Primary key. - action_id: Action being decided. - decision: approved, rejected, returned, deferred, edited. - decided_by: Human/user id or demo approver label. - reason: Reason or return instruction. - edits: Structured edits to action or constraints. - created_at: Decision timestamp. | - item: reason: string, unique: boolean, columns: object | Human governance decisions for Actions. |
| TABLE-008 | Production: operator/approver/admin write; viewer read. | seo_constraints | - id: Primary key. - company_profile_id: Company profile receiving constraints. - constraint_type: budget, risk, brand, competitor, category, approval_policy, roi_assumption. - value: Constraint payload. - updated_at: Last update time. | - item: reason: string, unique: boolean, columns: object | User/business constraints that shape recommendation ranking and governance. |
| TABLE-009 | Scoped through company profile. | seo_outcome_metrics | - id: Primary key. - company_profile_id: Company profile this metric belongs to. - recommendation_id: Optional recommendation linked to metric. - metric_type: spend_baseline, savings, traffic_value, pipeline_impact, payback, ranking_delta. - value: Numeric metric value when applicable. - unit: Currency, percent, days, rank, etc. - assumption: Whether the metric is seeded/assumption-based. - metadata: Calculation inputs, caveats, display labels. | - item: reason: string, unique: boolean, columns: object | ROI and post-action outcome metrics. |
migrations
| id | path | purpose | depends on |
|---|---|---|---|
| MIG-001 | supabase/migrations/ad_seo_agent/001_ai_first_object_model.sql | Create AD SEO Agent AI-first object model tables. | |
| MIG-002 | supabase/seed/ad_seo_agent/001_hubbard_seed.sql | Seed Hubbard CompanyProfile, AnalysisRun, AgentSteps, Recommendations, Evidence, Actions, Constraints, and OutcomeMetrics. | - MIG-001 |
dev studio
views
- stack
- feature_coverage
- schema_map
- api_table
- auth_model
- services
- env_vars
- risks
- open_questions
render as
architecture
model reviews
| id | model | status | provider | task type | evidence ref |
|---|---|---|---|---|---|
| MODEL-ARCH-001 | sonnet | applied | claude | architecture-review | tmp/model-runsad-seo-agent-claude-architecture-review-ask-model.json |
| MODEL-ARCH-002 | sonnet | applied | claude | architecture-review | tmp/model-runsad-seo-agent-claude-architecture-review-after-fixes.json |
| MODEL-ARCH-003 | sonnet | applied | claude | architecture-review | tmp/model-runsad-seo-agent-claude-architecture-review-final.json |
| MODEL-M00-001 | sonnet | applied | claude | architecture-review | tmp/ad-seo-agent-m00-audit-claude-review-3.json |
open questions
| id | owner | blocks | status | question | resolution |
|---|---|---|---|---|---|
| OQ-ARCH-001 | atlas | No longer blocks decomposition; build planning must follow client project Cloudflare conventions. | answered | Which repo/app root should host the Monday production pilot? | client project app: C:/Users/jstnk/Downloads/cc/projects/seo-studio, canonical route /seo, optional /products/seo redirect. |
| OQ-ARCH-002 | atlas | Approval write behavior only; does not block read-only product route or decomposition. | deferred | Should Monday approval decisions persist to Supabase Projects/Demo immediately or remain demo-local/read-only until auth/policy is finalized? |
schema version
1.0
feature coverage
| notes | api refs | feature id | schema refs | service refs | coverage status |
|---|---|---|---|---|---|
| CompanyProfile stores Hubbard identity, domain, categories, competitors, and source mode. | - API-001 | F-01 | - TABLE-001 | - SVC-001 | covered |
| ROI fields come from OutcomeMetric plus configurable Constraint assumptions. | - API-001 - API-004 | F-02 | - TABLE-001 - TABLE-008 - TABLE-009 | - SVC-001 | covered |
| Recommendation, Evidence, and Action objects support OpportunityBoard and EvidenceDrawer. | - API-002 - API-003 | F-03 | - TABLE-004 - TABLE-005 - TABLE-006 | - SVC-001 - SVC-002 | covered |
| AnalysisRun and AgentStep records feed visible agent activity and audit trails. | - API-001 - API-005 | F-04 | - TABLE-002 - TABLE-003 | - SVC-001 - SVC-003 | covered |
| Action, ApprovalDecision, and Constraint records enforce governance tiers and human decisions. | - API-004 | F-05 | - TABLE-006 - TABLE-007 - TABLE-008 | - SVC-001 | covered |
| White-label story uses CompanyProfile network context and Constraint/brand token config; full tenant admin is out of scope. | - API-001 | F-06 | - TABLE-001 - TABLE-008 | - SVC-001 | covered |
| Seeded source mode and provider status keep Monday pilot reliable with graceful live-provider failures. | - API-001 - API-005 | F-07 | - TABLE-002 - TABLE-003 | - SVC-001 - SVC-002 - SVC-003 | covered |
architecture summary
stack
backend
Cloudflare Pages for static app delivery; Cloudflare Workers/Pages Functions for server-side approval actions, provider adapters, and secret-bearing calls when needed.
hosting
Cloudflare Pages for the seo-studio client repo, publicly routed at https://bezeliq.ai/seo.
database
Supabase Projects/Demo for product-build/demo records and future product project records; seeded Hubbard JSON may be bundled for first Monday slice if mirrored/importable to Supabase.
frontend
C:/Users/jstnk/Downloads/cc/projects/seo-studio is a Next/React client repo. Current implementation must be audited against artifacts; do not infer architecture solely from existing code.
redirects
canonical
/seo
mechanism
Canonical route belongs to the seo-studio Cloudflare Pages deployment at /seo. The /products/seo alias belongs to the parent domain/suite Cloudflare routing layer, not the seo-studio app internals.
public url
https://bezeliq.ai/seo
short alias
/products/seo
database project
url
https://fyauumztocuinwhcokbn.supabase.co
name
Projects/Demo
monday runtime role
Importable/mirrored seed target; bundled fixture remains the Monday route runtime source unless source mode is explicitly changed.
supabase project id
fyauumztocuinwhcokbn
external services
- Cloudflare Pages for client project hosting
- Cloudflare Workers/Pages Functions for server-side product actions and provider adapters
- Cloudflare Images/Stream for product media, screenshots, and future explainer/demo video assets
- Supabase Projects/Demo for seeded Hubbard data and product-build records
- Hubbard public website for public company/category context
- Optional SEO provider adapters for future live data: Google Search Console, SEMrush, Ahrefs, crawler provider
- Optional RedKey/agent infrastructure task event source for live AgentStep events
approach
AI-first production pilot built as a client project at /seo, around a structured Recommendation object model. Monday reliability comes from a versioned Hubbard seed dataset that uses the same shapes as future live provider adapters. The UI renders Blanc product patterns inside a client project route; Cloudflare hosts/runtime/media, and Supabase Projects/Demo provides product-build data.
repo roots
- C:/Users/jstnk/Downloads/cc/projects/redkey/docs/projects/ad-seo-agent
- C:/Users/jstnk/Downloads/cc/projects/seo-studio
- C:/Users/jstnk/Downloads/cc/projects/blanc
major decisions
| id | reason | decision | alternatives rejected |
|---|---|---|---|
| ADR-001 | Production-ready by Monday cannot depend on new live SEO provider credentials, provider limits, or crawling variability. | Use hybrid data: versioned seeded Hubbard dataset for Monday reliability plus live-provider adapter boundaries. | - Live providers only: too risky for Monday. - Static mockup only: would not be production-ready and would not preserve future architecture. |
| ADR-002 | The product's core value is AI-generated judgment moving through evidence, action, and governance. | Make Recommendation the central persisted object. | - Keyword rows as primary object: too close to conventional SEO tools. - Dashboard widget data only: loses execution and governance semantics. |
| ADR-003 | Blanc now encodes the AI-first product patterns needed here: ExecutiveDashboard, OpportunityBoard, AgentActivityRail, EvidenceDrawer, and ApprovalGate. | Use Blanc as the required UI system for the pilot. | - Ad hoc custom CSS: slower and less reusable. - Generic component library: would not express AI orchestration and governance as product primitives. |
| ADR-004 | Human changes must feed back into ranking, governance, and execution state instead of being local UI actions. | Persist approval decisions and constraints as first-class objects. | - Client-only approval state: not auditable. - Single freeform notes field: not machine-actionable. |
| ADR-007 | This matches client project architecture and keeps runtime, media, and edge/server concerns in the same platform family. | Use Cloudflare as the production platform for AD SEO Agent: Pages for route hosting, Workers/Pages Functions for server-side actions/adapters, and Images/Stream for media assets when needed. | - Generic Vercel-style Next deployment: ignores existing client project Cloudflare architecture. - Browser-only provider integrations: would expose secrets and weaken production readiness. |
| ADR-008 | The platform already uses Supabase for product-build/demo state. AD SEO Agent should follow the same convention instead of inventing a separate data store. | Use Supabase Projects/Demo as the product-build data layer for AD SEO Agent seeded/demo records and future project records. | - Local JSON as permanent source of truth: acceptable for first slice only, not product architecture. - New database/project just for AD SEO Agent: unnecessary fragmentation for this pilot. |
| ADR-010 | The repo already exists for the client project, but it was created during premature build work. To prevent repeating that mistake, artifacts remain the source of truth and the repo must be aligned to them before planning execution. | Use C:/Users/jstnk/Downloads/cc/projects/seo-studio as the canonical client repo for AD SEO Agent, with existing code treated as unapproved prototype output until audited. | - bezeliq-studio route: wrong project boundary and repeatedly confuses agents. - Dev Studio/internal Studio: wrong audience and not the product host. - Treat current repo code as approved implementation: wrong because it was created before artifact approval. |
monday data path
reason
This removes credential, RLS, network, and migration timing risk while preserving the approved object model and future Supabase migration path.
decision
For the Monday production pilot, the runtime UI reads a bundled, versioned Hubbard fixture via static Next import. Supabase Projects/Demo remains the product-build data layer and must receive an importable mirror/seed path, but browser runtime does not depend on live Supabase or Cloudflare read APIs for the Monday demo.
future path
After Monday, the same object shapes may be served from Supabase anon-read policies or Cloudflare Pages Functions; API-001 through API-005 are the future server boundary, not required for read-only Monday rendering.
blanc integration
decision
For the Monday Cloudflare Pages pilot, use a committed Blanc release snapshot inside the seo-studio repo at app/vendor/blanc. The upstream design-system source of truth remains C:/Users/jstnk/Downloads/cc/projects/blanc; future production hardening should publish Blanc as a package or move related projects into a monorepo before relying on shared package imports in Cloudflare.
release rule
Do not hand-edit the vendor snapshot as a fork. Changes should be made in the Blanc repo and copied/versioned into seo-studio for the Monday release until packaging/monorepo support exists.
verified import
import './vendor/blanc/blanc.css';
cloudflare reason
blanc: file:../blanc is local-development evidence only; sibling file dependencies are not Cloudflare-safe when Pages clones a single repo.
required next config
turbopack.root = path.resolve('.') so the seo-studio repo builds as a standalone Cloudflare Pages project.
implementation host
repo
C:/Users/jstnk/Downloads/cc/projects/seo-studio
status
confirmed_client_repo_requires_audit
decision
C:/Users/jstnk/Downloads/cc/projects/seo-studio is the canonical client repo for AD SEO Agent. Existing code in that repo was produced before artifacts were settled and must be audited/remediated against the architecture docs before PLAN/build.
route status
canonical public route confirmed as https://bezeliq.ai/seo; optional alias /products/seo must be implemented at the parent domain/suite routing layer.
route decision
alias path
/products/seo
alias owner
Parent bezeliq.ai Cloudflare/domain routing layer or suite host, not the seo-studio Pages project.
canonical path
/seo
canonical public url
https://bezeliq.ai/seo
source of truth
Architecture/UX/Requirements artifacts override existing repo implementation when they conflict.
disallowed hosts
- C:/Users/jstnk/Downloads/cc/projects/bezeliq-studio
- Dev Studio
- internal Studio tooling
non functional requirements
| id | category | requirement | verification hint |
|---|---|---|---|
| NFR-001 | performance | Command Center renders from seeded data in under 2 seconds and first meaningful insight is visible immediately. | Browser QA timing and Lighthouse/devtools timing. |
| NFR-002 | security | No SEO provider keys or RedKey credentials are exposed to the browser. | Inspect built client bundle/env usage. |
| NFR-003 | reliability | Pilot works end-to-end without live SEO provider availability. | Run with provider credentials absent and source_mode=seeded/hybrid. |
| NFR-004 | observability | Provider failures and seeded fallback states are visible in System/Data status. | Simulate provider unavailable state. |
| NFR-005 | accessibility | Core surfaces are keyboard navigable; statuses are text plus color; mobile layout has no text overlap. | Manual keyboard smoke and mobile viewport screenshot. |