feat: Integrate eslint-plugin-project-structure for bulletproof-react architecture enforcement (#204)feat: Integrate eslint-plugin-project-structure for bulletproof-react architecture enforcement (#204)feat: Integrate eslint-plugin-project-structure for bulletproof-react architecture enforcement (#204)Feat/eslint project structure rdiwakar

[ravikant-diwakar]

🚀 ESLint Project Structure Integration for Bulletproof React

Overview

This PR implements automated architecture enforcement for bulletproof-react using eslint-plugin-project-structure. This addresses Issue #204 by providing comprehensive linting rules that enforce the project's architectural patterns and prevent common violations.

🎯 Key Features

• 📁 Folder Structure Validation: Ensures adherence to bulletproof-react directory patterns
• 🚫 Cross-Feature Import Prevention: Maintains feature independence by blocking imports between features
• ➡️ Unidirectional Data Flow: Enforces proper architectural boundaries (shared → features → app)
• 📝 Naming Convention Compliance: Validates file and component naming conventions
• ⚙️ File Composition Rules: Ensures proper code organization within files

📦 Files Added

1. .project-structure.config.js - Core configuration defining:

   • Folder structure rules for bulletproof-react architecture
   • Independent module enforcement (prevents cross-feature imports)
   • File composition and naming conventions

2. eslint.config.js - Comprehensive ESLint configuration featuring:

   • Integration with project structure plugin
   • React and TypeScript best practices
   • Import/export organization rules
   • Cross-feature import restrictions

3. docs/eslint-project-structure.md - Complete documentation including:

   • Installation and usage instructions
   • Configuration breakdown and examples
   • Best practices and troubleshooting guide
   • CI/CD integration examples

🏗️ Architecture Enforcement

Folder Structure Rules

apps/
└── [app-name]/
    └── src/
        ├── app/              # Application layer
        ├── components/       # Shared components
        ├── features/         # Feature-based modules
        │   └── [feature]/
        │       ├── api/      # Feature-specific API
        │       ├── components/ # Feature components
        │       ├── hooks/    # Feature hooks
        │       └── ...
        ├── hooks/            # Shared hooks
        ├── lib/              # Configured libraries
        └── utils/            # Shared utilities

Independent Modules

• ✅ Features can import from: shared modules (components, hooks, lib, types, utils)
• ❌ Features cannot import from: other features or app layer
• ✅ App layer can import from: features and shared modules
• ❌ Shared modules cannot import from: features or app layer

Naming Conventions

• Components: PascalCase.tsx (e.g., UserProfile.tsx)
• Hooks: use*.ts (e.g., useUserData.ts)
• Types: *.types.ts (e.g., user.types.ts)
• Tests: *.test.ts/.tsx (e.g., UserProfile.test.tsx)
• Stories: *.stories.ts/.tsx (e.g., UserProfile.stories.tsx)

🛠️ Usage

# Install the plugin
npm install --save-dev eslint-plugin-project-structure

# Run ESLint with project structure validation
npx eslint . --fix

# Check specific directory
npx eslint apps/react-vite/src --fix

📋 Examples

✅ Valid Import Patterns

// ✅ Feature importing from shared modules
import { Button } from '../../../components/Button';
import { useApi } from '../../../hooks/useApi';

// ✅ App layer importing from features
import { AuthFeature } from '../features/auth/AuthFeature';

❌ Invalid Import Patterns (Will be caught by ESLint)

// ❌ Cross-feature imports
import { UserCard } from '../users/components/UserCard';

// ❌ Feature importing from app layer
import { AppRouter } from '../app/AppRouter';

🔧 Integration Benefits

1. Automated Architecture Enforcement: No more manual code reviews for architectural violations
2. Developer Experience: Clear error messages with suggested solutions
3. CI/CD Ready: Integrates seamlessly with existing linting workflows
4. Educational: Helps developers understand and follow bulletproof-react patterns
5. Scalable: Rules adapt to project growth while maintaining consistency

🧪 Testing

The configuration has been thoroughly tested to ensure:

• ✅ Valid bulletproof-react patterns pass linting
• ❌ Architectural violations are properly caught
• 📚 Clear error messages guide developers to solutions
• 🚀 Performance impact is minimal

📖 Documentation

Comprehensive documentation is included in docs/eslint-project-structure.md covering:

• Quick start guide
• Configuration breakdown
• Best practices
• Troubleshooting
• CI/CD integration
• Examples and use cases

🎉 Impact

This integration provides automated enforcement of bulletproof-react architecture patterns, ensuring:

• Consistency: All developers follow the same architectural patterns
• Quality: Prevents common architectural mistakes before they reach production
• Productivity: Reduces time spent on architectural code reviews
• Education: Helps team members learn and internalize best practices

---

Closes #204

Implementation by: Ravikant Diwakar
Plugin: eslint-plugin-project-structure

🔍 Review Checklist

• Comprehensive project structure configuration
• ESLint integration with React/TypeScript support
• Detailed documentation with examples
• Cross-feature import prevention
• Unidirectional data flow enforcement
• Naming convention validation
• Best practices guidance
• CI/CD integration examples
• Troubleshooting documentation

[netlify]

✅ Deploy Preview for bulletproof-react-app canceled.

Name	Link
🔨 Latest commit	10283e7
🔍 Latest deploy log	https://app.netlify.com/projects/bulletproof-react-app/deploys/68cce4afd243cf00088a1d73