Changelog¶

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

20260321 - 2026-03-21¶

Added¶

Staging attestation for docs / EventCatalog-only deploys: Attest Staging can run when Acceptance Test is skipped but Deploy Staging succeeded with docs and/or EventCatalog in the affected set (static-site path). Attestation payloads set acceptanceTestsPassed from the real Acceptance Test stage outcome (attestAcceptanceJson) instead of always true.
Digest checks before cosign attestation: Each per-image attestation step validates a sha256:<64-hex> digest for the service being attested (gateway, web, docs, EventCatalog, microservices, slicer).
Technology stack summary asset: New docs/03-architecture/technology-stack-summary.svg plus refresh of technology-stack.svg.

Fixed¶

Azure Pipelines variable expansion in bash attestation scripts: Replaced ${macro:-default}-style reads with $(macro) and explicit empty checks so runtime macros (acceptanceStageResult, image digests) resolve correctly under set -u-safe patterns.
Grype SBOM scan flakiness: .azuredevops/pipelines/templates/sbom-scan-publish.yml runs sync before scanning and retries Grype up to three times with incremental backoff for transient errors (for example “Text file busy”).
AuthWithAuditController session usage (@forma3d/service-common): Guard when session middleware is missing; capture req.session in a local variable before save / destroy callbacks for correct TypeScript strict typing and closure behavior.

Changed¶

Lighthouse CI report publishing: Pipeline selects the HTML report that pairs with the highest performance score from *.report.json, with fallback to the first HTML artifact; Python score extraction and float comparison simplified for reliability.
Business requirements: Substantial update to docs/01-business/requirements.md (implementation history and requirement alignment).
Root and EventCatalog dependencies: pnpm overrides for fast-xml-parser (≥5.5.7) and flatted (≥3.4.2); matching pins in docs/03-architecture/eventcatalog/package.json.

Security¶

Supply-chain hygiene: Patch-level bumps for fast-xml-parser and flatted via overrides and EventCatalog pins to stay on maintained versions.

Documentation¶

