@clidey/dory 0.1.0 → 0.3.0

package/docs/platform-admin/user-team-management/users.mdx

@@ -1,185 +0,0 @@
----
-title: 'User Management'
-description: 'User lifecycle management including invitations, authentication, and roles.'
----
-
-## User Management Module
-
-### 1. Purpose and Scope
-
-The User Management module is a core system component responsible for handling all aspects of user and team management, authentication, authorization, and user context within the Genie application. It solves key problems such as user identity management, secure authentication, team membership and permissions, user notifications, and related settings management.
-
-**System Boundaries:**
-- Handles all user-related data and interactions.
-- Manages teams and membership invitations.
-- Authenticates users using JWT-based strategies.
-- Integrates with email module for communication.
-- Supports context-aware services to provide customized user experiences.
-
-This module functions as a foundational building block that other application modules depend on for user and team context information, authentication enforcement, and user notifications.
-
-### 2. Technical Overview
-
-The `UserManagementModule` is implemented using the NestJS framework and follows a modular pattern integrating with various NestJS features and other system modules. This module utilizes TypeORM for ORM data access, Passport.js for authentication strategies, and strongly typed DTOs validated via Zod schemas.
-
-#### Architecture Diagram
-```mermaid
-flowchart TD
-  subgraph "User Management Module"
-    UM["UserManagementModule"]:::service
-    AuthS["AuthService"]:::service
-    JwtStrat["JwtStrategy"]:::service
-    TeamsS["TeamsService"]:::service
-    SettingsS["SettingsService"]:::service
-    ContextS["ContextService"]:::service
-
-    AuthC["AuthController"]:::controller
-    TeamsC["TeamsController"]:::controller
-    UserContextC["UserContextController"]:::controller
-
-    UM -->|"provides"| AuthS
-    UM -->|"provides"| JwtStrat
-    UM -->|"provides"| TeamsS
-    UM -->|"provides"| SettingsS
-    UM -->|"provides"| ContextS
-
-    UM -->|"exposes"| AuthC
-    UM -->|"exposes"| TeamsC
-    UM -->|"exposes"| UserContextC
-
-    UM -->|"imports"| EmailModule["EmailModule"]:::module
-    UM -->|"imports"| TypeOrmFeature["TypeOrmModule (UserEntity, TeamEntity, MemberInvitationEntity)"]:::module
-    UM -->|"imports"| PassportModule["PassportModule (JWT strategy)"]:::module
-    UM -->|"imports"| CommonsModule["CommonsModule"]:::module
-    UM -->|"imports"| BillingModule["BillingModule"]:::module
-    UM -->|"imports"| TrackingModule["TrackingModule"]:::module
-  end
-
-  classDef service fill:#91caff,stroke:#004080,color:#000;
-  classDef controller fill:#ffd9a8,stroke:#ff9a00,color:#000;
-  classDef module fill:#dcdcdc,stroke:#666,color:#000,stroke-dasharray: 2 2;
-
-  click UM "apps/api/src/user-management/user-management.module.ts"
-  click AuthS "apps/api/src/user-management/services/auth.service.ts"
-  click TeamsS "apps/api/src/user-management/services/teams.service.ts"
-  click SettingsS "apps/api/src/user-management/services/settings.service.ts"
-  click ContextS "apps/api/src/user-management/services/context.service.ts"
-  click AuthC "apps/api/src/user-management/controllers/auth.controller.ts"
-  click TeamsC "apps/api/src/user-management/controllers/teams.controller.ts"
-  click UserContextC "apps/api/src/user-management/controllers/user-context.controller.ts"
-```
-
-### 3. Core Concepts and Responsibilities
-
-- **UserEntity**: Represents the user with fields such as email, role, team relation, login codes, and activation status.
-- **TeamEntity**: Represents user teams; users may belong to a single team.
-- **MemberInvitationEntity**: Manages invitations for new team members.
-- **Authentication**: Uses JWT strategy with Passport.js ensuring stateless secure authentication.
-- **TeamsService**: Manages team-related functions including fetching users, notifications, and team settings.
-- **ContextService**: Provides enriched context about the user and team for services requiring user-specific data.
-- **SettingsService**: Stores and manages user/team-specific application settings.
-- **Notifications**: Users can get and update their notifications state via the UserContextController.
-
-#### Key Design Decisions
-
-- **Use of JWT Authentication**: Facilitates scalable, stateless user authentication handled via Passport.js integration.
-- **Modular Design**: Separates concerns clearly between authentication, teams, user context, and settings management.
-- **TypeORM Entities**: Enables straightforward mapping between the database and application domain.
-- **ForwardRef Usage**: To avoid circular dependencies with billing and tracking modules.
-
-#### Ownership & Maintenance
-
-- Maintained by the User Management team.
-- Errors and exceptional cases throw `GenieException` with well-defined codes.
-- Logs and errors are captured through a shared logging strategy (assumed from shared commons).
-
-#### Non-Functional Requirements (NFRs)
-
-- **Security**: Protects data using JWT and enforces role-based access.
-- **Scalability**: Designed for multi-team, multi-user environments.
-- **Reliability**: Handles user status (e.g., deactivation) and supports transactional updates.
-
-### 4. Code Structure
-
-| File | Description |
-| --- | --- |
-| [user-management.module.ts](apps/api/src/user-management/user-management.module.ts) | Module declaration and dependency injection setup. |
-| [index.ts](apps/api/src/user-management/index.ts) | Module export entry point. |
-| [user.entity.ts](apps/api/src/user-management/entities/user.entity.ts) | User entity ORM definition. |
-| [auth.service.ts](apps/api/src/user-management/services/auth.service.ts) | Handles authentication logic (login, JWT validation).
-| [teams.service.ts](apps/api/src/user-management/services/teams.service.ts) | Handles team data, notifications, invitations.
-| [settings.service.ts](apps/api/src/user-management/services/settings.service.ts) | Manages user and team settings.
-| [context.service.ts](apps/api/src/user-management/services/context.service.ts) | Provides user context data.
-| [auth.controller.ts](apps/api/src/user-management/controllers/auth.controller.ts) | Exposes authentication REST APIs.
-| [teams.controller.ts](apps/api/src/user-management/controllers/teams.controller.ts) | Manages teams-related endpoints.
-| [user-context.controller.ts](apps/api/src/user-management/controllers/user-context.controller.ts) | Manages user context and notifications endpoints.
-
-#### Example: User Entity Snippet
-```ts
-@Entity("user")
-export class UserEntity extends BaseEntity {
-  @Column({ unique: true })
-  email!: string;
-
-  @Column({ type: "enum", enum: UserRole, default: UserRole.Member })
-  role!: UserRole;
-
-  @Index()
-  @Column({ type: "uuid", nullable: true })
-  teamId?: string | null;
-
-  @ManyToOne(() => TeamEntity, (team) => team.users, { onDelete: "CASCADE" })
-  team?: Relation<TeamEntity>;
-
-  @Column({ type: "timestamp", nullable: true })
-  deactivatedAt?: Date | null;
-
-  isSupport() {
-    return (
-      this.email.startsWith("support+") && this.email.endsWith("@getgenie.io")
-    );
-  }
-}
-```
-
-### 5. API and Interfaces
-
-#### User Context APIs (UserContextController)
-- **GET /user-context**: Retrieves detailed user context, including team data.
-- **GET /user-context/notifications**: Gets user notification settings for their team.
-- **PUT /user-context/notifications**: Updates user notification preferences.
-
-#### Teams APIs (TeamsController)
-- Manages CRUD and retrieval actions related to teams and invitations. (Details not exposed in the provided context.)
-
-#### Authentication APIs (AuthController)
-- Manages login, JWT token issuance, and verification. (Details not exposed in the provided context.)
-
-#### Validation
-- Uses Zod schemas for request input validation.
-- Throws `GenieException` if user is not part of a team or for other validation failures.
-
-#### Authorization
-- Circuits ensure users are part of a team before proceeding.
-- Role-based checks are embedded in service logic where applicable.
-
-### 6. Environment & Configuration
-
-- The module depends on JWT configuration managed at the PassportModule level.
-- No explicit environment variables shown for the User Management module in the context.
-- Database integration relies on TypeORM with entities: UserEntity, TeamEntity, MemberInvitationEntity.
-
-### 7. Testing, Monitoring, and Deployment
-
-- No explicit testing instructions provided.
-- Logging and error monitoring are done via shared utilities (e.g., GenieException, Logger).
-- The module is included in the main application module with global guards for JWT and admin access.
-
-### 8. Troubleshooting & Known Issues
-
-- **User Not in Team Exception:** Most service methods throw a `GenieException` if a user lacks a teamId.
-- No other specific issues or runbooks described.
-
----
-
-This documentation serves as a comprehensive technical reference for in-house developers working on the User Management module, highlighting implementation details, integration points, and usage patterns.

