Skip to Content
FrontendCrud V2Crud React ProjectsPHPReaction Frontend CRUD React v2

PHPReaction Frontend CRUD React v2

The foundational enterprise CRUD implementation project serving as the reference implementation for all other CRUD v2 projects. Features comprehensive business entity management across multiple domains.

GitHub RepositoryGitHub Project BoardDemo Environment

Project Overview

Purpose

This project serves as the foundational enterprise CRUD implementation that demonstrates the full capabilities of the @phpcreation/frontend-crud-react-nextjs-bundle v2.22.5+. It provides comprehensive entity management for 137 different business entities across financial management, HR, inventory, project management, and more.

Key Statistics

  • 137 Business Entities: Complete CRUD operations across multiple business domains
  • phprCrud Bundle: Consistent bundle architecture across all entities
  • Multi-tenant: Support for multiple tenants and organizations
  • Multi-language: Full internationalization support with next-intl
  • Enterprise Features: Advanced filtering, bulk operations, export/import, Kanban views

Environment Configuration

Required Environment Variables

# App Configuration
NEXT_PUBLIC_APP_ID=phpreaction-crud-v2-prod
NEXT_PUBLIC_ENVIRONMENT=production
 
# API Configuration  
NEXT_PUBLIC_API_BASE_URL=https://api.phpreaction.com
NEXT_PUBLIC_API_VERSION=v1
 
# Authentication
NEXT_PUBLIC_AUTH_URL=https://auth.phpreaction.com
NEXT_PUBLIC_JWT_ISSUER=phpreaction-auth
 
# Icons and Assets
NEXT_PUBLIC_ICONS_URL=https://icons.phpreaction.com
 
# CRUD Bundle Configuration
NEXT_PUBLIC_Role_Accessibility_Check=1
NEXT_PUBLIC_KVS_DATA_STORE_TOGGLE=1
NEXT_PUBLIC_KVS_API_RESOURCE_NAME=key_values
NEXT_PUBLIC_USE_PUT_METHOD=0
NEXT_PUBLIC_IMPORT_FEATURE_TOGGLE=1
 
# Feedback System
NEXT_PUBLIC_TICKET_FEEDBACK=https://feedback.phpreaction.com
 
# AWS/Cloud Configuration
NEXT_PUBLIC_AWS_REGION=us-east-1
NEXT_PUBLIC_S3_BUCKET_URL=https://assets.phpreaction.com
 
# Monitoring
SENTRY_DSN=your-sentry-dsn
SENTRY_ENVIRONMENT=production

Backend API Endpoints

Primary API Resources

Base URL: ${NEXT_PUBLIC_API_BASE_URL}/api/${NEXT_PUBLIC_API_VERSION}

Core Entities

# Account Management
GET    /accounts                    # List accounts
POST   /accounts                    # Create account
GET    /accounts/{id}               # Get account details
PUT    /accounts/{id}               # Update account
DELETE /accounts/{id}               # Delete account
 
# People Management
GET    /people                      # List people
POST   /people                      # Create person
GET    /people/{id}                 # Get person details
PUT    /people/{id}                 # Update person
DELETE /people/{id}                 # Delete person
 
# Invoice Management
GET    /invoices                    # List invoices
POST   /invoices                    # Create invoice
GET    /invoices/{id}               # Get invoice details
PUT    /invoices/{id}               # Update invoice
DELETE /invoices/{id}               # Delete invoice
 
# Coordinate Management
GET    /coordinates                 # List coordinates
POST   /coordinates                 # Create coordinate
GET    /coordinates/{id}            # Get coordinate details
PUT    /coordinates/{id}            # Update coordinate
DELETE /coordinates/{id}            # Delete coordinate
# For SELECT_ASYNC fields
GET    /account_types/dropdown      # Account types dropdown
GET    /invoice_statuses/dropdown   # Invoice statuses dropdown
GET    /people/search?q={query}     # People search
GET    /coordinates/search?q={query} # Coordinates search

