Skip to content

AI Prompt: Part 6 — Event Flow Verification + Documentation + Cleanup

Series: Forma3D.Connect Microservice Decomposition + GridFlock STL Pipeline (Part 6 of 6) Purpose: Verify all event flows end-to-end, update all project documentation to reflect the new architecture, and clean up the deprecated monolith Estimated Effort: 18–26 hours Prerequisites: Parts 1–5 completed (all services deployed and working on staging) Output: All event flows verified, all documentation updated (C4, ADRs, sequences, state machines, event catalog, deployment guides), monolith deprecated Status: 🚧 TODO Previous Part: Part 5 — Order-GridFlock Integration + Docker/CI

🎯 Mission

This is the final part. All services are built and deployed. Now we need to:

  1. Verify every event flow works end-to-end across services
  2. Update all documentation to reflect the new microservice architecture
  3. Clean up the deprecated monolith and old pipeline artifacts
  4. Verify horizontal scaling works as designed

What this part delivers:

  1. Event Flow Verification — Systematic testing of all cross-service workflows
  2. Documentation Updates — C4 diagrams, ADRs, sequence diagrams, state machines, event catalog, deployment guides, pipeline reference
  3. Horizontal Scaling Verification — Confirm all scaling solutions work
  4. Cleanup — Deprecate apps/api, remove old pipeline jobs

📌 Prerequisites (Parts 1–5 Completed)

Verify these before starting:

  • All services running on staging (gateway, order, print, shipping, gridflock, slicer)
  • Redis running and accessible
  • All existing API endpoints working through gateway
  • GridFlock pipeline working end-to-end
  • Azure DevOps pipeline deploying all services
  • Uptime Kuma and Dozzle accessible

🔧 Implementation

Phase 11: Event Flow Verification (8–10 hours)

Priority: Critical | Impact: Very High

Systematically test every cross-service workflow:

11.1 Order Creation → Print Job Creation (HTTP)

Test: Create order via Shopify webhook
Expected: Order Service creates order → HTTP call to Print Service → print jobs created
Verify: Print jobs exist in DB with correct orderId and lineItemId

11.2 Print Job Completion → Order Status Update (BullMQ)

Test: Complete a print job in SimplyPrint (or simulate via webhook)
Expected: Print Service publishes print-job.completed → Order Service receives → recalculates order
Verify: Order status updated, part counts recalculated

11.3 Order Fulfillment → Shipment Creation (HTTP)

Test: All print jobs for an order complete
Expected: Order Service → FulfillmentService → HTTP call to Shipping Service → shipment created
Verify: Shipment exists, Sendcloud parcel created (if shipping enabled)

11.4 Shipment Creation → Fulfillment Completion (BullMQ)

Test: Shipment created with tracking info
Expected: Shipping Service publishes shipment.created → Order Service → Shopify fulfillment with tracking
Verify: Shopify fulfillment created with tracking number

11.5 GridFlock Pipeline: New Size

Test: Shopify order with GRID-CUSTOM SKU and new dimensions
Expected: Full pipeline: detect → generate STL → slice → upload to SimplyPrint → create mapping → print jobs
Verify: ProductMapping created with correct SKU, print jobs created, SimplyPrint files uploaded

11.6 GridFlock Pipeline: Existing Size

Test: Order with same GridFlock dimensions as a previous order
Expected: Mapping found → print jobs created immediately, no generation
Verify: No new STL generation, print jobs reference existing mapping

11.7 GridFlock Pipeline Failure

Test: Trigger pipeline with invalid parameters (e.g., slicer timeout)
Expected: gridflock.pipeline-failed event → Order Service marks line item failed → notification
Verify: Error event published with correct failedStep, operator notified

11.8 Concurrent GridFlock Orders (Race Condition)

Test: Two orders for same new GridFlock size arriving simultaneously
Expected: Only one generates, other detects existing mapping
Verify: Single ProductMapping created, both orders get print jobs