package/docs/support/legal/dependency-analysis.mdx

@@ -1,132 +0,0 @@
----
-title: Project Third‑Party Software Audit
-description: "Comprehensive breakdown of direct & transitive dependencies, licenses, risks, and compliance overview"
----
-
-# 🛡️ Project Overview
-
-**Monorepo Name**: `@genie/app`  
-**Purpose**: A multi‑package TypeScript monorepo powering backend APIs (`@genie/api`), shared utilities (`@genie/shared`), ESLint & TypeScript config packages, and a Next.js frontend (`@genie/web`). Designed for data processing, analytics, file handling, and integrations (Shopify, AWS, Slack, SendGrid, Sentry), with a strong focus on code quality (Lint, Vitest, Tailwind, Zod, etc.).
-
-**License**: All internal workspaces are **UNLICENSED**—no open‑source licensing for in‑house packages.  
-**SBOM Integration**: Recommend generating an SBOM using tools like *Syft* or *CycloneDX* (e.g., `syft packages -o cyclonedx` in CI) to formalize a bill of materials.
-
----
-
-## 📦 Dependency Breakdown
-
-Below is a combined view of direct runtime dependencies across main packages (`@genie/api`, `@genie/web`, `@genie/shared`). Dev‑only tools (ESLint, Vitest, Tailwind, etc.) are listed separately.
-
-| Package Name                    | Version     | License       | Source         | Purpose                            | Notes                                 |
-|----------------------------------|-------------|---------------|----------------|-------------------------------------|----------------------------------------|
-| `date‑fns`                      | ^2.29.3     | MIT           | npm            | Date handling                      | Lightweight, permissive license       |
-| `zod`                           | ^3.21.4     | MIT           | npm            | Runtime validation & schema parsing| Safe and permissive                   |
-| `@aws-sdk/client‑s3`           | ^3.363.0    | Apache‑2.0    | npm (AWS SDK)  | S3 integration                     | Common permissive license             |
-| `@aws-sdk/s3‑request‑presigner`| ^3.363.0    | Apache‑2.0    | npm (AWS SDK)  | S3 signed URLs                     | Same as above                         |
-| `@bull‑board/*`                 | ^6.6.2      | MIT           | npm            | Bull/MQ admin UI                   | MIT licensed                          |
-| `@bull‑mq`                     | ^5.26.2     | MIT           | npm            | Queue management                   | MIT                                  |
-| `@genie/shared`                | ^1.0.0      | UNLICENSED    | local workspace| Shared utility code                | In‑house utilities                    |
-| `@heymantle/client`            | ^1.1.30     | MIT (assumed) | npm            | HeyMantle SDK                      | Confirm license; likely MIT           |
-| `@hubspot/api‑client`          | ^11.1.0     | Apache‑2.0    | npm            | HubSpot API integration            | Permissive                            |
-| `@nestjs/*`                    | various     | MIT           | npm            | NestJS framework                   | MIT                                   |
-| `@segment/analytics‑node`      | ^1.0.0      | MIT           | npm            | Analytics tracking                 | MIT                                   |
-| `@sendgrid/mail`               | ^7.7.0      | MIT           | npm            | Email delivery                     | MIT                                   |
-| `@sentry/*`                    | ^8.38.0     | MIT           | npm            | Error & performance monitoring     | MIT                                   |
-| `@shopify/shopify‑api`         | ^11.6.0     | MIT           | npm            | Shopify API integration            | MIT                                   |
-| `@slack/web‑api`               | ^6.9.0      | MIT           | npm            | Slack integration                  | MIT                                   |
-| `big.js`                        | ^6.2.2      | MIT           | npm            | Arbitrary‑precision decimals       | MIT                                   |
-| `bullmq`                        | ^5.26.2     | MIT           | npm            | Message queue                      | MIT                                   |
-| `class‑transformer`, `class‑validator` | ^0.5.1, ^0.14.1 | MIT | npm  | Validation / transformation      | MIT                                   |
-| `compression`, `cookie‑parser`, `csv‑parser`/**‑stringify**/**‑writer** | various | MIT | npm | HTTP & CSV handling  | MIT           |
-| `crypto`                        | 1.0.1       | Node.js core  | Node.js        | Core crypto                        | Included in Node                       |
-| `dotenv`                        | ^16.4.5     | BSD‑2         | npm            | Env var loader                     | BSD‑2 license                         |
-| `graphql‑request`              | ^6.1.0      | MIT           | npm            | GraphQL client                     | MIT                                   |
-| `jspdf` + `jspdf‑autotable`    | ^2.5.2, ^3.8.4 | MIT       | npm            | PDF generation                     | MIT                                   |
-| `lodash`                        | ^4.17.21    | MIT           | npm            | Utility functions                  | MIT                                   |
-| `multer`                        | 1.4.5‑lts.1 | MIT           | npm            | File upload middleware             | MIT                                   |
-| `nest‑commander`, `nestjs‑cls`, `passport`, `passport‑jwt` | various | MIT | npm | CLI, context, auth       | MIT |
-| `pg`                            | ^8.13.1     | MIT           | npm            | PostgreSQL driver                  | MIT                                   |
-| `rxjs`                          | ^7.8.1      | Apache‑2.0    | npm            | Reactive programming               | Apache‑2.0                            |
-| `slugify`                       | ^1.6.6      | MIT           | npm            | URL‑friendly strings               | MIT                                   |
-| `snowflake‑sdk`                 | ^1.15.0     | MIT           | npm            | Snowflake DB integration           | MIT                                   |
-| `typeorm`                       | ^0.3.20     | MIT           | npm            | ORM for relational DBs             | MIT                                   |
-| `uuid`                          | ^11.0.3     | MIT           | npm            | Unique IDs generating              | MIT                                   |
-| `winston`                       | ^3.17.0     | MIT           | npm            | Logging                            | MIT                                   |
-
-### 🚧 Development / Tooling
-
-All dev‑dependencies are MIT‑licensed or similarly permissive (ESLint, Vitest, Tailwind, Prettier, Husky, Lerna, etc.), posing no licensing risk for production. They’re used for linting, formatting, typing, testing, and build orchestration.
-
----
-
-## 📝 License Overview & Obligations
-
-- **Dominant Licenses**:  
-  - **MIT** – All runtime and dev dependencies (≈90%); highly permissive.  
-  - **Apache 2.0** – AWS SDK, RxJS, HubSpot; includes patent clause obligations and **NOTICE** file retention.  
-  - **BSD‑2** – `dotenv` under BSD‑2; similarly permissive.
-
-- **Internal UNLICENSED workspaces**: No downstream obligations, but proprietary—ensure internal ownership and documentation.
-
-### ✅ Compliance Responsibilities
-
-- Include proper **copyright + license headers** for MIT/BSD/Apache.
-- Retain Apache **NOTICE** files (e.g., AWS SDKs, RxJS).
-- No copyleft or viral licenses detected—no GPL/AGPL risk.
-
----
-
-## ⚠️ Legal Flags & Risk Assessment
-
-| Risk Category         | Description                                                                           | Impact & Mitigation                                      |
-|----------------------|----------------------------------------------------------------------------------------|----------------------------------------------------------|
-| **Copyleft Risk**     | No GPL, AGPL, LGPL packages in the dependency tree.                                  | ✅ Low risk                                             |
-| **Patent Term Risk**  | Apache 2.0 license includes patent grants & retaliation clauses.                      | 🛡️ Acceptable if NOTICE files preserved               |
-| **Commercial SDKs**   | AWS, Shopify, HubSpot, Slack, SendGrid—all under permissive licenses.                 | ✅ Good, but check vendor-specific Terms of Service     |
-
----
-
-## 📦 Software Bill of Materials (SBOM)
-
-We recommend using tools in CI such as:
-
-```sh
-# generates CycloneDX SBOM
-syft packages -o cyclonedx > sbom.xml
-
-# or SPDX format for compliance scanning
-syft packages -o spdx-json > sbom.json
-````
-
-*SBOM files should be versioned and reviewed regularly.*
-
----
-
-## 🔄 Update & Audit Practices
-
-* **Regular scans**: Run `npm audit` or `yarn audit`; combine with license scanner (e.g., `license-checker`).
-* **CI gating**: Block builds on new copyleft or high‑risk license additions.
-* **Vendor SDK review**: Periodically review versions and associated ToS changes (e.g., Shopify API terms).
-
----
-
-## ✅ Summary & Compliance Statement
-
-* **License posture**: Clean, permissive—no viral copyleft licenses used.
-* **Risk level**: Low—standard obligations for MIT and Apache.
-* **Next steps**:
-
-  1. Generate SBOM and track as part of release artifacts.
-  2. Automate license header checks and documentation of NOTICE files.
-  3. Document internal policies for SDK term compliance (Shopify, AWS, Slack, HubSpot, SendGrid).
-
----
-
-## 🔍 Appendix: Key Dependencies
-
-* **`@genie/shared`**: Internal TS utilities
-* **`@aws-sdk/*`**: S3 file storage integrations
-* **`@shopify/shopify-api`**: E‑commerce platform integration
-* **`typeorm`, `pg`, `bullmq`**: Data persistence & job queue
-* **`nestjs`, `passport-jwt`**: Backend API framework & security
-* **`react`, `next`, `recharts`, `react-hook-form`**: Frontend UI & data visualization

package/docs/support/legal/privacy-terms.mdx

@@ -1,73 +0,0 @@
----
-title: 'Privacy & Terms'
-description: 'Privacy policy and terms of use for Genie App users.'
----
-
-# Privacy & Terms
-
-## Overview
-
-This document details the privacy and terms-related components and policies integrated within the Genie application. It covers cookie consent handling, Shopify permission management, and user privacy notices displayed across the app.
-
-## Cookie Consent
-
-The Genie app includes a Cookies Consent Banner component designed to comply with necessary cookie usage regulations. It handles obtaining user consent for cookie usage and informs users about the types of cookies used.
-
-### Key Features
-
-- Displays a banner to users not yet providing consent.
-- Explains the use of necessary cookies for core functionality.
-- Offers information on analytics cookies and preference remembrance.
-- Provides a link to the Privacy Policy for further details.
-- Allows users to accept cookies with a single click.
-
-### Usage Behavior
-
-- Once accepted, the consent is stored persistently.
-- The banner reappears if user navigates to a new page without previously giving consent.
-- Users may dismiss the banner temporarily.
-
-### Implementation Details
-
-The banner implementation listens to route changes to reset visibility, uses local storage keys to remember consent, and includes accessible buttons for acceptance or dismissal. The privacy policy link opens externally to provide legal context.
-
-## Shopify Permissions & Scopes
-
-Genie integrates with Shopify through a precise set of API scopes. These are permissions granted by Shopify to the Genie app to perform operations on the user's store data.
-
-### Shopify API Scopes
-
-The following permissions are requested and used by Genie, respecting Shopify's restrictions on overlapping scopes:
-
-- `read_orders` and `read_all_orders` for accessing order information.
-- `write_products` and `write_inventory` for managing product listings and inventory updates.
-- `read_locations` and `read_themes` for store locations and themes.
-- `read_returns` and `write_publications` for returns management and content publications.
-
-### Permission Updates Flow
-
-- When new features require additional Shopify permissions, Genie prompts the user with a modal to approve these new scopes.
-- If the current user is not the team owner, they are instructed to ask the owner to approve.
-- The modal ensures users understand the necessity of granting these permissions for uninterrupted features.
-
-## Links to Privacy Policy and Terms
-
-- The Cookies Consent Banner provides a direct link to Genie’s Privacy Policy at `http://privacy.getgenie.io/`.
-- This external page contains detailed legal information regarding data privacy and user terms.
-
-## User Privacy Considerations
-
-Genie limits cookie usage to necessary cookies required for website and application functionality and optional analytics cookies aimed at improving user experience.
-
-By explicitly obtaining user consent before setting analytics cookies, Genie respects user privacy and legal compliance.
-
-## Summary
-
-Genie prioritizes privacy and transparency by:
-
-- Informing users clearly about cookie usage.
-- Limiting permissions requested from Shopify to only those necessary.
-- Properly managing updates in permissions requiring user consent.
-- Offering easy access to privacy documentation.
-
-This approach ensures compliance and builds user trust while enabling Genie’s full feature set.

package/docs/support/troubleshooting/common-issues.mdx

@@ -1,159 +0,0 @@
----
-title: 'Common Issues & Debugging'
-description: 'Document known problems and developer tips for troubleshooting.'
----
-
-## Common Issues & Debugging
-
-This document provides an overview of frequent problems and debugging techniques encountered in the Genie backend system. It is intended for internal developers and maintainers to quickly diagnose and resolve issues related to team management, Shopify integration, webhook processing, data synchronization, and email notifications.
-
----
-
-### 1. Shopify Webhook Registration Failures
-
-**Issue:** Teams sometimes fail to register Shopify webhooks successfully.
-
-**Context:**
-- The registration process occurs in `WebhooksInsightsSyncService.registerShopifyWebhooksForTeam` where webhooks are registered unless the team is on a free plan or listed in the exclusion for product update topics.
-- Failures are logged with detailed error messages.
-- The system retries failed registrations periodically (every 10 minutes) using `attemptToRegisterWebhooksForFailedTeams` until successful.
-
-**Debugging Steps:**
-- Check logs from `WebhooksInsightsSyncService` for specific error messages during webhook registration.
-- Confirm team eligibility (not on free plan, not excluded from certain topics).
-- Verify that the Shopify API credentials are valid and that network connectivity with Shopify is intact.
-- Inspect the responses in the method `ShopifyWebhooksService.registerWebhooksForTeam` where individual webhook registration responses are validated.
-
----
-
-### 2. Shopify Webhook Event Processing Errors
-
-**Issue:** Errors during processing Shopify webhook events can cause the events to fail or get stuck.
-
-**Context:**
-- Events are stored in the database and processed asynchronously by `ShopifyWebhooksService.startEventsProcessingForTeam`.
-- Processing fails are caught, logged using the GenieException wrapper, and the corresponding events are marked with failed status.
-- The system skips duplicated or irrelevant events to prevent redundant processing.
-
-**Debugging Steps:**
-- Review logs for errors thrown inside the event processing pipelines in `WebhooksInsightsSyncService` such as product sync, collections sync, inventory levels update, and orders sync.
-- Check the `ShopifyWebhookEventEntity` table for event statuses (`PENDING`, `PROCESSED`, `FAILED`, `SKIPPED`) to identify problematic events.
-- If many events are stuck in `FAILED`, investigate the root cause in the callback handlers.
-- Monitor error tracking and exceptions captured to Sentry or other observability services.
-
----
-
-### 3. Data Synchronization Delays or Failures
-
-**Issue:** Delay or failure in syncing Shopify products, collections, inventory levels, or sales metrics.
-
-**Context:**
-- Sync is orchestrated within `InsightsSyncService.syncDataForTeam` and related methods.
-- Sync includes multiple steps: fetch products, import products, mark deletions, sync locations, sync collections, sync sales orders, and update metrics.
-- Scheduled syncs and manual syncs use the same pipelines, with `manual` flag handled for tracking.
-
-**Debugging Steps:**
-- Verify that Shopify API authentication (`shopifyApiService.getAuth`) returns valid credentials for the team.
-- Check the daily sync performance logs via `DailySyncPerformanceTrackerService` for bottlenecks.
-- On failed syncs, look for `GenieException` captures containing detailed error context.
-- Use `InsightsSyncService.debugAverageDailySales` to test sales data calculation for individual variants.
-- Confirm that all required dependencies (`ProductRepository`, `ProductVariantRepository`, `LocationService`, etc.) are operational.
-
----
-
-### 4. Inventory and Sales Metrics Misalignment
-
-**Issue:** Inventory metrics like average daily sales, cumulative sales percentages, or sales velocity reports may appear incorrect.
-
-**Context:**
-- Calculations use historical sales and inventory data queried in batches.
-- The thresholds for grading are enforced by database triggers to guarantee valid values (see migration `1702299870451-grading-settings-v3.ts`).
-- Failed transformations or missing product variant data cause inaccurate aggregates.
-
-**Debugging Steps:**
-- Verify that threshold settings (`inventoryItemGradingLevelAThresholdSetting`, `B`, `C`) adhere to the constraints enforced by the DB trigger.
-- Use the debug endpoint in `InsightsSyncService.debugAverageDailySales` to examine detailed calculation steps per variant.
-- Check if variants or products are soft-deleted unexpectedly during sync.
-- Review sales orders data and line items imported via `SalesOrdersService.importSalesOrders`.
-
----
-
-### 5. Slack Notification Failures
-
-**Issue:** Slack notifications for system alerts, user requests, or sales health checks fail or do not appear on the expected channels.
-
-**Context:**
-- `SlackService` uses the Slack Web API client configured with the `SLACK_APP_TOKEN` environment variable.
-- Before sending a message, it verifies membership in the Slack channel and attempts to join if not already a member.
-- Messages include detailed contextual information such as team IDs, user emails, and report summaries.
-
-**Debugging Steps:**
-- Verify that the Slack app is installed in the workspace with the correct bot token (`SLACK_APP_TOKEN`).
-- Confirm that channel IDs (`SLACK_APP_USER_REQUESTS_CHANNEL_ID`, `SLACK_APP_SYSTEM_ALERTS_CHANNEL_ID`) are correctly configured in environment variables.
-- Check logs from `SlackService` for errors when sending messages or joining channels.
-- Ensure the app has permissions to join channels and send messages.
-
----
-
-### 6. Scheduled Tasks Not Running or Partially Executed
-
-**Issue:** Scheduled cron jobs for deleting old sales orders or sales sync health checks do not trigger as expected.
-
-**Context:**
-- Scheduled tasks are implemented in `ScheduledTasksService` using decorators like `@EnhancedCron`.
-- Tasks include conditions like checking for midnight in the configured timezone before executing.
-- Notifications are sent on completion, leveraging `SlackService`.
-
-**Debugging Steps:**
-- Confirm the system clock and timezone configuration (`DATA_SYNC_TIMEZONE`) are correct.
-- Verify the cron expressions for the scheduled tasks.
-- Review logs for task start and completion messages.
-- Confirm that the environment runs with all needed permissions and dependencies.
-
----
-
-### 7. User and Team Data Synchronization Issues
-
-**Issue:** Users associated with teams are not filtered correctly, or incomplete Shopify permissions causing team feature restrictions.
-
-**Context:**
-- The `TeamService.getAllTeams` filters out internal users (`@getgenie.io` emails) and maps shops.
-- Missing Shopify permissions detected via `TeamsService.hasMissingShopifyScopes` for active teams.
-- Teams with disabled reasons or uninstalled Mantle billing token are tracked.
-
-**Debugging Steps:**
-- Verify the user filters in `TeamService.getAllTeams`.
-- Use administrative API endpoints to check for missing scopes or uninstalled teams.
-- Review billing service connection via `MantleService` and mantle tokens.
-
----
-
-## Summary
-
-This section consolidates major debugging areas with pointers to relevant classes and methods:
-
-| Issue Category                         | Key Components / Files                                            | Notes                                                                                  |
-|--------------------------------------|-----------------------------------------------------------------|----------------------------------------------------------------------------------------|
-| Shopify Webhook Registration         | `WebhooksInsightsSyncService.registerShopifyWebhooksForTeam`    | Retry logic, logging successful and failed registrations                               |
-| Webhook Event Processing             | `ShopifyWebhooksService.startEventsProcessingForTeam`           | Event status management, error captures                                               |
-| Data Sync Failures                   | `InsightsSyncService.syncDataForTeam`                            | Multi-step product and sales data sync                                               |
-| Inventory Metrics Incorrect          | `InsightsSyncService.debugAverageDailySales`                     | Grading thresholds, sales data recalculations                                        |
-| Slack Notification Errors            | `SlackService.sendNotification`                                  | Channel membership verification and error handling                                  |
-| Scheduled Tasks                     | `ScheduledTasksService`                                          | Cron job timing checks and notification sending                                     |
-| User & Team Data Integrity           | `TeamService.getAllTeams`, `TeamsService.hasMissingShopifyScopes`| User filtering, Shopify permissions, billing status                                  |
-
----
-
-For detailed code and method references, developers should consult the source files linked below for direct exploration and debugging annotations:
-
-- [apps/api/src/pim/services/webhooks-insights-sync.service.ts](apps/api/src/pim/services/webhooks-insights-sync.service.ts)
-- [apps/api/src/shopify/services/shopify-webhooks.service.ts](apps/api/src/shopify/services/shopify-webhooks.service.ts)
-- [apps/api/src/pim/services/insights-sync.service.ts](apps/api/src/pim/services/insights-sync.service.ts)
-- [apps/api/src/slack/services/slack.service.ts](apps/api/src/slack/services/slack.service.ts)
-- [apps/api/src/sales-order/services/sales-orders.service.ts](apps/api/src/sales-order/services/sales-orders.service.ts)
-- [apps/api/src/sales-order/services/scheduled-tasks.service.ts](apps/api/src/sales-order/services/scheduled-tasks.service.ts)
-- [apps/api/src/admin/services/team.service.ts](apps/api/src/admin/services/team.service.ts)
-
----
-
-This document will be updated as new common issues or debugging procedures emerge from development and support activities.