LFX PCC

This is a monorepo for the LFX PCC (Projects Self-Service) application, built with Angular 19 and experimental zoneless change detection.

What's inside?

Apps and Packages

• apps/lfx-pcc: Angular 19 SSR application with zoneless change detection and direct PrimeNG UI components

The app is 100% TypeScript.

Architecture

• Frontend: Angular 19 with experimental zoneless change detection, Angular Signals, PrimeNG components, Tailwind CSS
• UI Framework: PrimeNG 19 with custom LFX UI Core preset and Tailwind CSS integration
• Styling: Tailwind CSS v3 with PrimeUI plugin, CSS layers architecture, Google Fonts (Open Sans + Roboto Slab)
• Icons: Font Awesome Pro via kits (no npm packages)
• Backend: Express.js server with Angular 19 SSR, Auth0 authentication, Pino logging
• Infrastructure: PM2 process management for production deployment

Development Tools

This has comprehensive development tooling:

• TypeScript for static type checking with strict configuration
• ESLint for code linting with Angular 19 specific rules
• Prettier for code formatting with Tailwind class sorting
• Turborepo for efficient monorepo builds and caching
• PM2 for production process management

Contributing

Please read our Contributing Guide for details on our code of conduct, development process, and how to submit pull requests.

Development

Getting Started

Prerequisites

• Node.js v22+ (specified in package.json)
• Yarn v4.9.2+ package manager
• Auth0 Account for authentication setup
• Supabase Project (Temporary Mock) for database operations

Environment Setup

1. Copy the environment template:

   cp apps/lfx-pcc/.env.example apps/lfx-pcc/.env

2. Configure required environment variables:

   Auth0 Configuration:

   • Get the Auth0 Application values from 1Password
   • Set PCC_AUTH0_CLIENT_ID and PCC_AUTH0_CLIENT_SECRET
   • Update PCC_AUTH0_ISSUER_BASE_URL with your Auth0 domain
   • Configure PCC_AUTH0_AUDIENCE for your API

   Supabase Configuration:

   • Create a project in Supabase
   • Get your project URL and anon key from Project Settings → API
   • Set SUPABASE_URL and POSTGRES_API_KEY

   Microservice Configuration:

   • Set QUERY_SERVICE_URL to your query service endpoint
   • Provide a valid JWT token in QUERY_SERVICE_TOKEN

Install and Run

# Install dependencies
yarn install

# Start development server (Angular dev server)
yarn start

# Build the application
yarn build

# Run tests
yarn test

Code Quality Commands

# Linting
yarn lint           # Lint and auto-fix all packages
yarn lint:check     # Check linting without fixing

# Formatting
yarn format         # Format code with Prettier
yarn format:check   # Check formatting without fixing

# Testing
yarn test           # Run unit tests
yarn test:watch     # Run tests in watch mode

Common Commands

# Development
yarn start          # Start Angular dev server (ng serve)
yarn build          # Build the application
yarn watch          # Build in watch mode

# Production
yarn serve:ssr      # Serve SSR application locally
yarn start:prod     # Start with PM2 in production
yarn reload:prod    # Zero-downtime reload
yarn logs:prod      # View PM2 logs

Working with the application

You can run commands for the application using Turborepo filters:

# Start the Angular app
yarn start --filter=lfx-pcc

# Build the Angular app
yarn build --filter=lfx-pcc

# Run tests for the app
yarn test --filter=lfx-pcc

# Lint the app
yarn lint --filter=lfx-pcc

Project Structure

lfx-pcc-v3/
├── apps/
│   └── lfx-pcc/              # Angular 19 SSR application
│       ├── src/app/config/   # Tailwind custom configurations
│       │   └── styles/       # Colors and font-size configurations
│       ├── eslint.config.mjs # Angular-specific ESLint rules
│       ├── .prettierrc       # Prettier with Tailwind integration
│       └── tailwind.config.js # Tailwind with PrimeUI plugin
├── docs/                     # Architecture and deployment documentation
├── turbo.json               # Turborepo pipeline configuration
├── ecosystem.config.js      # PM2 production configuration
└── package.json             # Root workspace configuration

Key Features

Angular 19 with Zoneless Change Detection

• Experimental zoneless change detection for improved performance
• Angular Signals for reactive state management (preferred over RxJS)
• Standalone components with explicit imports
• Component prefix: All components use lfx- prefix (enforced by ESLint)

CSS Architecture

