@clidey/dory 0.1.0 → 0.3.0

package/docs/usage/ui-workflows/onboarding.mdx

@@ -1,215 +0,0 @@
----
-title: 'User Onboarding'
-description: 'Step-by-step user onboarding workflow including product syncing, bundle mapping, excluding products, and favorite products setup.'
----
-
-# User Onboarding - Internal Developer Documentation
-
-## 1. Purpose and Scope
-
-The **Onboarding** functionality orchestrates the initial setup flow for new teams and users within Genie. It ensures teams are properly configured with products, bundles, purchase orders, and settings necessary for smooth operation. This service-driven onboarding process allows new users to start using Genie effectively and ensures the backend tracks and verifies onboarding progress to completion.
-
-**System Boundaries and Context:**
-- The onboarding service is primarily part of the backend API layer under `setup/services/onboarding.service.ts`.
-- It interacts closely with user and team management services, Shopify integration components, product management, purchase order services, workflow services, and notification components.
-- It manages persistent onboarding state stored in the database (`OnboardingProgressEntity` and related entities).
-
-This module is critical for initializing and validating new team environments and monitoring onboarding status to drive the user onboarding UI and workflows.
-
-## 2. Technical Overview
-
-### Architectural Placement
-
-Onboarding is implemented as a NestJS injectable service (`OnboardingService`) that encapsulates business logic related to onboarding progress and related workflows.
-
-It consumes the following key dependencies:
-- `TeamsService` for user and team context and updates
-- `ShopifyStoreService` for store details and status
-- `ProductsService` and `ShopifyProductsService` for product data syncing and variants counts
-- `PurchaseOrdersService` to manage purchase order data syncing and notifications
-- `WorkflowService` to trigger bundle mapping workflows
-- `SlackService` and tracking services for notifications and telemetry
-
-A high-level data and interaction flow is as follows:
-- Onboarding progress is stored and updated in `OnboardingProgressEntity`
-- The service runs data sync flows to import products, orders, and settings from Shopify
-- Tracks confirmation steps users complete (e.g., settings, grading, suppliers)
-- Onboarding completion triggers enabling the team and initializing webhook registrations
-- Manages bundle products and purchase order import tracking
-- Provides APIs for front-end to query progress and update steps
-
-
-```mermaid
-flowchart TD
-  subgraph Backend API
-    O["OnboardingService"]:::service
-    T["TeamsService"]:::service
-    SS["ShopifyStoreService"]:::service
-    PS["ProductsService"]:::service
-    PO["PurchaseOrdersService"]:::service
-    WF["WorkflowService"]:::service
-    SL["SlackService"]:::service
-    JWT["JWT Service"]:::service
-  end
-
-  DB["Database (Postgres Entities)"]:::database
-
-  subgraph User Management
-    U["UserEntity"]:::entity
-    TM["TeamEntity"]:::entity
-  end
-
-  subgraph Shopify Integration
-    SP["ShopifyStore"]:::external
-    SPProd["Shopify Products"]:::external
-  end
-
-  UI["Onboarding UI"]:::frontend
-
-  UI -->|queries| O
-  O -->|uses| T
-  O -->|uses| SS
-  O -->|uses| PS
-  O -->|uses| PO
-  O -->|uses| WF
-  O -->|uses| SL
-  O -->|updates| DB
-  T -->|manages| TM
-  T -->|manages| U
-  SS --> SP
-  PS --> SPProd
-
-  classDef service fill:#6fcf97,stroke:#2d6a4f,color:#fff,stroke-width:1px
-  classDef database fill:#ffd6a5,stroke:#b06500,color:#000,stroke-width:1px
-  classDef entity fill:#f9c74f,stroke:#f9844a,color:#000,stroke-width:1px
-  classDef external fill:#90e0ef,stroke:#0077b6,color:#000,stroke-width:1px
-  classDef frontend fill:#f72585,stroke:#9d174d,color:#fff,stroke-width:1px
-
-  click O "apps/api/src/setup/services/onboarding.service.ts"
-  click T "apps/api/src/user-management/services/teams.service.ts"
-
-```
-
-## 3. Core Concepts and Responsibilities
-
-- **Onboarding Progress Tracking:** Maintains persistent state per team of which onboarding steps have been completed and which required data syncs are done.
-- **Data Sync:** Triggers asynchronous data import flows for Shopify products, purchase orders, and settings to prepare the environment.
-- **Step Confirmation:** Tracks user confirmations of key setup steps such as insights settings, grading, suppliers, orders import, favorites, exclusions, bundle setup, and final completion.
-- **Invitation and User Management:** Managed by `TeamsService` with invitations, user creation/assignment, and deactivation as part of onboarding.
-- **Bundle Products:** Supports onboarding flows for identifying and mapping bundle products.
-- **Notifications & Tracking:** Integrates with Slack service and internal tracking events to alert admins and monitor progress.
-
-### Ownership & Maintenance
-- Owned by backend platform team - service located in `setup/services/onboarding.service.ts`.
-- Logs errors and exceptions via the logger and centralized capture mechanisms.
-
-### Non-Functional Requirements
-- **Reliability:** Onboarding flows support resuming after outages or server restarts (`resumeOnboardingProgressFlows`).
-- **Performance:** Implements deduplicated job queues for long-running syncs.
-- **Security:** Access to updating onboarding state requires authenticated user's team context.
-
-## 4. Code Structure
-
-### Key Files
-- `apps/api/src/setup/services/onboarding.service.ts`
-  - Core business logic and state management
-  - Integrates with all other services mentioned
-- `apps/api/src/setup/controllers/onboarding.controller.ts`
-  - REST API layer exposing onboarding endpoints
-  - Validates user team context before delegating to service
-- `apps/api/src/user-management/services/teams.service.ts`
-  - Manages user invitations, team users, and onboarding step updates
-
-### Important Code Excerpt - Progress Retrieval
-```ts
-async getProgress(teamId: string): Promise<GetOnboardingProgressResponseDto> {
-  const progress = await this.progressRepository.findOneOrFail({ where: { teamId } });
-  return {
-    steps: {
-      hasInsightSettingsStepConfirmed: progress.hasInsightSettingsStepConfirmed,
-      hasGradingStepConfirmed: progress.hasGradingStepConfirmed,
-      hasSuppliersStepConfirmed: progress.hasSuppliersStepConfirmed,
-      hasImportPurchaseOrdersStepConfirmed: progress.hasImportPurchaseOrdersStepConfirmed,
-      hasFavouriteProductsStepConfirmed: progress.hasFavouriteProductsStepConfirmed,
-      hasExcludeProductsStepConfirmed: progress.hasExcludeProductsStepConfirmed,
-      hasBundleMappingStepConfirmed: progress.hasBundleMappingStepConfirmed,
-      hasSetupCompleteStepConfirmed: progress.hasSetupCompleteStepConfirmed,
-    },
-    data: {
-      hasPimDataSynced: progress.hasPimDataSynced,
-      hasInitialOrdersDataSynced: progress.hasInitialOrdersDataSynced,
-    },
-  };
-}
-```
-
-### Entry Points and Main Flows
-- **Initialization:** `initOnboardingProgress(teamId)` - sets initial progress if none exists, checks variant count constraints.
-- **Progress Updates:** `updateProgressSteps(teamId, steps)` updates partial step confirmations and triggers completion check asynchronously.
-- **Completion:** `ensureCompletion(teamId)` called post-step confirmation and data sync to finalize onboarding.
-- **Data Sync:** `ensureDataSync(teamId)` triggers deduplicated workflow jobs to sync Shopify data.
-- **Resume:** `resumeOnboardingProgressFlows()` resumes all incomplete onboarding sync flows after downtime.
-
-## 5. API and Interfaces
-
-### Controller Endpoints (exposed via `/onboarding`)
-
-| Method | Path                      | Description                                | Request Body/Params                             | Response                       |
-|--------|---------------------------|--------------------------------------------|------------------------------------------------|--------------------------------|
-| GET    | /progress                 | Retrieve onboarding progress for user's team | Authenticated user context (teamId required)   | Onboarding progress DTO        |
-| PUT    | /progress                 | Update progress steps                       | Partial confirmation steps DTO                  | 204 No Content                 |
-| PUT    | /purchase-orders/import   | Update purchase order import URLs           | PurchaseOrdersImport DTO                         | 204 No Content                 |
-| GET    | /purchase-orders/import   | Get purchase order import URLs               | Authenticated user context                       | PurchaseOrdersImport DTO       |
-| PUT    | /bundle-products          | Update bundle products setup state          | BundleProducts DTO                               | 204 No Content                 |
-| GET    | /bundle-products          | Get bundle products                          | Authenticated user context                       | BundleProductsResponse DTO     |
-| GET    | /shopify-products-variants-count | Get count of Shopify product variants | Authenticated user context                       | Count DTO                     |
-| POST   | /setup-subscription       | Assign default plan/subscription             | Authenticated user context                       | Redirect URL DTO for payment  |
-
-### Validation
-- All inputs use Zod schemas for validation.
-- Requests require users to be assigned to a team; otherwise, exceptions are thrown.
-
-### Failure Modes & Edge Cases
-- Missing or invalid team associations cause errors.
-- Teams exceeding maximum allowed product variants are disabled automatically.
-- Data sync workflows use deduplication to avoid duplicate job execution.
-
-## 6. Environment & Configuration
-
-- **Env Vars used include:**
-  - `INTERCOM_IDENTITY_VERIFICATION_SECRET` for user hash generation.
-  - `MANTLE_FREE_PLAN_ID` to identify free subscription plans.
-  - Slack related tokens and channel IDs such as `SLACK_APP_TOKEN`, `SLACK_APP_USER_REQUESTS_CHANNEL_ID`, `SLACK_APP_SYSTEM_ALERTS_CHANNEL_ID` for notifications.
-
-- ConfigService manages and exposes these values.
-
-## 7. Testing, Monitoring, and Deployment
-
-- Service uses NestJS logger (`Logger`) and centralized exception capturing (`captureException`).
-- Includes telemetry via tracking events, e.g., when onboarding status changes or bundle products imported.
-- Slack service integration sends onboarding notifications.
-- Onboarding flows are resilient and resume on server restarts.
-
-## 8. Troubleshooting & Known Issues
-
-- Teams with excessive Shopify product variants are automatically disabled to prevent system overload.
-- Onboarding progress resumes automatically but manual triggers exist for admins via `/admin/onboarding/resume-all-teams` or `/admin/onboarding/resume-for-team`.
-
-## 9. Style and Tone
-
-- Documentation follows concise, declarative style.
-- Terminology aligns with Genie codebase (e.g., `teamId`, `UserEntity`, `OnboardingProgressEntity`).
-- Use code links for ease of navigation.
-
----
-
-## References to Key Source Files
-
-- [Onboarding Service](apps/api/src/setup/services/onboarding.service.ts)
-- [Onboarding Controller](apps/api/src/setup/controllers/onboarding.controller.ts)
-- [Teams Service](apps/api/src/user-management/services/teams.service.ts)
-- [Slack Service](apps/api/src/slack/services/slack.service.ts)
-
----
-
-This document enables developers to understand the onboarding domain fully and guides maintenance or enhancement work efficiently.

