Core ERN Monorepo - TailStack

Overview

The Core Monorepo is TailStack’s flagship template, providing a complete ERN Stack (Express, React, Node.js) in a unified, production-ready architecture. It’s designed for full-stack applications where frontend and backend are tightly integrated and deployed together.

This template is located at packages/core/ in the TailStack repository.

Architecture Components

Frontend

Vite + React + TailwindModern client application with:

React 19 with latest features
Vite 6 for lightning-fast HMR
Tailwind CSS 4 (new engine)
Shadcn UI component library
React Router 7 for routing

Backend

Express + TypeScript + ClusteringScalable server foundation:

Express 5 web framework
Full TypeScript type safety
Multi-core Node clustering
CORS and security configured
RESTful API architecture

Automation

Cross-Platform ScriptsDevelopment utilities:

Smart clean (parallel purge)
Smart install (load-aware)
Both PowerShell and Bash
Located in scripts/ directory

AI Skills

Agent-Powered DevelopmentThree pre-configured skills:

Vercel React Best Practices
Node.js Backend Patterns
Tailwind v4 + shadcn/ui

Directory Structure

Here’s the complete structure of the Core monorepo:

core/
├── .agent/                          # Gemini agent skills
│   └── skills/
│       ├── nodejs-backend-patterns/
│       ├── tailwind-v4-shadcn/
│       └── vercel-react-best-practices/
├── .claude/                         # Claude agent skills
│   └── skills/                      # (same structure as .agent/)
├── .cursor/                         # Cursor agent skills
│   └── skills/                      # (same structure as .agent/)
├── .opencode/                       # OpenCode agent skills
│   └── skills/                      # (same structure as .agent/)
├── .agents/                         # Trae agent skills
│   └── skills/                      # (same structure as .agent/)
├── .husky/                          # Git hooks configuration
├── .vscode/                         # VS Code workspace settings
├── assets/                          # Static assets (logo, images)
├── Docs/                            # Project documentation
│   ├── CODE_OF_CONDUCT.md
│   ├── CONTRIBUTING.md
│   └── SECURITY.md
├── scripts/                         # Automation utilities
│   ├── clean.ps1                    # PowerShell: Fast cleanup
│   ├── clean.sh                     # Bash: Fast cleanup
│   ├── install.ps1                  # PowerShell: Smart installer
│   └── install.sh                   # Bash: Smart installer
├── source/                          # Main application code
│   ├── frontend/                    # React client application
│   │   ├── src/
│   │   │   ├── api/                 # API client functions
│   │   │   ├── components/          # React components
│   │   │   │   ├── layout/          # Layout components
│   │   │   │   ├── ui/              # Shadcn UI components
│   │   │   │   └── theme-toggle.tsx
│   │   │   ├── config/              # App configuration
│   │   │   ├── constants/           # Constants and variants
│   │   │   ├── hooks/               # Custom React hooks
│   │   │   ├── lib/                 # Utility functions
│   │   │   ├── pages/               # Application pages
│   │   │   │   ├── docs/            # Documentation pages
│   │   │   │   ├── home.tsx         # Home page
│   │   │   │   ├── weather.tsx      # Weather demo
│   │   │   │   └── not-found.tsx    # 404 page
│   │   │   ├── types/               # TypeScript types
│   │   │   ├── App.tsx              # Root component
│   │   │   └── main.tsx             # Entry point
│   │   ├── index.html
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── vite.config.ts
│   └── Server/                      # Express backend application
│       ├── src/
│       │   ├── cluster/             # Clustering logic
│       │   │   └── index.ts         # Cluster initialization
│       │   ├── config/              # Server configuration
│       │   │   └── index.ts         # Environment config
│       │   ├── constant/            # Server constants
│       │   │   └── cluster.ts       # Cluster settings
│       │   ├── controller/          # Request controllers
│       │   ├── middlewares/         # Express middlewares
│       │   ├── routes/              # API route definitions
│       │   ├── services/            # Business logic services
│       │   ├── types/               # TypeScript types
│       │   ├── app.ts               # Express app setup
│       │   └── server.ts            # Server entry point
│       ├── .env.example
│       ├── package.json
│       └── tsconfig.json
├── .editorconfig
├── .gitignore
├── .npmrc
├── .nvmrc
├── .node-version
├── commitlint.config.cjs
├── package.json                     # Root package (workspace config)
└── README.md

Frontend Architecture

Technology Stack

The frontend is built with modern React best practices:

Core Libraries
Components
Weather Demo

package.json (frontend)

