@clidey/dory 0.1.0 → 0.2.0

package/docs/platform-admin/system-maintenance/health-monitoring.mdx

@@ -1,222 +0,0 @@
----
-title: 'Health & Monitoring'
-description: 'Health checks and system testing utilities for Genie App components.'
----
-
-# Health & Monitoring
-
-## Overview
-
-The **Health & Monitoring** module ensures the ongoing stability, availability, and operational integrity of key system components within the Genie platform. It provides mechanisms for health checks, scheduled maintenance tasks, system synchronization, and alerts through integrated channels.
-
-This module plays a critical role in maintaining service reliability, enabling early detection of potential issues, and facilitating timely operational actions.
-
-## Purpose and Scope
-
-This module encompasses several backend services and REST API controllers, primarily responsible for:
-
-- Exposing health endpoints to verify system status.
-- Running scheduled tasks such as data cleanup and system health checks.
-- Synchronizing inventory insights and sales data.
-- Sending notifications about system performance and health check results.
-
-It operates within the backend API service boundary and integrates tightly with Shopify, Slack, sales order management, and insightful analytics services.
-
-## Technical Overview
-
-The Health & Monitoring features are implemented mainly within the API backend service using the NestJS framework. Key components include:
-
-- **HealthController:** Provides basic health check endpoints.
-- **ScheduledTasksService:** Runs scheduled cron jobs for maintenance and health validation.
-- **SyncController:** Offers admin endpoints to trigger manual synchronization of insights and sales data.
-- **SlackService:** Responsible for sending system alerts and notifications over Slack channels.
-
-### Architectural Context
-
-- The HealthController is a public REST endpoint responding with the system's current status.
-- ScheduledTasksService uses cron-based jobs to automate repetitive maintenance tasks, leveraging date-time utilities for timezone awareness.
-- SyncController facilitates administrative operations for syncing data, impacting multiple teams.
-- SlackService acts as an integration client with Slack, automating alerts and reporting critical system events.
-
-These components collaborate to maintain system health proactively and inform relevant stakeholders.
-
-```mermaid
-flowchart TD
-  subgraph Backend API Service
-    direction TB
-    HealthController["HealthController"]:::controller
-    ScheduledTasksService["ScheduledTasksService"]:::service
-    SyncController["SyncController"]:::controller
-    SlackService["SlackService"]:::service
-  end
-
-  subgraph External Systems
-    Shopify["Shopify"]:::external
-    Slack["Slack"]:::external
-  end
-
-  HealthController -->|"Responds to Health Check Requests"| users["Clients / Monitoring Tools"]
-  ScheduledTasksService -->|"Runs Scheduled Jobs"| SalesOrdersService["SalesOrdersService"]
-  ScheduledTasksService -->|"Sends Notifications"| SlackService
-  SyncController -->|"Triggers Data Syncs"| InsightsSyncService["InsightsSyncService"]
-  SyncController -->|"Triggers Data Syncs"| SalesOrdersService
-  SyncController -->|"Triggers Shopify Sync"| Shopify
-  SlackService -->|"Sends Alerts"| Slack
-
-  %% Style for components
-  classDef controller fill:#d1e7fd,stroke:#1e40af,color:#1e40af,stroke-width:1px
-  classDef service fill:#c7f0d8,stroke:#047857,color:#047857,stroke-width:1px
-  classDef external fill:#fef3c7,stroke:#78350f,color:#78350f,stroke-width:1px
-
-  %% Click events
-  click HealthController "apps/api/src/health/controllers/health.controller.ts"
-  click ScheduledTasksService "apps/api/src/sales-order/services/scheduled-tasks.service.ts"
-  click SyncController "apps/api/src/admin/controllers/sync.controller.ts"
-  click SlackService "apps/api/src/slack/services/slack.service.ts"
-```
-
-## Core Concepts and Responsibilities
-
-### Components
-
-- **Health Check Endpoint:** Provides a simple status response `{ status: "OK" }` via a public GET endpoint to facilitate uptime monitoring.
-- **Scheduled Tasks:** Automated jobs running process-heavy or periodic cleanup and health verification tasks at predefined cron schedules.
-- **Data Synchronization:** Manual admin-triggered endpoints to synchronize inventory insights, sales data, and shop settings on demand.
-- **Slack Notifications:** Automated messages to designated Slack channels for system alerts, data sync reports, and health check summaries.
-
-### Responsibilities
-
-- Ensure that the backend services report their operational status accurately.
-- Clean up old sales orders to maintain database hygiene.
-- Monitor sales synchronization health and report discrepancies.
-- Allow admin users to trigger data syncs for insights and sales as needed.
-- Generate Slack notifications that highlight the status and health of core system operations.
-
-### Design Decisions
-
-- Use of **NestJS controllers** to encapsulate HTTP API endpoints.
-- Scheduled tasks annotated with `@EnhancedCron` decorator for declarative cron job scheduling.
-- Dependency injection for clean integration with services such as Slack and SalesOrders.
-- Use of timezone-aware date handling via `date-fns-tz` to maintain consistent timing across regions.
-
-### Ownership and Monitoring
-
-- Owned and maintained by the backend API development team.
-- Logs primarily written via NestJS Logger with identifiable class scopes.
-- Slack messages sent to system alerts and user requests channels for operational monitoring.
-
-## Code Structure
-
-### Key Files
-
-- [`apps/api/src/health/controllers/health.controller.ts`](apps/api/src/health/controllers/health.controller.ts): Health check controller exposing the `/health` REST endpoint.
-- [`apps/api/src/sales-order/services/scheduled-tasks.service.ts`](apps/api/src/sales-order/services/scheduled-tasks.service.ts): Contains scheduled jobs for routine maintenance and health checks.
-- [`apps/api/src/admin/controllers/sync.controller.ts`](apps/api/src/admin/controllers/sync.controller.ts): Admin controller with POST endpoints for manual data sync operations.
-- [`apps/api/src/slack/services/slack.service.ts`](apps/api/src/slack/services/slack.service.ts): Slack integration service handling message dispatch and channel management.
-
-### Example: HealthController
-
-```ts
-import { Controller, Get, Logger } from "@nestjs/common";
-import { Public } from "~/user-management/decorators/decorators";
-
-@Controller("health")
-export class HealthController {
-  private readonly logger = new Logger(HealthController.name);
-
-  @Public()
-  @Get()
-  async getHealth() {
-    return { status: "OK" };
-  }
-}
-```
-
-This controller exposes a public endpoint returning a simple `{ status: "OK" }` JSON response to indicate that the system is operational.
-
-### ScheduledTasksService Highlights
-
-- Schedules jobs using the `@EnhancedCron` decorator with cron time set to specific EST times.
-- Runs daily cleanup of old sales orders.
-- Performs sales synchronization health checks on Mondays and Fridays at midnight.
-- Sends Slack notifications with summaries of health checks.
-
-```ts
-@EnhancedCron({
-  cronTime: "0 12 * * *", // every day at 12pm
-  taskName: "deleteOldSalesOrdersTask",
-})
-async deleteOldSalesOrdersTask() {
-  this.logger.log("Deleting old sales orders for all teams...");
-  await this.salesOrdersService.deleteOldSalesOrders();
-  this.logger.log("Deleted old sales orders for all teams");
-}
-```
-
-### SyncController Responsibilities
-
-- Provides POST endpoints like `/sync-inventory-insights-for-all-teams` and `/sync-weekly-sales-for-last-year-for-team` to trigger manual syncs.
-- Uses request validation via Zod schemas to accept well-typed request bodies.
-- Logs detailed performance summaries upon sync completion.
-
-## API and Interfaces
-
-### Health API
-
-- **GET /health**
-  - Publicly accessible endpoint.
-  - Returns `{ status: "OK" }` to indicate service health.
-
-### Admin Sync APIs
-
-| Endpoint                                     | Method | Request Body                   | Description                                   |
-|----------------------------------------------|--------|-------------------------------|-----------------------------------------------|
-| /admin/sync-inventory-insights-for-all-teams | POST   | None                          | Triggers sync of inventory insights for all teams.
-| /admin/sync-inventory-insights-for-team      | POST   | `{ teamId: string }`          | Triggers sync of inventory insights for a specific team.
-| /admin/sync-daily-inventory-insights-for-all-teams | POST | None                          | Triggers daily sync of inventory insights for all teams.
-| /admin/sync-daily-inventory-insights-for-team | POST  | `{ teamId: string }`          | Triggers daily sync for a specific team.
-| /admin/sync-insights-and-ideas-for-all-teams | POST   | None                          | Triggers full sync of insights and ideas for all teams.
-| /admin/sync-shop-settings-for-team           | POST   | `{ teamId: string }`          | Syncs shop settings for a specific team.
-| /admin/update-sales-and-order-metrics-for-team | POST  | `{ teamId: string }`          | Updates sales and order metrics for a team.
-| /admin/sync-weekly-sales-for-last-year-for-team | POST | `{ teamId: string }`          | Syncs weekly sales data for last year.
-| /admin/sales-health-check-for-past-days      | POST   | `{ days: number }`            | Returns sales sync health check info for given past days.
-
-### SlackService
-
-- Provides async methods to send different types of notifications:
-  - New user report requests
-  - Feature suggestions
-  - Daily sync performance summaries
-  - Product bundle import/onboarding notifications
-  - Purchase order import requests
-  - Sales sync health check notifications
-
-- Ensures app is a member of Slack channels before sending messages.
-- Retrieves Slack app user ID for membership validation.
-
-## Environment and Configuration
-
-- **Slack tokens:** `SLACK_APP_TOKEN` for API access.
-- **Slack Channel IDs:**
-  - `SlACK_APP_USER_REQUESTS_CHANNEL_ID` for user request-related notifications.
-  - `SLACK_APP_SYSTEM_ALERTS_CHANNEL_ID` for system alerts and health notifications.
-- **Timezone settings:** `DATA_SYNC_TIMEZONE` used for scheduled tasks to align cron job execution times.
-- **API environment:** `API_ENV` variable used in Slack notification messages to indicate deployment environment.
-
-## Testing, Monitoring, and Deployment
-
-- Logging and debugging are handled through NestJS `Logger` instances per class.
-- Scheduled tasks log start and completion times.
-- Performance tracking integrated with `DailySyncPerformanceTrackerService` to monitor sync job durations.
-
-## Troubleshooting & Known Issues
-
-- No explicit troubleshooting or known issues documented in the current context.
-
-## Summary
-
-The Health & Monitoring module is fundamental to maintaining Genie’s backend system reliability. Through health endpoint exposure, scheduled operations, manual sync triggers, and Slack alerting, it ensures the platform remains operational and timely alerts notify stakeholders of potential issues.
-
-This module’s design leverages NestJS controllers and services, cron scheduling decorators, and external API integrations for a scalable and maintainable infrastructure.
-
-For detailed implementation, refer to the respective code files provided in the repository.

