AI Prompt: Part 1 — Shared Infrastructure & Libraries¶

apps/api/src/
├── analytics/         ─┐
├── audit/              │
├── auth/               │
├── cancellation/       │
├── common/             │
├── config/             │
├── database/           │  ALL IN ONE PROCESS
├── event-log/          │
├── fulfillment/        │
├── gateway/ (Socket.IO)│
├── notifications/      │
├── observability/      │
├── orchestration/      │
├── orders/             │
├── print-jobs/         │
├── product-mappings/   │
├── push-notifications/ │
├── retry-queue/        │
├── sendcloud/          │
├── shipments/          │
├── shopify/            │
├── simplyprint/        │
├── tenancy/            │
├── throttler/          │
├── users/             ─┘
└── versioning/

Order created → ORDER_EVENTS.CREATED
  → Orchestration: sets order PROCESSING, creates print jobs

Print job completed → PRINT_JOB_EVENTS.COMPLETED
  → Orchestration: recalculates part counts, checks order completion

Order ready → ORCHESTRATION_EVENTS.ORDER_READY_FOR_FULFILLMENT
  → Fulfillment: creates Shopify fulfillment

Shipment created → SHIPMENT_EVENTS.CREATED
  → Fulfillment: adds tracking info to fulfillment

IOrdersService     → used by Orchestration, Fulfillment, Sendcloud
IPrintJobsService  → used by Orchestration, Cancellation
IShipmentsService  → used by Sendcloud, Orders
IFulfillmentService → used by Gateway (status checks)

libs/domain/            — Domain entities, enums, types, errors, Zod schemas
libs/domain-contracts/  — Service interfaces (IOrdersService, etc.), DTOs
libs/api-client/        — External API client types (SimplyPrint, Sendcloud)
libs/config/            — Shared configuration constants
libs/utils/             — Date/string utilities
libs/observability/     — Sentry + OpenTelemetry configuration
libs/testing/           — Centralized test fixtures

traefik  — Reverse proxy with Let's Encrypt
api      — NestJS monolith (port 3000)
web      — React frontend (port 80)
docs     — Documentation site
pgadmin  — PostgreSQL admin

                        ┌─────────────┐
                        │   Clients   │
                        └──────┬──────┘
                               │
                        ┌──────▼──────┐
                        │ API Gateway │  ← Part 2
                        └──────┬──────┘
                               │
          ┌────────────────────┼────────────────────┐
          │                    │                     │
    ┌─────▼──────┐     ┌──────▼──────┐      ┌──────▼──────┐
    │   Order    │     │   Print    │      │  Shipping  │
    │  Service   │     │  Service   │      │  Service   │  ← Parts 2–3
    └─────┬──────┘     └──────┬─────┘      └──────┬─────┘
          │            ┌──────▼──────┐             │
          │            │  GridFlock  │             │  ← Part 4
          │            │  Service    │             │
          │            └──────┬──────┘             │
          │            ┌──────▼──────┐             │
          │            │   Slicer   │             │  ← Part 4
          │            └──────┬──────┘             │
    ┌─────▼────────────────────▼────────────────────▼─────┐
    │   Redis (BullMQ Events + Queues + Sessions)  ← THIS PART │
    └─────────────────────────┬───────────────────────────┘
    ┌─────────────────────────▼───────────────────────────┐
    │                   PostgreSQL (Shared)                 │
    └──────────────────────────────────────────────────────┘