{
  "dependencies": {
    "react": "^19.2.0",
    "react-dom": "^19.2.0",
    "react-router-dom": "^7.12.0",
    "@tailwindcss/vite": "^4.1.18",
    "tailwindcss": "^4.1.18",
    "axios": "^1.7.9",
    "lucide-react": "^0.562.0",
    "sonner": "^2.0.7",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.4.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^5.1.1",
    "typescript": "~5.9.3",
    "vite": "^7.2.4"
  }
}

Shadcn UI Components

Pre-configured components in source/frontend/src/components/ui/:

button.tsx - Button with variants
card.tsx - Card container with header/footer
badge.tsx - Status badges
input.tsx - Form input fields
select.tsx - Select dropdowns
separator.tsx - Visual dividers
scroll-area.tsx - Scrollable containers
sheet.tsx - Slide-out panels
code-block.tsx - Syntax-highlighted code

All components use the CVA (Class Variance Authority) pattern:

import { cn } from "@/lib/utils"
import { buttonVariants } from "@/constants/ui-variants"

const Button = ({ variant, size, ...props }) => (
  <button
    className={cn(buttonVariants({ variant, size }))}
    {...props}
  />
)

Full-Stack Weather Application

The Core template includes a complete weather app demo at source/frontend/src/pages/weather.tsx.Features:

Real-time weather data fetching
Location-based search
Responsive design
Error handling
Loading states
API integration with backend

Architecture:

Frontend (weather.tsx)
  ↓ axios request
Backend (routes/weather.ts)
  ↓ external API call
Weather Service API
  ↓ response
Frontend (display)

Backend Architecture

Node Clustering

The backend uses Node.js clustering to maximize performance across CPU cores:

source/Server/src/cluster/index.ts

import cluster from 'node:cluster';
import { availableParallelism } from 'node:os';

export const initializeCluster = (workerCallback: () => void) => {
  if (cluster.isPrimary) {
    const numCPUs = config.workers || availableParallelism();
    
    console.log(`🚀 Primary process ${process.pid} is running`);
    console.log(`⚙️ Spawning ${numCPUs} workers...`);

    // Fork workers
    for (let i = 0; i < numCPUs; i++) {
      cluster.fork();
    }

    // Auto-restart failed workers
    cluster.on('exit', (worker, code, signal) => {
      console.log(`⚠️ Worker ${worker.process.pid} died`);
      setTimeout(() => cluster.fork(), CLUSTER_CONFIG.RESTART_DELAY);
    });
  } else {
    workerCallback();
  }
};

Performance Impact: Clustering allows the server to handle concurrent requests across all CPU cores, dramatically improving throughput for compute-intensive operations.

Server Entry Point

The server initialization in source/Server/src/server.ts:

import app from './app';
import { config } from './config';
import { initializeCluster } from './cluster';

initializeCluster(() => {
  const server = app.listen(config.port, () => {
    console.log(`✅ Worker ${process.pid} started on port ${config.port}`);
  });

  // Graceful shutdown handling
  const gracefulShutdown = (signal: string) => {
    console.log(`${signal} signal received: closing HTTP server`);
    server.close(() => {
      console.log(`HTTP server closed`);
      process.exit(0);
    });
  };

  process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
  process.on('SIGINT', () => gracefulShutdown('SIGINT'));
});

Dependencies

package.json (Server)

{
  "dependencies": {
    "express": "^5.2.1",
    "axios": "^1.7.9",
    "cors": "^2.8.6",
    "cookie-parser": "^1.4.7",
    "dotenv": "^17.2.3"
  },
  "devDependencies": {
    "@types/express": "^5.0.6",
    "@types/node": "^25.0.10",
    "tsx": "^4.21.0",
    "typescript": "^5.9.3"
  }
}

Development Workflow

Concurrent Development

The root package.json includes a unified dev script:

{
  "scripts": {
    "dev": "concurrently \"pnpm --filter ./source/frontend dev\" \"pnpm --filter ./source/Server dev\""
  }
}

Running pnpm dev from the root starts both frontend and backend simultaneously:

Frontend: http://localhost:5173 (Vite dev server)
Backend: http://localhost:5000 (Express API)

Hot Module Replacement

Frontend
Backend

Vite provides instant HMR for React components:

Sub-100ms updates
Preserves component state
No full page reload needed
Works with Tailwind CSS changes

TSX watch mode automatically restarts the server:

tsx watch src/server.ts

Detects TypeScript file changes
Recompiles and restarts workers
Maintains all cluster workers

Agent Skills Integration

The Core template includes three agent skills across multiple AI platforms:

Vercel React

Location: .agent/skills/vercel-react-best-practices/

