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

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

@@ -0,0 +1,66 @@
+---
+description: 
+globs: 
+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
+├── 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 `src/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, types, and configuration should be placed in `src/shared/`.
+
+## 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.
+
+## Enforcement
+
+- PRs introducing new Temporal workers or workflows **must** follow this structure and update documentation accordingly.

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
 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,26 @@
+FROM node:20-bullseye AS deps
+WORKDIR /app
+COPY workers/main/package*.json ./
+RUN npm ci
+
+FROM node:20-bullseye AS dev
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+ENV NODE_ENV=development
+CMD ["npx", "nodemon", "--watch", "./", "--ext", "ts", "--exec", "npx", "ts-node", "src/index.ts"]
+
+FROM node:20-bullseye AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY workers/main/ ./
+RUN npm run build
+
+FROM gcr.io/distroless/nodejs20-debian11 AS prod
+WORKDIR /app
+COPY --from=build /app/build ./build
+COPY --from=build /app/node_modules ./node_modules
+
+ARG NODE_ENV=production
+ENV NODE_ENV=${NODE_ENV}
+
+CMD ["node", "build/worker.js"]

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,33 @@ 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
+      - NODE_ENV=production
+    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