11.9 Tenant Print Settings

Test: Configure different print settings for a tenant, trigger generation
Expected: Slicer called with tenant-specific profiles
Verify: Gcode produced with correct nozzle/layer/filament settings

11.10 Cancellation Across Services

Test: Cancel an order that has active print jobs and a pending shipment
Expected: Order Service → Cancel print jobs (HTTP to Print Service) → Cancel shipment (HTTP to Shipping Service)
Verify: All print jobs cancelled, shipment cancelled

11.11 Error Handling and Retries

Test: Simulate transient failure in Print Service during job creation
Expected: BullMQ retries the event, eventually succeeds
Verify: Event processed after retry, no duplicate processing

11.12 Load Test Event Bus

Test: Submit 50 concurrent orders
Expected: All orders processed without duplicate events or missed events
Verify: Correct number of print jobs created, no duplicate processing

Phase 12: Documentation Updates (8–12 hours)

Priority: High | Impact: High

The microservice decomposition and GridFlock pipeline are major architectural changes. All relevant documentation MUST be updated.

12.1 C4 Model — Level 1 Context

File: docs/03-architecture/c4-model/1-context/C4_Context.puml - Add GridFlock Service, Slicer Container, and Redis as system components - Update the API boundary to show API Gateway instead of monolithic API

12.2 C4 Model — Level 2 Container

File: docs/03-architecture/c4-model/2-container/C4_Container.puml - Replace single api container with: Gateway, Order Service, Print Service, Shipping Service, GridFlock Service, Slicer Container - Add Redis container - Show inter-service communication (HTTP + BullMQ events)

12.3 C4 Model — Level 3 Component

File: docs/03-architecture/c4-model/3-component/C4_Component.puml - Update to show internal module decomposition per service - Add GridFlock pipeline components

12.4 C4 Model — Level 3 Component Web

File: docs/03-architecture/c4-model/3-component/C4_Component_Web.puml - Verify web diagram still reflects reality (minimal changes since gateway preserves endpoints)

12.5 C4 Model — Level 4 Code / Domain Model

File: docs/03-architecture/c4-model/4-code/C4_Code_DomainModel.puml - Add GridFlock domain entities: GridflockJob, GridflockPreset - Add slicer-related models: PrintSettings, SlicerProfile - Update ProductMapping for GridFlock fields

12.6 C4 Model — Level 4 Code / DTO Contracts

File: docs/03-architecture/c4-model/4-code/C4_Code_DTOContracts.puml - Add inter-service DTOs - Add GridFlock DTOs

12.7 C4 Model — Deployment

File: docs/03-architecture/c4-model/deployment/C4_Deployment.puml - Multi-service deployment on DigitalOcean Droplet (4 GB) - Add Redis, Slicer, Uptime Kuma, Dozzle

12.8 C4 Model — Database

File: docs/03-architecture/c4-model/deployment/C4_Database.puml - Add GridFlock tables - Add SystemConfig entries

12.9 ADR — Architecture Decision Records

File: docs/03-architecture/adr/ADR.md

Add new ADRs: - "Decompose monolithic API into domain-aligned microservices" - "Use BullMQ event queues for inter-service async communication" - "Buffer-based GridFlock pipeline (no local file storage)" - "SimplyPrint API Files for gcode upload (Print Farm plan required)" - "BambuStudio CLI slicer container (SimplyPrint cloud slicer not API-accessible)" - "Redis for sessions, event queues, and Socket.IO adapter"

12.10 Sequence Diagrams

Directory: docs/03-architecture/sequences/

  • New: C4_Seq_10_GridFlockPipeline.puml — Full pipeline: Shopify order → detect → check SKU → generate STL → slice → upload → mapping → print
  • Update: C4_Seq_01_ShopifyWebhook.puml — Multi-service flow
  • Update: C4_Seq_03_PrintJobCreation.puml — Print Service as separate service
  • Update: C4_Seq_04_PrintJobSync.puml — SimplyPrint polling in Print Service
  • Update: C4_Seq_05_Fulfillment.puml — Multi-service orchestration

