@clidey/dory 0.1.0

package/docs/configuration/installation-setup/env-vars.mdx

@@ -0,0 +1,198 @@
+---
+title: 'Environment Variables & Configuration'
+description: 'Details of required environment variables, example values, and configuration across dev, staging, and prod.'
+---
+
+# Environment Variables & Configuration
+
+## Purpose and Scope
+
+This document provides a detailed technical overview of the environment variables and configuration management within the Genie application, specifically focusing on how team, shop, and general settings are handled. It covers the backend service responsible for settings management, the structure of configuration data, integration points with external services (notably Shopify), and the interaction with frontend components for settings updates.
+
+The scope is limited to the environment and configuration aspects related to team settings, insights, shop configurations, and business details within the Genie platform. It clarifies the flow and storage of configuration data, including environment-dependent settings like time zone and currency.
+
+## Technical Overview
+
+The SettingsService in the backend manages the core configuration and environment-specific settings at the team level. It acts as the interface to stored data for team general settings, insights settings, and shop settings, primarily through the `TeamEntity` persisted in the database.
+
+### System Boundaries and Architecture
+
+- **Backend:** The `SettingsService` uses TypeORM repository to read and update the `TeamEntity` database representation.
+- **Frontend:** React-based web UI components fetch and mutate settings by invoking API endpoints which under the hood use `SettingsService`.
+- **External API Integration:** Shopify data such as shop currency and time zone are imported into the team settings and validated.
+
+### Key Technologies and Patterns
+
+- **NestJS** with the `@Injectable()` pattern for service injection.
+- **TypeORM** to interface with PostgreSQL or relational DB for `TeamEntity` storage.
+- **Data Transfer Objects (DTOs)** encapsulate settings data structures for transmission between layers.
+- **React Query** in the frontend for data fetching and mutation.
+
+### Configuration Data Flow
+
+1. Shopify data (currency, time zone) imported via webhooks or manual sync.
+2. Stored persistently in the `TeamEntity` fields (`currency`, `timeZone`).
+3. General team business settings stored as JSON in `generalSettings` in the same entity.
+4. Insights settings regarding inventory grading, sales periods, etc., stored via dedicated columns.
+5. Frontend reads/writes through APIs that delegate to `SettingsService` methods.
+
+```mermaid
+flowchart TD
+  subgraph Backend
+    SS["SettingsService"]:::service
+    TE["TeamEntity (DB Model)"]:::database
+  end
+
+  subgraph Frontend
+    GU["GeneralSettings UI Component"]:::frontend
+  end
+
+  subgraph Shopify
+    SH["Shopify API / Webhook"]:::external
+  end
+
+  GU -->|"API calls for get/update settings"| SS
+  SS -->|"Read/Write settings"| TE
+  SH -->|"Push shop data (currency/timezone)"| SS
+
+  classDef service fill:#1976d2,color:#fff,stroke:#0b3d91,stroke-width:1px;
+  classDef database fill:#795548,color:#fff,stroke:#5d4037,stroke-width:1px;
+  classDef frontend fill:#388e3c,color:#fff,stroke:#2e7d32,stroke-width:1px;
+  classDef external fill:#fbc02d,color:#000,stroke:#f9a825,stroke-width:1px;
+
+  click SS "apps/api/src/user-management/services/settings.service.ts"
+  click TE "apps/api/src/user-management/entities/team.entity.ts"
+  click GU "apps/web/src/components/pages/settings/general-settings.tsx"
+```
+
+## Core Concepts and Responsibilities
+
+### Team Settings
+
+- Represented primarily by `TeamEntity`.
+- Contains both simple scalar settings (e.g., `name`, `currency`, `timeZone`) and complex JSON blobs (e.g., `generalSettings`, `stockLevelsSettings`).
+- Manages onboarding, enabled state, and disables reasons.
+
+### Insights Settings
+
+- Includes inventory grading strategy and threshold levels.
+- Important validation: `InventoryItemGradingStrategy.SalesFrequency` is explicitly unsupported and raises exceptions.
+
+### Shopify Integration
+
+- The Shopify shop data (e.g., currency, time zone) is imported and validated. Time zone validation is done via `isValidTimeZone`.
+- Defaults to `Etc/UTC` if invalid or missing.
+
+### Error Handling
+
+- Uses `GenieException` to encapsulate errors with context, such as team ID or invalid states.
+
+### Ownership
+
+- Maintained by the user management backend module.
+- Settings changes propagate via API and frontend UI.
+
+### Non-functional Requirements
+
+- Time zone and currency are critical for correct operation and must always be valid.
+- The system must guard against unsupported grading strategies.
+- Updates must be atomic and error-resilient.
+
+## Code Structure
+
+| File/Folder                      | Role Description                                       |
+|---------------------------------|--------------------------------------------------------|
+| `apps/api/src/user-management/services/settings.service.ts` | Core backend logic for loading and updating team settings. |
+| `apps/api/src/user-management/entities/team.entity.ts`      | Database entity modeling the team configuration persistently. |
+| `apps/web/src/components/pages/settings/general-settings.tsx` | Frontend UI component for managing general team and shop settings. |
+| `apps/web/src/api/resources/settings`                         | API layer exports for settings-related calls. |
+
+### Key Code Snippet from `SettingsService`
+
+```ts
+async updateTeamGeneralSettings(teamId: string, settings: TeamGeneralSettingsDto) {
+  const { businessName: name, ...generalSettings } = settings;
+  try {
+    await this.teamRepository.update(teamId, {
+      name,
+      generalSettings,
+    });
+  } catch (error) {
+    throw new GenieException("Failed to update team general settings", {
+      error,
+      teamId,
+      settings,
+    });
+  }
+}
+```
+
+This method extracts the business name to the `name` column and stores other general settings in the JSON field `generalSettings`.
+
+## API and Interfaces
+
+### Key Methods in `SettingsService`
+
+| Method                        | Description                                         | Input                          | Output                           |
+|-------------------------------|----------------------------------------------------|---------------------------------|----------------------------------|
+| `getTeamGeneralSettings`      | Retrieves general team settings.                    | `teamId: string`                | `TeamGeneralSettingsDto`          |
+| `updateTeamGeneralSettings`   | Updates general team settings.                      | `teamId: string`, `TeamGeneralSettingsDto` | void                             |
+| `getTeamInsightsSettings`     | Retrieves team insights settings.                   | `teamId: string`                | `InsightsSettingsDto`             |
+| `updateTeamInsightsSettings`  | Updates insights settings including grading configs.| `teamId: string`, `InsightsSettingsDto` | void                             |
+| `getShopSettings`             | Retrieves the shop-level config like currency, timezone.| `teamId: string`              | `GetShopSettingsResponseDto`      |
+| `saveShopSettings`            | Saves Shopify shop currency and time zone settings.| `teamId: string`, Optional Shopify webhook payload | void                     |
+
+### Error Conditions
+
+- Unsupported inventory grading strategies throw a `GenieException`.
+- Any update failure results in a thrown exception with contextual info including the failing settings and team ID.
+
+### Frontend Integration
+
+- Uses React Query hooks such as `useGetTeamGeneralSettingsQuery` and mutation hooks `useUpdateTeamGeneralSettingsMutation`.
+- UI includes controlled forms managing business details and Shopify sync status.
+
+## Environment & Configuration
+
+### Team Configuration Properties
+
+| Setting                              | Type                     | Description                                               | Default / Validation                  |
+|------------------------------------|--------------------------|-----------------------------------------------------------|--------------------------------------|
+| `name`                             | string                   | Business name of the team.                                 | Nullable, stored in `name` column.   |
+| `generalSettings`                  | JSON object              | Business address, VAT number, contact info, etc.          | Stored in JSON column.                |
+| `currency`                        | string                   | Team's accounting/display currency.                       | From Shopify, nullable.               |
+| `timeZone`                       | string                   | IANA time zone identifier for the team/shop.             | Default: `Etc/UTC`, validated against timezone list. |
+| `averageDailySalesPeriodDaysSetting` | integer Enum (7,30,60,90,180) | Period for sales averaging in analysis.                   | Default: 30                          |
+| `inventoryItemGradingPeriodDaysSetting` | integer Enum             | Period over which inventory grading is calculated.       | Default: 30                          |
+| `inventoryItemGradingStrategySetting` | Enum `InventoryItemGradingStrategy` | The strategy for inventory grading (e.g., SalesRevenue). | Default: `SalesRevenue`, `SalesFrequency` disallowed. |
+| `inventoryItemGradingLevelAThresholdSetting` | integer              | Threshold % for grading level A.                           | Default: 80                          |
+| `inventoryItemGradingLevelBThresholdSetting` | integer              | Threshold % for grading level B.                           | Default: 15                          |
+| `inventoryItemGradingLevelCThresholdSetting` | integer              | Threshold % for grading level C.                           | Default: 5                           |
+| `stockLevelsSettings`             | JSON object              | Settings for stock buffer, lead time, reorder frequency. | Defaults to leadTime=30, stockBuffer=10, reorderFrequency=EveryTwoMonths |
+
+### Shopify Environment Integration
+
+- Shopify shop data such as currency and IANA time zone are pulled from webhook payloads or API calls.
+- Time zone validation is performed by `isValidTimeZone` utility.
+- If invalid or missing, time zone falls back to `Etc/UTC`.
+
+### Local Development and Environment Setup
+
+- Environment variables managing database and Shopify credentials are outside the scope of this document.
+- Configuration for environment management likely handled in `ConfigModule` and `ConfigService` (referenced exports), but specific environment variables are not detailed here.
+
+## Testing, Monitoring, and Deployment
+
+- Test details for settings service and UI are unspecified.
+- Error conditions raise `GenieException` logged with context for debugging.
+- Frontend mutation success triggers user notifications.
+
+## Troubleshooting & Known Issues
+
+- Attempting to use the unsupported `SalesFrequency` grading strategy results in explicit exceptions.
+- Manual Shopify sync on the frontend has race-condition warnings (HTTP 409) if multiple syncs are attempted simultaneously.
+
+
+---
+
+This document is aimed at backend and frontend developers managing and extending the Genie platform's environment and team settings system. It should serve as a guide for understanding configuration storage, validation, API design, and usage patterns for consistent, reliable environment configuration handling.

