ProjectX

ProjectX is a comprehensive full-stack template designed to simplify the development of scalable and resilient applications using React and Temporal. By integrating Temporal's advanced workflow orchestration with React's dynamic frontend framework, ProjectX enables developers to build applications with durable executions and seamless communication between services.

Features 🧰

- ⏳ Temporal TypeScript SDK running from a Turborepo monorepo
- 🧭 React Router v7 (Framework mode) + React Query
- 🎨 TailwindCSS v4
- 🧱 NestJS for APIs & microservices
- 🐳 Docker setup to run everything locally on any machine
- 🤖 AI-first with Cursor Rules + MCP servers & Claude Subagents + Skills
- 📚 Storybook for building UI components
- 📧 MJML for lightning-fast email templates
- 🛒 Stripe for checkout & payments
- 🪝 Ngrok for local integrations and webhooks

Why Temporal? 🤔

████████╗███████╗███╗   ███╗██████╗  ██████╗ ██████╗  █████╗ ██╗     
╚══██╔══╝██╔════╝████╗ ████║██╔══██╗██╔═══██╗██╔══██╗██╔══██╗██║     
   ██║   █████╗  ██╔████╔██║██████╔╝██║   ██║██████╔╝███████║██║     
   ██║   ██╔══╝  ██║╚██╔╝██║██╔═══╝ ██║   ██║██╔══██╗██╔══██║██║     
   ██║   ███████╗██║ ╚═╝ ██║██║     ╚██████╔╝██║  ██║██║  ██║███████╗
   ╚═╝   ╚══════╝╚═╝     ╚═╝╚═╝      ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝

Challenges of Maintaining State in Distributed Systems

• Consistency
• Fault Tolerance
• Scalability
• Concurrency Control
• Security

Temporal is introduced here as a Workflow Orchestration tool for managing long-running operations (durable execution), human-in-the-loop and system lifecycle (state management, guaranteed completion with compensations and uniqueness). You can use Temporal today to implement sequences of steps/actions in a specific order for your business processes (workflows), not only for communication between services (Microservices Orchestration) but also within Monolithic apps. Workflows can react to asynchronous and external events (signals, updates), aggregate data and perform actions (activities) with exponential retries (retry policy) and run for extended periods (heartbeat) if needed, then you can check the state of these executions at any time (queries). Additionally, workflows support scheduled and time-based executions with configurable delays to handle recurring business logic (scheduling).

Use Cases

• Order Processing Systems: Managing the lifecycle of orders from placement to fulfillment, including inventory checks, payment processing, and shipping.

• User Onboarding: Coordinating steps involved in onboarding new users, such as account creation, email verification, and initial setup tasks.

• Data Pipelines: Orchestrating data ingestion, transformation, and storage processes with reliability and scalability.

• Batch Processing: Handling large-scale batch jobs with retry mechanisms and progress monitoring.

Getting Started 🚀

Prerequisites 🧰

• Docker Compose
• Node.js LTS Version
• Git

Quick Setup 🛠️

1. Clone and Setup Environment:

git clone https://github.com/proyecto26/projectx.git
cd projectx
cp .env.example .env

2. Start Development Environment:

# Build and start all services (db, temporal, backend services)
docker-compose up -d

# Install dependencies and start web application
pnpm install
pnpm run dev:web

Documentation 📚

For detailed information about the project, please refer to:

• Architecture Overview
• Frontend Guide
• Backend Guide

Project Structure Overview

Markmap format 🍬

#### Root Directory

- **package.json**: Contains the dependencies and scripts for the entire monorepo.
- **turbo.json**: Configuration for Turborepo, which manages the monorepo structure and build processes.
- **tsconfig.json**: Base TypeScript configuration shared across the project.

#### Apps

- **apps/auth**: 
  - **Purpose**: Handles user authentication and data retrieval.
  - **Key Features**: Login, registration, and user profile management.

- **apps/order**: 
  - **Purpose**: Manages order processing, checkout, and payment handling.
  - **Key Features**: Cart management, order tracking, and payment integration.

- **apps/product**: 
  - **Purpose**: Manages product catalog and inventory.
  - **Key Features**: Product listing, details, and inventory management.

- **apps/web**: 
  - **Purpose**: The main web application interface.
  - **Key Features**: User interaction with the system.
  - **Configuration**: 
    - **tsconfig.json**: TypeScript configuration specific to the web app.

#### Packages

- **packages/core**: 
  - **Purpose**: Contains business logic and common utilities.
  - **Key Features**: Shared functions and services used across backend applications.

- **packages/db**: 
  - **Purpose**: Manages database access using Prisma and the Repository pattern.
  - **Key Features**: Database schema definitions and data access layers.
  - **Documentation**: 
    - **README.md**: Provides details on database setup and usage.

- **packages/email**: 
  - **Purpose**: Handles email template creation and sending.
  - **Key Features**: Uses MJML for templates and provides email sending services.

- **packages/models**: 
  - **Purpose**: Defines DTOs and common types.
  - **Key Features**: Ensures consistency across web and backend services.

- **packages/ui**: 
  - **Purpose**: Contains UI components and themes.
  - **Key Features**: Built with React and TailwindCSS, includes Storybook for component visualization.
  - **Configuration**: 
    - **package.json**: Dependencies and scripts for the UI library.
    - **tsconfig.json**: TypeScript configuration for the UI library.

- **packages/workflows**: 
  - **Purpose**: Temporal workflow orchestration utilities.
  - **Key Features**: Shared workflow client and worker services.

- **packages/payment**: 
  - **Purpose**: Payment provider integrations.
  - **Key Features**: Stripe and other payment gateway implementations.

Code Generators 🏗️

ProjectX includes powerful Turborepo generators to scaffold new services quickly and consistently.

Available Generators