12.11 State Machines

Directory: docs/03-architecture/state-machines/

  • New: C4_Code_State_GridflockPipeline.puml — States: PENDING → GENERATING_STL → SLICING → UPLOADING → CREATING_MAPPING → COMPLETE / FAILED

12.12 Event Catalog

File: docs/03-architecture/events/README.md

  • Add all BullMQ event types with schemas, publishers, subscribers
  • Replace EventEmitter2 references with BullMQ event queues
  • Document event delivery guarantees

12.13 Deployment Guide

File: docs/05-deployment/staging-deployment-guide.md

  • Update Docker Compose service list
  • Update deployment order (Redis → backends → gateway)
  • Add Redis configuration section
  • Add slicer container configuration
  • Update environment variable inventory
  • Add Uptime Kuma and Dozzle setup

12.14 Pipeline Reference

File: docs/05-deployment/pipeline-reference.md

  • Add new Package jobs
  • Update affected detection
  • Document image tagging strategy

12.15 Architecture README

File: docs/03-architecture/README.md

  • Update overview to describe microservice topology
  • Link to new C4 diagrams and sequences

12.16 Implementation Plan

File: docs/04-development/implementation-plan.md

  • Reflect microservice architecture phases
  • Add GridFlock pipeline as milestone

Phase 13: Cleanup (2–4 hours)

13.1 Deprecate apps/api

  • Mark apps/api as deprecated in its project.json
  • Add README noting it's replaced by the microservice architecture
  • Keep temporarily for rollback capability

13.2 Remove Old Pipeline Jobs

  • Remove PackageApi job from azure-pipelines.yml
  • Remove API_IMAGE_TAG and apiImageName pipeline variables
  • Remove apiAffected detection

13.3 Final Consistency Check

  • Verify all documentation reflects the new architecture
  • No stale references to monolithic API in any documentation
  • All Nx projects build and lint successfully

🧪 Horizontal Scaling Verification

Verify all 5 scaling solutions work:

1. Sessions — Redis-Backed

  • Gateway sessions stored in Redis
  • docker compose up --scale gateway=2 → sessions work across replicas

2. Event Bus — BullMQ

  • Each event type is a BullMQ queue
  • Only one worker instance processes each event (no duplicates)
  • Retry works (3 attempts, exponential backoff)
  • Dead letter retention for failed events

3. Socket.IO — Redis Adapter

  • WebSocket events broadcast across Gateway replicas

4. GridFlock Pipeline — Buffer-Based

  • No files written to disk at any point
  • Plates processed sequentially (bounded memory)
  • SimplyPrint is the only permanent storage

5. Database — Connection Pooling

  • connection_limit=3 in all DATABASE_URL strings
  • With 3 replicas × 5 services × 3 connections = 45 total (within PostgreSQL limits)

6. Idempotent Event Handlers

  • All handlers check if work already done before acting
  • Duplicate events don't cause duplicate processing

✅ Final Validation Checklist

Build & Lint

  • pnpm nx run-many -t build --all succeeds
  • pnpm nx run-many -t lint --all passes
  • pnpm nx run-many -t test --all passes
  • No TypeScript errors

Full System

  • All services running on staging
  • Gateway health aggregates all services as healthy
  • apps/web works without changes

Event Flows

  • Order → print jobs (HTTP)
  • Print completion → order update (BullMQ)
  • Order ready → shipment (HTTP)
  • Shipment → fulfillment (BullMQ)
  • GridFlock: new size pipeline works end-to-end
  • GridFlock: existing size skips generation
  • Cancellation across services

Monitoring

  • Uptime Kuma monitors all service health endpoints
  • Uptime Kuma notifications configured
  • Dozzle shows all containers with live logs
  • Sentry receives errors from all services

