@clidey/dory 0.1.0 → 0.3.0

package/docs/overview/developer-overview/dev-architecture.mdx

@@ -1,292 +0,0 @@
----
-title: 'Technical Architecture Overview'
-description: 'High-level explanation of backend modules, communication patterns, shared resources, and tech stacks.'
----
-
-# Technical Architecture Overview
-
-## 1. Purpose and Scope
-
-The **PIM (Product Information Management) Module** is a core backend component responsible for managing products, variants, inventory, collections, locations, suppliers, and related business logic within the Genie application. It serves as the authoritative source for product-related data, synchronizes with external systems (notably Shopify), and supports workflows such as bundles, stock levels, and supplier management.
-
-This module handles all CRUD operations and complex relations for product data, including tags, bundles, suppliers, and inventory tracking. It also integrates with other subsystems like Sales Orders, Purchase Orders, User Management, Shopify, and Workflow modules.
-
-**System Boundaries:**
-- Owns product/catalog domain data
-- Interfaces with Shopify for product and inventory synchronization
-- Supports warehouse location and inventory tracking
-- Exposes controllers for API usage
-
-**Architectural Context:**
-- Implemented as a NestJS Module using TypeORM for ORM
-- Relies on event-driven processing (via BullMQ queues) for asynchronous workflows
-- Interacts with shared services such as Slack and Email for notifications
-
-## 2. Technical Overview
-
-The PIM module forms a central part of the Genie backend architecture, acting as the product data hub.
-
-### Core Components:
-- **Entity Layer:** Defines TypeORM entities representing products, variants, inventory items, collections, suppliers, locations, and related historical or snapshot data.
-- **Service Layer:** Contains business logic for managing products, suppliers, tags, bundles, inventory, and variant data.
-- **Controller Layer:** API endpoints facilitating product management, inventory control, saved views, dashboards, locations, and bundles.
-- **Integration with External Modules:** Forward references to Shopify, Sales Order, Purchase Order, User Management, and Supplier modules enable cross-domain operations.
-- **Event Queue Processing:** Uses BullMQ queues and consumers to process asynchronous tasks such as insights synchronization, inventory item history, and snapshot management.
-
-### Key Technologies:
-- **NestJS Framework:** Modular design with decorators and dependency injection.
-- **TypeORM:** ORM for database schema and queries, leveraging PostgreSQL (implied).
-- **BullMQ:** Distributed job queue for handling asynchronous tasks.
-- **Slack & Email Modules:** For notifications and communication.
-- **Event-driven design:** Consumers react to queued events for data synchronization and historical tracking.
-
-### Architectural Pattern:
-The module employs a layered architecture with clear separation of concerns and uses event-driven paradigms to handle asynchronous processes and external system synchronization efficiently.
-
-```mermaid
-flowchart TD
-  subgraph "API Layer"
-    PC["ProductsController"]
-    IC["InventoryController"]
-    LC["LocationsController"]
-    SC["SavedViewController"]
-    DC["DashboardController"]
-    IPC["IdeaProductsController"]
-    PMC["ProductsMappingController"]
-  end
-
-  subgraph "Service Layer"
-    PS["ProductsService"]
-    IS["InsightsSyncService"]
-    ISyncS["InsightsScheduledSyncService"]
-    IIS["InventorySalesMetricsService"]
-    InvS["InventoryService"]
-    LocS["LocationsService"]
-    FavS["FavouritesService"]
-    IdeaPS["IdeaProductsService"]
-    SavedVS["SavedViewService"]
-    DashS["DashboardService"]
-    DSTS["DailySyncPerformanceTrackerService"]
-    WebhooksSyncS["WebhooksInsightsSyncService"]
-    ScheduledTS["ScheduledTasksService"]
-    PMSnapS["ProductVariantSnapshotService"]
-    PoBundlesS["PoBundlesService"]
-    PMappingS["ProductsMappingService"]
-  end
-
-  subgraph "Entities & DB"
-    PE["ProductEntity"]
-    PVE["ProductVariantEntity"]
-    IIHE["InventoryItemHistoryEntity"]
-    CE["CollectionEntity"]
-    CEProd["CollectionProductEntity"]
-    LE["LocationEntity"]
-    PVLE["ProductVariantLocationEntity"]
-    PVCE["ProductVariantComponentEntity"]
-    PSTE["ProductSupplierEntity"]
-    PSVTE["ProductSupplierVariantEntity"]
-    PVTCE["ProductVariantTagEntity"]
-    PVBLIE["ProductVariantBuyIgnoreEntity"]
-    PVSLE["ProductVariantShipmentLandedCostEntity"]
-  end
-
-  subgraph "External Modules"
-    SOM["SalesOrderModule"]
-    ShM["ShopifyModule"]
-    UMM["UserManagementModule"]
-    TM["TrackingModule"]
-    CM["CommentModule"]
-    AM["AssetModule"]
-    POM["PurchaseOrderModule"]
-    SupM["SupplierModule"]
-    EM["EmailModule"]
-    SM["SlackModule"]
-    WM["WorkflowModule"]
-    BM["BillingModule"]
-  end
-
-  subgraph "Queues & Consumers"
-    ISyncC["InsightsSyncConsumer"]
-    IIHC["InventoryItemHisotryConsumer"]
-    PVSnapC["ProductVariantSnapshotConsumer"]
-  end
-
-  %% API to services
-  PC -->|"calls"| PS
-  IPC -->|"calls"| IdeaPS
-  PMC -->|"calls"| PMappingS
-  IC -->|"calls"| InvS
-  LC -->|"calls"| LocS
-  SC -->|"calls"| SavedVS
-  DC -->|"calls"| DashS
-
-  %% Services to Entities
-  PS -->|"manages"| PE
-  PS -->|"manages"| PVE
-  PS -->|"manages"| PVTCE
-  PS -->|"manages"| PVTTagE[PVTCE]
-  PS -->|"manages"| PVTCE
-  InvS -->|"manages"| IIHE
-  LocS -->|"manages"| LE
-  SavedVS -->|"manages"| SavedViewE["SavedViewEntity"]
-  PS -->|"manages"| PVTCE
-  PS -->|"manages"| PSTE
-  PS -->|"manages"| PSVTE
-  PS -->|"manages"| PVBLIE
-  PS -->|"manages"| PVSLE
-  WebhooksSyncS -->|"reads/writes"| PE
-  WebhooksSyncS -->|"reads/writes"| PVE
-
-  %% Consumers consume queue and update services
-  ISyncC -->|"process events"| IS
-  IIHC -->|"process events"| InvS
-  PVSnapC -->|"process events"| PMSnapS
-
-  %% Service dependencies
-  PS -.->|"depends"| POM
-  PS -.->|"depends"| WM
-  PS -.->|"depends"| SM
-  PS -.->|"depends"| ShM
-
-  %% Module imports
-  PimModule[PIM Module] --> SOM
-  PimModule --> ShM
-  PimModule --> UMM
-  PimModule --> TM
-  PimModule --> CM
-  PimModule --> AM
-  PimModule --> POM
-  PimModule --> SupM
-  PimModule --> EM
-  PimModule --> SM
-  PimModule --> WM
-  PimModule --> BM
-
-  %% External module relationships
-  ShM -->|"integrates Shopify APIs"| EM
-  SM -.->|"Slack alerts"| PS
-
-  %% Legend
-  classDef api fill:#0b74de,stroke:#085aab,color:#fff;
-  classDef service fill:#2a9d8f,stroke:#207157,color:#fff;
-  classDef entity fill:#e76f51,stroke:#b04027,color:#fff;
-  classDef module fill:#264653,stroke:#1b2e3b,color:#fff;
-  classDef queue fill:#f4a261,stroke:#ce7421,color:#000;
-
-  class PC,IC,LC,SC,DC,IPC,PMC api;
-  class PS,IS,ISyncS,IIS,InvS,LocS,FavS,IdeaPS,SavedVS,DashS,DSTS,WebhooksSyncS,ScheduledTS,PMSnapS,PoBundlesS,PMappingS service;
-  class PE,PVE,IIHE,CE,CEProd,LE,PVLE,PVCE,PSTE,PSVTE,PVTCE,PVBLIE,PVSLE entity;
-  class SOM,ShM,UMM,TM,CM,AM,POM,SupM,EM,SM,WM,BM module;
-  class ISyncC,IIHC,PVSnapC queue;
-
-  click PC "apps/api/src/pim/controllers/products.controller.ts"
-  click IC "apps/api/src/pim/controllers/inventory.controller.ts"
-  click LC "apps/api/src/pim/controllers/locations.controller.ts"
-  click SC "apps/api/src/pim/controllers/saved-view.controller.ts"
-  click DC "apps/api/src/pim/controllers/dashboard.controller.ts"
-  click IPC "apps/api/src/pim/controllers/idea-products.controller.ts"
-  click PMC "apps/api/src/pim/controllers/products-mapping.controller.ts"
-
-  click PS "apps/api/src/pim/services/products.service.ts"
-  click IS "apps/api/src/pim/services/insights-sync.service.ts"
-  click ISyncS "apps/api/src/pim/services/insights-scheduled-sync.service.ts"
-  click IIS "apps/api/src/pim/services/inventory-sales-metrics.service.ts"
-  click InvS "apps/api/src/pim/services/inventory.service.ts"
-  click LocS "apps/api/src/pim/services/locations.service.ts"
-  click FavS "apps/api/src/pim/services/favourites.service.ts"
-  click IdeaPS "apps/api/src/pim/services/idea-products.service.ts"
-  click SavedVS "apps/api/src/pim/services/saved-view.service.ts"
-  click DashS "apps/api/src/pim/services/dashboard.service.ts"
-  click DSTS "apps/api/src/pim/services/daily-sync-performance-tracker.service.ts"
-  click WebhooksSyncS "apps/api/src/pim/services/webhooks-insights-sync.service.ts"
-  click ScheduledTS "apps/api/src/pim/services/scheduled-tasks.service.ts"
-  click PMSnapS "apps/api/src/pim/services/product-variant-snapshot.service.ts"
-  click PoBundlesS "apps/api/src/purchase-order/services/po-bundles.service.ts"
-  click PMappingS "apps/api/src/pim/services/products-mapping.service.ts"
-
-  click PE "apps/api/src/pim/entities/product.entity.ts"
-  click PVE "apps/api/src/pim/entities/product-variant.entity.ts"
-  click IIHE "apps/api/src/pim/entities/inventory-item-history.entity.ts"
-  click CE "apps/api/src/pim/entities/collection.entity.ts"
-  click CEProd "apps/api/src/pim/entities/collection-product.entity.ts"
-  click LE "apps/api/src/pim/entities/location.entity.ts"
-  click PVLE "apps/api/src/pim/entities/product-variant-location.entity.ts"
-  click PVCE "apps/api/src/pim/entities/product-variant-component.entity.ts"
-  click PSTE "apps/api/src/pim/entities/product-supplier.entity.ts"
-  click PSVTE "apps/api/src/pim/entities/product-supplier-variant.entity.ts"
-  click PVTCE "apps/api/src/pim/entities/product-variant-tag.entity.ts"
-  click PVBLIE "apps/api/src/pim/entities/product-variant-buy-ignore.entity.ts"
-  click PVSLE "apps/api/src/pim/entities/product-variant-shipment-landed-cost.entity.ts"
-
-  click SOM "apps/api/src/sales-order"
-  click ShM "apps/api/src/shopify"
-  click UMM "apps/api/src/user-management"
-  click TM "apps/api/src/tracking"
-  click CM "apps/api/src/comment"
-  click AM "apps/api/src/asset"
-  click POM "apps/api/src/purchase-order"
-  click SupM "apps/api/src/supplier"
-  click EM "apps/api/src/email"
-  click SM "apps/api/src/slack"
-  click WM "apps/api/src/workflow"
-  click BM "apps/api/src/billing"
-
-  click ISyncC "apps/api/src/pim/services/insights-sync.consumer.ts"
-  click IIHC "apps/api/src/pim/services/inventory-item-history.consumer.ts"
-  click PVSnapC "apps/api/src/pim/services/product-variant-snapshot.consumer.ts"
-
-  style PC fill:#0b74de,stroke:#085aab,color:#fff
-  style IC fill:#0b74de,stroke:#085aab,color:#fff
-  style LC fill:#0b74de,stroke:#085aab,color:#fff
-  style SC fill:#0b74de,stroke:#085aab,color:#fff
-  style DC fill:#0b74de,stroke:#085aab,color:#fff
-  style IPC fill:#0b74de,stroke:#085aab,color:#fff
-  style PMC fill:#0b74de,stroke:#085aab,color:#fff
-
-  style PS fill:#2a9d8f,stroke:#207157,color:#fff
-  style IS fill:#2a9d8f,stroke:#207157,color:#fff
-  style ISyncS fill:#2a9d8f,stroke:#207157,color:#fff
-  style IIS fill:#2a9d8f,stroke:#207157,color:#fff
-  style InvS fill:#2a9d8f,stroke:#207157,color:#fff
-  style LocS fill:#2a9d8f,stroke:#207157,color:#fff
-  style FavS fill:#2a9d8f,stroke:#207157,color:#fff
-  style IdeaPS fill:#2a9d8f,stroke:#207157,color:#fff
-  style SavedVS fill:#2a9d8f,stroke:#207157,color:#fff
-  style DashS fill:#2a9d8f,stroke:#207157,color:#fff
-  style DSTS fill:#2a9d8f,stroke:#207157,color:#fff
-  style WebhooksSyncS fill:#2a9d8f,stroke:#207157,color:#fff
-  style ScheduledTS fill:#2a9d8f,stroke:#207157,color:#fff
-  style PMSnapS fill:#2a9d8f,stroke:#207157,color:#fff
-  style PoBundlesS fill:#2a9d8f,stroke:#207157,color:#fff
-  style PMappingS fill:#2a9d8f,stroke:#207157,color:#fff
-
-  style PE fill:#e76f51,stroke:#b04027,color:#fff
-  style PVE fill:#e76f51,stroke:#b04027,color:#fff
-  style IIHE fill:#e76f51,stroke:#b04027,color:#fff
-  style CE fill:#e76f51,stroke:#b04027,color:#fff
-  style CEProd fill:#e76f51,stroke:#b04027,color:#fff
-  style LE fill:#e76f51,stroke:#b04027,color:#fff
-  style PVLE fill:#e76f51,stroke:#b04027,color:#fff
-  style PVCE fill:#e76f51,stroke:#b04027,color:#fff
-  style PSTE fill:#e76f51,stroke:#b04027,color:#fff
-  style PSVTE fill:#e76f51,stroke:#b04027,color:#fff
-  style PVTCE fill:#e76f51,stroke:#b04027,color:#fff
-  style PVBLIE fill:#e76f51,stroke:#b04027,color:#fff
-  style PVSLE fill:#e76f51,stroke:#b04027,color:#fff
-
-  style SOM fill:#264653,stroke:#1b2e3b,color:#fff
-  style ShM fill:#264653,stroke:#1b2e3b,color:#fff
-  style UMM fill:#264653,stroke:#1b2e3b,color:#fff
-  style TM fill:#264653,stroke:#1b2e3b,color:#fff
-  style CM fill:#264653,stroke:#1b2e3b,color:#fff
-  style AM fill:#264653,stroke:#1b2e3b,color:#fff
-  style POM fill:#264653,stroke:#1b2e3b,color:#fff
-  style SupM fill:#264653,stroke:#1b2e3b,color:#fff
-  style EM fill:#264653,stroke:#1b2e3b,color:#fff
-  style SM fill:#264653,stroke:#1b2e3b,color:#fff
-  style WM fill:#264653,stroke:#1b2e3b,color:#fff
-  style BM fill:#264653,stroke:#1b2e3b,color:#fff
-
-  style ISyncC fill:#f4a261,stroke:#ce7421,color:#000
-  style IIHC fill:#f4a261,stroke:#ce7421,color:#000
-  style PVSnapC fill:#f4a261,stroke:#ce7421,color:#000

package/docs/overview/product-intro/app-overview.mdx

@@ -1,167 +0,0 @@
----
-title: 'Genie App Overview'
-description: 'Summary of the product, its purpose, components (front-end, back-end, database), and high-level system responsibilities.'
----
-
-# Genie App Overview
-
-## Purpose and Scope
-
-The Genie App is a comprehensive operations management platform primarily used for inventory management, purchase orders, reporting, and demand planning. It targets growing Shopify merchants to streamline inventory workflows and enhance operational visibility.
-
-This documentation covers the overall structure and key components of the Genie App, detailing the frontend and backend integration, important modules, and interaction patterns within the system.
-
-## Architectural Context
-
-- **Frontend:** Built with Next.js, providing the web UI for users to interact with the system.
-- **Backend:** Powered by a NestJS API responsible for business logic, data processing, and integration with third-party services.
-- **Database:** PostgreSQL serves as the primary data store.
-
-The Genie App integrates tightly with Shopify for inventory syncing and offers embedded calendar scheduling features to facilitate user onboarding and support.
-
-## Technical Overview
-
-The Genie App follows a modular architecture with clear separation between frontend UI components and backend services. Key technologies and design principles include:
-
-- **React with Next.js:** For server-side rendered and client-side web UI delivering fast and SEO-friendly pages.
-- **NestJS:** An opinionated Node.js framework leveraging TypeScript, used to implement RESTful APIs.
-- **PostgreSQL:** Relational database for core data persistence.
-- **Docker and Docker Compose:** Used for local development and integration testing including the Postgres database.
-- **TypeORM:** Handles database migrations, schema generation, and database seeding.
-- **Cal.com widget embedded:** Provides inline calendar scheduling functionality for user engagement.
-
-## High-Level System Flow
-
-This flow describes major system parts and their interactions:
-
-1. **User Interaction (Frontend)**
-   - Users access the system via the web app UI.
-   - Authentication is initiated via email with "magic links."
-   - Core workflows include inventory management, purchase orders, reporting, and onboarding.
-2. **API Layer (Backend)**
-   - Processes business logic.
-   - Sends emails including purchase order notifications and reports.
-   - Handles database migrations and data seeding.
-3. **External Integrations**
-   - Shopify integration for inventory syncing.
-   - SendGrid for transactional email delivery.
-   - Cal.com for demo booking calendar embedded in modals.
-
-## Core Components and Responsibilities
-
-### Frontend Components
-
-- **WelcomeModal** (`apps/web/src/components/jasmine/welcome-modal.tsx`):
-  - Displays a welcome screen with trial details and demo booking calendar.
-  - Embeds a Cal.com calendar iframe to allow users to book onboarding sessions.
-  - Uses React hooks like `useStorageState` to control showing the modal.
-
-- **Registration and Login Pages**:
-  - Handle user sign-up and login flows using email-based magic links.
-  - Use `react-hook-form` for form handling and mutations from API calls.
-
-- **Settings and Billing Pages**:
-  - Manage subscription plans and billing details.
-  - Provide links to Shopify Apps page and booking support.
-
-### Backend Services
-
-- **EmailService** (`apps/api/src/email/services/email.service.ts`):
-  - Centralizes email sending using SendGrid.
-  - Sends various templated emails: purchase order status, alerts, login verification, invitations, reports, trial expirations, and subscription confirmations.
-  - Contains helper methods to generate HTML content for different report types.
-
-- **Database Migrations & Seeding:**
-  - Managed via TypeORM commands and scripts for schema evolution and initial data.
-
-- **Error Handling:**
-  - Customized exception class `GenieException` adds context to errors.
-  - Integration with Sentry for monitoring and capturing detailed error data.
-
-## Code Structure
-
-### Frontend Code Structure
-
-- `apps/web/src/components/jasmine`: Common UI components including modals, typography, buttons, icons, and links.
-- `apps/web/src/components/pages/auth`: Login and registration pages.
-- `apps/web/src/components/pages/settings`: Settings pages including billing and locations.
-- `apps/web/src/components/pages/Onboarding`: Onboarding flow UI components.
-
-### Backend Code Structure
-
-- `apps/api/src/email/services`: Email service implementations.
-- `apps/api/src/commons/errors`: Exception and error handling logic.
-- `apps/api/src/commons/error-handlers`: Integration with monitoring and logging.
-
-## Environment and Configuration
-
-- Environment variables control API URLs, SendGrid API key, app URLs, and other secrets.
-- `.env` files need to be configured with database credentials and integration keys.
-- Postgres setup requires creating dedicated users for different concerns (general, task runner, sales metrics), with specific SQL grants.
-- Local dev environment setup includes running database via Docker Compose and starting API + frontend concurrently.
-
-## Deployment & Development
-
-- Development servers run using Yarn workspaces commands:
-  - `yarn workspace @genie/api dev` for backend.
-  - `yarn workspace @genie/web dev` for frontend.
-  - Combined `yarn dev` for full stack.
-
-- Database migrations handled by TypeORM commands:
-  - Create: `yarn typeorm:create <MigrationName>`
-  - Generate: `yarn typeorm:generate <MigrationName>`
-  - Run: `yarn typeorm:run`
-  - Revert: `yarn typeorm:revert`
-
-- Seeding local database with initial data using `yarn cmd seed-data`.
-
-## Integration Summary
-
-- **Shopify:** Sync product variants and inventory levels.
-- **Cal.com:** Embedded scheduling calendar for booking demos and onboarding sessions inside modals.
-- **SendGrid:** Transactional and alert emails with rich HTML templates.
-
-## Mermaid Diagram
-
-```mermaid
-flowchart TD
-  subgraph Frontend
-    FE["React / Next.js Web UI"]:::frontend
-    WM["Welcome Modal (Calendar Embed)"]:::component
-    Login["Login & Register Pages"]:::component
-    Settings["Settings & Billing UI"]:::component
-  end
-
-  subgraph Backend
-    API["NestJS API Server"]:::backend
-    EmailSvc["Email Service (SendGrid)"]:::component
-    DB["PostgreSQL Database"]:::database
-    ErrorMonitor["Error Handling & Sentry"]:::component
-    Migration["TypeORM Migration & Seeding"]:::component
-  end
-
-  subgraph Integrations
-    Shopify["Shopify Inventory Integration"]:::external
-    CalCom["Cal.com - Scheduling Widget"]:::external
-  end
-
-  FE -->|"API Calls"| API
-  API -->|"Reads/Writes"| DB
-  API -->|"Sends Emails"| EmailSvc
-  EmailSvc -->|"SMTP"| SendGrid["SendGrid Service"]:::external
-  FE -->|"Embeds"| CalCom
-  API --> Shopify
-  API --> ErrorMonitor
-
-  classDef frontend fill:#783fd9,stroke:#4e2a99,color:#fff,stroke-width:2px;
-  classDef backend fill:#337ab7,stroke:#2c5a93,color:#fff,stroke-width:2px;
-  classDef database fill:#28a745,stroke:#1e7e34,color:#fff,stroke-width:2px;
-  classDef external fill:#f0ad4e,stroke:#d48806,color:#2d2d2d,stroke-width:2px;
-  classDef component fill:#563d7c,stroke:#3a2761,color:#fff,stroke-width:1.5px;
-
-  click WM "apps/web/src/components/jasmine/welcome-modal.tsx"
-  click Login "apps/web/src/components/pages/auth/login.tsx"
-  click Settings "apps/web/src/components/pages/settings/plans-and-billing-settings.tsx"
-  click EmailSvc "apps/api/src/email/services/email.service.ts"
-  click ErrorMonitor "apps/api/src/commons/error-handlers/captureException.ts"
-  click Migration "README.md"