package/docs/configuration/installation-setup/installation.mdx

@@ -0,0 +1,127 @@
+---
+title: 'Installation & Setup Guide'
+description: 'Steps to clone, install dependencies, run the application, and prepare the database.'
+---
+
+## Installation & Setup Guide
+
+### Overview
+This guide covers the installation and setup of the Genie application backend and frontend components essential for onboarding, data synchronization, and product variant management.
+
+Genie integrates tightly with Shopify stores to synchronize product, inventory, bundle, and purchase order data. It handles onboarding workflows, monitors product variant counts, and manages webhooks for real-time data sync.
+
+### Components Involved
+- **Onboarding Service**: Manages user onboarding progress, data synchronization, and notification workflows.
+- **Shopify Webhooks Service**: Registers and manages Shopify webhook subscriptions for data updates.
+- **Database Views and Migrations**: Defines database schemas, especially for inventory data and product variant tracking.
+- **Frontend Modals and UI Components**: Provide user feedback and guides, such as store size warnings when variant count is large.
+
+---
+
+## Backend Installation & Setup
+
+### 1. Database Setup and Migrations
+
+Genie uses a PostgreSQL database with TypeORM. Core migrations include:
+
+- **Initial Database Schema**: Creates tables for users, teams, products, product variants, purchase orders, and related entities. [Initialise Migration](apps/api/src/migrations/db/1688040345407-Initialise.ts)
+- **Inventory Item View**: Creates a SQL view consolidating product and variant data for inventory management, including sales and stock metrics. This view gets updated with new columns like `isNewProduct` for enhanced data insights. [Inventory View Migration](apps/api/src/migrations/db/1692960155848-add-is-new-product-to-inventory-item-view.ts)
+- **Product Variant Location & Shopify Inventory Item ID**: Adds location-based inventory tracking and links variants to Shopify InventoryItem IDs. [Variant Location Migration](apps/api/src/migrations/db/1701958615964-add-product-variant-location-and-shopify-inventory-item-id.ts)
+
+Run migrations after database setup to ensure schema is current.
+
+### 2. Onboarding Service Setup
+
+The `OnboardingService` handles setup progress and sync workflows:
+
+- Initializes onboarding progress record for a new team.
+- Verifies product variant count does not exceed limits and disables teams if necessary.
+- Manages multi-step onboarding including insight settings, grading, suppliers, purchase order import, bundle mapping, and final completion.
+- Tracks progress and triggers background data sync jobs using BullMQ queues (`QUEUE.ONBOARDING`).
+
+Key files and location:
+- Service: `apps/api/src/setup/services/onboarding.service.ts`
+- Controller: `apps/api/src/setup/controllers/onboarding.controller.ts`
+- Module: `apps/api/src/setup/setup.module.ts`
+
+**Important:** On module initialization, the onboarding service resumes incomplete onboarding flows for all teams to ensure no data sync or onboarding step is left hanging after a server restart.
+
+### 3. Shopify Webhooks
+
+Webhook registration is essential for real-time syncing of Shopify events such as:
+- Products and variants create, update, delete
+- Locations activate, create, update, delete
+- Inventory levels update and disconnect
+- Collections create, update, delete
+- Orders create, update, cancel, delete
+- Shop updates
+
+The `WebhooksInsightsSyncService` manages webhook registration and event processing pipelines. It includes:
+- Registration and unregistration of webhooks for active/inactive teams
+- Processing batched Shopify events through a set of ordered pipes for syncing data to database
+- Retry mechanism for failed webhook registrations
+
+Files of interest:
+- `apps/api/src/pim/services/webhooks-insights-sync.service.ts`
+
+### 4. Billing & Subscription
+
+The `MantleService` integrates billing, subscription state handling, and plan assignments:
+- Identifies customers in the billing system and assigns plans
+- Handles trial expirations, subscription cancellations, activations
+- Reacts to install/reinstall/uninstall Shopify app webhooks
+
+File:
+- `apps/api/src/billing/services/mantle.service.ts`
+
+---
+
+## Frontend Setup
+
+### 1. Store Size Warning Modal
+
+To alert users whose Shopify store has a very high number of product variants (exceeding `MAX_ALLOWED_PRODUCT_VARIANTS_COUNT`), Genie shows a modal prompting a discovery call before proceeding with onboarding.
+
+- The modal displays the exact variant count fetched by querying the API.
+- Includes an embedded HubSpot calendar iframe to book time with the Genie team.
+
+Relevant file:
+- `apps/web/src/components/pages/Onboarding/store-too-large-modal.tsx`
+
+### 2. Sync Product Variants Manually
+
+Users can manually refresh Shopify store sync from settings:
+
+- The "Shopify Store Data" card lets users trigger manual sync to refresh product variants.
+- Sync status and feedback notifications are provided.
+
+Relevant file:
+- `apps/web/src/components/pages/settings/general-settings.tsx`
+
+---
+
+## Running Genie Locally
+
+1. **Set up all environment variables** as per your environment. Refer to `Environment Variables & Configuration` documentation for required keys.
+2. **Initialize and migrate the database** using TypeORM migrations.
+3. **Start backend services**, ensuring BullMQ queues and Redis are operational for job processing.
+4. **Start the frontend web server** using Next.js; the onboarding modals and syncing features will be accessible.
+
+---
+
+## Summary
+This installation and setup guide provides technical details for initializing Genie’s backend services, database, webhooks integration with Shopify, billing system connectivity, and frontend user experience components necessary for a seamless onboarding and store data synchronization process.
+
+Developers are encouraged to familiarize themselves with the onboarding service flows and webhook synchronization pipelines to understand the end-to-end data flow from Shopify to Genie’s internal representations and UI triggers.
+
+For deeper understanding, review:
+- [Onboarding Service Implementation](apps/api/src/setup/services/onboarding.service.ts)
+- [Webhook Synchronization Service](apps/api/src/pim/services/webhooks-insights-sync.service.ts)
+- [General Settings Sync Component](apps/web/src/components/pages/settings/general-settings.tsx)
+- [Store Too Large Modal](apps/web/src/components/pages/Onboarding/store-too-large-modal.tsx)
+
+Regularly check migration files to keep the schema updated and refer to the workflow queues for processing status.
+
+---
+
+Please refer to the respective internal modules and service implementations for detailed operational logic and error handling behaviors.