Documentation

  • C4 Level 1–4 diagrams updated
  • C4 Deployment + Database diagrams updated
  • ADR entries added (6 new decisions)
  • GridFlock pipeline sequence diagram
  • GridFlock state machine diagram
  • Event catalog with all BullMQ events
  • Staging deployment guide updated
  • Pipeline reference updated
  • Architecture README updated
  • No stale monolith references in docs

Verification Commands

# Build all (local)
pnpm nx run-many -t build --all

# Lint all
pnpm nx run-many -t lint --all

# Test all
pnpm nx run-many -t test --all

# Verify gateway health (aggregates all services)
curl http://localhost:3000/health

# Verify individual services
curl http://localhost:3001/health  # Order Service
curl http://localhost:3002/health  # Print Service
curl http://localhost:3003/health  # Shipping Service
curl http://localhost:3004/health  # GridFlock Service
curl http://localhost:3010/health  # Slicer

# Verify existing order flow
curl http://localhost:3000/api/v1/orders -H "Cookie: session=..."

# Verify GridFlock (authenticated)
curl -X POST http://localhost:3000/api/v1/gridflock/baseplates/sync \
  -H "Content-Type: application/json" \
  -H "Cookie: session=..." \
  -d '{"gridX": 2, "gridY": 2, "magnets": true, "connectorType": "none"}' \
  --output test.stl

# Verify Redis
docker compose exec redis redis-cli ping

# Verify staging deployment
ssh root@167.172.45.47 "docker ps --format 'table {{.Names}}\t{{.Status}}'"
ssh root@167.172.45.47 "curl -s http://localhost:3000/health | jq ."

# Verify Nx affected detection
pnpm nx show projects --affected --base=main --head=HEAD --type=app

🚫 Constraints

  • Documentation updates are NOT optional — stale docs are worse than no docs
  • No stale references to monolithic API in any updated documentation
  • All NestJS services must output JSON structured logs
  • Keep Sentry — Dozzle does NOT replace it
  • apps/api kept temporarily for rollback (do not delete yet)
  • No any, ts-ignore, or eslint-disable

📚 Key References

Documentation Files to Update

  • docs/03-architecture/c4-model/1-context/C4_Context.puml
  • docs/03-architecture/c4-model/2-container/C4_Container.puml
  • docs/03-architecture/c4-model/3-component/C4_Component.puml
  • docs/03-architecture/c4-model/3-component/C4_Component_Web.puml
  • docs/03-architecture/c4-model/4-code/C4_Code_DomainModel.puml
  • docs/03-architecture/c4-model/4-code/C4_Code_DTOContracts.puml
  • docs/03-architecture/c4-model/deployment/C4_Deployment.puml
  • docs/03-architecture/c4-model/deployment/C4_Database.puml
  • docs/03-architecture/adr/ADR.md
  • docs/03-architecture/sequences/ (existing + new)
  • docs/03-architecture/state-machines/ (new GridFlock)
  • docs/03-architecture/events/README.md
  • docs/05-deployment/staging-deployment-guide.md
  • docs/05-deployment/pipeline-reference.md
  • docs/04-development/implementation-plan.md
  • docs/03-architecture/README.md

External References

  • Uptime Kuma: https://uptime.kuma.pet/
  • Dozzle: https://dozzle.dev/
  • Dozzle SQL: https://dozzle.dev/guide/sql-engine

END OF PART 6 — SERIES COMPLETE

This completes the Forma3D.Connect microservice decomposition and GridFlock STL pipeline implementation.

Summary of all 6 parts: 1. Part 1: Shared Infrastructure & Libraries (8–12h) 2. Part 2: API Gateway + Order Service (24–30h) 3. Part 3: Print Service + Shipping Service + Event Rewiring (20–26h) 4. Part 4: GridFlock Service + Slicer Container (22–28h) 5. Part 5: Order-GridFlock Integration + Docker/CI (24–32h) 6. Part 6: Event Verification + Documentation + Cleanup (18–26h)

Total estimated effort: 116–154 hours