libs/service-common/
├── src/
│   ├── index.ts
│   ├── lib/
│   │   ├── events/
│   │   │   ├── event-bus.interface.ts       # IEventBus interface
│   │   │   ├── bullmq-event-bus.ts          # BullMQ implementation
│   │   │   ├── event-types.ts               # All cross-service event definitions
│   │   │   └── event-bus.module.ts
│   │   ├── internal-auth/
│   │   │   ├── internal-auth.guard.ts       # Validates INTERNAL_API_KEY
│   │   │   └── internal-auth.module.ts
│   │   ├── service-client/
│   │   │   ├── base-service-client.ts       # HTTP client base class
│   │   │   ├── order-service.client.ts      # Typed client for Order Service
│   │   │   ├── print-service.client.ts      # Typed client for Print Service
│   │   │   ├── shipping-service.client.ts   # Typed client for Shipping Service
│   │   │   ├── gridflock-service.client.ts  # Typed client for GridFlock Service
│   │   │   ├── slicer.client.ts             # HTTP client for Slicer Container
│   │   │   └── service-client.module.ts
│   │   ├── user-context/
│   │   │   ├── user-context.middleware.ts    # Extracts user from gateway headers
│   │   │   └── user-context.types.ts
│   │   └── health/
│   │       └── service-health.indicator.ts
│   └── __tests__/
├── project.json
└── jest.config.ts

libs/gridflock-core/
├── src/
│   ├── index.ts
│   ├── lib/
│   │   ├── generator.ts                   # Main plate generation
│   │   ├── types.ts                       # GridFlock parameter interfaces
│   │   ├── defaults.ts                    # Default values
│   │   ├── printer-profiles.ts            # Pre-configured printers
│   │   ├── plate-set-calculator.ts        # Multi-plate surface planning
│   │   ├── assembly-guide.ts              # Assembly instructions
│   │   ├── geometry/
│   │   │   ├── base-plate.ts
│   │   │   ├── grid-cells.ts
│   │   │   ├── magnet-holes.ts
│   │   │   ├── intersection-puzzle.ts     # GRIPS-like connectors
│   │   │   ├── edge-puzzle.ts             # Edge puzzle connectors
│   │   │   └── numbering.ts
│   │   └── serializer.ts
│   └── __tests__/
├── project.json
└── jest.config.ts

# Redis, BullMQ event bus, session store, Socket.IO adapter
pnpm add ioredis @nestjs/microservices connect-redis @socket.io/redis-adapter

# BullMQ for event queues + GridFlock pipeline jobs
pnpm add bullmq @nestjs/bullmq

# HTTP proxy for gateway (used in Part 2)
pnpm add http-proxy-middleware @nestjs/axios

# JSCAD for GridFlock
pnpm add @jscad/modeling @jscad/stl-serializer

redis:
  image: redis:7-alpine
  restart: unless-stopped
  ports:
    - '6379:6379'
  volumes:
    - redis-data:/data
  healthcheck:
    test: ['CMD', 'redis-cli', 'ping']
    interval: 10s
    timeout: 5s
    retries: 5
  networks:
    - forma3d-network

pnpm nx generate @nx/js:library service-common --directory=libs/service-common --bundler=tsc --unitTestRunner=jest

// libs/service-common/src/lib/events/event-bus.interface.ts
export interface IEventBus {
  publish(event: ServiceEvent): Promise<void>;
  subscribe(eventType: string, handler: EventHandler): Promise<void>;
  unsubscribe(eventType: string): Promise<void>;
}

// libs/service-common/src/lib/events/bullmq-event-bus.ts
import { Queue, Worker, Job } from 'bullmq';

@Injectable()
export class BullMQEventBus implements IEventBus {
  private queues = new Map<string, Queue>();
  private workers = new Map<string, Worker>();

  constructor(
    @Inject('REDIS_CONNECTION') private readonly connection: IORedis,
  ) {}

  /**
   * Publish an event by adding a job to the corresponding BullMQ queue.
   * The queue name IS the event type (e.g., 'order.created', 'print-job.completed').
   */
  async publish(event: ServiceEvent): Promise<void> {
    const queue = this.getOrCreateQueue(event.eventType);
    await queue.add(event.eventType, event, {
      removeOnComplete: 1000,
      removeOnFail: 5000,
      attempts: 3,
      backoff: { type: 'exponential', delay: 1000 },
    });
  }

