@clidey/dory 0.1.0 → 0.2.0

package/docs/overview/product-intro/core-concepts.mdx

@@ -1,267 +0,0 @@
----
-title: 'Core Concepts & Terminology'
-description: 'Internal definitions, key domain concepts, and important terminology consistent across the codebase and documentation.'
----
-
-## Core Concepts & Terminology
-
-This document provides an in-depth technical overview of key concepts, entities, and modules within the Product Information Management (PIM) domain and its integration points within the Genie system. It serves as a reference for developers working with product, inventory, and supplier data, clarifying terminology and architectural boundaries.
-
----
-
-### 1. Overview
-
-The PIM module handles the management of product variants, inventory, suppliers, collections, and related entities. It integrates deeply with other subsystems including Sales Orders, Shopify, User Management, Purchase Orders, and Tracking, supporting the core workflows of product inventory and vendor management.
-
-The PIM module's responsibilities include:
-
-- Managing product and variant data, including Shopify synchronization and tagging.
-- Tracking inventory items, their locations, histories, and sales metrics.
-- Handling product-supplier relationships, including variant-level supplier mappings and pricing.
-- Coordinating with external services such as Shopify for real-time webhook syncs and sales orders.
-- Providing APIs and services consumed by UI workflows and other microservices.
-
-### 2. Architectural Context and Boundaries
-
-- The PIM module encapsulates all product, variant, inventory, location, and supplier-related domain logic primarily within itself.
-- It acts as a backbone for the Genie application’s supply chain and inventory management capabilities.
-- It exposes services for syncing insights, scheduled tasks, and data snapshotting.
-- It connects to external platforms such as Shopify (via the Shopify module) and internal modules like Sales Order, Purchase Order, Workflow, and User Management.
-
-### 3. Technical Overview
-
-#### Main Components
-
-- **Entities**: Core database models using TypeORM representing products, variants, inventory items, suppliers, locations, collections, and related domain objects.
-- **Services**: Business logic layers managing CRUD, batch processing, syncing operations, and data mappings.
-- **Controllers**: REST API endpoints for managing products, inventory, locations, saved views, and dashboard queries.
-
-#### Key Dependencies
-
-- **TypeORM**: ORM framework for database interaction.
-- **NestJS**: Framework organizing the module via controllers, providers, and dependency injection.
-- **External Modules**: Shopify (integration and syncing), Sales Order, Purchase Order, Slack, Email, User Management, Comment, Asset, Tracking, Workflow, and Billing.
-
-### 4. Core Concepts and Data Model Glossary
-
-| Term                                | Description                                                                                                   |
-|------------------------------------|---------------------------------------------------------------------------------------------------------------|
-| **Product**                        | Represents a merchant's item catalog entry, linked to Shopify products, identified by `shopifyId` and team.     |
-| **Product Variant**                | A specific version of a product, differing by options (e.g., size, color).                                    |
-| **Inventory Item**                 | Physical stock unit linked to a product variant and its location, maintaining quantity and history.             |
-| **Location**                      | Physical or logical stock storage place, uniquely tied to a team and Shopify location ID.                      |
-| **Supplier**                      | Vendor entity supplying products, including contact info and payment terms.                                    |
-| **Product Supplier**              | Junction entity linking products with suppliers. Can denote primary suppliers.                                 |
-| **Product Supplier Variant**      | Links a product supplier to specific product variants, storing unit price and supplier SKU.                    |
-| **Collection**                   | Grouping of products, often used for categorization or marketing.                                             |
-| **Product Variant Component**     | Used for representing bundled or composed products where variants have child components.                        |
-| **Inventory Item History**        | Time-series data tracking inventory metrics such as quantity, sales velocity, and related attributes.          |
-| **Saved View**                   | User-customizable saved filters or views for data presentation.                                               |
-| **Stock Levels Settings**         | Configuration for stock level management on a product, stored as JSON metadata.                                |
-
-### 5. Detailed Conceptual Definitions
-
-#### ProductEntity
-- Uniquely identified by a team-scoped UUID and a Shopify product ID (`shopifyId`).
-- Maintains fields such as `title`, `shopifyVendor`, `shopifyStatus`, publication timestamps, tags, and synchronization metadata.
-- Relationships with `variants` (product variants) and `suppliers`.
-- Supports soft deletion with a `deletedAt` timestamp.
-- Stores stock level configuration in JSON format.
-
-#### ProductVariantEntity (Referenced indirectly)
-- Represents the individual variant of a product.
-- Supports tagging and components indicating sub-parts if part of bundles.
-
-#### InventoryItemEntity and InventoryItemHistoryEntity
-- Inventory items represent stock of a variant at a given location.
-- Inventory item history maintains daily snapshots and metrics, including sales velocity, quantities, incoming stock, and grading.
-- Tracks if the item is marked as a favorite and relevant retail/cost values.
-
-#### LocationEntity
-- Represents physical or virtual stock storage points.
-- Includes address details encapsulated in a JSON `info` field.
-- Linked uniquely to a team and Shopify location ID.
-- Includes flags such as `isDefault` and `isSynced` to manage location state and integration.
-
-#### SupplierEntity
-- Describes supplier with contact details, lead time, minimum order quantities, payment terms (upfront, net days, installments), and operational metadata.
-- Payment terms are managed via related entities to encapsulate different terms.
-- Maintains relationships to products and purchase orders.
-
-#### ProductSupplierEntity and ProductSupplierVariantEntity
-- Junction tables linking suppliers with products and product variants respectively.
-- Flag for primary suppliers at the product level.
-- Variant-level mapping includes pricing and supplier SKU.
-
-#### ProductVariantComponentEntity
-- Defines hierarchical relationships between variants when products are bundled or composed of multiple variants.
-- Supports quantity mapping of child components.
-
-### 6. Key Services and Providers
-
-- **ProductsService** & **ProductsMappingService**: Handles product and variant data operations including mappings.
-- **InventoryService** & **InventorySalesMetricsService**: Manages inventory levels, history, and sales-related metrics.
-- **LocationsService**: Manages stock location data.
-- **IdeaProductsService**: Specialized service for managing proposed or conceptual product entities.
-- **SavedViewService**: Provides management of persisted user views.
-- **DashboardService**: Aggregates and provides dashboard-relevant data.
-- **InsightsSyncService** and related Consumers: Handles data synchronization with external analytics and reporting services.
-
-### 7. Integration Points
-
-- **ShopifyModule**: Importing and syncing product, variant, location, and inventory data using webhooks and APIs.
-- **SalesOrderModule**: Coordinating product sales data.
-- **PurchaseOrderModule**: Handling procurement and supply chain purchase orders.
-- **UserManagementModule**: Managing team and user ownership of product and supplier data.
-
-### 8. System Boundaries
-
-- PIM module operates within Genie backend API, exposing RESTful API controllers.
-- External communication for Shopify synchronization is delegated via the Shopify integration.
-- Internal modules rely on PIM services for product and supplier data operations.
-
----
-
-## Code Structure and Key Files
-
-- **`pim.module.ts`**
-  - Defines module imports, controllers, providers, and exports.
-  - Key imports include TypeOrm entities representing core domain models.
-  - Uses `forwardRef` to resolve circular dependencies with SalesOrder and Shopify modules.
-
-- **Entities**
-  - `product.entity.ts`: Core product data.
-  - `product-variant.entity.ts`: Variants of a product.
-  - `inventory-item.entity.ts` and `inventory-item-history.entity.ts`: Current stock and historical records.
-  - `location.entity.ts`: Stock locations.
-  - `supplier.entity.ts`: Supplier data.
-  - `product-supplier.entity.ts`, `product-supplier-variant.entity.ts`: Supplier-product relationships.
-  - `product-variant-component.entity.ts`: Components representing product bundles.
-
-- **Controllers**
-  - Handle HTTP requests for product, inventory, locations, saved views, dashboard, idea products, and product-supplier mappings.
-
-- **Services**
-  - Implement business logic for each domain, including synchronization, metrics, favorites, and scheduled background tasks.
-
----
-
-## Example Entity Snippet: LocationEntity
-```ts
-@Entity("location")
-@Index(["teamId", "shopifyId"], { unique: true })
-export class LocationEntity extends BaseEntity {
-  @Index()
-  @Column({ type: "uuid" })
-  teamId!: string;
-
-  @ManyToOne(() => TeamEntity, { onDelete: "CASCADE" })
-  team?: TeamEntity;
-
-  @Column({ type: "bigint", transformer: BigIntTransformer })
-  shopifyId!: number;
-
-  @Column({ type: "character varying", nullable: true })
-  name?: string | null;
-
-  @Column({ type: "jsonb" })
-  info!: LocationInfo;
-
-  @OneToMany(() => ProductVariantLocationEntity, (entity) => entity.location)
-  productVariants?: ProductVariantLocationEntity[];
-
-  @Column()
-  isDefault!: boolean;
-
-  @Column({ type: "boolean", default: true })
-  isSynced!: boolean;
-
-  @Index()
-  @DeleteDateColumn()
-  deletedAt?: Date;
-}
-```
-
----
-
-## Mermaid Diagram: PIM Module Architecture
-
-```mermaid
-flowchart TD
-  subgraph "PIM Module"
-    ProductsService["ProductsService"]:::service
-    InventoryService["InventoryService"]:::service
-    LocationsService["LocationsService"]:::service
-    SuppliersService["SuppliersService"]:::service
-    SavedViewService["SavedViewService"]:::service
-    DashboardService["DashboardService"]:::service
-    ProductsController["ProductsController"]:::controller
-    InventoryController["InventoryController"]:::controller
-    LocationsController["LocationsController"]:::controller
-    SuppliersController["SuppliersController"]:::controller
-  end
-
-  subgraph "Entities"
-    ProductEntity["ProductEntity"]:::entity
-    ProductVariantEntity["ProductVariantEntity"]:::entity
-    InventoryItemEntity["InventoryItemEntity"]:::entity
-    InventoryItemHistoryEntity["InventoryItemHistoryEntity"]:::entity
-    LocationEntity["LocationEntity"]:::entity
-    SupplierEntity["SupplierEntity"]:::entity
-    ProductSupplierEntity["ProductSupplierEntity"]:::entity
-    ProductSupplierVariantEntity["ProductSupplierVariantEntity"]:::entity
-    ProductVariantComponentEntity["ProductVariantComponentEntity"]:::entity
-  end
-
-  subgraph "External Modules"
-    ShopifyModule["ShopifyModule"]:::module
-    SalesOrderModule["SalesOrderModule"]:::module
-    PurchaseOrderModule["PurchaseOrderModule"]:::module
-    UserManagementModule["UserManagementModule"]:::module
-    TrackingModule["TrackingModule"]:::module
-  end
-
-  %% Relationships
-  ProductsController -->|"uses"| ProductsService
-  InventoryController -->|"uses"| InventoryService
-  LocationsController -->|"uses"| LocationsService
-  SuppliersController -->|"uses"| SuppliersService
-  ProductsService -->|"manages"| ProductEntity
-  ProductsService -->|"manages"| ProductVariantEntity
-  InventoryService -->|"manages"| InventoryItemEntity
-  InventoryService -->|"manages"| InventoryItemHistoryEntity
-  LocationsService -->|"manages"| LocationEntity
-  SuppliersService -->|"manages"| SupplierEntity
-  SuppliersService -->|"manages"| ProductSupplierEntity
-  SuppliersService -->|"manages"| ProductSupplierVariantEntity
-  ProductsService -->|"manages"| ProductVariantComponentEntity
-
-  %% Cross-Module Dependencies
-  ProductsService -->|"calls"| ShopifyModule
-  InventoryService -->|"calls"| SalesOrderModule
-  SuppliersService -->|"calls"| PurchaseOrderModule
-  SuppliersService -->|"calls"| UserManagementModule
-  InventoryService -->|"calls"| TrackingModule
-
-  %% Click Events
-  click ProductsModule "apps/api/src/pim/pim.module.ts"
-  click ProductEntity "apps/api/src/pim/entities/product.entity.ts"
-  click ProductVariantEntity "apps/api/src/pim/entities/product-variant.entity.ts"
-  click InventoryItemEntity "apps/api/src/pim/entities/inventory-item.entity.ts"
-  click InventoryItemHistoryEntity "apps/api/src/pim/entities/inventory-item-history.entity.ts"
-  click LocationEntity "apps/api/src/pim/entities/location.entity.ts"
-  click SupplierEntity "apps/api/src/supplier/entities/supplier.entity.ts"
-  click ProductSupplierEntity "apps/api/src/pim/entities/product-supplier.entity.ts"
-  click ProductSupplierVariantEntity "apps/api/src/pim/entities/product-supplier-variant.entity.ts"
-  click ProductVariantComponentEntity "apps/api/src/pim/entities/product-variant-component.entity.ts"
-  click ShopifyModule "apps/api/src/shopify"
-  click SalesOrderModule "apps/api/src/sales-order"
-  click PurchaseOrderModule "apps/api/src/purchase-order"
-  click UserManagementModule "apps/api/src/user-management"
-  click TrackingModule "apps/api/src/tracking"
-
-  classDef service fill:#f9f,stroke:#333,stroke-width:2px
-  classDef controller fill:#bbf,stroke:#333,stroke-width:2px
-  classDef entity fill:#bfb,stroke:#333,stroke-width:2px
-  classDef module fill:#ffd700,stroke:#333,stroke-width:2px
-```

