How haqeeqiazadee-ux/yousell-admin works
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: engines Engine core · supabase Supabase access · jobs Job modules · providers Providers
Components 22
Presentation
Public site, auth, dashboard, and admin surfaces in the Next.js app.
- Marketing site · Public acquisition pages and product marketing surfaces.
src/app/(marketing) - Auth pages · Login, signup, password reset, and auth callbacks.
src/app/login/page.tsx - Dashboard · Authenticated customer experience and product workspace.
src/app/dashboard - Admin console · Internal operational console for intelligence, governance, and system views.
src/app/admin - Shared UI · Reusable dashboard, marketing, engine, and design-system components.
src/components
API Layer
Route handlers grouped by audience and responsibility.
- Dashboard APIs · Client-scoped API routes for dashboard data and actions.
src/app/api/dashboard - Admin APIs · Operator-scoped API routes for oversight and control.
src/app/api/admin - Engine APIs · Engine-facing endpoints for discovery, scoring, content, and orchestration.
src/app/api/engine - Auth APIs · Authentication callbacks, OAuth, and sign-out endpoints.
src/app/api/auth - Webhooks · 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 · Primary analytical and orchestration engines used across the app.
src/lib/engines - Governor · Budgets, gating, dispatch, cost tracking, and lifecycle control for engines.
src/lib/engines/governor - Scoring · Composite scoring, profitability, and fulfillment modifiers.
src/lib/scoring - Automation · 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 · Separate deployable runtime for asynchronous job execution.
backend/src/worker.ts - Job modules · Discrete backend jobs for scanning, enrichment, outreach, content, and fulfillment.
backend/src/jobs
Data Layer
Supabase schema, auth, RLS, and access helpers.
- Supabase access · Server, client, and admin helpers for Supabase access patterns.
src/lib/supabase - Migrations · Authoritative database, auth, RLS, and platform schema history.
supabase/migrations/CONSOLIDATED_MIGRATION.sql
Integrations
External providers and service adapters used by the platform.
Connections 28
- 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.