Metadata & Configuration

GET    /metadata/entities           # List all entities
GET    /metadata/entities/{name}    # Get entity metadata
GET    /metadata/bundles            # List bundles
GET    /config/key_values           # KVS configuration
POST   /config/key_values           # Update KVS values

Technology Stack

Core Technologies

  • Framework: Next.js 14.2.28 (React 18)
  • Language: TypeScript 5
  • Package Manager: pnpm 10.9.0
  • Styling: Tailwind CSS 3.4.1 with animations
  • State Management: Redux Toolkit 2.2.6
  • Forms: React Hook Form 7.51.5 with Zod 3.23.8 validation
  • UI Components: Mantine Core 8.1.2
  • Internationalization: next-intl 4.0.2
  • HTTP Client: Axios 1.7.2
  • Date Management: Moment.js 2.30.1

PHPCreation Bundles (Private Dependencies)

  • @phpcreation/frontend-auth-authorization-flow-react-nextjs-bundle v2.3.6
  • @phpcreation/frontend-components-react-nextjs-bundle v2.13.3
  • @phpcreation/frontend-config-react-nextjs-bundle v2.2.0
  • @phpcreation/frontend-crud-react-nextjs-bundle v2.22.5
  • @phpcreation/frontend-icons-react-nextjs-bundle v1.9.6
  • @phpcreation/frontend-status-react-nextjs-bundle v1.1.0
  • @phpcreation/frontend-utils-react-nextjs-bundle v1.17.0

Infrastructure

  • Cloud: AWS (DynamoDB, S3, Lambda)
  • Deployment: SST (Serverless Stack) 2.43.3
  • Containerization: Docker support
  • Local Development: Localstack for AWS services
  • Monitoring: Sentry integration (configured but commented out)
  • Testing: Cypress 14.5.2

Installation & Setup

Prerequisites

Required Software

  • Node.js 18+
  • pnpm 10.9.0+
  • Git
  • Docker (for LocalStack)
  • GitHub Personal Access Token (for PHPCreation bundles)

Installation Steps

Clone Repository

git clone https://github.com/PHPCreation/phpreaction-frontend-crud-react-v2.git
cd phpreaction-frontend-crud-react-v2

Setup NPM Authentication

# Method 1: NPM Login
npm login --scope=@phpcreation --auth-type=legacy --registry=https://npm.pkg.github.com
 
# Method 2: Create .npmrc (don't commit this file)
echo "@phpcreation:registry=https://npm.pkg.github.com/" > .npmrc
echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc

Install Dependencies

# Install all dependencies
pnpm install

Configure Environment

# Copy environment template
cp .env.example .env.local
 
# Edit with your configuration
nano .env.local

Setup LocalStack (for local development)

# Navigate to LocalStack directory
cd infrastructure/localstack
docker compose up -d
 
# Install LocalStack dependencies
pnpm install
 
# Create AWS resources
pnpm run create

Run Development Server

# Load environment and start
pnpm run dev
 
# Or with SST binding
pnpm run dev:sst

Project Structure

Source Code Organization

src/
├── app/                          # Next.js 14 App Directory
│   ├── [locale]/                # Internationalized routes
│   │   ├── page.tsx             # Dashboard page
│   │   ├── metadata/            # Metadata management
│   │   ├── parameters/          # System parameters
│   │   └── support/             # Support page
│   └── api/                     # API routes
│       ├── auth/                # Authentication
│       ├── config-login/        # Configuration login
│       ├── oauth/               # OAuth handlers
│       └── status/              # Health checks
├── components/
│   └── common/
│       └── ThemeProvider/       # Theme management
├── containers/
│   ├── MetadataEntities/        # Metadata container
│   └── Modals/
│       └── HelpModal/           # Help modal
├── crud_config/                 # Entity Configurations (137 entities)
│   ├── accounts/                # Account entity config
│   ├── bills/                   # Bill entity config
│   ├── coordinates/             # Coordinates entity config
│   ├── invoices/                # Invoice entity config
│   ├── payrolls/                # Payroll entity config
│   ├── people/                  # People entity config
│   ├── products/                # Product entity config
│   ├── projects/                # Project entity config
│   ├── timesheets/              # Timesheet entity config
│   └── [128+ other entities]/   # Various business entities
├── store/                       # Redux Store
│   ├── index.ts                 # Store configuration
│   ├── slices/                  # Redux slices
│   └── thunks/                  # Async actions
├── utils/                       # Utility Functions
│   ├── functions/               # Helper functions
│   ├── hooks/                   # Custom hooks
│   └── types/                   # TypeScript types
└── middleware.ts               # Next.js middleware