Pipeline reference & staging deployment: docs/05-deployment/pipeline-reference.md and staging-deployment-guide.md — Acceptance Test vs Attest Staging flow, docs/EventCatalog-only attestation path, digest and predicate behavior.
Agentic team operations: docs/10-agentic-team and root agentic-team/ — Ryan’s scope extended to SonarCloud, license-check, Grype, and Lighthouse failures with full failed-step logs to Cody; Sam’s scope explicit for infrastructure anomalies (e.g. cryptominer-style processes, suspicious CPU); configure-secrets.sh, setup-summary.md, agent CLAUDE.md files, and prompts updated accordingly.
Agentic team health-check cadence: Ryan (build agent) and Sam (staging) routine monitoring documented as hourly (24 checks/agent/day); pipeline failures remain Azure DevOps webhook-driven (immediate). Updated prompts, agentic-team/agents/*/CLAUDE.md, implementation-plan.md, agentic-team/README.md, and related notes.
Sonar issue resolution guide: Updates to reports/sonarcloud-issue-resolution-guide.md.
AI implementation advantage: Minor revision in docs/04-development/AI-implementation-advantage.md.

20260319 - 2026-03-19¶

Added¶

Inventory & stock replenishment system: Full inventory management with reorder-point / order-up-to model. StockBatch and InventoryTransaction Prisma models, InventoryModule and StockReplenishmentModule in order-service, scheduled replenishment evaluation, stock-aware order fulfillment with ORDER-over-STOCK print job priority, and GRIDFLOCK_PIPELINE retry job type for transient pipeline failures with exponential backoff.
Inventory management UI: Four new pages — Stock Levels dashboard (/inventory), Inventory Config (/inventory/config) with inline editing of min/max stock, priority, and batch size, Transaction History (/inventory/transactions) with product selector and pagination, and Replenishment Status (/inventory/replenishment). Navigation sidebar updated with ArchiveBoxIcon link. Permission-gated behind inventory.read / inventory.write.
Inventory API endpoints: GET /api/v1/inventory/stock-levels, PATCH /api/v1/inventory/config, POST /api/v1/inventory/adjust, POST /api/v1/inventory/scrap, GET /api/v1/inventory/transactions, GET /api/v1/inventory/replenishment-status. TanStack Query hooks for all endpoints.
Feature flags admin UI: New admin page (/settings/feature-flags) for managing feature availability per tenant, with FeatureFlagsAdminModule in gateway, API client methods, and tenant-specific feature flag hooks.
Tenant feature flags in health checks: HealthController now filters reported services based on tenant feature flags (e.g. gridflock-service and slicer hidden when GridFlock disabled for tenant). TenantFeaturesModule integrated into gateway.
Grid pricing settings UI: New settings page for managing grid pricing parameters (currency, pricing fields), with SettingsModule in order-service, GridPricingSettingsController, gateway route, API client methods, and frontend hooks.
SimplyPrint upload folder configuration: Tenants can configure a SimplyPrint folder path for uploaded grid files, with a test endpoint to validate folder existence before saving.
API Gateway OpenAPI aggregation: Gateway now aggregates OpenAPI specifications from all microservices with background fetching — initial load shows gateway endpoints, subsequent loads include all service endpoints.
Lighthouse CI: @lhci/cli integration with .lighthouserc.cjs config (Performance 70, Accessibility 90, Best Practices 90, SEO 90), lighthouse Nx target in apps/web, and LighthouseAudit pipeline stage running against staging after deployment.
SonarCloud integration: SonarCloud code quality analysis in Azure Pipelines with quality gate checks, coverage reporting, and duplication detection.
CodeCharta city visualization: Pipeline stage generates CodeCharta metrics from SonarCloud data, deploys interactive 3D visualization to staging via Docker volume mount (decoupled from docs image build).
Grype CVE scanning: Grype vulnerability scanning after each of the 9 SBOM generation steps in the pipeline, with --fail-on high threshold.
ClickHouse log backup cron job: Daily automated backup at 3 AM UTC via deploy.sh cron setup.
Storefront variant tracking: isNewVariant boolean in GridAddToCartResponse indicating newly created variants, with configurator delay for variant propagation.
Storefront pricing throttle: Relaxed rate limiting decorator (StorefrontPricingThrottle) for read-only pricing endpoints, separate from checkout/add-to-cart throttling.
Acceptance tests for inventory: inventory-stock-api.feature with step definitions for stock level, configuration, adjustment, and transaction endpoints.
@forma3d/service-common shared modules: Extracted and centralized the following duplicated code into the shared library:
SharedAuthModule.forRoot() — auth services, guards, decorators, DTOs
SharedNotificationsModule.forRoot() — email service, notifications service, Handlebars templates
SharedConfigModule.forRoot() — env validation, SystemConfigService
Event log module — EventLogService, controller, module
Shipments module — repository, service, controller
Sendcloud module — SendcloudBaseService, API client, connection repository, webhook types
Product mappings module — controller, service, repository, DTOs
Print jobs controllers — PrintJobsController, PrintJobsAdminController
Auth controllers — AuthWithAuditController
Correlation, throttler, fulfillment events
Notification event handlers

Fixed¶

SimplyPrint reconciliation CANCELLED → COMPLETED guard: Prevented incorrect status transition from CANCELLED to COMPLETED during reconciliation when stale printer references remain after job re-queues.
Service worker stale data: Switched API caching from StaleWhileRevalidate to NetworkFirst with 5-second timeout for /api/v1/orders and /api/v1/dashboard, ensuring React Query cache invalidation retrieves fresh data.
Staging deployment npx not found: Fixed Error: Cannot find module '/app/npx' by changing migration commands from npx prisma migrate deploy to pnpm prisma migrate deploy in deploy.sh and azure-pipelines.yml.
SonarCloud S6853 (form label association): Wired htmlFor/id attributes on form labels and controls in stock adjustment modal, shipping info, user form modal, inventory config, transactions, and new mapping pages.
SonarCloud S7735 (negated conditions): Fixed 40 negated-condition instances across ~20 files by flipping conditions and swapping branches.
SonarCloud S3863 (duplicate imports): Merged 80 duplicate imports from the same module across production and test files.
SonarCloud S3776 (cognitive complexity): Reduced cognitive complexity in handleSimplyPrintStatusChange, updateJobStatus, runBackfillForShop, runLegacyBackfill, uploadFileToSimplyPrint, generatePlateBorderStls, calculatePlateSet, and enumerateAllBasePlateKeys by extracting helper functions.
File promotion resilience: Added retry logic with exponential backoff for promoting SimplyPrint temporary API files to user files, with Sentry error reporting on failure.
Path sanitization in gridflock: Replaced regex-based .. removal with string replacement in sanitizePathSegment for clarity.
Constructor parameter count: Reduced SendcloudBaseService and shipping-service constructor parameters from 9 to ≤7 by grouping dependencies.
fast-xml-parser CVE: Updated to v5.4.1.
Security headers: Added SecurityHeadersMiddleware to order-service AppModule.
Email input sanitization: Refactored email handling in auth services to safely convert inputs to strings.
Cosign attestation retry: Added retry logic for cosign attest in Azure Pipelines to handle transient registry authentication failures.
Database migration reliability: Updated migration commands in CI/CD scripts for consistent behavior across environments.

Changed¶

0.6mm nozzle support for Bambu Lab A1: Updated default print settings (nozzle diameter, layer height, infill, layer counts), added machine/process/filament profile paths, enhanced GridflockPipelineService to select edge puzzle parameters based on nozzle diameter.
Slicer profile resolution: Introduced fallback mechanism prioritizing custom profiles, refactored profile flattening for multiple profile types (machine, process, filament), improved output naming.
GridFlock feature flag key: Changed from gridflock.enabled to feature.gridflock.enabled for consistency with generic feature flag management UI.
Grid pricing service: Refactored to use currency-agnostic keys.
Prisma seed: grid.unitSizeMm changed from 75 to 42 (Gridfinity standard).
Jest → SWC: Switched all 5 backend services from ts-jest to @swc/jest for faster TypeScript compilation during tests.
Duplication reduction: All 5 microservices now import auth, notifications, config, event-log, shipments, Sendcloud, product mappings, print job controllers, correlation, and throttler from @forma3d/service-common instead of maintaining local copies.
Print job lineItemId nullable: PrintJob.lineItemId is now optional (null for STOCK purpose jobs).
Azure Pipelines: SBOM generation and vulnerability scanning refactored with Syft + Grype replacing Aikido; deployment tagging improvements for deploymentHappened accuracy; registry maintenance and staging promotion stages restructured.
ClickHouse configuration: Daily partitions, adjusted TTL settings for query_metric_log and error_log, resolving OOM death spiral.
Nx project configuration: Added tagging and @nx/enforce-module-boundaries import rules across all projects.
Docs Dockerfile optimization: CodeCharta moved from image build to Docker volume mount, decoupling CodeCharta generation from docs packaging.
Acceptance tests: Product mapping selectors updated for improved accuracy and reliability.

Removed¶

Aikido security scanning: Replaced by Syft (SBOM) + Grype (CVE scanning) in the pipeline.
Duplicated service code: Removed local implementations of auth, notifications, config, event-log, shipments, Sendcloud, product mappings, print jobs controllers, correlation, throttler, and fulfillment events from individual microservices (now in @forma3d/service-common).

Security¶

Syft + Grype pipeline: SBOM generation (Syft) and CVE scanning (Grype, --fail-on high) for all 9 container images, replacing Aikido.
Cryptominer audit: Security audit of staging and nanoclaw servers — no cryptominers found; /tmp/slicer-build/ executables confirmed as expected build artifacts.
fast-xml-parser update: v5.4.1 addressing known CVEs.
Security headers middleware: Applied to order-service.

Documentation¶

Technology stack overview: Comprehensive technology stack document (docs/03-architecture/technology-stack.md) with rationale, PlantUML diagram, and SVG — Aikido replaced by Syft + Grype in security section.
Trunk-based development workflow: New workflow document with PlantUML branching model diagram and pipeline reference cross-link.
Operational tooling guide: New guide (docs/05-deployment/operational-tooling.md) documenting Uptime Kuma, Dozzle, pgAdmin, Grafana, Zensical, and EventCatalog.
CodeCharta research: Research document for CodeCharta city visualization integration with SonarCloud.
Inventory architecture diagrams: Updated C4 component (OrderService), domain model, database, and ERD diagrams. New sequence diagrams for stock replenishment, stock-aware fulfillment, and stock job completion. New state machine diagram for StockBatch lifecycle.
C4 container diagram: Added Uptime Kuma container with operator and gateway relationships.
C4 deployment diagram: Added pgAdmin container to staging Docker Compose node.
ClickHouse backup documentation: Updated staging deployment guide with backup types, storage locations, and verification steps.
Sonar quality gate protocols: Documented agent workflows for handling quality gate failures.
Stackshare documentation: Technology icons, tool usage mapping, and custom-built services documentation.
README.md: Added process documentation section.

Database¶

Added StockBatch model with status tracking (IN_PROGRESS, COMPLETED, FAILED, CANCELLED) and job count fields.
Added InventoryTransaction model with transaction types (PRODUCED, CONSUMED, ADJUSTMENT_IN, ADJUSTMENT_OUT, SCRAPPED), direction, reference tracking, and audit fields.
Added PrintJobPurpose enum (ORDER, STOCK) and purpose field on PrintJob.
Added stockBatchId field on PrintJob (nullable, for STOCK purpose jobs).
Made PrintJob.lineItemId nullable for STOCK purpose jobs.
Added inventory fields on ProductMapping: currentStock, minimumStock, maximumStock, replenishmentPriority, replenishmentBatchSize.
Added GRIDFLOCK_PIPELINE to RetryJobType enum.
Added composite indexes for stock replenishment queries (tenantId, purpose, status on PrintJob; tenantId, productMappingId, status on StockBatch).

Tests¶

Added stock replenishment unit tests: StockReplenishmentService (14 tests) and StockReplenishmentScheduler (4 tests).
Added @forma3d/gridflock-core geometry unit tests: numbering.spec.ts, grid-cells.spec.ts, intersection-puzzle.spec.ts, edge-puzzle.spec.ts, magnet-holes.spec.ts.
Added SendcloudBaseService unit tests (20+ cases covering all shared methods, error handling, retryable errors, service point delivery).
Added shared controller unit tests for service-common controllers.
Added frontend hook tests: use-inventory.test.tsx, use-feature-flags-admin.test.tsx, use-grid-pricing-settings.test.tsx, use-print-settings.test.tsx, use-stock-settings.test.tsx, use-feature-flags.test.tsx.
Added MSW handlers for inventory, settings, feature flags, and tenant features endpoints.
Added inventory acceptance tests (inventory-stock-api.feature).
Updated SimplyPrint reconciliation tests for CANCELLED → COMPLETED guard.
Updated acceptance tests for product mapping selector improvements.

20260302 - 2026-03-02¶

Added¶

Plate-level preview cache: 268 plate-level cache files (~60 MB) uploaded and verified on staging (Plate cache loaded: 268 plates, 59.5 MB), replacing the legacy full-preview cache. The preview service now uses a two-tier cascade: plate-level assembly (10–100 ms) → full JSCAD fallback (12–30 s).
Aikido security configuration: Added .aikido configuration file for automated security scanning (dependency vulnerabilities, exposed secrets, SAST, IaC, malware detection).
Microservice stubs and handlers: Implemented missing stubs and handlers across services — FulfillmentService.createFulfillment in shipping-service, AuditService in shipping/gridflock/print services, retry queue handlers for CANCELLATION and PRINT_JOB_CREATION in order-service and shipping-service.
Prisma connection retry logic: PrismaService now retries database connections on startup with configurable retry count and delay.

Fixed¶

Grid configurator dimension rounding: Changed snapToMm() from Math.round to Math.floor in the Shopify storefront configurator so dimensions like 74.41–74.49 cm floor to 74.4 cm instead of rounding up. Added step="0.1", max="100", and validation feedback to dimension inputs.
GridFlock rounded corners on individual plates: Fixed corner rendering on individual plate previews in the 3D configurator.

Changed¶

Preview cache architecture: Replaced the legacy per-dimension preview cache with plate-level assembly. Cache keys normalize dimensions with larger dimension first. Full JSCAD fallback retained for uncached combinations.
Internal prompt management: Moved prompt-openscad-server-side-preview.md from todo/ to done/ — superseded by the plate-level cache approach.

Removed¶

Legacy full-preview cache system: Deleted 16,471 preview files (~35 GB) from the staging server and removed all associated code: PreviewCacheController, preview cache management UI (/settings/preview-cache), usePreviewCache hooks, previewCache API client methods, scripts/populate-preview-cache.ts, and scripts/upload-preview-cache.sh. The legacy disk read/write path in GridflockPreviewService has been removed.

Security¶

Aikido security scanning: Configured Aikido for continuous security monitoring. Initial scan identified Prisma operator injection risks, Express security header gaps, and fast-xml-parser CVEs — tracked for remediation in fix/aikido-violations branch.

Documentation¶

SaaS launch readiness research: New research document (docs/03-architecture/research/saas-launch-readiness-research.md) covering onboarding, pricing/billing, invoicing, tax compliance, offboarding, GDPR, legal, multi-lingual/i18n, Stripe integration, security requirements, and feature flags for a future SaaS offering.
Internal README update: Updated docs/_internal/README.md with current workspace structure, projects, and configuration details.
Plate-level preview cache prompt: Created docs/_internal/prompts/todo/prompt-plate-level-preview-cache.md documenting the plate cache strategy.

20260227 - 2026-02-27¶

Added¶

STL preview cache pre-population scripts: Two offline scripts for eliminating cold-start latency in the storefront configurator. scripts/populate-preview-cache.ts generates all STL preview files locally on a powerful machine with CPU-aware parallelism (auto-detects cores, partitions concurrent jobs to prevent thread oversubscription), --dry-run mode, resumability, and progress reporting. scripts/upload-preview-cache.sh transfers generated files to the staging server via rsync with Docker container ownership fix.
Preview generation library extraction: Extracted generatePreviewStl() function from GridflockPreviewService into @forma3d/gridflock-core as a reusable, NestJS-independent module. Moved computeUniformOffsets(), computeOffsetsPerColumn(), PLATE_GAP_MM, and DEFAULT_PREVIEW_OPTIONS from the service class into the library. Both the server and offline scripts now share a single source of truth for STL preview generation.
Configurable worker thread count: Added optional maxWorkers parameter to generatePlatesParallel() in @forma3d/gridflock-core (backward-compatible — existing callers unaffected). Enables callers to control CPU usage when running multiple combinations concurrently.
STL cache management search: Added search/filter input to the Preview Cache admin screen for finding cached files by filename.
SimplyPrint default file color: Set default color to Jade White (Bambulab PLA) when uploading files to SimplyPrint for consistent color/material tagging.

Fixed¶

Three.js grid preview dark backside: Changed STL material from FrontSide to DoubleSide rendering and improved directional/ambient lighting in the storefront 3D configurator to eliminate dark backsides on grid previews.

Changed¶

GridFlock preview service refactored: GridflockPreviewService.generatePreview() is now a thin caching wrapper that delegates all generation logic to generatePreviewStl() from @forma3d/gridflock-core. No offset computation, plate set calculation, or STL combining logic remains in the service.
Cache key normalization: Preview cache keys now normalize dimensions with the larger dimension first — requesting 320×450 and 450×320 both resolve to preview-450x320.stl, preventing duplicate cache entries.

Documentation¶

ADR-060: Single Source of Truth for STL Preview Generation — documents the extraction of preview generation logic from the NestJS service into @forma3d/gridflock-core.
Real-world testing guide: Added Part 12: STL Preview Cache Pre-Population — offline generation and upload workflow, CLI usage, verification steps.
STL cache prepopulation research: Updated status from Research to Implemented with ADR cross-reference.
C4 component diagram: Updated GridFlock Service component diagram with preview generator and preview controller components.

20260222 - 2026-02-22¶

Added¶

On-demand pgAdmin container management: Gateway DevTools API (/api/v1/devtools/pgadmin) and web UI settings page for starting, stopping, and monitoring a pgAdmin container on demand. Gateway Dockerfile now includes Docker CLI, and the gateway container has Docker socket access for container orchestration. Includes DevtoolsModule, DevtoolsService, DevtoolsController, container status DTO, and unit tests.
Nx affected resilience via deploy tag (ADR-059): Pipeline DetectAffected job now uses a last-successful-deploy git tag as the --base ref instead of HEAD~1. A new UpdateDeployTag stage advances the tag only after the full pipeline succeeds. If a pipeline fails partway through, the next run re-evaluates all changes since the last successful deployment, preventing "forgotten" undeployed changes.
ClickHouse initialization scripts: Automated TTL policy application (apply-ttl.sh) mounted as a ClickHouse init script in Docker Compose, with pipeline support for deploying init scripts to staging.
TIMELINE.md: Project evolution timeline document added to docs build (.dockerignore updated, COPY added to docs Dockerfile).

Fixed¶

Database connection pool standardization: Explicit connection_limit parameter added to all 5 services' Prisma configuration via DATABASE_URL query parameter and configuration.ts pool settings, preventing connection exhaustion under load.
Sentry debug mode in non-production: Disabled debug: true in Sentry config for non-production environments to reduce console noise.
Sentry test configuration: Cleaned up Sentry config spec to work without live DSN.
Nginx proxy resolution: Updated nginx.conf proxy configuration for dynamic gateway hostname resolution, fixing 502 errors after container restarts.
ClickHouse backup script: Enhanced with JSONL export functionality alongside existing SQL backup for more portable log archives.
Grafana structured logs dashboard: Updated SQL queries for ClickHouse OTel schema compatibility; added log search dashboard.
pgAdmin Docker Compose: Switched from .env file mount to explicit environment variables, used explicit volume name and project name for reliable container lifecycle management.

Changed¶

Nx affected base ref: Pipeline compares against last-successful-deploy tag instead of HEAD~1, with automatic fallback to HEAD~1 when the tag doesn't exist (first run). Both nx affected and git diff (for docs, slicer, eventcatalog) use the same dynamic base ref.
pgAdmin monitoring: Removed pgAdmin from Uptime Kuma permanent monitors since it is now an on-demand container managed through the DevTools UI.

Documentation¶

ADR-059: Nx Affected Resilience via Last-Successful-Deploy Tag — documents the problem with HEAD~1 base ref, the git tag solution, bootstrap behavior, and alternatives considered.
Staging deployment guide: Updated with database connection pool configuration and pgAdmin on-demand instructions.

20260221 - 2026-02-21¶

Added¶

ClickHouse + Grafana logging pipeline: Full observability stack with OTel Collector (OTLP gRPC/HTTP receivers, batch processor, ClickHouse exporter), ClickHouse server with memory limits and S3 backup disk, Grafana with provisioned ClickHouse datasource, and backup scripts for DigitalOcean Spaces. Installed @opentelemetry/sdk-node, @opentelemetry/api, @opentelemetry/exporter-logs-otlp-grpc, @opentelemetry/sdk-logs, @opentelemetry/instrumentation-pino, and related packages. New OtelLoggerService in libs/observability using Pino with pino-pretty transport for dev.
Integration hot-reload architecture: SimplyPrint and Sendcloud API clients now re-initialize immediately when integration settings are saved or disconnected via the UI, with cross-service BullMQ event notification (INTEGRATION_SIMPLYPRINT_CHANGED, INTEGRATION_SENDCLOUD_CHANGED). Replaced startup-only initialization pattern with SimplyPrintInitializerService and SendcloudInitializerService that support on-demand reinitialize() and disable().
EventCatalog flows: 4 business flow visualizations — Order Fulfillment, Order Cancellation, GridFlock Pipeline, and Shipping & Tracking — with interactive visualizer pages, Mermaid diagram exports, and cross-references to domains and services.
EventCatalog Schema Explorer: Added schemaPath frontmatter to all 11 events, created TypeScript schema files for all 8 commands and 7 queries, enabling the Schema Explorer across the entire catalog.
EventCatalog architecture documentation: Full EventCatalog project (docs/03-architecture/eventcatalog/) with domain, service, event, command, query, and channel documentation, Mermaid flow diagrams, Dockerfile, Docker Compose configuration, and CI/CD pipeline integration.
Event traceability fields: Added eventId (UUID v4) and source (service name) to ServiceEvent interface for cross-service event tracing, cherry-picked from the CloudEvents specification.
SimplyPrint & Sendcloud UI configuration: Database-backed integration settings (SimplyPrintConnection, SendcloudConnection Prisma models) with AES-256-GCM encrypted credential storage, shared IntegrationTokenService, CRUD APIs, frontend settings page with connection status indicators and test-connection functionality.
Implementation prompts: Created prompts for ClickHouse + Grafana logging pipeline (prompt-clickhouse-grafana-logging.md) and on-demand pgAdmin container (prompt-pgadmin-on-demand-container.md).

Fixed¶

Unresolved Azure DevOps pipeline variables causing crash loops: Removed 10 dead pipeline variables (SIMPLYPRINT_API_URL, SIMPLYPRINT_API_KEY, SIMPLYPRINT_COMPANY_ID, SIMPLYPRINT_WEBHOOK_SECRET, SENDCLOUD_PUBLIC_KEY, SENDCLOUD_SECRET_KEY, SHOPIFY_SHOP_DOMAIN, SHOPIFY_ACCESS_TOKEN, DEFAULT_SHIPPING_METHOD_ID, DEFAULT_SENDER_ADDRESS_ID) from env.validation.ts (all 4 services), docker-compose.yml, azure-pipelines.yml heredoc template, and env templates. Azure DevOps passed literal $(VAR) strings when variables were undefined, failing @IsUrl() validation and crash-looping order-service and print-service.
Integration client initialization in order-service: Order-service had no startup services for SimplyPrint or Sendcloud — API clients were never initialized after container restart. Added SimplyPrintInitializerService, SendcloudInitializerService, connection repositories, and BullMQ event listeners.
Order status transition validation: Added FAILED → PROCESSING and PARTIALLY_COMPLETED → PROCESSING transitions, allowing orders to be revived when print jobs are requeued.
BullMQ print-job.status-changed subscription: Added missing Worker subscription in order-service for print job status change events; jobs were stuck in "waiting" state indefinitely.
Dashboard real-time updates: Added ['analytics'] and ['dashboard'] query key invalidation to socket event handlers; added missing handlers for order:fulfilled, order:failed, printjob:created, printjob:completed, printjob:cancelled.
Double # prefix in Shopify order numbers: Removed hardcoded # from frontend templates that duplicated the # already present in order data.
EventCatalog Dockerfile: Changed npm ci to npm install to fix build failure caused by missing package-lock.json in pnpm monorepo.
Docs Docker build: Fixed zensical build failing on CHANGELOG.md snippet — removed from .dockerignore, added COPY to Dockerfile, updated zensical.toml base paths, and fixed snippet path reference.
SimplyPrint reconciliation logic: Fixed printer state checking — OPERATIONAL now correctly maps to COMPLETED instead of PRINTING.
Cross-service event name mismatches: Fixed event publisher/subscriber to use PRINT_JOB_EVENTS.* constants instead of hardcoded strings.
Gateway webhook routing: Fixed SimplyPrint and Sendcloud webhook paths from /api/v1/webhooks/* to /webhooks/* to match controller paths.

Changed¶

Logging architecture: Replaced SentryLoggerService with OtelLoggerService (Pino + OpenTelemetry SDK) across all 5 backend services. Sentry retained for error tracking and performance monitoring. Added 3 new Docker Compose services (otel-collector, clickhouse, grafana) with OTEL_EXPORTER_OTLP_ENDPOINT in all backend services. Deleted 5 sentry-logger.service.ts files.
Environment configuration cleanup: Removed dead integration credential env vars from all 4 services' env.validation.ts and getIntegrationStatuses() — SimplyPrint and Sendcloud credentials are now DB-configured, Shopify uses OAuth.
Monolith API removed: Deleted apps/api/ and apps/api-e2e/ directories entirely (previously deprecated in favor of microservice architecture per ADR-051).
Removed duplicate webhook controllers: Cleaned up duplicate SimplyPrint and Sendcloud webhook controllers, guards, and DTOs from order-service (webhooks now handled exclusively by print-service and shipping-service).
Removed duplicate reconciliation services: Removed duplicate SimplyPrint and Sendcloud reconciliation from order-service (handled by print-service and shipping-service respectively).
Internal prompts reorganization: Updated docs/_internal/README.md to reflect prompts/done/ and prompts/todo/ structure with all completed and upcoming prompts listed.

Documentation¶

TIMELINE.md: Project evolution timeline with AI-human collaboration analysis, feature implementation chronology, and inline PlantUML diagrams.
Patterns evaluation: Comprehensive architectural patterns analysis (docs/03-architecture/patterns-evaluation.md) covering microservices patterns, design patterns, 12-factor app compliance, and enterprise application architecture patterns with inline PlantUML illustrations.
ClickHouse + Grafana logging: Infrastructure config files, application integration guide, and backup strategy documentation for the logging pipeline.
EventCatalog flows: 4 flow visualizations (Order Fulfillment, Order Cancellation, GridFlock Pipeline, Shipping & Tracking) with cross-references to 4 domains and 5 services.
Event handling architecture: Major update to docs/03-architecture/events/README.md — documented two-layer event architecture (internal EventEmitter2 + cross-service BullMQ), bridge pattern, event naming translation table, and service ownership.
CloudEvents evaluation research: New research document (docs/03-architecture/research/cloudevents-evaluation.md) covering gap analysis, cost/benefit, cherry-picked fields, and when to revisit full adoption.
Real-world testing: Added service point delivery setup, grid product configuration in Shopify, and GridFlock pipeline documentation sections to docs/04-development/real-world-testing.md.
State machine diagram: Updated C4_Code_State_Order.puml for FAILED → PROCESSING and PARTIALLY_COMPLETED → PROCESSING transitions.
EventCatalog prompt corrections: Updated prompt with corrected commands (8), queries (7), delivery guarantee (at-least-once), and service subscription tables.
Pre-production flowchart: Updated ROADMAP.md pre-production flow diagram to loop back to the top instead of the replenishment node.

Database¶

Added SimplyPrintConnection and SendcloudConnection models with migration for UI-configurable integration credentials.

Tests¶

Updated bullmq-event-bus.spec.ts with required eventId and source fields.
Updated gateway route config tests for corrected webhook paths.
Added SimplyPrint reconciliation tests for printer-state-aware behavior.

20260217 - 2026-02-17¶

Added¶

Microservice architecture: Split monolith API into 5 independent NestJS services — Gateway (:3000), Order Service (:3001), Print Service (:3002), Shipping Service (:3003), and GridFlock Service (:3004) — with HTTP for synchronous and Redis pub/sub for asynchronous inter-service communication.
API Gateway: New gateway service (apps/gateway/) with session-based auth, HTTP reverse proxy to downstream services, WebSocket proxy, and aggregated health checks.
GridFlock STL generation service: New microservice (apps/gridflock-service/) for automated STL baseplate generation — baseplates, plate sets, async BullMQ job processing, STL-to-gcode pipeline via BambuStudio CLI slicer, SimplyPrint integration, scheduled cleanup, and feature flag guard.
Slicer container: BambuStudio CLI wrapper (deployment/slicer/) with Express REST API for STL slicing, printer profile management (Bambu A1, A1 Mini, P1S), and health checks.
GridFlock database models: GridflockJob and GridflockPreset Prisma models with migration 20260215100000_add_gridflock_tables.
SimplyPrint history-based reconciliation: getJobHistory() API method with graceful fallback chain — 5-minute grace period, triple matching (uid/id/queueItemId), rate limiting (max 10 history lookups per cycle), and escalation logging for persistently missing jobs.
Build agent setup: Automated DigitalOcean droplet provisioning script (deployment/build-agent/setup-build-agent.sh) for Azure DevOps self-hosted build agents.
Container registry cleanup script: Script (scripts/cleanup-registry.sh) for DigitalOcean container registry image cleanup.
Activity log detail modal: Clickable log rows (desktop table and mobile cards) now open a detail modal showing severity, event type, timestamp, message, and contextual action links (e.g. "View Order").
Shopify variant selection in product mapping: Products with multiple variants can be expanded in the Shopify product picker to select a specific variant (e.g. grey vs white).
ECharts dashboard analytics research: Research document (docs/03-architecture/research/echarts-dashboard-analytics-research.md) evaluating Apache ECharts for dashboard analytics with mockup assets and implementation prompt.
ECharts dashboard analytics: Full analytics dashboard with Apache ECharts (v6) — donut charts for order/print job/shipment status distributions, weekly revenue bar chart, 30-day order trend line chart, and enhanced KPI tiles with day-over-day comparison deltas. Includes shared period dropdown (Today / Week / Month / All Time), click-to-filter navigation on donut slices, and lazy-loaded chart components for bundle optimization.
Analytics backend module: New AnalyticsModule with repository, service, controller, and DTOs exposing 6 REST endpoints under /api/v1/analytics/* (order analytics, print job analytics, shipment analytics, revenue trend, order trend, enhanced dashboard stats).
Analytics shared contracts: AnalyticsPeriod, OrderAnalyticsApiResponse, PrintJobAnalyticsApiResponse, ShipmentAnalyticsApiResponse, TrendsApiResponse, EnhancedDashboardStatsApiResponse in libs/domain-contracts.
Analytics database indexes: Composite indexes @@index([tenantId, status, createdAt]) on Order, PrintJob, and Shipment models for efficient analytics queries.
Analytics TanStack Query hooks: useOrderAnalytics, usePrintJobAnalytics, useShipmentAnalytics, useRevenueTrend, useOrderTrend, useEnhancedDashboardStats with automatic refetching.
Bull Board queue dashboard: Integrated BullMQ job queue monitoring UI at /admin/queues on the gateway, accessible only to admin users on the default tenant.
Help & Support admin tiles: Added external link tiles for Aikido Security, Bull Board queue dashboard, pgAdmin, Dozzle, and Sentry in Settings > Help & Support section, visible only to admin users on the default tenant.
Per-service version & uptime display: Extended gateway /health/services endpoint to include per-service uptime. Added ServiceHealthInfo interface and HealthServicesApiResponse type in domain-contracts. Settings page now shows a "Service Versions" card with status badges, versions, and uptime for all microservices.
Shared service context utility: setServiceName()/getServiceName() helpers in libs/observability for consistent per-service identification in Sentry.
Gateway proxy route for push notifications: Added missing /api/v1/push route entry in gateway route config pointing to Order Service.

Fixed¶

pnpm lockfile out of sync: Regenerated pnpm-lock.yaml to include missing form-data dependency causing ERR_PNPM_OUTDATED_LOCKFILE in CI.
Git fetch non-fast-forward in CI: Fixed Nx affected calculation by correcting git fetch behavior with force-ref syntax on self-hosted agents.
Gateway proxy unit tests: Fixed failing proxy service spec.
Toast "New order arrived: undefined": OrderCreatedEvent now includes shopifyOrderNumber so toast notifications display the actual Shopify order number.
Missing ExclamationTriangleIcon import: Fixed lint error on the order detail page.
Integrations page useEffect dependency warnings: Wrapped fetchConnectedShops in useCallback and added it to dependency arrays.
"View Order" button missing for flagged print jobs: Added orderId to the flagForReview log call so the "View Order" link appears for PRINT_JOB_NEEDS_REVIEW activity log entries.
ECharts v6 TypeScript strict types: Fixed formatter callback types (CallbackDataParams), graphic element textAlign → align, and event handler typing for ECharts v6 compatibility.
Microservice crash loops after deployment: Fixed NestJS dependency injection errors in order-service (missing GridflockServiceClient in OrchestrationModule), print-service (missing AuditService in AuthModule), and shipping-service (missing IOrdersService in SendcloudModule).
Gridflock-service crash loop: AuthModule didn't provide AuditService required by AuthController.
Push notification subscription failure: Missing gateway proxy route for /api/v1/push caused 404 after monolith-to-microservices split.
Shipping label 404 returning 500: Fixed createShipment service method to properly throw NotFoundException for non-existent orders; resolved the last failing acceptance test (95/95 now pass).
Sentry service identification: All 5 backend microservices had identical Sentry tags (app: 'api'). Updated each instrument.ts with unique service and component tags, and updated SentryLoggerService to include service attribute on every log entry.
Bull Board 403 on cross-subdomain access: Fixed session cookie issue by adding nginx proxy rule for /admin/queues, using window.location.origin for the link, and enabling trust proxy in gateway Express config.
CI pipeline code coverage not published: Moved --coverage flag after -- separator in pnpm nx run-many so it reaches the test runners instead of being consumed by Nx.
Cosign attestation 401 Unauthorized: Pipeline attestation/verification jobs ran on MS-hosted agents where cosign couldn't authenticate with DigitalOcean registry. Fixed by specifying pool: name: 'DO-Build-Agents' for all attestation jobs.
Unit test --passWithNoTests forwarding on self-hosted agent: --passWithNoTests was not forwarded through the -- separator to Jest, causing 5 projects with no test files to fail.

Changed¶

Azure Pipelines: Rewritten for microservice architecture with parallel build/push stages for gateway, order-service, print-service, shipping-service, gridflock-service, and slicer; image signing (cosign) and SBOM generation (syft) for each service.
Docker Compose staging: Updated for all new microservice containers with Traefik routing and service dependencies.
Staging environment: Updated Traefik routing rules and environment variable template for all new services.
Monolith API deprecated: Marked apps/api/project.json as deprecated in favor of microservice architecture.
Shopify product picker modal: Updated to support expandable variant selection for multi-variant products.
Product mapping form: onSelectShopifyProduct now accepts an optional variant parameter.
Dashboard stat cards: Replaced simple stat cards with enhanced KPI tiles showing trend delta indicators (up/down arrows with day-over-day change values).
Dashboard layout: Added analytics charts section (3 donut charts + 2 trend charts) between KPI tiles and existing lists, with responsive grid layout.
Docker build cache optimization: Created .dockerignore to reduce build context from ~330MB to a few MB. Optimized ARG placement to prevent cache-busting, replaced RUN chown -R with COPY --chown, switched to local BuildKit cache on self-hosted agent, and removed docker builder prune -af that was wiping cache after every deployment.
Microservice configuration cleanup: Trimmed configuration.ts in print-service, shipping-service, and gridflock-service to remove copy-pasted monolith env vars each service doesn't use.
C4 component overview diagram: Refactored C4_Component.puml from monolithic detail view to inter-service ecosystem overview showing communication patterns between the 5 microservices.
C4 web component diagram: Updated C4_Component_Web.puml to reflect current state — new pages (Settings/Integrations, Admin/Users, Audit Logs), PWA components, shipping components, and permission-gated routes.
Pipeline unit test tuning: Added --maxWorkers=2 to limit parallel workers on self-hosted agents and reduce memory pressure.

Removed¶

Deprecated PackageApi pipeline job: Removed the fully disabled PackageApi job and associated apiAffected variable/detection logic from azure-pipelines.yml, as the monolithic API was replaced by microservices per ADR-051.

Documentation¶

ADR-050: Apache ECharts for Dashboard Analytics — decision, rationale, implementation details, alternatives considered, and test coverage.
Updated research document status from "Research / Proposal" to "Implemented" with ADR-050 cross-reference.
Updated docs/03-architecture/research/README.md with ECharts entry.
Updated ADR with SimplyPrint history API integration details (history-based reconciliation, grace period, rate limiting, escalation).
Updated docs/04-development/real-world-testing.md: replaced "no backfill mechanism" warning with self-healing history reconciliation documentation.
Updated C4 architecture diagrams (Context, Container, Component API/Web, Domain Model, DTO Contracts, Deployment, Database) for microservice architecture.
New sequence diagram C4_Seq_10_GridFlockPipeline.puml for GridFlock STL generation pipeline.
Updated sequence diagrams: Shopify webhook, print job creation, print job sync, and fulfillment sequences for microservice routing.
New state machine diagram C4_Code_State_GridflockPipeline.puml for GridFlock job lifecycle.
Updated prisma/ERD.puml with GridFlock entities.
Split monolithic GridFlock prompt into 6 focused part files (docs/_internal/prompts/todo/prompt-gridflock-stl-generation-service-part1.md through part6.md).
New implementation prompts: inventory/stock management, GridFlock microservice architecture, EventCatalog architecture documentation.
Created pipeline template .azuredevops/pipelines/templates/setup-database.yml.
C4 component-level diagrams: 5 new per-microservice PlantUML diagrams — C4_Component_Gateway.puml, C4_Component_OrderService.puml, C4_Component_PrintService.puml, C4_Component_ShippingService.puml, C4_Component_GridflockService.puml.
ClickHouse + Grafana logging research: Research document evaluating OpenTelemetry collector, ClickHouse storage, Grafana dashboards, log rotation, and backup strategy to DigitalOcean Object Spaces.
Uptime Kuma monitoring setup guide: Comprehensive guide with import-ready JSON configuration for monitoring all 13 staging Docker containers.

Database¶

Added GridflockJob and GridflockPreset models with migration 20260215100000_add_gridflock_tables.

Tests¶

Added GridFlock service unit tests: feature guard, pipeline service, service, repository, cleanup service, internal controller, event publisher (7 test files).
Added SimplyPrint history reconciliation tests: API client getJobHistory() tests, reconciliation service history-based fallback tests (grace period, rate limiting, escalation, cleanup).
Added print service SimplyPrint service tests.
Updated push.service.spec.ts and orchestration.service.spec.ts for shopifyOrderNumber in OrderCreatedEvent.
Added shopify-product-picker-modal.test.tsx unit tests for the product picker modal.
Updated new-mapping-page.test.tsx for variant selection behavior.
Added analytics.repository.spec.ts — 11 tests covering all repository methods (groupBy, aggregate, raw SQL queries, date filtering, null handling).
Added analytics.service.spec.ts — 13 tests covering business logic (percentage calculations, zero-division guards, period date filtering, enhanced stats with comparison deltas).
Added analytics.controller.spec.ts — 7 tests covering all 6 endpoints with tenant scoping and period param passthrough.
Added use-analytics.test.tsx — 14 hook tests covering all 6 analytics hooks (loading state, success data, period passthrough, delta values).
Added MSW handlers for all 6 analytics API endpoints with mock data factories.
Added gateway route config test for /api/v1/push route mapping to order-service.
All 95 Gherkin acceptance tests passing on staging after shipping label 404 fix.

0.11.0 - 2026-02-12¶

Added¶

Order "Needs Attention" status: Orders with stuck or failed print jobs are now flagged with a "needs attention" indicator; new filter, badge, and dashboard UI for quick operator triage.
Shopify Fulfillment Orders API: Fulfillment service now uses the Shopify Fulfillment Orders API (getFulfillmentOrders) instead of the deprecated fulfillment endpoint, with new OAuth scopes read_merchant_managed_fulfillment_orders and write_merchant_managed_fulfillment_orders.
Service point delivery: End-to-end support for Sendcloud service point delivery — Prisma schema, note_attributes parsing from Shopify orders, Sendcloud parcel creation with service point fields, and shipping info display on the order detail page.
"Select from Shopify" product picker: Product mapping form now offers a Shopify product picker to select products directly instead of manual data entry.
Settings Integrations page: New UI page for managing Shopify OAuth connections (/settings/integrations).
Activity log and audit log clearing: Admin endpoints and UI ("Clear All" button) for clearing event logs and audit logs, gated behind new logs.write and audit.write permissions.
Stuck job monitor: StuckJobMonitorService detects and resolves stuck print jobs with configurable thresholds; admin API endpoints for force-status, stuck-job listing, and threshold management.
SimplyPrint job_unassigned webhook: New webhook event handler for unassigned print jobs with reconciliation support.
simplyprintQueueItemId tracking: New Prisma field on PrintJob for tracking SimplyPrint queue item IDs, enabling accurate job-to-queue mapping.
Product mapping activate/deactivate: Replaced boolean isActive with explicit activate/deactivate actions across API, domain, and web layers.
Settings page enhancements: Frontend version display and PWA sync information.
Route preloading: Lazy route preloading and <link rel="preload"> hints for faster dashboard navigation (Lighthouse performance optimization).
Configurable SIMPLYPRINT_API_URL: SimplyPrint base URL is now configurable via environment variable.
Shopify theme: Storefront theme in deployment/shopify-theme/ with design system, sections, templates, and logos.
Penetration testing research: Methodology document (docs/03-architecture/research/penetration-testing-research.md) covering staging pen-test tools, reports, and NIS2 compliance.
Disaster recovery research: Research document (docs/03-architecture/research/disaster-recovery-research.md) for backup and recovery planning.
Marketing research: Research document (docs/03-architecture/research/marketing-research.md) covering product photoshoot, webshop copy, Instagram content, and blog strategy.

Fixed¶

Shopify fulfillment error: Fulfillment service now uses the Fulfillment Orders API, resolving errors caused by the deprecated fulfillment endpoint.
Shopify webhook route mismatch: Fixed 404s caused by Shopify posting to /shopify/webhooks while the API expected /api/v1/webhooks/shopify; updated webhook guard, service, and routes.
Product mapping edit mode: Fixed edit form not loading existing mapping data correctly.
SimplyPrint job ID release: Relaxed releaseSimplyPrintJobId to allow release from active jobs (QUEUED/ASSIGNED/PRINTING), fixing "Cannot release simplyPrint.JobId" errors when the same file is queued multiple times.
Cancelled orders excluded from "Needs Attention": CANCELLED orders no longer appear in the needs-attention filter or failed print job counts.
Fulfillment error status transition: Fulfillment error handler no longer incorrectly transitions an order from COMPLETED to FAILED; status update wrapped in try/catch.
SimplyPrint webhook guard: Made X-SP-Token verification optional when SIMPLYPRINT_WEBHOOK_SECRET is not configured.
Shopify backfill OAuth: Fixed API request handling for OAuth-connected shops during backfill.

Changed¶

Shopify OAuth scopes: Added read_merchant_managed_fulfillment_orders and write_merchant_managed_fulfillment_orders scopes to shopify.app.toml and configuration.
Acceptance tests: Global setup/teardown now persists seeded data to JSON for cross-worker sharing; product mapping steps use activate/deactivate instead of isActive.
Default Shipping Method docs: Updated to point to Verzenden (Shipping) instead of Settings → Integrations, with API-based shipping method ID lookup.
Order detail page: Added "Force status" button for resolving stuck print jobs.

Documentation¶

Updated docs/04-development/real-world-testing.md with Shopify webhook URL configuration, SimplyPrint webhook process, Sendcloud test mode, and service point delivery setup.
Updated docs/05-deployment/staging-deployment-guide.md with OAuth and webhook environment variables.
Updated docs/04-development/keys-certificates-inventory.md with webhook secrets and fulfillment scopes.
Updated runbook with Shopify theme installation instructions and stuck job troubleshooting.
Updated architecture docs (ADR, C4 models, sequences, ERD) for needs-attention flow and fulfillment orders.

Database¶

Added simplyprintQueueItemId field to PrintJob model with migration.

Tests¶

Updated fulfillment service tests for Fulfillment Orders API flow.
Updated SimplyPrint service, reconciliation, and webhook tests for job_unassigned and simplyprintQueueItemId.
Updated print job service, repository, and controller tests for queue item tracking.
Updated orders repository tests for needs-attention filter and hasFailedJobs.
Updated product mapping tests for activate/deactivate (removed isActive from specs and mocks).
Updated acceptance tests with seeded data persistence and activate/deactivate product mapping flows.
Updated push notification and notification service tests.

0.10.0 - 2026-02-03¶

Added¶

Shopify OAuth 2.0 Authentication: Full OAuth flow implementation replacing legacy static API keys for multi-shop support (ADR-048).
OAuth authorization flow with CSRF protection (/api/v1/shopify/oauth/authorize, /api/v1/shopify/oauth/callback)
Encrypted token storage using AES-256-GCM with HMAC verification
Automatic token refresh for expiring tokens (24-hour threshold)
App uninstall webhook handler with HMAC verification
Admin endpoints for shop management (/api/v1/shopify/oauth/shops, /api/v1/shopify/oauth/status)
Multi-shop backfill support: Enhanced ShopifyBackfillService to support both legacy mode and OAuth-connected shops with per-shop watermarks.
Third-party CLI & MCP server research: Added research document (docs/03-architecture/research/third-party-cli-mcp-research.md) documenting CLI and MCP server availability for Shopify, SendCloud, and SimplyPrint.
GridFlock feasibility study: Added research document for STL generation service (docs/03-architecture/research/gridflock-feasibility-study.md).
SimplyPrint emulator feasibility study: Added research document for virtual printer testing (docs/03-architecture/research/SimplyPrint-emulator-feasibility-study.md).
AI agent cluster feasibility study: Added research document for PicoCluster with OpenClaw (docs/03-architecture/research/ai-agent-cluster-feasibility-study.md).
Design documentation: Added docs/09-design/ folder with Shopify storefront mockups and design notes.

Changed¶

Shopify API upgraded to 2026-01: Updated all Shopify API calls to use the latest API version.
ShopifyApiClient: Added requestForShop() and requestForShopByDomain() methods for per-shop token support while maintaining backward compatibility with legacy static token mode.
Container registry cleanup: Improved error handling and resilience in scripts/cleanup-registry.sh.
Docker build process: Enhanced Docker image builds for API and Web with optimized multi-stage builds.
Documentation site: Updated Dockerfile for PlantUML integration and optimized rendering process.
Real-world testing docs: Updated Shopify app creation instructions for Dev Dashboard (legacy custom apps deprecated as of January 1, 2026).

Documentation¶

ADR-048: Shopify OAuth 2.0 Authentication decision documenting the migration from static API keys to OAuth.
Updated docs/04-development/real-world-testing.md with OAuth setup instructions.
Updated docs/04-development/runbook.md with OAuth troubleshooting section.
Updated docs/04-development/security-audit-checklist.md with OAuth-specific security checks.
Updated C4 diagrams with ShopifyShop entity and OAuth sequence diagram (C4_Seq_09_ShopifyOAuth.puml).
Updated research README with all feasibility studies.

Database¶

Added ShopifyShop model for storing OAuth-connected shop credentials with encrypted tokens.
Migration 20260128000000_add_shopify_oauth for new ShopifyShop table.

Tests¶

Added ShopifyTokenService unit tests for token encryption, decryption, and refresh.
Added ShopifyOAuthController unit tests for OAuth flow endpoints.
Updated ShopifyBackfillService tests for multi-shop backfill support.

0.9.0 - 2026-01-27¶

Added¶

Role-Based Access Control (RBAC): Full multi-user authentication with session-based login, Argon2id password hashing, and permission-based authorization.
User Management UI: Admin interface to create, edit, and deactivate users with role assignment (accessible via Settings → Administration for users with users.read/users.write permissions).
Audit Logs UI: Admin page (/admin/audit-logs) displaying security-relevant events with filtering by user, action type, and date range (requires audit.read permission).
Predefined Roles: Four built-in roles (admin, operator, viewer, legacy-admin) with appropriate permission bundles.
Session Authentication: HTTP-only cookie-based sessions with PostgreSQL session store, replacing API key requirement for dashboard access.
Tenant-Ready Architecture: All entities include tenantId for future multi-tenant support; single default tenant for current operations.
Security Auditing: AuditLog table captures authentication events, permission changes, and security-relevant actions.
Shopify order backfill service for downtime recovery: scheduled job polls Shopify Orders API to catch orders missed during webhook delivery failures (configurable via SHOPIFY_BACKFILL_ENABLED, SHOPIFY_BACKFILL_BATCH_SIZE).
Admin endpoints for Shopify backfill management (GET /api/v1/admin/shopify/backfill/status, POST /api/v1/admin/shopify/backfill/trigger, POST /api/v1/admin/shopify/backfill/reset).
SystemConfigService for durable key-value storage of operational state (backfill watermarks, etc.).
SimplyPrint webhook idempotency using database-backed deduplication (reuses ProcessedWebhook table).
SimplyPrint job reconciliation service: scheduled job (every minute) that syncs print job statuses with SimplyPrint API to catch missed webhooks (configurable via SIMPLYPRINT_RECONCILIATION_ENABLED).
SendCloud webhook receiver for real-time shipment status updates (POST /webhooks/sendcloud) with HMAC-SHA256 signature verification (configurable via SENDCLOUD_WEBHOOK_SECRET).
SendCloud shipment reconciliation service: scheduled job (every 5 minutes) that polls SendCloud API to catch missed webhook updates (configurable via SENDCLOUD_RECONCILIATION_ENABLED).
IShipmentsService.findBySendcloudParcelId() method for parcel ID lookups.
Structured event logging for ShipmentsService (shipment.created, shipment.status_changed, shipment.cancelled, shipment.tracking_updated, shipment.label_generated).
CI/CD: docs image now receives staging and production promotion attestations (parity with API and Web images).
Container registry cleanup script (scripts/cleanup-registry.sh) now processes forma3d-connect-docs repository and uses promotion-aware cleanup logic.

Fixed¶

Push subscriptions: validated input for subscription cleanup endpoints to prevent a NoSQL-injection style payload from reaching Prisma filters.
SSL certificate configuration for PostgreSQL session store in staging/production environments.
Webhook guard tests: fixed mocks to use configService.get() instead of getOrThrow().

Changed¶

Acceptance tests (Playwright BDD): removed flaky networkidle waits and tightened step synchronization; re-enabled previously skipped flaky scenarios in orders + product mappings UI specs.
Orders page (/orders) now supports client-side search filtering (order number, customer name, email), aligning UI behavior with acceptance coverage.
Observability: Sentry sampling is now configurable via env vars with safer production defaults (10% traces/profiles by default), and staging env template documents SENTRY_TRACES_SAMPLE_RATE / SENTRY_PROFILES_SAMPLE_RATE (plus VITE_SENTRY_TRACES_SAMPLE_RATE for the web build).
Backend robustness: runtime validation added for Prisma Json columns (shippingAddress, print profiles, event metadata), and remaining generic error throws were replaced with typed DomainError variants where applicable.
External integrations: API client timeouts and webhook idempotency retention are now configurable via ConfigService (apiTimeout.*, webhook.idempotencyRetentionHours).
Container registry cleanup: improved retention logic to preserve currently-deployed images and promotion-attested images, with docs repository now included.
C4 context model updated to include SendCloud (shipping) and Sentry (observability) as external systems.

Security¶

Backend API: enforce X-API-Key authentication globally for all endpoints except /health/** and external webhook receivers; removed the "allow when INTERNAL_API_KEY is missing" bypass (fail-closed).
Real-time updates: secured Socket.IO /events namespace with the same internal API key.
SimplyPrint inbound webhooks: require SIMPLYPRINT_WEBHOOK_SECRET (fail-closed) for webhook verification.
RBAC Guards: SessionGuard and PermissionsGuard enforce authentication and authorization on all protected routes.
Password Security: Argon2id hashing with automatic rehashing on algorithm/parameter updates.

Documentation¶

ADR-047: Two-Tier Logging Strategy documenting Application Logs (Pino), Business Events (EventLog), and Security Audit (AuditLog).
User manual updated with Audit Logs page documentation and new screenshots.
Updated docs/04-development/AI-implementation-advantage.md with real cost data from January 2026.

Tests¶

Added missing Nest controller unit tests across API modules (Shopify, Sendcloud, SimplyPrint webhook, Product Mappings, Event Log, Observability, Cancellation, Test Seeding, App).
Added User Management UI unit tests (UserFormModal, ChangePasswordModal, UsersPage component tests).
Added ShipmentsService event logging unit tests (create, status change, cancel, tracking update, label generation).
Added Audit Logs controller tests and acceptance test coverage.

0.8.0 - 2026-01-21¶

Added¶

User manual in docs/08-user-manual/ with automated screenshot capture into docs/assets/user-manual/ via scripts/capture-user-manual-screenshots.ts.
Product-mapping "part library" API for reusing parts at scale: GET /api/v1/product-mappings/parts (search + pagination by parts).
"Use existing" part picker in the Product Mapping form (/mappings/new, /mappings/:id/edit) with search and Prev/Next pagination.

Changed¶

Product mappings now always model printable Parts: creating/updating a mapping requires at least 1 part, and the UI no longer offers "Single Part vs Assembly".
Print job creation now always iterates mapping parts (a single-part product is a mapping with exactly 1 part).

Removed¶

ProductMapping.isAssembly removed from the database schema and API/domain contracts.

Documentation¶

Updated prisma/ERD.puml and related docs to reflect the "always parts" model.

Tests¶

Added/updated unit + acceptance coverage for copying an existing part into a new mapping and for the parts library query/pagination.

0.7.1 - 2026-01-20¶

Added¶

POST /api/v1/push/test test endpoint to send a Web Push notification to all subscribed clients (excluded and blocked in production).

0.7.0 - 2026-01-19¶

Added¶

Progressive Web App (PWA) support for the dashboard (manifest, service worker caching, install/update prompts).
Web Push notifications end-to-end (push subscription persistence, backend push service, frontend subscription flow).
VAPID-based server configuration for Web Push (VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT).
Offline-first UX (IndexedDB caching, queued actions for later sync, online/offline indicators).

Changed¶

Dashboard experience optimized for mobile and "app-like" usage (install guidance, pull-to-refresh, app badges where supported).

0.6.0 - 2026-01-18¶

Added¶

Production hardening: added operational documentation (runbook, troubleshooting, environment setup, keys/certificates inventory, security audit checklist).
Load testing integrated into CI/CD (optional LoadTest stage with runLoadTests and loadTestBaselineMode parameters; k6 thresholds and baseline mode).

Security¶

Dependency vulnerability remediation:
@remix-run/router 1.22.0 → 1.23.2 (CVE-2026-22029)
react-router-dom 6.29.0 → 6.30.3 (CVE-2025-68470)
Removed vulnerable transitive axios@0.21.4 via pnpm override (CVE-2025-27152)

Changed¶

Health checks and diagnostics improved for external integrations and runtime dependencies.

0.5.0 - 2026-01-16¶

Added¶

Sendcloud shipping integration:
Shipment persistence (Shipment model + ShipmentStatus)
Sendcloud API client + shipping service listening to order.ready-for-fulfillment
Shipment/shipping endpoints and dashboard shipping UI (label download, regenerate, cancel)
Shipping acceptance coverage (apps/acceptance-tests/src/features/shipping.feature).

0.4.0 - 2026-01-14¶

Added¶

Dashboard MVP foundation:
UI component kit (Button, Badge, Card, Input, Select, Modal, Pagination, LoadingSpinner, EmptyState)
Auth context (API key storage) and protected routing
TanStack Query integration and extended API client
Order management UI (/orders, /orders/:id) with manual actions (retry print job, cancel order).
Product mapping UI (/mappings, /mappings/new) including assembly parts editor for multi-part products.
Activity logs UI (/logs) with filtering + CSV export.
Real-time updates via Socket.IO (backend EventsGateway, frontend SocketProvider, toast notifications).

0.3.0 - 2026-01-14¶

Added¶

Fulfillment automation loop (print completion → Shopify fulfillment) with a manual "force fulfill" path.
Cancellation handling (Shopify cancel → cancel/flag SimplyPrint jobs; operator notifications for edge cases).
Retry queue with exponential backoff + jitter and operator notification for repeated failures.

0.2.0 - 2026-01-13¶

Added¶

SimplyPrint core integration:
apps/api/src/simplyprint/ (API client, webhook controller, token guard, DTOs)
apps/api/src/print-jobs/ (create/update/cancel/retry + REST endpoints)
apps/api/src/orchestration/ (order-to-job orchestration and order.ready-for-fulfillment)
Print job endpoints:
GET /api/v1/print-jobs, GET /api/v1/print-jobs/active, GET /api/v1/print-jobs/:id
GET /api/v1/print-jobs/order/:orderId
POST /api/v1/print-jobs/:id/cancel, POST /api/v1/print-jobs/:id/retry
POST /webhooks/simplyprint

0.1.3 - 2026-01-12¶

Added¶

apps/acceptance-tests/ Playwright + Gherkin test project (playwright-bdd).
Feature coverage for staging verification:
health-check.feature
api-docs.feature (Swagger UI + OpenAPI spec)
web-dashboard.feature (dashboard smoke tests)
CI integration: acceptance test stage that publishes JUnit results and HTML report artifacts.

0.1.2 - 2026-01-10¶

Added¶

Automated staging deployment:
apps/api/Dockerfile + apps/web/Dockerfile (multi-stage)
apps/web/nginx.conf for SPA routing
deployment/staging/docker-compose.yml, deployment/staging/traefik.yml, deployment/staging/deploy.sh, deployment/staging/env.staging.template
CI/CD pipeline extended with Docker packaging and staging deploy (including migration handling).

0.1.1 - 2026-01-10¶

Added¶

Full-stack observability (Sentry error tracking + performance monitoring, OpenTelemetry tracing, structured JSON logging with correlation IDs).
Frontend error boundaries and shared observability utilities.

0.1.0 - 2026-01-09¶

Added¶

Shopify inbound integration:
Shopify Admin API client (apps/api/src/shopify/shopify-api.client.ts) including rate-limit retry
Webhook receiver at POST /api/v1/webhooks/shopify (orders/create, orders/updated, orders/cancelled, orders/fulfilled)
Orders API (/api/v1/orders) and Product Mapping API (/api/v1/product-mappings)
Order persistence with idempotency, validated status transitions, event emission, and audit/event logging.
Product mapping system with assembly parts support and unmapped SKU detection.
OpenAPI/Swagger API documentation.

Security¶

Webhook authenticity verification (HMAC validation) and defensive handling for idempotency and replay/duplication scenarios.

0.0.0 - 2026-01-09¶

Added¶

Nx monorepo foundation (apps/api, apps/web, shared libraries) with strict TypeScript and workspace linting.
PostgreSQL + Prisma schema (orders, line items, print jobs, product mappings/assemblies, event logs, system config, printers).
CI pipeline scaffolding and environment configuration templates.