package/docs/platform-admin/billing-subscriptions/billing.mdx

@@ -1,176 +0,0 @@
----
-title: 'Billing & Plans'
-description: 'Details on plan selection, subscription management, and billing integration.'
----
-
-## Billing & Plans Module Documentation
-
----
-
-### 1. Purpose and Scope
-
-The Billing & Plans module manages subscription plans and billing interactions for users within the Genie platform. It facilitates plan selection, subscription management, and billing interval adjustments. This component enables users to view and upgrade their current subscription plans, handles plan-related UI interactions, and integrates with the Mantle billing service.
-
-**System boundaries and architectural context:**
-- This module is part of the Platform & Administration layer responsible for billing and subscription management.
-- It interfaces with the Mantle client library (`@heymantle/react`), which provides hooks like `useMantle` for accessing plans, subscriptions, and subscription mutations.
-- It interacts with routing (`next/router`) and authentication context to manage user state.
-- The component is implemented in React with hooks and integrated into the settings page UI under billing controls.
-
-
-### 2. Technical Overview
-
-The Billing & Plans module consists primarily of UI React components that:
-- Display the current active plan for a team (`TeamActivePlanCard`).
-- Present a modal dialog (`PlanSelectionModal`) for users to select a subscription plan and billing interval.
-
-The module relies on Mantle API hooks (`useMantle`) for retrieving plans and subscriptions, subscribing users to selected plans, and refetching subscription data post-actions.
-
-The subscription flow includes:
-- Rendering the user's current plan in `TeamActivePlanCard` with option to upgrade.
-- Displaying selectable plans filtered by billing interval in `PlanSelectionModal`.
-- Managing form state with `react-hook-form` to select plans and billing intervals.
-- Triggering the Mantle `subscribe` mutation when the user submits a selection.
-- Handling redirection to confirmation URLs or returning to the billing settings tab upon subscription success.
-
-#### Key Technologies and Patterns
-- React functional components with hooks (`useForm`, `useWatch`) for state and form management.
-- Mantle React SDK for billing logic integration.
-- Next.js routing utilities for programmatic navigation.
-- Controlled components pattern for form inputs.
-- UI composition with custom reusable components (`Modal`, `Button`, `Radio`, `Typography`, etc.).
-
-
-### 3. Core Concepts and Responsibilities
-
-- **Plans:** A subscription offering defined by ID, name, billing interval (`EVERY_30_DAYS` or `ANNUAL`), price, currency, and optional description.
-- **Subscription:** The current user’s active subscription, includes the plan and payment status.
-- **Billing Intervals:** Differ between monthly (`EVERY_30_DAYS`) and annual (`ANNUAL`) billing cycles.
-- **Plan Selection Modal:** Enables users to select and subscribe to plans filtered by chosen billing interval.
-- **Subscription Flow:** Handled via Mantle `subscribe` method with automatic redirection to external payment confirmation or immediate update.
-
-**Ownership & Logging:**
-- UI components logging is minimal as this module focuses on user interaction.
-- Mantle service manages backend billing workflows and errors.
-
-
-### 4. Code Structure
-
-| File | Description |
-|-------|-------------|
-| `apps/web/src/components/jasmine/billing/plan-selection-modal/index.tsx` | Implements the plan selection modal component with billing interval selector and plan cards. Handles subscription mutation and routing post-selection. |
-| `apps/web/src/components/jasmine/billing/plan-selection-modal/plan-card.tsx` | Renders individual selectable plan cards including name, description, pricing, and current plan indicator. |
-| `apps/web/src/components/jasmine/billing/plan-selection-modal/billing-interval-select.tsx` | Dropdown component for selecting billing interval (Monthly or Yearly). |
-| `apps/web/src/components/jasmine/billing/team-active-plan-card.tsx` | Displays the currently active team plan with details and an 'Upgrade Plan' call to action. |
-| `apps/web/src/components/pages/settings/plans-and-billing-settings.tsx` | Top-level page component that shows the active plan card and controls opening the plan selection modal. |
-
-**Key component snippet from plan-selection-modal:**
-
-```tsx
-// Default form values set based on available plans or current subscription
-const {
-  control,
-  handleSubmit,
-  resetField,
-  reset,
-  formState: { isSubmitting, isLoading },
-} = useForm<FormFields>({
-  defaultValues: {
-    selectedPlan: plans.find(p => p.interval === 'EVERY_30_DAYS')?.id || subscription?.plan.id,
-    billingInterval: 'EVERY_30_DAYS',
-  },
-});
-
-// Filter plans visible based on selected billing interval or free plans
-const filteredPlans = plans
-  .filter(plan => plan.interval === watchBillingInterval || plan.amount === 0)
-  .sort((a, b) => a.interval === 'EVERY_30_DAYS' ? -1 : b.interval === 'EVERY_30_DAYS' ? 1 : 0);
-
-// On form submit, execute subscription mutation and handle redirects
-await subscribe({ planId: selectedPlan, returnUrl });
-```
-
-
-### 5. API and Interfaces
-
-#### Subscribed Functions
-- `subscribe({ planId: string, returnUrl: string }) => Promise<{ confirmationUrl?: string }>`
-  - Initiates the subscription to a selected plan.
-  - If `confirmationUrl` is provided, the client redirects the user for payment or confirmation.
-
-#### Forms
-- `selectedPlan` (string): The unique ID of the selected plan.
-- `billingInterval` (`EVERY_30_DAYS` | `ANNUAL`): The chosen subscription recurrence period.
-
-#### Failure modes
-- Subscription mutation may fail or return an error (not explicitly handled in UI, fallback to Mantle error handling).
-- No fallback UI is described for failures or loading errors beyond button disabling and loading state.
-
-
-### 6. Environment & Configuration
-
-- No explicit environment variables or secrets are required by the frontend module beyond those configured globally for Mantle and Next.js.
-- The backend Mantle service (not detailed here) handles billing API calls and subscriptions.
-
-
-### 7. Testing, Monitoring, and Deployment
-
-- Specific tests for the Billing & Plans UI are not detailed in the provided context.
-- Loading states and controlled form validations are implemented to manage UX during asynchronous calls.
-- Monitoring and errors during subscription are managed downstream in Mantle and API layers.
-
-
-### 8. Troubleshooting & Known Issues
-
-- No documented known issues or specific troubleshooting guides exist in the current context.
-- UI disables subscription button if the selected plan matches the current subscription plan to prevent redundant submissions.
-
-
-### 9. Integration Details
-
-This module tightly integrates:
-- With the Mantle billing service for fetching plans and managing subscriptions.
-- With Next.js routing to redirect users after subscription actions.
-- With authentication context to personalize UI (e.g., displaying user initials).
-
-The common integration pattern is user-initiated plan changes within the app settings UI, backed by Mantle API calls, with smooth UI updates upon success.
-
-
----
-
-## Mermaid Diagram: Billing & Plans Module Architecture
-
-```mermaid
-flowchart TD
-  subgraph UI
-    SettingsPage["Plans & Billing Settings Page"]:::ui
-    ActivePlanCard["TeamActivePlanCard"]:::ui
-    PlanModal["PlanSelectionModal"]:::ui
-    BillingIntervalSelect["BillingIntervalSelect"]:::ui
-    PlanCard["PlanCard (Selectable Plan Cards)"]:::ui
-  end
-
-  subgraph Services
-    Mantle["Mantle Billing Service"]:::service
-    AuthContext["Auth Context"]:::service
-    Router["Next.js Router"]:::service
-  end
-
-  SettingsPage -->|"shows current plan"| ActivePlanCard
-  SettingsPage -->|"opens modal"| PlanModal
-  PlanModal --> BillingIntervalSelect
-  PlanModal --> PlanCard
-  PlanModal -->|"uses hook"| Mantle
-  PlanModal -->|"uses auth info"| AuthContext
-  PlanModal -->|"redirect after subscribe"| Router
-
-  classDef ui fill:#f9f9f9,stroke:#77aaff,color:#222,stroke-width:1px;
-  classDef service fill:#cde9ff,stroke:#005aee,color:#03396c,stroke-width:2px;
-
-  click SettingsPage "apps/web/src/components/pages/settings/plans-and-billing-settings.tsx"
-  click ActivePlanCard "apps/web/src/components/jasmine/billing/team-active-plan-card.tsx"
-  click PlanModal "apps/web/src/components/jasmine/billing/plan-selection-modal/index.tsx"
-  click BillingIntervalSelect "apps/web/src/components/jasmine/billing/plan-selection-modal/billing-interval-select.tsx"
-  click PlanCard "apps/web/src/components/jasmine/billing/plan-selection-modal/plan-card.tsx"
-
-```