57 performance rules
8 optimization categories
React 19 best practices
Next.js patterns

Node.js Patterns

Location: .agent/skills/nodejs-backend-patterns/

Scalable architectures
Security best practices
Error handling patterns
Production deployment

Tailwind + shadcn

Location: .agent/skills/tailwind-v4-shadcn/

Tailwind v4 syntax
shadcn/ui components
Dark mode setup
Migration guides

Supported AI Agents

Skills are duplicated across agent directories for compatibility:

.agent/ - Gemini and generic agents
.claude/ - Claude Desktop and API
.cursor/ - Cursor IDE
.opencode/ - OpenCode CLI
.agents/ - Trae and custom agents

Automation Scripts

Located in scripts/ directory:

Smart Clean
Smart Install

Lightning-Fast Cleanup

Files: clean.ps1 (PowerShell) / clean.sh (Bash)Features:

Parallel deletion across all node_modules
Kills locking processes (Node.js, VS Code)
Removes pnpm-lock.yaml files
3-retry verification loop
Cross-platform compatibility

Usage:

# Bash (Linux/macOS)
./scripts/clean.sh

# PowerShell (Windows)
.\scripts\clean.ps1

Intelligent Installer

Files: install.ps1 (PowerShell) / install.sh (Bash)Features:

Parallel pnpm install for all packages
CPU/RAM load monitoring
Auto-suspend at 90% system load
Auto-resume when load drops below 75%
Prevents system crashes on low-end hardware

State Machine:

RUNNING → (load > 90%) → SUSPENDED
SUSPENDED → (load < 75%) → RUNNING

Usage:

# Bash (Linux/macOS)
./scripts/install.sh

# PowerShell (Windows)
.\scripts\install.ps1

Security Features

Gitleaks

Automatic secret detection on every commit via Husky hooks

Scans staged files for secrets
Blocks commits with leaked credentials
Configured via .gitleaks.toml

Commitlint

Enforces Conventional Commits format

feat:, fix:, docs:, etc.
Automated changelog generation
Semantic versioning support

CORS

Backend CORS configured for frontend origin

Environment-based origins
Credential support
Pre-flight handling

Environment Variables

Secure configuration via .env files

.env.example templates
Never committed to Git
Dotenv for loading

Production Deployment

Build Process

Frontend
Backend

cd source/frontend
pnpm build

Outputs to source/frontend/dist/:

Optimized bundle with tree-shaking
Minified JavaScript and CSS
Hashed filenames for caching
Ready for static hosting (Vercel, Netlify, S3)

cd source/Server
pnpm build

Outputs to source/Server/dist/:

Compiled TypeScript to JavaScript
Preserves directory structure
Ready for Node.js deployment

Run production:

pnpm start  # node dist/server.js

Deployment Strategies

Monolithic

Deploy frontend and backend together

Single Docker container
Express serves React build
Simplified deployment
Single domain/certificate

Separated

Deploy frontend and backend independently

Frontend: Vercel/Netlify
Backend: Heroku/Railway/AWS
CDN for static assets
Better scalability

Next Steps

Project Structure

Explore detailed directory organization

Getting Started

Set up your first TailStack project

React Template

Compare with frontend-only architecture

Node Template

Compare with backend-only architecture

Getting Started

Architecture

Core Concepts

Development

Guides

​Overview

​Architecture Components

Frontend

Backend

Automation

AI Skills

​Directory Structure

​Frontend Architecture

​Technology Stack

​Shadcn UI Components

​Full-Stack Weather Application

​Backend Architecture

​Node Clustering

​Server Entry Point

​Dependencies

​Development Workflow

​Concurrent Development

​Hot Module Replacement

​Agent Skills Integration

Vercel React

Node.js Patterns

Tailwind + shadcn

​Supported AI Agents

​Automation Scripts

​Lightning-Fast Cleanup

​Intelligent Installer

​Security Features

Gitleaks

Commitlint

CORS

Environment Variables

​Production Deployment

​Build Process

​Deployment Strategies

Monolithic

Separated

​Next Steps

Project Structure

Getting Started

React Template

Node Template

Build docs developers (and LLMs) love

Overview

Architecture Components

Directory Structure

Frontend Architecture

Technology Stack

Shadcn UI Components

Full-Stack Weather Application

Backend Architecture

Node Clustering

Server Entry Point

Dependencies

Development Workflow

Concurrent Development

Hot Module Replacement

Agent Skills Integration

Supported AI Agents

Automation Scripts

Lightning-Fast Cleanup

Intelligent Installer

Security Features

Production Deployment

Build Process

Deployment Strategies

Next Steps