  /**
   * Subscribe a handler to an event type. BullMQ ensures only ONE worker
   * instance across all replicas processes each job (event).
   */
  async subscribe(eventType: string, handler: EventHandler): Promise<void> {
    if (this.workers.has(eventType)) {
      throw new Error(`Already subscribed to ${eventType}`);
    }

    const worker = new Worker(
      eventType,
      async (job: Job<ServiceEvent>) => {
        await handler(job.data);
      },
      {
        connection: this.connection,
        concurrency: 5,
      },
    );

    this.workers.set(eventType, worker);
  }

  async unsubscribe(eventType: string): Promise<void> {
    const worker = this.workers.get(eventType);
    if (worker) {
      await worker.close();
      this.workers.delete(eventType);
    }
  }

  private getOrCreateQueue(eventType: string): Queue {
    if (!this.queues.has(eventType)) {
      this.queues.set(eventType, new Queue(eventType, {
        connection: this.connection,
      }));
    }
    return this.queues.get(eventType)!;
  }
}

// libs/service-common/src/lib/events/event-types.ts
export const SERVICE_EVENTS = {
  // Order Service publishes
  ORDER_CREATED: 'order.created',
  ORDER_READY_FOR_FULFILLMENT: 'order.ready-for-fulfillment',
  ORDER_CANCELLED: 'order.cancelled',

  // Print Service publishes
  PRINT_JOB_COMPLETED: 'print-job.completed',
  PRINT_JOB_FAILED: 'print-job.failed',
  PRINT_JOB_STATUS_CHANGED: 'print-job.status-changed',
  PRINT_JOB_CANCELLED: 'print-job.cancelled',

  // GridFlock Service publishes
  GRIDFLOCK_MAPPING_READY: 'gridflock.mapping-ready',
  GRIDFLOCK_PIPELINE_FAILED: 'gridflock.pipeline-failed',

  // Shipping Service publishes
  SHIPMENT_CREATED: 'shipment.created',
  SHIPMENT_STATUS_CHANGED: 'shipment.status-changed',
} as const;

// Base event interface — all events carry tenant context
export interface ServiceEvent {
  eventType: string;
  tenantId: string;
  timestamp: string;
  correlationId?: string;
}

// Concrete event interfaces
export interface OrderCreatedEvent extends ServiceEvent {
  eventType: typeof SERVICE_EVENTS.ORDER_CREATED;
  orderId: string;
  lineItems: Array<{
    lineItemId: string;
    productSku: string;
    quantity: number;
  }>;
}

export interface PrintJobCompletedEvent extends ServiceEvent {
  eventType: typeof SERVICE_EVENTS.PRINT_JOB_COMPLETED;
  printJobId: string;
  orderId: string;
  lineItemId: string;
}

export interface PrintJobFailedEvent extends ServiceEvent {
  eventType: typeof SERVICE_EVENTS.PRINT_JOB_FAILED;
  printJobId: string;
  orderId: string;
  lineItemId: string;
  errorMessage: string;
}

export interface ShipmentCreatedEvent extends ServiceEvent {
  eventType: typeof SERVICE_EVENTS.SHIPMENT_CREATED;
  shipmentId: string;
  orderId: string;
  trackingNumber: string | null;
  trackingUrl: string | null;
  carrier: string | null;
}

export interface GridflockMappingReadyEvent extends ServiceEvent {
  eventType: typeof SERVICE_EVENTS.GRIDFLOCK_MAPPING_READY;
  orderId: string;
  lineItemId: string;
  sku: string;
}

export interface GridflockPipelineFailedEvent extends ServiceEvent {
  eventType: typeof SERVICE_EVENTS.GRIDFLOCK_PIPELINE_FAILED;
  orderId: string;
  lineItemId: string;
  sku: string;
  errorMessage: string;
  failedStep: 'stl-generation' | 'slicing' | 'simplyprint-upload' | 'mapping-creation';
}