Key Directories Explained

  • crud_config/: Contains configuration for each entity type (137 business entities)
  • containers/: Reusable container components
  • store/: Redux store with authentication and app state
  • utils/: Shared utilities, hooks, and types

Entity Categories

Financial Management (35+ entities)

  • Accounting: accounts, account_types, accounting_entries, accounting_periods, accounting_transactions, accounting_transactiontypes
  • Invoicing: invoices, invoice_lines, invoice_line_types, invoice_payments, invoice_payment_types, invoice_statuses, invoice_taxes, invoice_types, invoice_distribution_types
  • Bills: bills, bill_lines, bill_line_types, bill_payments, bill_payment_types, bill_statuses, bill_taxes, bill_types, bill_distributiontypes
  • Payroll: payrolls, payroll_linetypes, payroll_payments, payroll_paymenttypes, payroll_statuses, payroll_t4s

People & Contact Management (25+ entities)

  • Core People: people, coordinates, coordinate_genders, coordinate_locations, coordinate_mbtis, coordinate_types
  • Person Types: person_applicants, person_clients, person_competitors, person_contacts, person_corporations, person_employees, person_employee_types, person_partners, person_prospects, person_suppliers
  • Classifications: person_companytypes, person_industries, person_industrysectors, person_marketingsources, person_preparation_levels, person_prospect_statuses, person_prospect_types, person_skills, person_person_skills, person_workingtypes

Product & Inventory Management (15+ entities)

  • Products: products, product_brands, product_options, product_types, product_unit_types
  • Product Relations: product_product_components, product_product_options, product_productbuycosts, product_productsellprices
  • Inventory: inventory_batches, inventory_entries

Project Management (10+ entities)

  • Projects: projects, project_priorities, project_sectors, project_project_sectors, project_statuses, project_tasks, project_types

HR & Time Management (10+ entities)

  • HR: hr_availabilitytypes, hr_schedules, hr_statuses
  • Timesheets: timesheets, timesheet_allowances, timesheet_allowance_types, timesheet_bonis, timesheet_entry_modes, timesheet_statuses, timesheet_types

System & Configuration (20+ entities)

  • Dashboard: dashboard_filters, dashboard_filtertypes, dashboard_reports, dashboard_reporttypes, dashboard_reportwidgets, dashboard_widgets
  • Data Analysis: dataanalysis_datacollectors, dataanalysis_datacollectorparameters, dataanalysis_datacollectorresults, dataanalysis_dataprocessors, dataanalysis_dataprocessorcollectors, dataanalysis_dataprocessorresults
  • System: meta_bundles, meta_entities, users, user_roles, tags, taggings

Additional Modules (15+ entities)

  • Notes: notes, note_comments, note_connections, note_noteparticipants, note_statuses, note_types
  • Storage: storage_files, storage_entityfiles, storage_entityfiletypes
  • Shipping: shipping_shipments, shipping_shippers
  • Languages: langs, lang_languages, lang_translations, lang_alerts
  • Others: approvals, custom_properties, data_ownerships, event_subscribers, rates, rents, rent_types

Entity Configuration Examples

Complete Entity Setup