package/docs/platform-admin/system-maintenance/db-migrations.mdx

@@ -1,184 +0,0 @@
----
-title: 'Database Migrations & Seeding'
-description: 'How to manage database schema migrations and seed the database with initial or demo data.'
----
-
-# Database Migrations & Seeding
-
-## Purpose and Scope
-
-This document provides detailed technical guidance on managing database migrations and seeding for the Genie application. It covers how to create, generate, run, and revert database schema migrations using TypeORM tools integrated into the project, alongside instructions for initializing and seeding the local database. This module is essential for maintaining the PostgreSQL database schema consistency across development, staging, and production environments.
-
-The migration system is part of the back-end API built with NestJS and operates within the PostgreSQL database context managed via Docker.
-
-## Technical Overview
-
-Database migrations in Genie are handled through TypeORM's CLI commands, orchestrated via Yarn scripts. Migrations ensure database schema evolves reliably along with application code changes. Seed commands reset the database, apply all migrations, and populate the database with required initial data.
-
-A dedicated migration class specifically addresses Purchase Orders, handling complex content version migrations in a paginated manner for scalability.
-
-## Key Features
-
-- Creation and generation of new database migrations.
-- Execution and reversion of migrations.
-- Seeding of the local development database with initial data.
-- Migration of complex domain entities with version control.
-
-## Setup and Configuration
-
-Before working with migrations, ensure the PostgreSQL database is running locally using Docker Compose as described in the installation guide. Ensure all necessary users are created in the database with appropriate privileges.
-
-Fill in the `.env` file with correct credentials corresponding to each database user.
-
-## Migration Commands
-
-### Create a Migration
-
-Creates a blank migration file for manual editing.
-
-```bash
-yarn typeorm:create <MigrationName>
-```
-
-Replace `<MigrationName>` with a descriptive name, e.g., `AddNewTable`.
-
-### Generate a Migration
-
-Automatically generates a migration reflecting entity changes.
-
-```bash
-yarn typeorm:generate <MigrationName>
-```
-
-Replace `<MigrationName>` appropriately.
-
-### Run Migrations
-
-Apply all pending migrations to the database.
-
-```bash
-yarn typeorm:run
-```
-
-### Revert Last Migration
-
-Undo the last applied migration, reverting schema changes.
-
-```bash
-yarn typeorm:revert
-```
-
-## Seeding Local Database
-
-To reset and populate the local database with initial data, run:
-
-```bash
-yarn cmd seed-data
-```
-
-This command drops the current schema, reapplies all migrations, and seeds essential data required for local development and testing.
-
-## Purchase Orders Migration
-
-The `PurchaseOrdersMigration` service manages migration of purchase order records to keep content schemas up-to-date with the current version. It:
-
-- Iterates over purchase orders with versions older than the current defined version.
-- Loads migration functions from the migrations directory.
-- Applies migrations sequentially to the content field.
-- Saves updated purchase orders with the new version.
-- Logs errors and captures exceptions without failing the entire migration process.
-
-This approach handles large datasets efficiently by paginating through records in batches of 1000.
-
-### Code Snippet (Migration Process Entry Point)
-
-```ts
-@Injectable()
-export class PurchaseOrdersMigration implements Migration {
-  private readonly logger = new Logger(PurchaseOrdersMigration.name);
-
-  constructor(
-    @InjectRepository(PurchaseOrderEntity)
-    private purchaseOrderRepository: Repository<PurchaseOrderEntity>
-  ) {}
-
-  async migrate() {
-    const migrateFns = await this.getMigrateFns();
-    const pageSize = 1000;
-    let page = 0;
-    let purchaseOrders;
-
-    do {
-      purchaseOrders = await this.purchaseOrderRepository.find({
-        where: { version: LessThan(PURCHASE_ORDER_CURRENT_VERSION) },
-        skip: page * pageSize,
-        take: pageSize,
-      });
-
-      await Promise.all(
-        purchaseOrders.map(po => this.migratePurchaseOrder(po, migrateFns))
-      );
-
-      page++;
-    } while (purchaseOrders.length === pageSize);
-  }
-
-  private async migratePurchaseOrder(po: PurchaseOrderEntity, migrateFns: MigrateFn[]) {
-    try {
-      if (po.version === migrateFns.length) return;
-      po.content = await this.migrateSequentially(po.version, po.content, migrateFns);
-      po.version = migrateFns.length;
-      await this.purchaseOrderRepository.save(po);
-    } catch (error) {
-      this.logger.error(`Failed to migrate purchase order: ${po.id}`);
-      captureException({ error, purchaseOrderEntity: JSON.stringify(po, null, 2) });
-    }
-  }
-}
-```
-
-## Database Integration & Access
-
-- The PostgreSQL database runs inside a Docker container, controlled via `docker-compose up -d`.
-- Use `docker ps` to identify the container ID and `docker logs <container-id>` to view database logs.
-- To enter the database shell:
-
-```bash
-docker exec -it <container-id> bash
-psql -U postgres
-```
-
-- To stop the database container:
-
-```bash
-docker-compose down
-```
-
-## Database View Migrations
-
-Several migration scripts create or modify SQL views (e.g., `inventory_item`, `inventory_sales_metrics`) to reflect updated business logic, such as adding columns, views, indexes, or changing table structures.
-
-### Important Database Views
-
-- **inventory_item**: Aggregates detailed inventory item information across products, variants, suppliers, and locations.
-- **inventory_sales_metrics**: Provides sales metrics for active product variants over configurable periods, supporting grading strategies.
-
-These views get updated as part of migrations to align with evolving application analytics and reporting requirements.
-
-## Best Practices
-
-- Always create descriptive migration names that clearly indicate the schema change.
-- Confirm migrations run successfully in a development environment before applying to staging or production.
-- Use the `seed-data` command during initial setup or when resetting the local database to maintain consistent test data.
-- Monitor migration logs for errors, especially in batch operations like purchase order migrations.
-
-## References
-
-- [TypeORM Migrations Documentation](https://typeorm.io/migrations)
-- Purchase orders migration entry: [purchase-orders.migration.ts](apps/api/src/migrations/purchase-orders/purchase-orders.migration.ts)
-
----
-
-For detailed schema changes, view the individual migration files under `apps/api/src/migrations/db`.
-
----