// libs/service-common/src/lib/internal-auth/internal-auth.guard.ts
@Injectable()
export class InternalAuthGuard implements CanActivate {
  constructor(private readonly configService: ConfigService) {}

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const apiKey = request.headers['x-internal-api-key'];
    const expectedKey = this.configService.get<string>('INTERNAL_API_KEY');

    if (!apiKey || apiKey !== expectedKey) {
      throw new ForbiddenException('Invalid internal API key');
    }

    return true;
  }
}

// libs/service-common/src/lib/service-client/base-service-client.ts
export abstract class BaseServiceClient {
  constructor(
    protected readonly httpService: HttpService,
    protected readonly baseUrl: string,
    protected readonly apiKey: string,
  ) {}

  protected async get<T>(path: string, headers?: Record<string, string>): Promise<T> {
    const response = await firstValueFrom(
      this.httpService.get<T>(`${this.baseUrl}${path}`, {
        headers: {
          'x-internal-api-key': this.apiKey,
          ...headers,
        },
      }),
    );
    return response.data;
  }

  protected async post<T>(path: string, data: unknown, headers?: Record<string, string>): Promise<T> {
    const response = await firstValueFrom(
      this.httpService.post<T>(`${this.baseUrl}${path}`, data, {
        headers: {
          'x-internal-api-key': this.apiKey,
          ...headers,
        },
      }),
    );
    return response.data;
  }
}

// libs/service-common/src/lib/service-client/print-service.client.ts
@Injectable()
export class PrintServiceClient extends BaseServiceClient {
  constructor(httpService: HttpService, configService: ConfigService) {
    super(
      httpService,
      configService.get<string>('PRINT_SERVICE_URL'),
      configService.get<string>('INTERNAL_API_KEY'),
    );
  }

  async createPrintJobs(tenantId: string, orderId: string, lineItems: LineItemDto[]): Promise<PrintJobDto[]> {
    return this.post('/internal/print-jobs', { tenantId, orderId, lineItems });
  }

  async getJobsByOrderId(tenantId: string, orderId: string): Promise<PrintJobDto[]> {
    return this.get(`/internal/print-jobs/order/${orderId}?tenantId=${tenantId}`);
  }

  async cancelJobsForOrder(tenantId: string, orderId: string): Promise<void> {
    await this.post(`/internal/print-jobs/order/${orderId}/cancel`, { tenantId });
  }

  /**
   * Upload a gcode file buffer to SimplyPrint via the Print Service.
   * The buffer is sent as base64 in the HTTP body — no file system involved.
   */
  async uploadFileToSimplyPrint(tenantId: string, file: { filename: string; buffer: Buffer }): Promise<{ simplyPrintFileId: string; filename: string }> {
    return this.post('/internal/simplyprint/upload', {
      tenantId,
      filename: file.filename,
      fileBase64: file.buffer.toString('base64'),
    });
  }
}

// libs/service-common/src/lib/service-client/gridflock-service.client.ts
@Injectable()
export class GridflockServiceClient extends BaseServiceClient {
  constructor(httpService: HttpService, configService: ConfigService) {
    super(
      httpService,
      configService.get<string>('GRIDFLOCK_SERVICE_URL'),
      configService.get<string>('INTERNAL_API_KEY'),
    );
  }

  async generateForOrder(request: GenerateForOrderDto): Promise<void> {
    await this.post('/internal/gridflock/generate-for-order', request);
  }

  async getMappingStatus(tenantId: string, sku: string): Promise<{ exists: boolean }> {
    return this.get(`/internal/gridflock/mapping-status/${encodeURIComponent(sku)}?tenantId=${tenantId}`);
  }
}

// libs/service-common/src/lib/service-client/slicer.client.ts
@Injectable()
export class SlicerClient {
  constructor(
    private readonly httpService: HttpService,
    private readonly configService: ConfigService,
  ) {}

