feat(workers): add Temporal worker structure and initial implementation

.cursor/rules/temporal-project-structure.mdc

@@ -0,0 +1,75 @@
+---
+description: 
+globs: ["workers/**/*", "docs/user-guide/temporal/**/*"]
+alwaysApply: false
+---
+# Temporal Project Structure Rule
+
+## Purpose
+Defines the required directory and documentation structure for Temporal-based workflows and workers in this repository.
+
+## Project Structure
+
+The project follows a modular structure with workers as independent packages:
+
+```
+.
+├── workers/                  # Root directory for all Temporal workers
+│   ├── main/                 # Main worker package
+│   │   ├── src/              # Source code
+│   │   │   ├── activities/   # Activity implementations
+│   │   │   ├── workflows/    # Workflow definitions
+│   │   │   ├── index.ts      # Worker entry point
+│   │   │   └── types.ts      # Worker-specific types
+│   │   ├── package.json      # Worker dependencies
+│   │   ├── tsconfig.json     # TypeScript configuration
+│   │   └── README.md         # Worker documentation
+│   └── [other-workers]/      # Additional worker packages
+├── workers-shared/           # Shared utilities, types, and configuration for all workers
+├── docs/                      # Project documentation
+│   └── user-guide/           # User guides and documentation
+├── docker-compose.yml        # Docker compose configuration
+└── Dockerfile.temporal       # Base Temporal worker Dockerfile
+```
+
+All Temporal workers must be placed under `workers/<worker-name>/` and include:
+
+- `workflows/` — workflow definitions for this worker
+- `activities/` — activity implementations for this worker
+- `index.ts` — worker entry point (registers workflows/activities, sets task queue)
+- `types.ts` — (optional) worker-specific types
+- `README.md` — brief usage and development instructions
+
+### Shared Utilities
+
+Shared utilities, types, and configuration that are used by multiple workers should be placed in the `workers-shared/` directory at the project root. This directory is intended for code that is not specific to a single worker but is reused across multiple workers to avoid duplication and promote consistency.
+
+- `workers-shared/` — shared modules, types, and configuration for all workers
+    - Utilities and helpers
+    - Common type definitions
+    - Shared configuration files
+
+## Documentation
+
+Each worker must have a dedicated documentation file at:
+`docs/user-guide/temporal/workers/<worker-name>.md`
+
+Documentation must include:
+
+- Purpose and responsibilities of the worker
+- List and description of workflows and activities
+- Required environment variables
+- Integration points (e.g., databases, APIs)
+- Best practices and troubleshooting
+
+## Best Practices
+
+- Keep workflow and activity logic modular and well-tested.
+- Use clear, descriptive names for workflows, activities, and task queues.
+- Update documentation with every significant change to workflows or activities.
+- New workers must not duplicate logic already present in shared modules.
+- Place all shared code in `workers-shared/` to maximize reuse and maintainability.
+
+## Enforcement
+
+- PRs introducing new Temporal workers or workflows **must** follow this structure and update documentation accordingly.

.dockerignore

@@ -139,4 +139,7 @@ volumes/
 *.vdi
 *.qcow2
 *.raw
-*.vhdx 
+*.vhdx
+
+# Workers
+workers/main/node_modules 

.github/workflows/code-quality.yml

@@ -25,6 +25,10 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
+      - name: Install dependencies
+        run: cd workers/main && npm ci
+      - name: Run tests with coverage
+        run: cd workers/main && npm run coverage
       - name: Run SonarQube scan
         uses: SonarSource/sonarqube-scan-action@v5
         env:

Dockerfile.temporal

@@ -1,31 +1,26 @@
-FROM temporalio/auto-setup:1.20.5
+FROM temporalio/auto-setup:1.27.2
 
-# Build arguments are still needed for the temporal container setup
-# Keeping only those used in the HEALTHCHECK or other commands
+# Set build arguments and environment variables
 ARG HOST=temporal
+ARG POSTGRES_SEEDS=postgresql
+ARG POSTGRES_USER=temporal
+ARG POSTGRES_DB_TEMPORAL_VISIBILITY=temporal_visibility
+ARG DB_PORT=5432
 ARG TEMPORAL_PORT=7233
 
-RUN temporal-sql-tool --plugin postgres \
-      --endpoint "$POSTGRES_SEEDS" \
-      --user "$POSTGRES_USER" \
-      --port "$DB_PORT" \
-      --database "$POSTGRES_DB_TEMPORAL_VISIBILITY" \
-      setup-schema -v 0.0 && \
-    temporal-sql-tool --plugin postgres \
-      --endpoint "$POSTGRES_SEEDS" \
-      --user "$POSTGRES_USER" \
-      --port "$DB_PORT" \
-      --database "$POSTGRES_DB_TEMPORAL_VISIBILITY" \
-      update-schema -d /etc/temporal/schema/postgresql/v96/visibility/versioned
+ENV POSTGRES_SEEDS=$POSTGRES_SEEDS \
+    POSTGRES_USER=$POSTGRES_USER \
+    POSTGRES_DB_TEMPORAL_VISIBILITY=$POSTGRES_DB_TEMPORAL_VISIBILITY \
+    DB_PORT=$DB_PORT \
+    TEMPORAL_PORT=$TEMPORAL_PORT
 
-# Add custom healthcheck using exec form
-HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
-  CMD ["/bin/sh", "-c", "temporal operator cluster health --address ${HOST}:${TEMPORAL_PORT} | grep -q SERVING || exit 1"]
-
-# Explicitly set the user to the non-root 'temporal' user (already defined in the base image)
+# Install netcat as root, then switch to non-root user
+USER root
+RUN apk add --no-cache netcat-openbsd=1.226.1.1-r0
 USER temporal
 