Bundle Configuration Pattern

All entities use the consistent phprCrud bundle with the pattern:

  • Bundle: phprCrud
  • Unit: {ModuleName}Bundle{EntityName} (e.g., BillBundleBill, PersonBundlePerson)
  • Interfaces: base, listing, create, edit, show
// src/crud_config/bills/index.tsx
import {
	CreateProps,
	EditProps,
	FilterField,
	Sidebox,
	IFQCN_BUI,
	ListingProps,
	MainColumnsListing,
	ShowProps,
	ColumnTypeEnum,
	FormInput,
	DisplayField
} from '@phpcreation/frontend-utils-react-nextjs-bundle/utils/types';
 
// Base FQCN - Real PHPReaction Configuration
const fqcn_bui: IFQCN_BUI = {
	Bundle: 'phprCrud',
	Unit: 'BillBundleBill',
	Interface: 'base'
};
 
// Resource name
const resource: string = 'bills';
 
// Fields for export
const fieldsExport: string[] = ['id','supplier','billNumber','billTotal','billStatus','uniqueId'];
 
// All available fields
const fieldsAll: string[] = ['id','supplier','billNumber','billTotal','billStatus','uniqueId'];
 
// Default selected fields
const selectedList: string[] = ['id','supplier','billNumber','billTotal','billStatus'];
 
// Default actions
const defaultActions: string[] = ['show', 'quick-edit', 'duplicate', 'delete'];
 
// Implemented interfaces
const implementedInterfaces: { [key: string]: boolean } = {
	treeview: false,
	translatable: true,
	taggable: true,
	deleteable: true,
	slugable: true,
	kvsDefaultValues: true,
	timestampable: true,
	disableable: true,
	stringable: true
};
 
// Quick modal inputs
const formModalInputs: FilterField[] = [{
	title: 'Bill Number',
	key: 'billNumber',
	type: ColumnTypeEnum.TEXT,
	placeholder: 'Input the Bill Number',
	required: true,
},{
	title: 'Bill Total',
	key: 'billTotal',
	type: ColumnTypeEnum.DECIMAL,
	placeholder: 'Input the Bill Total',
	required: false,
}];
 
// Main listing columns
const mainColumns: MainColumnsListing[] = [
{
	title: 'Id',
	key: 'id',
	sortable: true,
},
{
	title: 'Supplier',
	key: 'toString',
	type: ColumnTypeEnum.ENTITY_URL,
	link: 'id',
	entity: 'supplier',
	targetResourceAsync: 'suppliers',
},
{
	title: 'Bill Number',
	key: 'billNumber',
	type: ColumnTypeEnum.TEXT,
},
{
	title: 'Bill Total',
	key: 'billTotal',
	type: ColumnTypeEnum.DECIMAL,
},
{
	title: 'Bill Status',
	key: 'toString',
	type: ColumnTypeEnum.ENTITY_URL,
	link: 'id',
	entity: 'billStatus',
	targetResourceAsync: 'bill_statuses',
},
{
	title: 'Unique Id',
	key: 'uniqueId',
	type: ColumnTypeEnum.TEXT,
}];
 
// Form inputs for detailed pages
const formInputs: FormInput[] = [{
    title: 'General',
    fields: [{
    title: 'Supplier',
    key: 'supplier',
    type: ColumnTypeEnum.SELECT_ASYNC,
    targetResourceAsync: 'suppliers',
    itemSpecificPath: 'supplier.uniqueId',
    prefixOnSubmit: '/open-api/v3/suppliers/',
    placeholder: 'Select Supplier',
    resourceAsyncLabelParam: 'uniqueId',
    isMulti: false,
    required: false,
},{
    title: 'Bill Number',
    key: 'billNumber',
    type: ColumnTypeEnum.TEXT,
    placeholder: 'Input the Bill Number',
    required: true,
},{
    title: 'Bill Total',
    key: 'billTotal',
    type: ColumnTypeEnum.DECIMAL,
    placeholder: 'Input the Bill Total',
    required: false,
},{
    title: 'Bill Status',
    key: 'billStatus',
    type: ColumnTypeEnum.SELECT_ASYNC,
    targetResourceAsync: 'bill_statuses',
    itemSpecificPath: 'billStatus.uniqueId',
    prefixOnSubmit: '/open-api/v3/bill_statuses/',
    placeholder: 'Select Bill Status',
    resourceAsyncLabelParam: 'uniqueId',
    isMulti: false,
    required: false,
}]
}];
 