  async slice(request: {
    stlBuffer: Buffer;
    stlFilename: string;
    machineProfile: string;
    processProfile: string;
    filamentProfile: string;
  }): Promise<{ gcodeBuffer: Buffer; filename: string }> {
    const slicerUrl = this.configService.get<string>('SLICER_URL');
    const formData = new FormData();
    formData.append('stl', new Blob([request.stlBuffer]), request.stlFilename);
    formData.append('machineProfile', request.machineProfile);
    formData.append('processProfile', request.processProfile);
    formData.append('filamentProfile', request.filamentProfile);

    const response = await firstValueFrom(
      this.httpService.post(`${slicerUrl}/slice`, formData, {
        responseType: 'arraybuffer',
        timeout: 120_000,
      }),
    );

    return {
      gcodeBuffer: Buffer.from(response.data),
      filename: request.stlFilename.replace('.stl', '.3mf'),
    };
  }

  async health(): Promise<{ status: string }> {
    const slicerUrl = this.configService.get<string>('SLICER_URL');
    const response = await firstValueFrom(this.httpService.get(`${slicerUrl}/health`));
    return response.data;
  }
}

// libs/service-common/src/lib/user-context/user-context.types.ts
export interface UserContext {
  userId: string;
  tenantId: string;
  email: string;
  roles: string[];
  permissions: string[];
  isSuperAdmin: boolean;
}

export const USER_CONTEXT_HEADERS = {
  USER_ID: 'x-user-id',
  TENANT_ID: 'x-tenant-id',
  USER_EMAIL: 'x-user-email',
  USER_ROLES: 'x-user-roles',
  USER_PERMISSIONS: 'x-user-permissions',
  IS_SUPER_ADMIN: 'x-is-super-admin',
} as const;

// libs/service-common/src/lib/user-context/user-context.middleware.ts
@Injectable()
export class UserContextMiddleware implements NestMiddleware {
  use(req: Request, _res: Response, next: NextFunction): void {
    const headers = req.headers;

    if (headers[USER_CONTEXT_HEADERS.USER_ID]) {
      req['user'] = {
        userId: headers[USER_CONTEXT_HEADERS.USER_ID] as string,
        tenantId: headers[USER_CONTEXT_HEADERS.TENANT_ID] as string,
        email: headers[USER_CONTEXT_HEADERS.USER_EMAIL] as string,
        roles: (headers[USER_CONTEXT_HEADERS.USER_ROLES] as string || '').split(','),
        permissions: (headers[USER_CONTEXT_HEADERS.USER_PERMISSIONS] as string || '').split(','),
        isSuperAdmin: headers[USER_CONTEXT_HEADERS.IS_SUPER_ADMIN] === 'true',
      } as UserContext;
    }

    next();
  }
}

pnpm nx generate @nx/js:library gridflock-core --directory=libs/gridflock-core --bundler=tsc --unitTestRunner=jest

Customer orders: 450×320mm grid
Printer bed:     256×256mm (Bambu Lab A1)
Grid unit:       42mm (Gridfinity standard)

Calculation:
  Max grid per plate: floor(256/42) = 6 units per axis
  Max plate size:     6×6 = 252×252mm

  Plates needed X:  ceil(450/252) = 2
  Plates needed Y:  ceil(320/252) = 2
  Total plates:     2×2 = 4

Result: 4 STL files → 4 gcode files → 4 SimplyPrint files → 1 product mapping (4 parts)

  JSCAD generates STL         Slicer converts to gcode      SimplyPrint stores files
  ┌──────────────────┐       ┌──────────────────────┐       ┌────────────────────┐
  │ generatePlate()  │       │ POST /slice           │       │ Upload gcode file  │
  │ → Buffer (STL)   │──HTTP→│ Body: STL Buffer      │──HTTP→│ Body: gcode Buffer │
  │                  │       │ Response: gcode Buffer│       │ → SimplyPrint ID   │
  └──────────────────┘       └──────────────────────┘       └────────────────────┘
       In-memory                    In-memory                   Permanent storage
       (GridFlock)                  (Slicer)                    (SimplyPrint cloud)