Command	Description
pnpm gen:service	Create a basic NestJS microservice (like product)
pnpm gen:temporal-service	Create a NestJS service with Temporal workflows (like auth, order)
pnpm gen:workflow	Add a new workflow to an existing Temporal-enabled service

Creating a New Service

Basic Service (without Temporal)

pnpm gen:service

This will prompt you for:

• Service name (e.g., inventory, notification)
• Port number (auto-suggests next available)
• Description
• Optional modules (Email, Payment)

Temporal-Enabled Service

pnpm gen:temporal-service

Additional prompts:

• Initial workflow name (e.g., process, handle)

Adding a Workflow to Existing Service

pnpm gen:workflow

Select the target service and provide workflow details.

What Gets Generated

Basic Service:

apps/{serviceName}/
├── src/
│   ├── app/
│   │   ├── app.module.ts
│   │   ├── app.controller.ts
│   │   └── app.service.ts
│   ├── config/
│   │   ├── app.config.ts
│   │   ├── env.config.ts
│   │   └── swagger.config.ts
│   └── main.ts
├── test/
├── package.json
└── tsconfig.json

Temporal Service (additional):

├── src/
│   ├── app/activities/
│   │   ├── activities.module.ts
│   │   └── activities.service.ts
│   ├── config/
│   │   └── temporal.config.ts
│   └── workflows/
│       ├── index.ts
│       └── {workflowName}.workflow.ts

Auto-Configuration

The generators automatically:

• Add dev:{serviceName} and build:{serviceName} scripts to root package.json
• Update docker-compose.yml with the new service configuration
• Configure the builder to include the new service in the build pipeline

Post-Generation Steps

1. Add the environment variable to .env:

   {SERVICE_NAME}_PORT={port}

2. Install dependencies:

   pnpm install

3. Start the service:

   pnpm dev:{serviceName}

ProjectX CLI 🖥️

ProjectX includes an interactive CLI tool for a more developer-friendly experience when generating services and customizing the template.

Running the CLI

# Interactive mode (recommended)
pnpm cli

# Or run specific commands
pnpm cli generate service
pnpm cli generate temporal-service
pnpm cli generate workflow
pnpm cli init
pnpm cli info

CLI Commands

Command	Description
pnpm cli	Interactive mode - select what to do
pnpm cli generate [type]	Generate service or workflow
pnpm cli init	Initialize/customize project for your needs
pnpm cli info	Display project information

Initialize Command

The init command helps you customize the template for your own project:

pnpm cli init

This allows you to:

• Rename the project: Updates all package names and references from @projectx/* to @your-project/*
• Clean up example services: Remove auth, order, product services to start fresh
• Update Docker configuration: Adjust docker-compose.yml for your project name

Example Workflow

# 1. Clone the template
git clone https://github.com/proyecto26/projectx.git my-app
cd my-app

# 2. Customize for your project
pnpm install
pnpm cli init
# - Enter your project name
# - Select customizations (rename, cleanup, etc.)

# 3. Generate your first service
pnpm cli generate temporal-service
# - Enter service name: "orders"
# - Select port: 8084
# - Add Email module: Yes
# - Initial workflow: "processOrder"

# 4. Start development
docker-compose up -d
pnpm dev

Development Tools 🔧

Monorepo Management

# View project structure
pnpm list --recursive --only-projects

# View dependency graph
turbo run build --dry-run --graph

# Run specific task across all packages
turbo run build
turbo run test
turbo run lint

# Run task for specific package
turbo run build --filter=@projectx/core
turbo run dev --filter=web

# Clear Turborepo cache
turbo run build --force

UI Development

# Run Storybook
pnpm run storybook

Package Management

# Add dependency to specific package
pnpm add <package> --filter=@projectx/core

# Add dev dependency to root
pnpm add -D <package> -w

# Update all dependencies
pnpm update --recursive

Docker Configuration 🐳

Services defined in docker-compose.yml:

• PostgreSQL with PostGIS
• Temporal server and UI
• Auth, Order, and Product services

Common Commands

# Build fresh images
docker-compose build --no-cache

# Start services
docker-compose up -d

# Remove services and volumes
docker-compose down --volumes

Notable Links 🤓

• Get started with Temporal and TypeScript
• Workflow Messages - TypeScript SDK

Public Courses

• Temporal 101 with TypeScript
• Temporal 102: Exploring Durable Execution with TypeScript
• Versioning Workflows with TypeScript
• Interacting with Workflows with TypeScript
• Securing Temporal Applications with TypeScript
• Introduction to Temporal Cloud
• Crafting an Error Handling Strategy with TypeScript

Payment Providers

• Stripe:
  • Test Webhooks
  • Stripe Webhook integration
  • Stripe Checkout
  • Webhooks Dashboard
  • Automatic fulfillment Orders
  • Interactive webhook endpoint builder
  • Trigger webhook events with the Stripe CLI
  • Testing cards
• Stripe commands for testing webhooks:

brew install stripe/stripe-cli/stripe
stripe login --api-key ...
stripe trigger payment_intent.succeeded
stripe listen --forward-to localhost:8081/order/webhook // or using the secure tunnel created by Ngrok

Supporting 🍻

I believe in Unicorns 🦄 Support me, if you do too.

Donate Ethereum, ADA, BNB, SHIBA, USDT/USDC, DOGE, etc:

Wallet address: jdnichollsc.eth

Please let us know your contributions! 🙏

Happy coding 💯

Made with ❤️

╔╦╗╔═╗╔╦╗╔═╗╔═╗╦═╗╔═╗╦   
 ║ ║╣ ║║║╠═╝║ ║╠╦╝╠═╣║  
 ╩ ╚═╝╩ ╩╩  ╚═╝╩╚═╩ ╩╩═╝⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