package/docs/usage/ui-workflows/purchase-orders.mdx

@@ -1,200 +0,0 @@
----
-title: 'Purchase Orders'
-description: 'Creating, editing, viewing, and managing purchase orders including shipments, payments, bundles, and export options.'
----
-
-## Purchase Orders - Internal Developer Documentation
-
-### Purpose and Scope
-
-The Purchase Orders module manages all aspects of purchase order (PO) lifecycle within the Genie system. It encompasses creation, retrieval, updating, deleting, shipment handling, payment processing, and exporting purchase orders. This module is responsible for ensuring accurate PO data management, shipment tracking, cost calculations, and integration with external systems such as Shopify and email notifications.
-
-This module defines the system boundary around Purchase Order business logic and persistence, exposing APIs consumed by the web frontend and internal services.
-
----
-
-### Technical Overview
-
-Purchase Orders are implemented as a backend service with a RESTful API layer and paired frontend components for UI interaction. The backend is primarily encapsulated in the `PurchaseOrdersService` class, supported by related controllers and repositories. The frontend UI includes React components for form handling, editing, and actions on purchase orders.
-
-#### Architecture Diagram
-
-```mermaid
-flowchart TD
-  subgraph Backend["Backend Services"]
-    direction TB
-    POService["PurchaseOrdersService"]:::service
-    POController["PurchaseOrdersController"]:::controller
-    POBundlesService["PoBundlesService"]:::service
-    ExportService["ExportService"]:::service
-    ShopifyService["ShopifyProductsService"]:::service
-    EmailService["EmailService"]:::service
-    SlackService["SlackService"]:::service
-    TeamsService["TeamsService"]:::service
-    AssetsService["AssetsService"]:::service
-    WorkflowService["WorkflowService"]:::service
-    PORepository[("PurchaseOrderEntity Repository")]:::db
-    POItemRepository[("PurchaseOrderItemEntity Repository")]:::db
-    POShipmentRepository[("PurchaseOrderShipmentEntity Repository")]:::db
-    POShipmentItemRepository[("PurchaseOrderShipmentItemEntity Repository")]:::db
-    POPaymentRepository[("PurchaseOrderPaymentEntity Repository")]:::db
-    LocationRepository[("LocationEntity Repository")]:::db
-  end
-
-  subgraph Frontend["Web Frontend"]
-    direction TB
-    POForm["PurchaseOrderForm Component"]:::frontend
-    POPage["PurchaseOrder Page"]:::frontend
-  end
-
-  POController -->|calls| POService
-  POService -->|uses DB access| PORepository
-  POService -->|uses DB access| POItemRepository
-  POService -->|uses DB access| POShipmentRepository
-  POService -->|uses DB access| POShipmentItemRepository
-  POService -->|uses DB access| POPaymentRepository
-  POService -->|uses DB access| LocationRepository
-  POService -->|calls| ShopifyService
-  POService -->|calls| ExportService
-  POService -->|calls| EmailService
-  POService -->|calls| SlackService
-  POService -->|calls| TeamsService
-  POService -->|calls| WorkflowService
-  POService -->|calls| AssetsService
-  POService -->|calls| POBundlesService
-
-  POController -->|serves| POPage
-  POPage -->|wraps with FormProvider| POForm
-  POForm -->|calls API via hooks| POService
-
-  classDef service fill:#4a90e2,stroke:#1c5480,color:#ffffff,stroke-width:1px;
-  classDef controller fill:#f5a623,stroke:#b07000,color:#000000,stroke-width:1px;
-  classDef db fill:#7ed321,stroke:#4b7100,color:#000000,stroke-width:1px,stroke-dasharray: 5 5;
-  classDef frontend fill:#9013fe,stroke:#5b0a9b,color:#ffffff,stroke-width:1px;
-
-  click POService "apps/api/src/purchase-order/services/purchase-orders.service.ts"
-  click POController "apps/api/src/purchase-order/controllers/purchase-orders.controller.ts"
-  click ExportService "apps/api/src/admin/services/export.service.ts"
-  click POForm "apps/web/src/components/pages/purchase-order/index.tsx"
-```
-
----
-
-### Core Concepts and Responsibilities
-
-- **PurchaseOrderEntity**: Represents a purchase order in the database, including status, supplier, currency, and associated items and shipments.
-- **PurchaseOrderItemEntity**: Represents individual items within a PO, linked to product variants and containing quantity, cost, and SKU info.
-- **PurchaseOrderShipmentEntity**: Represents shipments linked to a PO, contains shipment details, costs, and status (e.g., received or not).
-- **PurchaseOrderPaymentEntity**: Details payments against the PO, with status tracking (paid, not paid).
-- **Supplier Integration**: Suppliers and related product variants are linked to enable default unit costs and SKUs.
-- **Bundles**: Support for grouped products appearing as bundles, handled both in backend (`PoBundlesService`) and frontend UI (`BundlesCard`).
-- **Shipment Receipt & Shopify Sync**: Backend updates stock quantities on shipment receipt, optionally pushing changes to Shopify inventories.
-
-#### Ownership
-- Maintained by the Purchase Order backend and frontend teams.
-- Critical integrations: Shopify for stock sync, Email and Slack for notifications.
-
-#### Non-Functional Requirements
-- **Performance**: Query optimizations and paginated shipment queries implemented.
-- **Reliability**: Transactions used for key updates like duplicating POs to ensure consistency.
-- **Security**: Team-based authorization enforced at controller layer.
-
----
-
-### Code Structure
-
-| Path | Description |
-|---|---|
-| `apps/api/src/purchase-order/services/purchase-orders.service.ts` | Main backend service logic covering PO CRUD, shipment and payment management, exporting PDFs, duplication, and business rules. |
-| `apps/api/src/purchase-order/controllers/purchase-orders.controller.ts` | REST controller exposing the Purchase Orders API, with input validation and error handling. |
-| `apps/web/src/components/pages/purchase-order/index.tsx` | React components for viewing, editing, and managing a single purchase order. Includes form state and UI actions. |
-| `apps/api/src/admin/services/export.service.ts` | Service supporting CSV and JSON exports related to purchase orders and inventory data. |
-| `apps/web/src/api/resources/purchase-orders` | API hooks and mutations for frontend usage. |
-| `apps/web/src/components/pages/purchase-orders` | UI components for listing and bulk actions on purchase orders. |
-
-#### Key Code Snippet: Purchase Order Update Flow
-```ts
-const onSubmit = handleSubmit(({ supplierId, lineItems, status, exchangeRates, payments, shipmentCosts, issueDate, ...values }) => {
-  updatePurchaseOrder({
-    id: purchaseOrderId,
-    data: {
-      content: {
-        ...values,
-        name: values.name?.trim(),
-        exchangeRates: exchangeRates.reduce((acc, { currency, value }) => ({ ...acc, [currency]: value }), {}),
-      },
-      items: lineItems,
-      status,
-      supplierId,
-      issueDate,
-      payments,
-      shipmentCosts: Object.entries(_.groupBy(shipmentCosts, "shipmentId")).map(([shipmentId, costs]) => ({ shipmentId, costs })),
-    },
-  });
-});
-```
-This excerpt from the frontend `PurchaseOrderForm` component demonstrates submission of all related data to the update mutation in `PurchaseOrdersService`.
-
----
-
-### API and Interfaces
-
-The `PurchaseOrdersController` exposes a comprehensive REST API surface:
-
-- `POST /purchase-orders`: List purchase orders with filtering by supplier or variant IDs.
-- `GET /purchase-orders/summary`: Returns summarized purchase order information including statuses and key dates.
-- `GET /purchase-orders/:purchaseOrderId`: Retrieve detailed PO including items, shipments, payments.
-- `POST /purchase-orders/create`: Create new purchase order with product variants.
-- `POST /purchase-orders/create-with-quantities`: Create PO specifying quantities.
-- `PUT /purchase-orders/status`: Bulk status updates.
-- `PUT /purchase-orders/:purchaseOrderId`: Update PO details.
-- `DELETE /purchase-orders/:purchaseOrderId`: Soft delete a purchase order.
-- `POST /purchase-orders/:purchaseOrderId/duplicate`: Duplicate an existing PO.
-- `POST /purchase-orders/import`: Handle import requests for POs from files.
-- `POST /purchase-orders/:purchaseOrderId/export/pdf`: Export PO to PDF.
-- Several endpoints for shipments and payments management.
-
-Input schemas and validation are implemented using Zod (`ZodValidationPipe`), ensuring type-safe and correct data structures.
-
-Failures are handled via exceptions, including dedicated error codes for common cases (e.g., PO not found).
-
----
-
-### Environment & Configuration
-
-- Utilizes database connections managed through TypeORM repositories injected into the service.
-- Relies on external services such as EmailService, SlackService, ShopifyProductsService.
-- ExportService manages PDF and CSV generation.
-- Configuration (including toggles, environment modes) is accessible through injected ConfigService.
-
-Local development requires running backend with connected Postgres DB, Elasticsearch (where applicable), and frontend with mocked or live backend endpoints.
-
----
-
-### Testing, Monitoring, and Deployment
-
-- No explicit test code provided in context, but the layered architecture promotes unit testing of service methods and integration tests of controllers.
-- Logging is implemented using NestJS Logger in services.
-- Exception tracking through `captureException` utility enables external issue monitoring.
-- Scheduled background jobs exist for sending notifications related to POs left in draft, arriving soon, and overdue (in `ScheduledTasksService`).
-
----
-
-### Troubleshooting & Known Issues
-
-- Error handling is designed to differentiate missing POs (404) from other errors.
-- Shipment receipt updates may fail if shipment or shipment items are not found.
-- Bulk updates ensure transactional integrity where possible.
-
----
-
-### References
-
-- [`PurchaseOrdersService` Source Code](apps/api/src/purchase-order/services/purchase-orders.service.ts)
-- [`PurchaseOrdersController` Source Code](apps/api/src/purchase-order/controllers/purchase-orders.controller.ts)
-- [`PurchaseOrderForm` Frontend Component](apps/web/src/components/pages/purchase-order/index.tsx)
-- [`ExportService` Source Code](apps/api/src/admin/services/export.service.ts)
-
----
-
-This document summarizes the internal workings and structure of the Purchase Orders module, providing developers with a detailed reference for maintenance and extension efforts.