package/docs/overview/product-intro/architecture.mdx

@@ -1,203 +0,0 @@
----
-title: 'System Architecture'
-description: 'Detailed architectural view including front-end (Next.js), back-end (NestJS), database, and integration points with key diagrams.'
----
-
-## System Architecture
-
-### 1. Purpose and Scope
-
-The System Architecture documentation provides an in-depth overview of the core backend modules and their interactions within the Genie application. This documentation explains the responsibilities and boundaries of key modules, especially those related to Shopify integration, Product Information Management (PIM), forecasting, setup/onboarding, administration, sales order processing, billing, and queue management.
-
-The primary goal is to describe how these modules fit together within the system, highlighting their roles and dependencies, to assist developers in maintaining, extending, and debugging the application.
-
----
-
-### 2. Technical Overview
-
-The backend application is architected as a modular NestJS system, organized into feature modules that encapsulate specific domains or integrations. The core modules are interconnected via shared services, repositories, and message queues (using BullMQ) to provide a scalable, event-driven architecture.
-
-Main architectural traits include:
-
-- **Modular Design:** Each domain feature such as Shopify, PIM, Forecast, Admin, Setup, Sales Order, Billing, and User Management is implemented as a NestJS module.
-- **Event-Driven Processing:** Modules use BullMQ queues and consumers for asynchronous workflows and task processing (e.g., onboarding, demand planning, webhooks).
-- **Database ORM Layer:** TypeORM is used extensively for entity management and database interaction.
-- **API Layer:** Controllers expose REST API endpoints per module.
-
-The application’s core integration is centered around the Shopify module, which interfaces with Shopify stores and pushes data asynchronously into PIM and Forecast layers, feeding into business workflows.
-
-
-### 3. Core Modules and Their Responsibilities
-
-#### Shopify Module
-- Responsible for handling Shopify API interactions, managing stores, products, orders, and webhooks.
-- Processes Shopify webhooks asynchronously via BullMQ queues.
-- Contains services for Shopify API calls (`ShopifyApiService`), product management (`ShopifyProductsService`), store management (`ShopifyStoreService`), orders (`ShopifyOrdersService`), and compliance webhooks.
-- Hosts controllers for webhook endpoints.
-- Integrates with User Management and PIM modules, reflecting multi-directional dependencies.
-
-#### Product Information Management (PIM) Module
-- Manages product entities, inventories, collections, locations, and related data.
-- Provides APIs and services for products, inventory, locations, and dashboards.
-- Handles extensive entity models such as `ProductVariantEntity`, `InventoryItemEntity`, and `CollectionEntity`.
-- Uses BullMQ queues for syncing insights and scheduled background jobs.
-- Interacts closely with Shopify (for syncing data) and Sales Order modules.
-
-#### Forecast Module
-- Provides demand planning and forecasting capabilities.
-- Uses BullMQ queues for demand plan, forecast, and historical sales data processing.
-- Includes services for workflow orchestration, scheduled tasks, and API controllers exposing demand plan functionalities.
-- Depends on PIM, Shopify, User Management, and Sales Order modules.
-
-#### Setup Module
-- Manages onboarding flows and Shopify connection setup.
-- Implements onboarding progress tracking and syncing initial Shopify data.
-- Runs onboarding jobs via BullMQ and resumes flows on module initialization.
-- Contains controllers and services specifically for Shopify connection and onboarding.
-- Includes Slack and billing integrations to support onboarding notifications and subscription handling.
-
-#### Admin Module
-- Coordinates administrative functionalities including billing, reports, client management, exporting, seeding data, and syncing.
-- Aggregates multiple submodules, providing a unified API layer for admin interactions.
-- Relies on various modules like Shopify, PIM, Purchase Order, Forecast, Supplier, and User Management.
-- Hosts multiple controllers and services for detailed admin features.
-
-#### Sales Order Module
-- Manages sales orders and their items.
-- Supports scheduled tasks and Slack service integration for notifications.
-- Depends on PIM and Shopify for data consistency.
-
-#### Billing Module
-- Manages subscription and billing workflows.
-- Integrates with Shopify and User Management modules.
-- Uses email and tracking services.
-
-#### Queue Module
-- Configures BullMQ globally with Redis connection settings.
-- Provides a secured Bull Board UI for monitoring queues.
-- Applies middleware for UI authentication.
-
-#### Cmd Module
-- Hosts CLI commands for database seeding, reset, Shopify API testing, and demo data handling.
-- Operates with PIM, User Management, Purchase Order, Shopify, and Sales Order modules.
-
-### 4. Code Structure Overview
-
-Key modules and files:
-
-- **Shopify Module** ([apps/api/src/shopify/shopify.module.ts](apps/api/src/shopify/shopify.module.ts))
-  - Contains services like `ShopifyApiService`, `ShopifyProductsService`, `ShopifyOrdersService`, and webhooks consumer.
-  - Entities: `ShopifyEventEntity`, `ShopifyStoreEntity`, `ShopifyWebhookEventEntity`.
-  - Controllers: `WebhooksController`, `ComplianceWebhooksController`.
-
-- **PIM Module** ([apps/api/src/pim/pim.module.ts](apps/api/src/pim/pim.module.ts))
-  - Entity and services rich: products, variants, inventory, locations
-  - Controllers for products, inventory, dashboards, and saved views.
-  - Background consumers and scheduled tasks.
-
-- **Forecast Module** ([apps/api/src/forecast/forecast.module.ts](apps/api/src/forecast/forecast.module.ts))
-  - Handles demand plan entities, consumers, and API controllers.
-  - Uses BullMQ queues and flows for forecast processing.
-
-- **Setup Module** ([apps/api/src/setup/setup.module.ts](apps/api/src/setup/setup.module.ts))
-  - Manages onboarding state and Shopify connection lifecycle.
-  - Job consumer `OnboardingConsumer` processes onboarding queue jobs.
-
-- **Admin Module** ([apps/api/src/admin/admin.module.ts](apps/api/src/admin/admin.module.ts))
-  - Composes various admin-related controllers and services.
-
-- **Sales Order Module** ([apps/api/src/sales-order/sales-order.module.ts](apps/api/src/sales-order/sales-order.module.ts))
-  - Sales order entity management and scheduled tasks.
-
-- **Cmd Module** ([apps/api/src/cmd/cmd.module.ts](apps/api/src/cmd/cmd.module.ts))
-  - CLI commands for demo data insertion and Shopify API testing.
-
-- **Billing Module** ([apps/api/src/billing/billing.module.ts](apps/api/src/billing/billing.module.ts))
-  - Manages billing logic and webhook processing.
-
-- **Queue Module** ([apps/api/src/queue/queue.module.ts](apps/api/src/queue/queue.module.ts))
-  - BullMQ and Bull Board setup with ExpressAdapter and UI authentication.
-
-### Example snippet from `ShopifyModule` showing imports and providers:
-
-```ts
-@Module({
-  imports: [
-    TypeOrmModule.forFeature([
-      ShopifyEventEntity,
-      ShopifyStoreEntity,
-      ShopifyWebhookEventEntity,
-      TeamEntity,
-    ]),
-    UserManagementModule,
-    EmailModule,
-    CommonsModule,
-    ConfigModule,
-    forwardRef(() => PimModule),
-    BullModule.registerQueue({
-      name: QUEUE.SHOPIFY_WEBHOOKS.name,
-    }),
-  ],
-  providers: [
-    ShopifyApiService,
-    ShopifyProductsService,
-    ShopifyStoreService,
-    ComplianceWebhooksService,
-    ShopifyOrdersService,
-    ShopifyWebhooksService,
-    ShopifyWebhooksConsumer,
-  ],
-  exports: [
-    TypeOrmModule,
-    ShopifyApiService,
-    ShopifyProductsService,
-    ShopifyStoreService,
-    ShopifyOrdersService,
-    ShopifyWebhooksService,
-  ],
-  controllers: [ComplianceWebhooksController, WebhooksController],
-})
-export class ShopifyModule {}
-```
-
-### 5. Integration and Data Flow
-
-- **Shopify Module** acts as the gateway for all Shopify interactions.
-- Shopify webhooks arrive at `WebhooksController` and are enqueued in BullMQ queues.
-- `ShopifyWebhooksConsumer` processes webhook events asynchronously, allowing decoupled downstream updates.
-- Product and inventory data sync flows pass data from Shopify to the **PIM Module**.
-- **Forecast Module** consumes product sales and demand data from **PIM** and **Sales Order Modules** to generate demand plans.
-- **Setup Module** orchestrates onboarding flows using queues, updating onboarding progress entities.
-- **Admin Module** aggregates various modules and exposes management APIs.
-- **Billing Module** coordinates billing activities, integrates with Shopify and user management.
-
-### 6. Environment & Configuration
-
-Critical environment dependencies include:
-- Redis server configuration for BullMQ queues as specified in `QueueModule`.
-- Shopify API keys and credentials managed within configuration modules.
-- Google Drive API key used for seeding demo data in commands.
-- Snowflake data warehouse credentials for analytics.
-
-### 7. Key Non-Functional Requirements
-
-- **Scalability:** Modular and queue-driven design supports horizontal scaling.
-- **Reliability:** Long-running jobs have timeout controls and multiple attempts (e.g., onboarding queue jobs).
-- **Security:** API layers enforce JWT and Admin guards; Bull Board UI is secured with middleware.
-- **Observability:** Bull Board and logging are integrated for background jobs.
-
-### 8. Troubleshooting & Monitoring
-
-- Queues can be monitored via the Bull Board UI at `/ui/queues`, protected by middleware.
-- Logs from background consumers (e.g., onboarding, insights sync) report job status and errors.
-- Module-initialization resumes onboarding flows to handle incomplete progress after restarts.
-
----
-
-For detailed developer insights, refer to module-specific files as indexed above, starting with:
-- [Shopify Module](apps/api/src/shopify/shopify.module.ts)
-- [PIM Module](apps/api/src/pim/pim.module.ts)
-- [Forecast Module](apps/api/src/forecast/forecast.module.ts)
-- [Setup Module](apps/api/src/setup/setup.module.ts)
-
-This architecture overview should equip developers to navigate and evolve the system effectively.