• CSS Layers: Organized layer system (tailwind-base, primeng, tailwind-utilities)
• PrimeNG Integration: Custom preset using LFX UI Core design system
• Tailwind CSS: Utility-first styling with PrimeUI plugin integration
• Custom Fonts: Google Fonts (Open Sans + Roboto Slab) with CSS variables

Direct PrimeNG Usage

• PrimeNG Components: Direct integration of PrimeNG components with LFX theming
• Custom Styling: PrimeNG components styled with LFX UI Core design system
• Template Support: Full access to PrimeNG template functionality
• Type Safety: Full TypeScript support with PrimeNG type definitions

Code Quality

• ESLint: Angular 19 specific rules with import organization and naming conventions
• Prettier: Automatic code formatting with Tailwind class sorting
• TypeScript: Strict configuration with path mappings (@app/*, @config/*)
• Testing: Angular testing framework with comprehensive coverage

Deployment

The application supports deployment with PM2:

1. Node.js with PM2: Production process management with clustering and zero-downtime deployments

See the deployment documentation for detailed instructions.

📚 Documentation

Architecture Documentation

Comprehensive documentation organized by domain:

🎨 Frontend Architecture

• Angular Patterns - Zoneless change detection, SSR, and Angular 19 features
• Component Architecture - PrimeNG wrappers, layout patterns, and component hierarchy
• Styling System - CSS layers, Tailwind configuration, and LFX UI Core
• State Management - Angular Signals patterns and service architecture
• Performance - SSR optimization, build strategies, and monitoring

🖥 Backend Architecture

• SSR Server - Express.js configuration and Angular 19 SSR integration
• Authentication - Auth0 integration with express-openid-connect
• Logging & Monitoring - Pino logging, structured logs, and health monitoring
• Deployment - PM2 configuration and production deployment

📦 Shared Architecture

• Package Architecture - Shared interfaces, constants, and TypeScript types
• Development Workflow - Turborepo configuration and monorepo patterns

🧪 Testing Architecture

• Unit Testing - Component and service testing with Angular Signals
• Integration Testing - API testing and service integration patterns
• E2E Testing - Playwright configuration and user workflow testing

Quick Start Guides

• 📋 Main Architecture Overview - High-level system overview and navigation
• ⚡ Development Setup - Claude Code assistant instructions and patterns

Development Workflow

Before Committing

Always run these commands before committing code:

yarn lint           # Fix code linting issues
yarn format         # Format code consistently
yarn test           # Ensure all tests pass
yarn build          # Verify build succeeds

# Use the GitHub CI job to check license headers
act -W .github/workflows/license-header-check.yml  # Verify license headers, requires container runtime

# Use the GitHub CI job to check markdown formatting
act -W .github/workflows/markdown-lint.yml # Check markdown formatting

Note: All source files must include the proper license header. See the Contributing Guide for details.

Component Development

# Generate new component (will use lfx- prefix automatically)
ng generate component my-feature --standalone

# Generate service
ng generate service my-service

# Generate guard
ng generate guard my-guard

Using PrimeNG Components

// Import PrimeNG modules directly in your components
import { ButtonModule } from 'primeng/button';
import { CardModule } from 'primeng/card';

@Component({
  selector: 'lfx-example',
  imports: [ButtonModule, CardModule],
  templateUrl: './example.component.html',
  styleUrl: './example.component.scss',
})
export class ExampleComponent {}

<!-- example.component.html -->
<p-card header="Example Card">
  <p-button label="Click me" severity="primary"></p-button>
</p-card>

Technology Stack

Frontend

• Angular 19 with experimental zoneless change detection
• Angular Signals for state management
• PrimeNG 19 UI component library with custom LFX preset
• Tailwind CSS v3 with PrimeUI plugin
• LFX UI Core design system integration
• Font Awesome Pro icons (via kits)
• Google Fonts (Open Sans + Roboto Slab)

Backend & Infrastructure

• Express.js server with Angular 19 SSR
• Auth0 authentication with express-openid-connect
• Pino high-performance structured logging
• PM2 for production process management and clustering

Useful Links

Learn more about the technologies used:

• Turborepo Documentation - Monorepo build system
• Angular Documentation - Angular framework
• Angular Signals - Reactive programming with Signals
• PrimeNG Components - UI component library
• Tailwind CSS - Utility-first CSS framework
• LFX UI Core - Linux Foundation design system
• PM2 Documentation - Process manager for Node.js

License

Copyright The Linux Foundation and each contributor to LFX.

This project’s source code is licensed under the MIT License. A copy of the license is available in LICENSE.

This project’s documentation is licensed under the Creative Commons Attribution 4.0 International License (CC-BY-4.0). A copy of the license is available in LICENSE-docs.