package/docs/usage/ui-workflows/reports.mdx

@@ -1,257 +0,0 @@
----
-title: 'Reports & Analytics'
-description: 'Generating, viewing, and managing reports including custom reports, report instance details, and scheduled alerts.'
----
-
-## Reports & Analytics - Internal Developer Documentation
-
-### Purpose and Scope
-The **Reports & Analytics** module in Genie is responsible for creating, managing, and delivering detailed inventory and purchase order reports and alert emails to users. It supports both manual and scheduled report generation, integrates with inventory, purchase orders, teams, and email services, and facilitates insightful business analytics that help users monitor critical inventory metrics and operational health.
-
-This module serves as the bridge between raw inventory and purchase order data and user-facing reporting features. It handles complex data aggregation, report instance management, alert email dispatch, and report exclusion logic for variants.
-
-**System Boundaries:**
-- Acts as the backend service layer interacting with the database and domain services such as inventory, purchase orders, suppliers, payment services, and email sending.
-- Exposes APIs to the frontend (React web UI) for report definitions, report instances, exclusions, and alert configuration.
-- Automated scheduled tasks generate reports and send alerts based on defined frequencies.
-
-The module's codebase resides primarily in `apps/api/src/reports/` and its API consumption by the frontend is through well-defined resource endpoints.
-
----
-
-### Technical Overview
-
-The Reports system consists of several interconnected services and components:
-
-- **ReportsService**: Core service implementing report definition management, generation of report instances, content creation, and exclusion handling.
-- **ScheduledTasksService**: A cron-driven service that periodically triggers generation of scheduled reports and sends alert emails.
-- **EmailService**: Handles templating and dispatch of report alert emails, including formatting and notifications.
-- **Report Definitions and Instances**: Persisted in the database, defining report types, frequencies, and generated content snapshots.
-- **Frontend Components**: React-based UI components fetch definitions and instances, display lists of reports, their details, and allow users to manage exclusions.
-
-The system employs the following technologies and patterns:
-- **NestJS Framework**: For backend API development.
-- **TypeORM**: ORM layer managing entity persistence and repository queries.
-- **React with React Query**: For frontend data fetching and UI rendering.
-- **Cron Scheduling via EnhancedCron Decorator**: For background scheduled tasks.
-
-#### Key interactions flow (Mermaid Sequence)
-
-```mermaid
-sequenceDiagram
-  participant UI as Web UI (React)
-  participant API as Reports API (NestJS)
-  participant DB as Database
-  participant Email as EmailService (SendGrid)
-  participant InventorySvc as InventoryService
-  participant POSvc as PurchaseOrdersService
-
-  UI->>API: Fetch report definitions
-  API->>DB: Query ReportDefinitions
-  DB-->>API: Return definitions
-  API-->>UI: Send definitions
-
-  UI->>API: Request manual report generation
-  API->>ReportsSvc: GenerateReportInstance
-  ReportsSvc->>InventorySvc/POSvc: Aggregate data
-  ReportsSvc->>DB: Save ReportInstance
-  ReportsSvc-->>API: Return instance ID
-  API-->>UI: Confirm generation
-
-  ScheduledTasks->>API: Trigger scheduled report generation
-  API->>ReportsSvc: Generate for due reports
-  ReportsSvc->>DB: Save generated instances
-  API->>Email: Send alerts to users
-  Email-->>Users: Alert emails
-
-```
-
----
-
-### Core Concepts and Responsibilities
-
-- **Report Definitions**: Templates specifying report type, frequency, schedule, and settings. Each is associated with a team.
-- **Report Instances**: Generated reports based on definitions, each with an attached snapshot of data content.
-- **Email Alerts**: Sent automatically for some report types if `notifyViaEmail` flag is set.
-- **Variant Exclusions**: Product variants can be excluded from reports, stored in exclusion entities and managed via API.
-- **Scheduled Execution**: The system runs every 15 minutes to determine which reports need generation based on schedule and frequency.
-- **Report Content Types**: Diverse types covering inventory health, sales velocity, stock risk, purchase order snapshots, dashboard data, and variance.
-
-**Ownership & Logging:**
-- The Reports team maintains this module.
-- Logging is done extensively via NestJS Logger in backend services to trace report generation and errors.
-
-**Non-Functional Requirements:**
-- Must support scalability across multiple teams with isolation.
-- Ensure reliability for timely report generation and alert delivery.
-- Secure access, verifying user's team membership before data access.
-
----
-
-### Code Structure
-
-- `apps/api/src/reports/controllers/reports.controller.ts`: Handles REST API endpoints for reports — fetching definitions, generating reports, updating exclusions.
-- `apps/api/src/reports/services/reports.service.ts`: Implements core report generation logic, data aggregation, and persistence.
-- `apps/api/src/reports/services/scheduled-tasks.service.ts`: Scheduled cron jobs for automated report generation and email alerts.
-- `apps/api/src/email/services/email.service.ts`: Email templating and sending mechanisms, specifically for report alerts and purchase order notifications.
-- `apps/web/src/components/pages/reports/reports.tsx`: Frontend main page rendering report lists and managing open definition slide outs.
-- `apps/web/src/components/pages/reports/report-definition-slide-out/past-reports-tab.tsx`: Displays list of past report instances.
-- `apps/web/src/components/pages/report-instance/no-results.tsx`: UI component showing message when a report instance has no data.
-
-#### Example snippet: report instance generation flow
-```ts
-// Trigger report instance generation
-async generateReportInstance({teamId, definitionId, type}) {
-  const definition = await this.getReportDefinition(teamId, definitionId);
-  if (!definition.isValid()) throw new Error("Invalid report");
-
-  const instance = this.reportInstanceRepository.create({
-    teamId,
-    reportDefinitionId: definitionId,
-    reportDefinitionSnapshot: definition.getSnapshot(),
-    type,
-  });
-
-  instance.content = await this.generateReportContent(instance);
-  await this.reportInstanceRepository.save(instance);
-  return instance;
-}
-```
-
-[Link to source](apps/api/src/reports/services/reports.service.ts)
-
----
-
-### API and Interfaces
-
-The Reports API uses standard REST semantics with authentication and authorization based on user team membership.
-
-**Endpoints overview include:**
-- `GET /reports/definitions` - Retrieve all report definitions for the user's team.
-- `GET /reports/definitions/:id` - Get a single report definition.
-- `PUT /reports/definitions/:id` - Update a report definition.
-- `POST /reports/definitions/:id/generate` - Manually trigger report generation.
-- `GET /reports/definitions/:id/instances` - List past report instances (previews).
-- `GET /reports/instances/:id/details` - Get detailed data of a report instance.
-- `GET /reports/definitions/:id/excluded-product-variants` - Get list of excluded variants.
-- `POST /reports/definitions/:id/excluded-product-variants/exclude` - Exclude variants.
-- `POST /reports/definitions/:id/excluded-product-variants/include` - Include variants back.
-
-Input validation is performed with Zod schemas (e.g., `createReportRequestDtoSchema`). Exceptions such as missing team membership or unfound report definitions respond with 403 or 404 respectively.
-
----
-
-### Environment & Configuration
-
-Key environment variables used in related modules:
-- `APP_URL` - Base URL for the web app, used in email links.
-- `SENDGRID_API_KEY` - API key for SendGrid email service.
-- `API_ENV` - Environment designation (production, staging, dev) for conditional behaviors.
-
-Configurations for report scheduling and frequency are stored in the database per team and may include timezone preferences via settings service.
-
----
-
-### Testing, Monitoring, and Deployment
-
-- Unit and integration tests are implied to exist covering service methods and API controllers (no explicit test details provided).
-- Logging via NestJS Logger and error capturing via `captureException` provide observability.
-- Reports run automatically via cron (every 15 minutes) with precise time-window checks to avoid duplicate generation.
-- Email sending failures are caught and logged without crashing the batch.
-
-Deployment follows standard CI/CD pipelines for the NestJS backend and React frontend.
-
----
-
-### Troubleshooting & Known Issues
-
-There is no explicit documented troubleshooting guidance, but due to detailed logging and error capture patterns in the ScheduledTasksService and ReportsService, developers can trace:
-- Report generation failures.
-- Email sending errors.
-- Report exclusion inconsistencies.
-
-No known critical pitfalls or remediation steps are documented.
-
----
-
-### Summary
-The Reports & Analytics module is a highly integrated backend service with database persistence, scheduled tasks, and email notification capabilities. It empowers teams to monitor inventory health through scheduled and manual reports made visible through the Genie Web UI. The codebase is organized around domain services, RESTful controllers, scheduled tasks, and email dispatch.
-
-##### Key Documentation Links:
-- [Reports Controller](apps/api/src/reports/controllers/reports.controller.ts)
-- [Reports Service Core Logic](apps/api/src/reports/services/reports.service.ts)
-- [Scheduled Tasks Service](apps/api/src/reports/services/scheduled-tasks.service.ts)
-- [Email Service](apps/api/src/email/services/email.service.ts)
-- [Frontend Reports Page](apps/web/src/components/pages/reports/reports.tsx)
-
----
-
-### Mermaid Architecture Diagram
-
-```mermaid
-flowchart TD
-  subgraph "Frontend (React Web UI)"
-    UI_Reports["Reports Page UI"]:::frontend
-    UI_ReportDefinition["Report Definition Slide Out"]:::frontend
-  end
-
-  subgraph "Reports API (NestJS Backend)"
-    ReportsController["ReportsController"]:::backend
-    ReportsService["ReportsService"]:::backend
-    ScheduledTasks["ScheduledTasksService"]:::backend
-  end
-
-  subgraph "Support Services"
-    InventorySvc["InventoryService"]:::backend
-    PurchaseOrdersSvc["PurchaseOrdersService"]:::backend
-    SuppliersSvc["SuppliersService"]:::backend
-    DashboardSvc["DashboardService"]:::backend
-    PaymentSvc["PaymentsService"]:::backend
-    EmailSvc["EmailService"]:::backend
-    TeamsSvc["TeamsService"]:::backend
-    SettingsSvc["SettingsService"]:::backend
-  end
-
-  subgraph "Database"
-    ReportDefs[("ReportDefinitions Table")]:::database
-    ReportInstances[("ReportInstances Table")]:::database
-    VariantExclude[("ReportDefinitionVariantExclude Table")]:::database
-    EmailAlertDefs[("EmailAlertDefinitions Table")]:::database
-  end
-
-  %% UI -> API
-  UI_Reports -->|"REST API calls"| ReportsController
-  UI_ReportDefinition -->|"Fetch / Update"| ReportsController
-
-  %% Reports API
-  ReportsController -->|"call"| ReportsService
-  ScheduledTasks -->|"call cron jobs"| ReportsService
-  ReportsService -->|"query/update"| ReportDefs
-  ReportsService -->|"query/update"| ReportInstances
-  ReportsService -->|"query/update"| VariantExclude
-  ReportsService -->|"query/update"| EmailAlertDefs
-
-  %% ReportsService calls supporting services
-  ReportsService --> InventorySvc
-  ReportsService --> PurchaseOrdersSvc
-  ReportsService --> SuppliersSvc
-  ReportsService --> DashboardSvc
-  ReportsService --> PaymentSvc
-  ReportsService --> TeamsSvc
-  ReportsService --> SettingsSvc
-
-  %% ScheduledTasks email alerts
-  ScheduledTasks --> EmailSvc
-  ReportsService --> EmailSvc
-
-  %% Click events
-  click ReportsController "apps/api/src/reports/controllers/reports.controller.ts"
-  click ReportsService "apps/api/src/reports/services/reports.service.ts"
-  click ScheduledTasks "apps/api/src/reports/services/scheduled-tasks.service.ts"
-  click EmailSvc "apps/api/src/email/services/email.service.ts"
-  click UI_Reports "apps/web/src/components/pages/reports/reports.tsx"
-
-  %% Styles
-  classDef frontend fill:#f9f,stroke:#333,stroke-width:1px,color:#222
-  classDef backend fill:#bbf,stroke:#333,stroke-width:1px,color:#000
-  classDef database fill:#bfb,stroke:#333,stroke-width:1px,color:#000