package/docs/dory.json

@@ -0,0 +1,162 @@
+{
+  "name": "Docucod",
+  "colors": {
+    "primary": "#60A5FA",
+    "light": "#60A5FA",
+    "dark": "#1E3A8A"
+  },
+  "favicon": "/favicon.svg",
+  "styling": {
+    "eyebrows": "breadcrumbs",
+    "codeblocks": "dark"
+  },
+  "icons": {
+    "library": "fontawesome"
+  },
+  "fonts": {
+    "family": "Montserrat",
+    "source": "https://fonts.gstatic.com/s/googlesansflex/v5/t5sJIQcYNIWbFgDgAAzZ34auoVyXkJCOvp3SFWJbN5hF8Ju1x6sKCyp0l9sI40swNJwGpVd4AZzz0v6lJ4qFXNZhGjLvDSkV4USKMo6qQzwliVdHAy9jxTDHg_ugnAakpwGc-cxgUqDCIUI.woff2",
+    "format": "woff2"
+  },
+  "background": {
+    "decoration": "gradient"
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Overview",
+        "groups": [
+          {
+            "group": "Developer Overview",
+            "pages": [
+              "overview/developer-overview/dev-architecture"
+            ]
+          },
+          {
+            "group": "Product Intro",
+            "pages": [
+              "overview/product-intro/app-overview",
+              "overview/product-intro/architecture",
+              "overview/product-intro/core-concepts"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Configuration",
+        "groups": [
+          {
+            "group": "App Settings",
+            "pages": [
+              "configuration/app-settings/feature-flags",
+              "configuration/app-settings/user-settings"
+            ]
+          },
+          {
+            "group": "Installation Setup",
+            "pages": [
+              "configuration/installation-setup/env-vars",
+              "configuration/installation-setup/installation"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Usage",
+        "groups": [
+          {
+            "group": "API Usage",
+            "pages": [
+              "usage/api-usage/api-inventory",
+              "usage/api-usage/api-products",
+              "usage/api-usage/api-purchase-orders",
+              "usage/api-usage/api-reports",
+              "usage/api-usage/api-suppliers",
+              "usage/api-usage/api-user-management"
+            ]
+          },
+          {
+            "group": "UI Workflows",
+            "pages": [
+              "usage/ui-workflows/bundles",
+              "usage/ui-workflows/demand-planning",
+              "usage/ui-workflows/favorites",
+              "usage/ui-workflows/inventory-management",
+              "usage/ui-workflows/onboarding",
+              "usage/ui-workflows/purchase-orders",
+              "usage/ui-workflows/reports"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Integrations",
+        "groups": [
+          {
+            "group": "Analytics Monitoring",
+            "pages": [
+              "integrations/analytics-monitoring/error-tracking",
+              "integrations/analytics-monitoring/notifications",
+              "integrations/analytics-monitoring/user-analytics"
+            ]
+          },
+          {
+            "group": "Shopify Integration",
+            "pages": [
+              "integrations/shopify-integration/shopify-setup",
+              "integrations/shopify-integration/shopify-webhooks"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Platform Admin",
+        "groups": [
+          {
+            "group": "Billing Subscriptions",
+            "pages": [
+              "platform-admin/billing-subscriptions/billing"
+            ]
+          },
+          {
+            "group": "System Maintenance",
+            "pages": [
+              "platform-admin/system-maintenance/db-migrations",
+              "platform-admin/system-maintenance/health-monitoring",
+              "platform-admin/system-maintenance/queue-management"
+            ]
+          },
+          {
+            "group": "User Team Management",
+            "pages": [
+              "platform-admin/user-team-management/teams",
+              "platform-admin/user-team-management/users"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Support",
+        "groups": [
+          {
+            "group": "Legal",
+            "pages": [
+              "support/legal/dependency-analysis",
+              "support/legal/privacy-terms"
+            ]
+          },
+          {
+            "group": "Troubleshooting",
+            "pages": [
+              "support/troubleshooting/common-issues"
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "logo": {
+    "light": "./logo/logo.png",
+    "dark": "./logo/logo.png"
+  }
+}