package/docs/platform-admin/system-maintenance/queue-management.mdx

@@ -1,234 +0,0 @@
----
-title: 'Queue Management'
-description: 'Overview of queue system powered by BullMQ, its UI and configuration.'
----
-
-## Queue Management
-
-### Purpose and Scope
-
-This module handles the management and processing of queues within the Genie App backend system. It orchestrates various asynchronous background jobs, responsible for syncing data, processing events, maintaining inventory history snapshots, forecasting, demand planning, and onboarding workflows.
-
-Queue management enables scalable, reliable, and fault-tolerant processing of tasks by leveraging BullMQ and its NestJS integration in a modular fashion. The service ensures jobs are queued, processed, deduplicated, retried, and cleaned up efficiently.
-
-This queue system operates primarily as part of the backend services, interfacing with core business logic in inventory, forecasting, Shopify integration, and user onboarding, ensuring smooth asynchronous workflows.
-
-### Technical Overview
-
-The system uses [BullMQ](https://docs.bullmq.io/) queues within NestJS, enhanced by `@bull-board` to provide UI monitoring of the queues' state and jobs.
-
-#### Components:
-
-- **Queues and Jobs**: Defined centrally in `const.ts`, grouping four main queues:
-  - `insights-sync`
-  - `shopify-webhooks`
-  - `inventory-item-history`
-  - `product-variant-quantity-snapshot`
-
-- **Queue Registration**: Each queue is registered with BullModule, including default job options like retry attempts and removal after completion.
-
-- **Queue Dashboard**: Each queue is registered with BullBoardModule using the `BullMQAdapter`, enabling web UI monitoring.
-
-- **Job Processors (Consumers)**: Each queue has corresponding processors that execute jobs, e.g. `OnboardingConsumer` for onboarding sync jobs, `InventoryItemHisotryConsumer` for inventory snapshot sync, etc.
-
-- **Workflow Service**: Manages complex flows (multi-job workflows) for demand planning and forecast updates, coordinating job creation and job dependencies using BullMQ flow producers.
-
-
-```mermaid
-flowchart TD
-  subgraph "Queues"
-    INSIGHTS_SYNC["Insights Sync Queue"]:::queue
-    SHOPIFY_WEBHOOKS["Shopify Webhooks Queue"]:::queue
-    INVENTORY_ITEM_HISTORY["Inventory Item History Queue"]:::queue
-    PRODUCT_VARIANT_QTY_SNAPSHOT["Product Variant Quantity Snapshot Queue"]:::queue
-  end
-
-  subgraph "Job Processors"
-    OnboardingConsumer["OnboardingConsumer"]:::processor
-    InventoryItemHistoryConsumer["InventoryItemHistoryConsumer"]:::processor
-    ProductVariantSnapshotConsumer["ProductVariantSnapshotConsumer"]:::processor
-    InsightsSyncConsumer["InsightsSyncConsumer"]:::processor
-  end
-
-  subgraph "Workflow Services & Producers"
-    WorkflowService["WorkflowService
-(Generates demand plan & forecast workflows)"]:::service
-  end
-
-  style INSIGHTS_SYNC fill:#d1e7dd,stroke:#0f5132,stroke-width:2px
-  style SHOPIFY_WEBHOOKS fill:#cff4fc,stroke:#055160,stroke-width:2px
-  style INVENTORY_ITEM_HISTORY fill:#f8d7da,stroke:#842029,stroke-width:2px
-  style PRODUCT_VARIANT_QTY_SNAPSHOT fill:#fff3cd,stroke:#664d03,stroke-width:2px
-  style OnboardingConsumer fill:#e2e3e5,stroke:#41464b,stroke-width:2px
-  style InventoryItemHistoryConsumer fill:#e2e3e5,stroke:#41464b,stroke-width:2px
-  style ProductVariantSnapshotConsumer fill:#e2e3e5,stroke:#41464b,stroke-width:2px
-  style InsightsSyncConsumer fill:#e2e3e5,stroke:#41464b,stroke-width:2px
-  style WorkflowService fill:#dbeafe,stroke:#2563eb,stroke-width:2px
-
-  INSIGHTS_SYNC -->|"processes job: SYNC_SHOPIFY_DATA"| InsightsSyncConsumer
-  SHOPIFY_WEBHOOKS -->|"processes job: PROCESS_EVENT"| OnboardingConsumer
-  INVENTORY_ITEM_HISTORY -->|"processes job: TAKE_SNAPSHOT"| InventoryItemHistoryConsumer
-  PRODUCT_VARIANT_QTY_SNAPSHOT -->|"processes jobs: WEEKLY_SNAPSHOT, MONTHLY_SNAPSHOT"| ProductVariantSnapshotConsumer
-
-  WorkflowService -->|"creates complex demand plan workflows"| INSIGHTS_SYNC
-  WorkflowService -->|"creates demand plan and forecast jobs"| INVENTORY_ITEM_HISTORY
-
-  click OnboardingConsumer "apps/api/src/setup/services/onboarding.consumer.ts"
-  click InventoryItemHistoryConsumer "apps/api/src/pim/services/inventory-item-history.consumer.ts"
-  click ProductVariantSnapshotConsumer "apps/api/src/pim/services/product-variant-snapshot.consumer.ts"
-  click InsightsSyncConsumer "apps/api/src/pim/services/insights-sync.consumer.ts"
-  click WorkflowService "apps/api/src/forecast/services/workflow.service.ts"
-  click INSIGHTS_SYNC "apps/api/src/pim/const.ts"
-  click SHOPIFY_WEBHOOKS "apps/api/src/pim/const.ts"
-  click INVENTORY_ITEM_HISTORY "apps/api/src/pim/const.ts"
-  click PRODUCT_VARIANT_QTY_SNAPSHOT "apps/api/src/pim/const.ts"
-```
-
-
-### Core Concepts and Responsibilities
-
-#### Queues and Jobs
-- Queues are named namespaces for logically grouping related jobs.
-- Jobs represent atomic units of asynchronous work identified by a unique name.
-- Jobs support deduplication using unique IDs to prevent double processing.
-- Default options include removing completed jobs after 7 days and retrying failed jobs twice.
-
-#### Flow Producers
-- Used for managing complex job workflows with children jobs and dependencies.
-- Used mainly for demand planning workflows involving multiple dependent jobs across different queues (`demand-plan`, `forecast`, `historical-sales`).
-
-#### Job Consumers
-- Implemented as NestJS `@EnhancedProcessor` classes, each responsible for processing jobs from a specific queue.
-- Include concurrency control for managing parallel job executions.
-- Ensure jobs are processed within a max 23-hour timeout to prevent indefinite execution.
-
-#### Key Design Decisions
-- BullMQ chosen for robustness and rich features for background job management.
-- BullBoard integration enables an out-of-the-box dashboard for queue health monitoring.
-- Centralized queue and job name constants avoid naming collisions and improve maintainability.
-
-#### Ownership
-- The backend engineering team owns these queue modules.
-- Logging is performed using NestJS's native `Logger` with clear contextual naming.
-- Error capturing integrates with centralized exception tracking via `GenieException` and sentry-like reporting.
-
-#### Non-functional Requirements (NFRs)
-- High concurrency support (e.g., 10-20 concurrent workers).
-- Job deduplication to avoid redundant processing.
-- Job retries with exponential backoff for transient failures.
-- Timely removal of completed jobs to maintain Redis memory hygiene.
-- Stable fault tolerance to avoid crashing on unhandled job names.
-
-### Code Structure
-
-Key files and their responsibilities:
-
-| File | Description |
-|-------|-------------|
-| `apps/api/src/pim/const.ts` | Declares all queue and job names, registers queues with BullModule and BullBoardModule to configure default options and dashboard UI |
-| `apps/api/src/forecast/services/workflow.service.ts` | Manages multi-job workflows via BullMQ's flow producers for demand plan generation, actual updates, and forecast refresh workflows |
-| `apps/api/src/setup/services/onboarding.consumer.ts` | Consumer for onboarding-related jobs from the `onboarding` queue; processes shop settings sync, PIM data sync, and orders sync jobs |
-| `apps/api/src/pim/services/inventory-item-history.consumer.ts` | Processes inventory item history snapshot jobs to sync historical inventory data per team |
-| `apps/api/src/pim/services/product-variant-snapshot.consumer.ts` | Handles weekly and monthly inventory quantity snapshot jobs for product variants by updating relevant database columns efficiently |
-| `apps/api/src/pim/services/insights-sync.consumer.ts` | Processes Shopify data synchronization jobs per team, includes concurrency control and job delay if duplicate jobs are active |
-
-
-### Selected Code Snippets
-
-#### Queue and Job Constants Registration
-```ts
-export const QUEUE = {
-  INSIGHTS_SYNC: { name: "insights-sync", jobs: { SYNC_SHOPIFY_DATA: "insights-sync:sync-shopify-data" } },
-  SHOPIFY_WEBHOOKS: { name: "shopify-webhooks", jobs: { PROCESS_EVENT: "shopify-webhooks:process-event" } },
-  INVENTORY_ITEM_HISTORY: { name: "inventory-item-history", jobs: { TAKE_SNAPSHOT: "inventory-item-history:take-snapshot" } },
-  PRODUCT_VARIANT_QUANTITY_SNAPSHOT: {
-    name: "product-variant-quantity-snapshot",
-    jobs: {
-      WEEKLY_SNAPSHOT: "product-variant-quantity-snapshot:weekly-snapshot",
-      MONTHLY_SNAPSHOT: "product-variant-quantity-snapshot:monthly-snapshot",
-    },
-  },
-} as const;
-
-export const BULLMQ_QUEUES = [
-  BullModule.registerQueue({ name: QUEUE.INSIGHTS_SYNC.name, defaultJobOptions: { removeOnComplete: { age: 604800 }, attempts: 2 } }),
-  BullBoardModule.forFeature({ name: QUEUE.INSIGHTS_SYNC.name, adapter: BullMQAdapter }),
-  // similarly for other queues
-];
-```
-
-#### Job Processing Example - OnboardingConsumer
-```ts
-@EnhancedProcessor(QUEUE.ONBOARDING.name, { concurrency: 10 })
-export class OnboardingConsumer extends GenieWorkerHost {
-  async process(job: Job) {
-    const jobName = job.name as string; // one of onboarding jobs
-    const { teamId } = z.object({ teamId: z.string().nonempty() }).parse(job.data);
-
-    const JOB_HANDLERS = {
-      [QUEUE.ONBOARDING.jobs.SYNC_SHOP_SETTINGS]: async () => {
-        await this.shopifyStoreService.syncShopSettings(teamId);
-        await this.onboardingProgressRepository.update({ teamId }, { hasShopSettingsDataSynced: true });
-      },
-      // Other handlers...
-    };
-
-    const jobHandler = JOB_HANDLERS[jobName];
-    if (!jobHandler) {
-      throw new UnreachableError(jobName as never, `Unhandled job name for queue: onboarding`);
-    }
-
-    // Enforce max 23 hour timeout
-    const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => reject(new GenieException(`Job ${jobName} timed out after 23 hours`, { id: job.id })), 23 * 3600 * 1000);
-    });
-
-    await Promise.race([jobHandler.call(this), timeoutPromise]);
-  }
-}
-```
-
-#### Workflow Service Job Addition Example
-```ts
-async startGenerateDemandPlanWorkflow({ teamId, demandPlanId, demandPlanStartDate }: { teamId: string; demandPlanId: string; demandPlanStartDate: Date; }) {
-  const historyStartDate = subYears(demandPlanStartDate, 1);
-
-  await this.generateDemandPlanFlowProducer.add({
-    name: FLOW_PRODUCER.GENERATE_DEMAND_PLAN,
-    queueName: QUEUE.DEMAND_PLAN.name,
-    data: { teamId, demandPlanId },
-    opts: {
-      deduplication: { id: `${FLOW_PRODUCER.GENERATE_DEMAND_PLAN}-${teamId}-${demandPlanId}` },
-    },
-    children: [ /*...child jobs with deduplication and priorities...*/ ],
-  });
-}
-```
-
-### Environment & Configuration
-
-- No specific environment variables are detailed for queue management except a feature flag check for disabling Shopify scheduled tasks (`DISABLE_SHOPIFY_SCHEDULED_TASKS`).
-- Queues use Redis as backend via BullMQ, configured elsewhere in the application.
-
-### Testing, Monitoring, and Deployment
-
-- Each consumer implements detailed error handling and logs job execution details.
-- Timeouts are enforced at 23 hours per job to avoid slow/hung processing.
-- Jobs leverage retry logic with exponential backoff configured as default.
-- Queue dashboard integration via BullBoard enables real-time monitoring of queue states.
-- Exception capturing employs `GenieException` and utilities to integrate with centralized error tracking.
-
-### Troubleshooting & Known Issues
-
-- If a job name is unhandled in a consumer, an `UnreachableError` is thrown, ensuring missing handlers are caught during development or deployment.
-- Long-running jobs are timed out and fail gracefully after 23 hours to prevent queue blockage.
-- Duplicate jobs for the same team are deferred (e.g., in `InsightsSyncConsumer`) to avoid race conditions.
-
-### References
-
-- [Queue and Job Constants](apps/api/src/pim/const.ts)
-- [Onboarding Consumer](apps/api/src/setup/services/onboarding.consumer.ts)
-- [Inventory Item History Consumer](apps/api/src/pim/services/inventory-item-history.consumer.ts)
-- [Product Variant Snapshot Consumer](apps/api/src/pim/services/product-variant-snapshot.consumer.ts)
-- [Insights Sync Consumer](apps/api/src/pim/services/insights-sync.consumer.ts)
-- [Workflow Service](apps/api/src/forecast/services/workflow.service.ts)

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

@@ -1,170 +0,0 @@
----
-title: 'Teams Management'
-description: 'Creating, managing, and configuring teams and their members.'
----
-
-## Teams Management Service - Internal Developer Documentation
-
-### 1. Purpose and Scope
-
-The Teams Management service is a core backend module responsible for handling operations related to teams within the Genie platform. It manages the storage, retrieval, and update of team settings, including general business information, insights configurations, and Shopify-related settings. Additionally, it provides API endpoints for team membership and invitation management.
-
-This service acts as a boundary between the user/team management domain and other subsystems such as purchase orders, product inventory, and onboarding workflows. It is a crucial part of the user collaboration and team configuration capabilities.
-
-### 2. Technical Overview
-
-The `SettingsService` and `TeamsController` work closely to enable team configuration and management functionalities. Teams are represented by `TeamEntity` in the database using TypeORM ORM.
-
-#### Architectural Role
-- Implements core business logic for team settings management.
-- Offers REST API endpoints via `TeamsController` to expose these operations.
-- Handles validation and error management, throwing domain-specific exceptions (`GenieException`) for consistent error reporting.
-
-#### Dependencies
-- Uses TypeORM repository for data access to `TeamEntity`.
-- Depends on shared DTOs and enums from `@genie/shared` (e.g., `TeamSettingsDto`).
-- Uses utility functions such as timezone validation.
-- Works together with `TeamsService` which provides user and membership logic.
-
-#### Design Pattern
-- Follows NestJS provider and controller patterns.
-- Separation between controller (request handling) and service (business logic).
-
-### Mermaid Diagram
-
-```mermaid
-flowchart TD
-  subgraph "User & Team Management"
-    SettingsService["SettingsService"]:::service
-    TeamsController["TeamsController"]:::controller
-    TeamsService["TeamsService"]:::service
-    TeamEntity["TeamEntity DB":::db]
-  end
-
-  TeamsController -->|"calls"| SettingsService
-  TeamsController -->|"uses"| TeamsService
-  SettingsService -->|"DB access via TypeORM"| TeamEntity
-  TeamsService -->|"DB & business logic"| TeamEntity
-
-  classDef service fill:#f9f,stroke:#333,stroke-width:1px,color:#000
-  classDef controller fill:#bbf,stroke:#333,stroke-width:1px,color:#000
-  classDef db fill:#fab,stroke:#333,stroke-width:2px,color:#000
-```
-
-### 3. Core Concepts and Responsibilities
-
-- **Team Settings** encompass general business info (e.g., business name), insights configuration (e.g., inventory grading), and Shopify-specific shop settings (currency, timezone).
-- **Inventory Item Grading Strategy:** Currently, only the `SalesRevenue` strategy is supported (the `SalesFrequency` strategy explicitly throws a `GenieException`).
-- **General Settings DTOs:** The API consumes and returns structured DTOs like `TeamGeneralSettingsDto`, `InsightsSettingsDto`, and `TeamSettingsDto`.
-- **Authorization:** Controllers enforce user membership (`user.teamId` presence) to restrict operations.
-- **Invitation Management:** Supports sending invitations, accepting invitations, and deactivating team users, with admin role enforcement.
-
-### Key Domain Terms
-- **TeamGeneralSettingsDto:** Business-facing settings such as business name, VAT number, contact email.
-- **InsightsSettingsDto:** Configurations for sales analysis and inventory grading.
-- **Shopify Shop Settings:** Currency and timezone data linked to Shopify integration.
-- **GenieException:** Centralized exception class for domain errors.
-
-### Ownership
-- Maintained primarily by the User and Team Management backend team.
-- Logs are generated via NestJS's internal logging and passed through to centralized error monitoring.
-
-### 4. Code Structure
-
-- **`apps/api/src/user-management/services/settings.service.ts`**
-  - Implements `SettingsService` providing methods:
-    - `getTeamGeneralSettings(teamId)`
-    - `getTeamInsightsSettings(teamId)`
-    - `updateTeamGeneralSettings(teamId, settings)`
-    - `updateTeamInsightsSettings(teamId, settings)`
-    - `updateTeamSettings(teamId, settings)`
-    - `getShopSettings(teamId)`
-    - `saveShopSettings(teamId, shopSettings)`
-  - Uses `teamRepository` injected via TypeORM.
-  - Throws `GenieException` for error scenarios.
-
-- **`apps/api/src/user-management/controllers/teams.controller.ts`**
-  - Defines REST endpoints prefixed with `/teams`.
-  - Endpoints include GET and PUT for team settings, management of team members, invitations, and deactivation.
-  - Uses request validation through `ZodValidationPipe` with strict DTO schemas.
-  - Checks for user membership and admin role authorization.
-
-- **`apps/api/src/user-management/entities/team.entity.ts`**
-  - Defines the `TeamEntity` mapped to the underlying database `team` table.
-  - Stores business and insights settings as JSON columns.
-  - Fields include shopify integration credentials, timezone, currency, onboarding progress, enabled status.
-  - Provides methods `getCompleteGeneralSettings()` and `hasOnboarded()`.
-  
-#### Example snippet from `SettingsService` update:
-```ts
-async updateTeamSettings(teamId: string, settings: TeamSettingsDto) {
-  const { businessName: name, ...generalSettings } = settings.general;
-  const { averageDailySalesPeriodDays, stockLevels, grading } = settings.insights;
-
-  await this.teamRepository.update(teamId, {
-    name,
-    generalSettings,
-    averageDailySalesPeriodDaysSetting: averageDailySalesPeriodDays,
-    stockLevelsSettings: stockLevels,
-    ...(grading ? {
-      inventoryItemGradingPeriodDaysSetting: grading.periodDays,
-      inventoryItemGradingStrategySetting: grading.strategy,
-      inventoryItemGradingLevelAThresholdSetting: grading.levelAThreshold,
-      inventoryItemGradingLevelBThresholdSetting: grading.levelBThreshold,
-      inventoryItemGradingLevelCThresholdSetting: grading.levelCThreshold,
-    } : {}),
-  });
-}
-```
-
-### 5. API and Interfaces
-
-- **Endpoints exposed by `TeamsController`:**
-
-| Method | Path                     | Description                               | Auth Required          | Body DTO                               |
-|--------|--------------------------|-------------------------------------------|-----------------------|---------------------------------------|
-| PUT    | `/teams/settings`         | Update complete team settings (general + insights) | User must belong to team | `TeamSettingsDto`                      |
-| PUT    | `/teams/settings/general` | Update general team settings only         | User must belong to team | `TeamGeneralSettingsDto`               |
-| GET    | `/teams/settings/general` | Retrieve general settings                 | User must belong to team | None                                  |
-| PUT    | `/teams/settings/insights`| Update insights settings                   | User must belong to team | `InsightsSettingsDto`                  |
-| GET    | `/teams/settings/insights`| Retrieve insights settings                 | User must belong to team | None                                  |
-| GET    | `/teams/settings/shop`    | Fetch shop currency and timezone settings | User must belong to team | None                                  |
-| POST   | `/teams/send-invitations` | Send team member invitations               | User must belong to team | `SendInvitationsRequestDto`           |
-| PATCH  | `/teams/user/:id/deactivate` | Deactivate a team user (admin only)    | User must be Admin       | None                                  |
-| DELETE | `/teams/invitations/:email` | Remove invitation by email               | User must belong to team | None                                  |
-| POST   | `/teams/accept-invitation` | Accept a team invitation (public)          | Public                  | `AcceptInvitationRequestDto`          |
-
-- **Error Modes:**
-  - Throws `GenieException` with contextual info.
-  - Specific cases: user without team, unsupported grading strategy.
-
-### 6. Environment & Configuration
-
-- No direct environment variables are required solely for this service.
-- Depends on database connection configured globally for TypeORM.
-- Uses shared DTOs and enums from the `@genie/shared` package.
-
-### 7. Testing, Monitoring, and Deployment
-
-- The service is tested through unit and integration tests leveraging NestJS testing modules (not shown in detail).
-- Logs exceptions via NestJS Logger and captures errors with `captureException` utility.
-- Throws domain-specific exceptions to simplify error handling.
-
-### 8. Troubleshooting & Known Issues
-
-- **SalesFrequency Grading Strategy Unsupported:** Attempting to use the `SalesFrequency` inventory grading strategy will throw an exception.
-- **User Without Team:** All team-related endpoints require authenticated users associated with a team; missing this triggers an exception.
-- **Only Admins Can Deactivate Users:** User deactivation requires admin role check enforced in controller.
-
-### 9. Style and Terminology Guidelines
-
-- Use `TeamEntity` when referring to the database team record.
-- Settings are split into `generalSettings`, `insightsSettings`, and `shopSettings`.
-- DTOs follow strict Zod schemas to enforce API contracts.
-
----
-
-### References
-- [SettingsService Source](apps/api/src/user-management/services/settings.service.ts)
-- [TeamsController Source](apps/api/src/user-management/controllers/teams.controller.ts)
-- [TeamEntity Source](apps/api/src/user-management/entities/team.entity.ts)