# haqeeqiazadee-ux/yousell-admin architecture

> Architecture diagram of the GitHub repository haqeeqiazadee-ux/yousell-admin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haqeeqiazadee-ux/yousell-admin
- Repository: https://github.com/haqeeqiazadee-ux/yousell-admin

## Overview

This repository is a multi-surface product platform built around a Next.js application, a separate backend worker service, and Supabase as the central data/auth layer. It is not just a UI repo: it contains the customer-facing product, an admin control plane, an engine/orchestration layer, background job processing, webhook entry points, and a Python-based analysis toolchain.

High-level structure

- Main application: a Next.js App Router app under src/app, serving:
  - Marketing site pages
  - Public auth pages
  - Customer dashboard
  - Admin console
  - API routes for both dashboard and admin workflows
  - Engine-facing endpoints and webhooks
- Background processing: a separate TypeScript backend service in backend/ that runs queue workers and scheduled jobs.
- Data layer: Supabase/Postgres, Supabase Auth, and RLS policies defined in supabase/migrations.
- Supporting analysis tool: gap_analyzer/ is a standalone Python/Node utility for comparing specs, scraping target pages, and exporting reports.
- QA and verification: extensive unit/integration/E2E coverage under tests/ and e2e/.

Primary runtime boundaries

1. Presentation layer
- Marketing pages live under src/app/(marketing) and src/app/pricing, src/app/privacy, src/app/terms, etc.
- Auth surfaces are separate routes: /login, /signup, /forgot-password, /reset-password.
- The authenticated product experience is split into:
  - /dashboard for clients/users
  - /admin for internal operators
- The UI is composed from a shared component library in src/components and design-system primitives in src/components/ui.