-# Expose the gRPC port
-EXPOSE ${TEMPORAL_PORT}
+HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=5 \
+  CMD sh -c "tctl --address temporal:7233 cluster health && nc -z temporal 7233"
 
-# The entrypoint script is already defined in the base image
+# Expose the gRPC port
+EXPOSE 7233

Dockerfile.temporal-worker-main

@@ -0,0 +1,31 @@
+# Install dependencies only
+FROM node:20-bullseye AS deps
+WORKDIR /app
+COPY workers/main/package*.json ./
+RUN npm ci --ignore-scripts
+
+# Development image
+FROM node:20-bullseye AS dev
+# sonarcloud-disable-next-line docker:S4507
+ENV NODE_ENV=development
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+CMD ["npx", "nodemon", "--watch", "./", "--ext", "ts", "--exec", "npx", "ts-node", "src/index.ts"]
+
+# Build the app
+FROM node:20-bullseye AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY workers/main/ ./
+RUN npm run build
+
+# Production image
+FROM gcr.io/distroless/nodejs20-debian11 AS production
+ARG NODE_ENV=production
+ENV NODE_ENV=${NODE_ENV}
+WORKDIR /app
+COPY --from=build /app/dist ./build
+COPY --from=build /app/node_modules ./node_modules
+
+USER node
+CMD ["node", "build/worker.js"]

docker-compose.prod.yml

@@ -102,6 +102,12 @@ services:
     networks:
       - app-network
 
+  temporal-worker-main:
+    build:
+      context: .
+      dockerfile: Dockerfile.temporal-worker-main
+      target: production
+
 volumes:
   n8n_data:
     driver: local

docker-compose.yml

@@ -74,21 +74,20 @@ services:
     build:
       context: .
       dockerfile: Dockerfile.temporal
-      args:
-        - HOST=temporal
-        - TEMPORAL_PORT=${TEMPORAL_PORT:-7233}
     restart: unless-stopped
     depends_on:
       postgresql:
         condition: service_healthy
     environment:
+      TEMPORAL_FRONTEND_GRPC_BIND_ON_IP: 0.0.0.0
       TEMPORAL_PORT: ${TEMPORAL_PORT:-7233}
       POSTGRES_SEEDS: postgresql
       DB_PORT: ${POSTGRES_PORT:-5432}
       DBNAME: ${POSTGRES_DB_TEMPORAL:-temporal}
       POSTGRES_USER: ${POSTGRES_USER_TEMPORAL:-temporal}
       POSTGRES_PWD: ${POSTGRES_PASSWORD_TEMPORAL:-temporal}
-      DB: postgresql
+      DB: postgres12
+      VISIBILITY_DB_NAME: ${POSTGRES_DB_TEMPORAL_VISIBILITY:-temporal_visibility}
       VISIBILITY_DB_USER: ${POSTGRES_USER_TEMPORAL:-temporal}
       VISIBILITY_DB_PWD: ${POSTGRES_PASSWORD_TEMPORAL:-temporal}
       VISIBILITY_DB_PORT: ${POSTGRES_PORT:-5432}
@@ -102,7 +101,7 @@ services:
         - path: .
           action: rebuild
     healthcheck:
-      test: ["CMD", "tctl", "--address", "temporal:${TEMPORAL_PORT:-7233}", "cluster", "health"]
+      test: ["CMD", "sh", "-c", "tctl --address temporal:7233 cluster health && nc -z temporal 7233"]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -147,11 +146,32 @@ services:
       timeout: 5s
       retries: 5
 
+  temporal-worker-main:
+    container_name: temporal-worker-main
+    build:
+      context: .
+      dockerfile: Dockerfile.temporal-worker-main
+      target: dev
+    depends_on:
+      temporal:
+        condition: service_healthy
+    environment:
+      - TEMPORAL_ADDRESS=temporal:7233
+      - TEMPORAL_TASK_QUEUE=default
+    volumes:
+      - ./workers/main:/app
+      - /app/node_modules
+    networks:
+      - app-network
+    develop:
+      watch:
+        - path: .
+          action: rebuild
+
 volumes:
   n8n_data:
   postgresql-data:
   redis-data:
 
 networks:
   app-network:
-    driver: bridge

docs/user-guide/temporal/overview.md

@@ -3,6 +3,7 @@
 ## Table of Contents
 - Introduction
 - Core Platform Components
+- Shared Utilities and Configuration
 - Key Features of Temporal
 - Temporal UI Interface
 
@@ -14,6 +15,9 @@ Temporal is a platform for reliable and scalable execution of business processes
 - **Worker Processes** — processes that execute user workflow and activity code. Operate using SDKs in various languages (Go, Java, TypeScript, Python, etc.).
 - **Temporal UI** — web interface for monitoring and managing workflows.
 
+## Shared Utilities and Configuration
+- **workers-shared/** — This directory contains shared utilities, type definitions, and configuration used by multiple Temporal workers. It is intended for code that is not specific to a single worker but is reused across the project to avoid duplication and promote consistency. Examples include common helper functions, shared type definitions, and configuration files that are imported by different worker packages.
+
 ## Key Features of Temporal
 - **Durable Execution**: process execution with state persistence and automatic recovery after failures.
 - **Scalability**: supports millions of parallel workflows.

sonar-project.properties

@@ -1,2 +1,4 @@
 sonar.projectKey=speedandfunction_automatization
 sonar.organization=speedandfunction
+sonar.javascript.lcov.reportPaths=workers/main/coverage/lcov.info
+sonar.exclusions=**/src/__tests__/**,**/src/dist/**,**/src/types.ts,**/src/activities/index.ts,**/src/workflows/index.ts,**/src/index.ts