// Listing props export
export const listingProps: ListingProps = {
	fqcn_bui: fqcn_bui,
	resource: resource,
	fieldsExport: fieldsExport,
	fieldsAll: fieldsAll,
	selectedList: selectedList,
	defaultActions: defaultActions,
	formModalInputs: formModalInputs,
	mainColumns: mainColumns,
	implementedInterfaces: implementedInterfaces,
	qField: 'BillBundleBill'
};

Deployment

AWS Deployment with SST

# Build for production
pnpm run build
 
# Deploy to staging
sst deploy --stage staging
 
# Deploy to production  
sst deploy --stage production

Environment-Specific Deployments

# Staging deployment
export APP_ENV=staging
export AWS_PROFILE=phpreaction-staging
 
# Deploy infrastructure
sst deploy --stage staging
 
# Verify deployment
curl https://staging-crud.phpreaction.com/api/status

Testing

E2E Testing with Cypress

# Open Cypress UI
pnpm run cypress:open
 
# Run tests headless
pnpm run cypress:run
 
# Run E2E tests with server
pnpm run test:e2e:cmd

Test Coverage Areas

  • Authentication Flow: Login/logout, role-based access
  • CRUD Operations: Create, read, update, delete for key entities
  • Form Validation: Field validation and error handling
  • Data Import: CSV/Excel import functionality
  • Export Features: Data export in various formats
  • Multi-language: Translation switching

Performance Monitoring

Sentry Configuration

The project includes comprehensive error tracking and performance monitoring:

// sentry.client.config.ts
import * as Sentry from "@sentry/nextjs";
 
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.SENTRY_ENVIRONMENT,
  tracesSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

Key Features Monitored

  • Performance: Bundle size optimization with Next.js 14.2.28
  • Error Tracking: Comprehensive error logging (Sentry configured but commented)
  • API Performance: Backend response time monitoring
  • User Experience: Real-time application performance
  • Development Tools: Hot reloading and development optimization

Contributing

Development Workflow

Create Feature Branch

git checkout -b feature/new-entity-support

Make Changes

Follow the established patterns for new entities

Test Changes

pnpm run lint
pnpm run build
pnpm run test:e2e:cmd

Submit Pull Request

Create PR targeting the main branch

Code Review

Ensure all checks pass and get approval

Deploy

Changes are automatically deployed after merge

Code Standards

  • TypeScript: Strict type checking enabled
  • ESLint: Consistent code formatting
  • Conventional Commits: Structured commit messages
  • Semantic Release: Automated versioning

Support & Troubleshooting

Common Issues

Bundle Authentication Issues

If you’re getting 404 errors when installing packages, ensure your GitHub token has the correct permissions and scope.

# Re-authenticate with correct scope
npm login --scope=@phpcreation --auth-type=legacy --registry=https://npm.pkg.github.com

LocalStack Connection Issues

Ensure LocalStack is running and AWS resources are created:

cd infrastructure/localstack
docker compose ps  # Check if running
pnpm run create   # Recreate resources

Getting Help

This comprehensive documentation covers the complete setup, configuration, and usage of the PHPReaction Frontend CRUD React v2 project - the foundational enterprise CRUD system with 137 business entities providing complete business management capabilities across financial, HR, inventory, and project management domains.

Last updated on
PHPReaction Frontend Account CRUD React v2Ticket Frontend CRUD React v2