2. Application/API layer
- The app exposes a large set of route handlers in src/app/api.
- These are organized by audience and responsibility:
  - /api/dashboard/* for client-facing data access and actions
  - /api/admin/* for internal operations and oversight
  - /api/engine/* for engine-to-engine or engine-control interactions
  - /api/webhooks/* for third-party event ingestion
  - /api/auth/* for authentication and OAuth callbacks
- This is the main server-side boundary for business operations. Frontend pages mostly call these APIs rather than talking directly to external services.

3. Domain/engine layer
- Core business logic is concentrated in src/lib/engines.
- This layer contains the product’s “intelligence engines” such as:
  - discovery
  - competitor intelligence
  - TikTok discovery and analysis
  - Amazon intelligence
  - product clustering
  - scoring
  - supplier discovery
  - content creation
  - profitability modeling
  - creator matching
  - order tracking
  - store integration
  - trend detection
- The engines are paired with supporting abstractions in src/lib/providers, src/lib/scoring, src/lib/integrations, and src/lib/automation.
- There is a dedicated “governor” subsystem under src/lib/engines/governor that acts as a control plane for budgets, gating, dispatch, cost tracking, external engine adapters, and lifecycle decisions.

4. Async/background processing layer
- backend/src is a separate worker service, with its own package.json, Dockerfile, and Railway deployment config.
- Its jobs directory contains discrete worker modules for scanning, enrichment, outreach, content generation, notifications, product pushing, shop sync, POD provisioning/fulfillment sync, TikTok processing, trend scanning, and automation scheduling.
- backend/src/worker.ts is the runtime entry point for job execution.
- backend/src/lib contains queue, email, provider wiring, scoring, Supabase access, and a governor job wrapper.
- This suggests a queue-driven architecture where the Next.js app enqueues or triggers work, and the backend service consumes it asynchronously.

Core data flow

1. User/customer flow
- Visitors land on the marketing site.
- They sign up or log in through the auth pages and auth callbacks.
- Once authenticated, they enter the dashboard.
- Dashboard pages call /api/dashboard/* routes for user-scoped data and actions.
- Those routes read/write Supabase and may invoke engine logic.

2. Admin/operator flow
- Internal users use /admin and /api/admin/*.
- The admin console appears to manage operational views such as:
  - products
  - scans
  - competitors
  - clusters
  - content
  - alerts
  - automation
  - analytics
  - governance
  - integrations
  - webhooks
  - pricing and financial views
- Admin routes typically have broader authority and likely use Supabase admin/server access patterns.

3. Intelligence pipeline
- Data enters from external sources via provider modules and webhooks:
  - Amazon
  - Shopify
  - TikTok
  - Etsy
  - WooCommerce
  - BigCommerce
  - Square
  - Printful/Printify
  - Resend
- The engines transform that raw input into structured intelligence:
  - product discovery and enrichment
  - trend detection
  - competitor/ad analysis
  - scoring and clustering
  - creator/influencer matching
  - profitability and forecasting
- Results are stored in Supabase and surfaced through dashboard/admin APIs and pages.

4. Automation/fulfillment flow
- Some actions are operational, not just analytical:
  - pushing products to Shopify/Amazon/TikTok
  - syncing stores and orders
  - generating and scheduling content
  - distribution and notifications
  - print-on-demand provisioning and fulfillment sync
- These are handled by a mix of API routes, engine modules, and backend jobs.
- This creates a loop from discovery/intelligence to execution/publishing.

5. Governance/control flow
- The governor subsystem sits across the engine layer and job layer.
- It appears to regulate:
  - which engines can run
  - budget and allowance constraints
  - dispatch and swap decisions
  - external engine integrations
  - cost manifests and envelope lifecycle
- The admin UI has dedicated governor pages for budgets, decisions, overrides, swaps, and engine fleet visibility.
- This is a distinct architectural boundary: it is the platform’s operational control plane, separate from the product intelligence itself.

Key subsystems to show in an architecture diagram

- Marketing and acquisition surface
  - public pages, comparison pages, feature pages, onboarding
- Authentication and identity
  - login/signup/reset flows, OAuth callbacks, role checks, middleware
- Client dashboard
  - product, content, analytics, alerts, requests, saved items, watchlists, integrations, billing, usage
- Admin console
  - deep operational views across intelligence, automation, finance, governance, scanning, webhooks, and system health
- API layer
  - grouped route handlers for dashboard/admin/engine/auth/webhooks
- Engine/domain layer
  - business logic modules and scoring/automation/governor abstractions
- Worker service
  - queue consumers and scheduled jobs
- Data layer
  - Supabase DB, auth, RLS, migrations, server/client/admin access helpers
- External integrations
  - e-commerce platforms, marketplaces, social/video platforms, email, AI/creative tools, fulfillment services
- QA/verification
  - unit tests, integration tests, inter-engine workflow tests, Playwright E2E, accessibility and visual regression

Technology and infrastructure choices that materially affect the architecture

- Next.js App Router
  - Used for both UI and server route handlers, so frontend and API are co-located.
- TypeScript
  - Main application and backend worker are TypeScript-based.
- Supabase
  - Centralized database, auth, and RLS enforcement; migration files define the schema and security model.
- Separate worker deployment
  - backend/ is independently deployable, with Docker and Railway configuration.
- Queue/event patterns
  - The presence of queue abstractions, Redis event bus, workers, and inter-engine tests indicates asynchronous processing and event-driven coordination.
- Stripe
  - Used for billing/subscriptions in the dashboard and webhook handling.
- OAuth/store integrations
  - Shopify, BigCommerce, WooCommerce, Etsy, and similar integrations are first-class, not incidental.
- Playwright and Vitest
  - There is serious coverage for end-to-end flows and engine/business logic.

Repository organization signals

- src/app is the product surface and API boundary.
- src/lib is the main domain/service layer, with clear subdomains for engines, providers, integrations, auth, scoring, automation, stores, and Supabase.
- backend/src is the asynchronous execution plane.
- supabase/migrations is the authoritative schema/security history.
- tests and e2e validate the system across unit, integration, and full-flow levels.
- docs, system, tasks, and archive contain extensive specification, QA, and operational notes; these are important for understanding intent but are not runtime components.

How the architecture hangs together

The simplest accurate mental model is:

- Supabase stores the source-of-truth data and enforces security.
- The Next.js app provides all human-facing interfaces and most server APIs.
- Engine modules perform the product’s analytical and orchestration logic.
- Webhooks and provider integrations ingest external signals.
- The backend worker executes asynchronous jobs, scheduled automations, and longer-running workflows.
- The governor subsystem regulates engine execution, spend, and operational policy.
- Admin and dashboard UIs expose different slices of the same underlying system: dashboard for end users, admin for operators.

If you were drawing the architecture, the strongest boundaries would be:
- public marketing/auth vs authenticated product UI
- UI/API layer vs domain engine layer
- synchronous request/response APIs vs asynchronous worker jobs
- application logic vs Supabase data/security
- product intelligence execution vs governor/control-plane oversight
- internal operator tools vs customer-facing dashboard

Main entry points: [`src/lib/engines`](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/engines) (Engine core), [`src/lib/supabase`](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/supabase) (Supabase access), [`backend/src/jobs`](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/backend/src/jobs) (Job modules), [`src/lib/providers`](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/providers) (Providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Presentation"
  marketing_ui["Marketing site<br/>Next.js public pages"]
  auth_ui["Auth pages<br/>Next.js auth UI<br/>[page.tsx]"]
  dashboard_ui["Dashboard<br/>Customer app"]
  admin_ui["Admin console<br/>Operator app"]
  shared_components["Shared UI<br/>Component library"]
end

subgraph "API Layer"
  dashboard_api["Dashboard APIs<br/>Route handlers"]
  admin_api["Admin APIs<br/>Route handlers"]
  engine_api["Engine APIs<br/>Engine gateway"]
  auth_api["Auth APIs<br/>Identity routes"]
  webhook_api["Webhooks<br/>Ingress routes"]
end

subgraph "Domain Engine"
  engine_core["Engine core<br/>Domain logic"]
  governor["Governor<br/>Control plane"]
  scoring["Scoring<br/>Signals and ranking"]
  automation["Automation<br/>Orchestration"]
end

subgraph "Async Workers"
  backend_worker["Worker service<br/>TypeScript backend<br/>[worker.ts]"]
  backend_jobs["Job modules<br/>Queue workers"]
end

subgraph "Data Layer"
  supabase_client[("Supabase access<br/>DB/auth helpers")]
  supabase_schema[("Migrations<br/>Postgres schema")]
end

subgraph "Integrations"
  provider_layer["Providers"]
  shopify_integration["Shopify<br/>Store integration"]
end

subgraph "Verification"
  tests_suite["Tests<br/>Vitest/Playwright"]
  e2e_suite["E2E<br/>Playwright flows"]
end

marketing_ui -->|"renders with"| shared_components
auth_ui -->|"calls"| auth_api
dashboard_ui -->|"calls"| dashboard_api
admin_ui -->|"calls"| admin_api
dashboard_ui -->|"composes"| shared_components
admin_ui -->|"composes"| shared_components
dashboard_api -->|"reads/writes"| supabase_client
admin_api -->|"admin access"| supabase_client
engine_api -->|"invokes"| engine_core
engine_api -->|"gated by"| governor
webhook_api -->|"ingests from"| provider_layer
engine_core -->|"pulls signals from"| provider_layer
engine_core -->|"uses"| scoring
engine_core -->|"orchestrates"| automation
engine_core -->|"stores results"| supabase_client
governor -->|"persists policy"| supabase_client
governor -->|"controls jobs"| backend_worker
backend_worker -->|"executes"| backend_jobs
backend_jobs -->|"reuses logic"| engine_core
backend_jobs -->|"consumes"| provider_layer
backend_jobs -->|"syncs data"| supabase_client
shopify_integration -->|"specializes"| provider_layer
supabase_schema -->|"defines"| supabase_client
tests_suite -->|"verifies"| engine_core
tests_suite -->|"verifies"| supabase_schema
e2e_suite -->|"covers"| dashboard_ui
e2e_suite -->|"covers"| admin_ui
e2e_suite -->|"covers"| marketing_ui

click marketing_ui "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/app/(marketing)"
click auth_ui "https://github.com/haqeeqiazadee-ux/yousell-admin/blob/main/src/app/login/page.tsx"
click dashboard_ui "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/app/dashboard"
click admin_ui "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/app/admin"
click shared_components "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/components"
click dashboard_api "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/app/api/dashboard"
click admin_api "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/app/api/admin"
click engine_api "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/app/api/engine"
click auth_api "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/app/api/auth"
click webhook_api "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/app/api/webhooks"
click engine_core "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/lib/engines"
click governor "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/lib/engines/governor"
click scoring "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/lib/scoring"
click automation "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/lib/automation"
click supabase_client "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/lib/supabase"
click supabase_schema "https://github.com/haqeeqiazadee-ux/yousell-admin/blob/main/supabase/migrations/CONSOLIDATED_MIGRATION.sql"
click provider_layer "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/lib/providers"
click shopify_integration "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/src/lib/integrations/shopify"
click backend_worker "https://github.com/haqeeqiazadee-ux/yousell-admin/blob/main/backend/src/worker.ts"
click backend_jobs "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/backend/src/jobs"
click tests_suite "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/tests"
click e2e_suite "https://github.com/haqeeqiazadee-ux/yousell-admin/tree/main/e2e"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class marketing_ui,auth_ui,dashboard_ui,admin_ui,shared_components,tests_suite,e2e_suite toneBlue
class dashboard_api,admin_api,engine_api,auth_api,webhook_api toneAmber
class engine_core,governor,scoring,automation toneMint
class backend_worker,backend_jobs toneRose
class supabase_client,supabase_schema toneIndigo
class provider_layer,shopify_integration toneTeal
```

## Components

### Presentation

Public site, auth, dashboard, and admin surfaces in the Next.js app.

- [Marketing site](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/app/(marketing)): Next.js public pages · Public acquisition pages and product marketing surfaces. · `src/app/(marketing)`
- [Auth pages](https://github.com/haqeeqiazadee-ux/yousell-admin/blob/HEAD/src/app/login/page.tsx): Next.js auth UI · Login, signup, password reset, and auth callbacks. · `src/app/login/page.tsx`
- [Dashboard](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/app/dashboard): Customer app · Authenticated customer experience and product workspace. · `src/app/dashboard`
- [Admin console](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/app/admin): Operator app · Internal operational console for intelligence, governance, and system views. · `src/app/admin`
- [Shared UI](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/components): Component library · Reusable dashboard, marketing, engine, and design-system components. · `src/components`

### API Layer

Route handlers grouped by audience and responsibility.

- [Dashboard APIs](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/app/api/dashboard): Route handlers · Client-scoped API routes for dashboard data and actions. · `src/app/api/dashboard`
- [Admin APIs](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/app/api/admin): Route handlers · Operator-scoped API routes for oversight and control. · `src/app/api/admin`
- [Engine APIs](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/app/api/engine): Engine gateway · Engine-facing endpoints for discovery, scoring, content, and orchestration. · `src/app/api/engine`
- [Auth APIs](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/app/api/auth): Identity routes · Authentication callbacks, OAuth, and sign-out endpoints. · `src/app/api/auth`
- [Webhooks](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/app/api/webhooks): Ingress routes · Third-party event ingestion for stores, payments, fulfillment, and social platforms. · `src/app/api/webhooks`

### Domain Engine

Core product logic, orchestration, scoring, and governance.

- [Engine core](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/engines): Domain logic · Primary analytical and orchestration engines used across the app. · `src/lib/engines`
- [Governor](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/engines/governor): Control plane · Budgets, gating, dispatch, cost tracking, and lifecycle control for engines. · `src/lib/engines/governor`
- [Scoring](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/scoring): Signals and ranking · Composite scoring, profitability, and fulfillment modifiers. · `src/lib/scoring`
- [Automation](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/automation): Orchestration · Scheduling and automation configuration used by engines and workers. · `src/lib/automation`

### Async Workers

Separate backend service for queue-driven and scheduled processing.

- [Worker service](https://github.com/haqeeqiazadee-ux/yousell-admin/blob/HEAD/backend/src/worker.ts): TypeScript backend · Separate deployable runtime for asynchronous job execution. · `backend/src/worker.ts`
- [Job modules](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/backend/src/jobs): Queue workers · Discrete backend jobs for scanning, enrichment, outreach, content, and fulfillment. · `backend/src/jobs`

### Data Layer

Supabase schema, auth, RLS, and access helpers.

- [Supabase access](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/supabase): DB/auth helpers · Server, client, and admin helpers for Supabase access patterns. · `src/lib/supabase`
- [Migrations](https://github.com/haqeeqiazadee-ux/yousell-admin/blob/HEAD/supabase/migrations/CONSOLIDATED_MIGRATION.sql): Postgres schema · Authoritative database, auth, RLS, and platform schema history. · `supabase/migrations/CONSOLIDATED_MIGRATION.sql`

### Integrations

External providers and service adapters used by the platform.

- [Providers](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/providers): External data providers · Provider abstractions for marketplaces, social sources, and discovery feeds. · `src/lib/providers`
- [Shopify](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/src/lib/integrations/shopify): Store integration · Shop and product integration layer for Shopify operations. · `src/lib/integrations/shopify`

### Verification

Tests and end-to-end validation coverage.

- [Tests](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/tests): Vitest/Playwright · Unit, integration, and end-to-end verification coverage. · `tests`
- [E2E](https://github.com/haqeeqiazadee-ux/yousell-admin/tree/HEAD/e2e): Playwright flows · Browser-level validation of auth, dashboard, admin, and marketing experiences. · `e2e`

## Connections

- Marketing site → Shared UI: renders with · Marketing pages are built from shared presentation components.
- Auth pages → Auth APIs: calls · Auth surfaces complete sign-in and callback flows through auth routes.
- Dashboard → Dashboard APIs: calls · Customer pages use dashboard APIs for scoped data and actions.
- Admin console → Admin APIs: calls · Operator pages use admin APIs for oversight and control actions.
- Dashboard → Shared UI: composes · Dashboard screens are assembled from shared UI primitives and widgets.
- Admin console → Shared UI: composes · Admin console pages reuse the shared component layer.
- Dashboard APIs → Supabase access: reads/writes · Dashboard routes persist and query product data through Supabase helpers.
- Admin APIs → Supabase access: admin access · Admin routes use privileged Supabase access patterns.
- Engine APIs → Engine core: invokes · Engine routes expose the core business logic over HTTP.
- Engine APIs → Governor: gated by · Engine execution is mediated by governor policies and limits.
- Webhooks → Providers: ingests from · Webhook entry points receive external platform events and normalize them.
- Engine core → Providers: pulls signals from · Engines depend on provider modules for external intelligence and discovery.
- Engine core → Scoring: uses · Engines use scoring and ranking logic to prioritize outputs.
- Engine core → Automation: orchestrates · Core engines coordinate scheduled and automated workflows.
- Engine core → Supabase access: stores results · Engine outputs are written back to the platform data layer.
- Governor → Supabase access: persists policy · Governor state, budgets, and decisions are backed by Supabase.
- Governor → Worker service: controls jobs · Governor policy extends into background job execution.
- Worker service → Job modules: executes · The worker runtime dispatches the individual job modules.
- Job modules → Engine core: reuses logic · Background jobs reuse the same domain engines as synchronous APIs.
- Job modules → Providers: consumes · Jobs pull from external sources and provider adapters.
- Job modules → Supabase access: syncs data · Jobs update the central Supabase-backed system of record.
- Shopify → Providers: specializes · Shopify is a concrete store integration built on provider abstractions.
- Migrations → Supabase access: defines · The schema and migrations define the tables and security model used by helpers.
- Tests → Engine core: verifies · Unit and integration tests cover the engine layer heavily.
- Tests → Migrations: verifies · Tests include database, security, and migration behavior.
- E2E → Dashboard: covers · Playwright flows validate the customer experience.
- E2E → Admin console: covers · Playwright flows validate the operator experience.
- E2E → Marketing site: covers · Playwright flows validate the public site and onboarding paths.
