@jmruthers/pace-core 0.6.4 → 0.6.6

package/docs/standards/02-project-structure.md

@@ -0,0 +1,985 @@
+# Project Structure Guide for Consuming Apps
+
+**🤖 Cursor Rule**: See [02-project-structure.mdc](../../cursor-rules/02-project-structure.mdc) for AI-optimized directives that automatically enforce this structure.
+
+## Purpose
+
+This guide defines the standard project structure and file organization patterns that all apps consuming `@jmruthers/pace-core` **MUST** follow. Adhering to this structure ensures:
+
+- **Consistency** across all PACE suite applications
+- **Maintainability** through predictable organization
+- **Developer Experience** with clear patterns and conventions
+- **Compatibility** with pace-core tooling and automation
+- **Scalability** as your app grows
+
+## Table of Contents
+
+1. [Standard Directory Structure](#standard-directory-structure)
+2. [File Organization Patterns](#file-organization-patterns)
+3. [Naming Conventions](#naming-conventions)
+4. [Import Path Configuration](#import-path-configuration)
+5. [Component Organization](#component-organization)
+6. [Testing Structure](#testing-structure)
+7. [Database & Supabase Structure](#database--supabase-structure)
+8. [Configuration Files](#configuration-files)
+9. [Migration from Existing Projects](#migration-from-existing-projects)
+10. [Structure Checklist](#structure-checklist)
+
+---
+
+## Standard Directory Structure
+
+### Complete Project Structure
+
+Every consuming app **MUST** follow this base structure:
+
+```
+your-app/
+├── .cursor/
+│   └── rules/                    # Cursor rules (pace-core + local)
+│       ├── 00-pace-core-compliance.mdc
+│       ├── 01-standards-compliance.mdc
+│       ├── 02-project-structure.mdc
+│       └── [local-rules].mdc
+│
+├── .vscode/                      # VS Code settings (optional)
+│   └── settings.json
+│
+├── public/                       # Static assets
+│   ├── favicon.ico
+│   ├── robots.txt
+│   └── [other-static-assets]/
+│
+├── src/                          # Source code
+│   ├── components/               # App-specific components
+│   │   ├── [feature-name]/      # Organized by feature
+│   │   └── shared/              # Shared app components
+│   │
+│   ├── hooks/                    # App-specific hooks
+│   │   ├── [feature-name]/      # Feature-specific hooks
+│   │   └── [hook-name].ts
+│   │
+│   ├── services/                 # App-specific services (if using service pattern)
+│   │   └── [service-name].ts
+│   │
+│   ├── pages/                    # Page components (route components)
+│   │   ├── [PageName].tsx
+│   │   └── [feature]/           # Feature-based pages
+│   │
+│   ├── types/                    # TypeScript type definitions
+│   │   ├── [domain].ts          # Domain-specific types
+│   │   └── index.ts             # Re-export barrel file
+│   │
+│   ├── utils/                    # App-specific utilities
+│   │   ├── [utility-name].ts
+│   │   └── index.ts             # Re-export barrel file
+│   │
+│   ├── lib/                      # Third-party library configurations
+│   │   └── supabase.ts          # Supabase client setup
+│   │
+│   ├── App.tsx                   # Main app component
+│   ├── main.tsx                  # Application entry point
+│   └── app.css                   # Global styles (MUST follow 08-markup-quality.md)
+│
+├── supabase/                     # Supabase configuration
+│   ├── migrations/              # Database migrations
+│   │   └── YYYYMMDDHHMMSS_description.sql
+│   ├── functions/                # Edge functions (if used)
+│   │   └── [function-name]/
+│   └── config.toml               # Supabase config
+│
+├── tests/                        # Integration/E2E tests (optional)
+│   └── [test-files].test.ts
+│
+├── audit/                        # Audit reports (generated, gitignored)
+│   └── audit-*.md
+│
+├── .gitignore
+├── .eslintrc.js                  # ESLint config (or eslint.config.js)
+├── package.json
+├── tsconfig.json                 # TypeScript config
+├── tsconfig.app.json             # App-specific TS config (if needed)
+├── vite.config.ts                # Vite configuration
+├── vitest.config.ts              # Vitest configuration
+├── README.md
+└── CHANGELOG.md                  # (optional but recommended)
+```
+
+### Directory Purpose Reference
+
+| Directory | Purpose | Required? |
+|-----------|---------|-----------|
+| `.cursor/rules/` | Cursor AI rules for code generation | ✅ Yes |
+| `public/` | Static assets served directly | ✅ Yes |
+| `src/` | All source code | ✅ Yes |
+| `src/components/` | App-specific React components | ✅ Yes |
+| `src/hooks/` | Custom React hooks | ✅ Yes |
+| `src/pages/` | Route/page components | ✅ Yes |
+| `src/types/` | TypeScript type definitions | ✅ Yes |
+| `src/utils/` | Utility functions | ✅ Yes |
+| `src/lib/` | Library configurations | ✅ Yes |
+| `supabase/` | Supabase config and migrations | ✅ Yes |
+| `supabase/migrations/` | Database migration files | ✅ Yes |
+| `tests/` | Integration/E2E tests | ⚠️ Optional |
+| `audit/` | Generated audit reports | ✅ Yes (gitignored) |
+
+---
+
+## File Organization Patterns
+
+### Pattern 1: Feature-Based Organization (Recommended for Small-Medium Apps)
+
+Organize components, hooks, and related code by feature/domain:
+
+```
+src/
+├── components/
+│   ├── events/
+│   │   ├── EventCard.tsx
+│   │   ├── EventList.tsx
+│   │   └── EventForm.tsx
+│   ├── users/
+│   │   ├── UserProfile.tsx
+│   │   └── UserList.tsx
+│   └── shared/
+│       ├── AppLayout.tsx
+│       └── Navigation.tsx
+│
+├── hooks/
+│   ├── events/
+│   │   ├── useEventData.ts
+│   │   └── useEventForm.ts
+│   └── users/
+│       └── useUserData.ts
+│
+├── pages/
+│   ├── EventsPage.tsx
+│   ├── EventDetailPage.tsx
+│   ├── UsersPage.tsx
+│   └── UserProfilePage.tsx
+│
+└── types/
+    ├── events.ts
+    └── users.ts
+```
+
+**When to use:** Small to medium-sized apps (< 20 features)
+
+### Pattern 2: Domain-Driven Organization (Recommended for Large Apps)
+
+For larger applications, organize by domain with internal structure:
+
+```
+src/
+├── domains/
+│   ├── events/
+│   │   ├── components/
+│   │   │   ├── EventCard.tsx
+│   │   │   └── EventList.tsx
+│   │   ├── hooks/
+│   │   │   └── useEventData.ts
+│   │   ├── services/
+│   │   │   └── EventService.ts
+│   │   ├── types.ts
+│   │   └── index.ts              # Domain barrel export
+│   │
+│   └── users/
+│       ├── components/
+│       ├── hooks/
+│       ├── services/
+│       ├── types.ts
+│       └── index.ts
+│
+├── shared/                        # Shared across domains
+│   ├── components/
+│   │   ├── Layout.tsx
+│   │   └── Navigation.tsx
+│   ├── hooks/
+│   │   └── useAppConfig.ts
+│   └── utils/
+│       └── formatDate.ts
+│
+└── pages/
+    ├── events/
+    │   ├── EventsListPage.tsx
+    │   └── EventDetailPage.tsx
+    └── users/
+        └── UsersPage.tsx
+```
+
+**When to use:** Large apps with multiple distinct domains (> 20 features, clear domain boundaries)
+
+### Pattern 3: Hybrid Organization
+
+Combine feature-based and domain-based as needed:
+
+```
+src/
+├── components/
+│   ├── events/                   # Feature-based (simple features)
+│   └── shared/                   # Shared components
+│
+├── domains/
+│   └── complex-feature/          # Domain-based (complex features)
+│       ├── components/
+│       ├── hooks/
+│       └── services/
+│
+└── pages/
+    └── [pages organized by route]
+```
+
+**When to use:** Apps with mixed complexity levels
+
+---
+
+## Naming Conventions
+
+### Files
+
+| Type | Convention | Example | Notes |
+|------|------------|---------|-------|
+| **Components** | `PascalCase.tsx` | `EventCard.tsx` | React components |
+| **Hooks** | `camelCase.ts` with `use` prefix | `useEventData.ts` | Custom hooks |
+| **Utilities** | `camelCase.ts` | `formatEvent.ts` | Helper functions |
+| **Types** | `camelCase.ts` or `types.ts` | `eventTypes.ts` | Type definitions |
+| **Services** | `PascalCase.ts` | `EventService.ts` | Service classes |
+| **Tests** | `*.test.ts` or `*.test.tsx` | `EventCard.test.tsx` | Test files |
+| **Config** | `kebab-case.config.js` | `vite.config.ts` | Config files |
+| **Pages** | `PascalCase.tsx` with `Page` suffix | `EventsPage.tsx` | Route components |
+
+### Directories
+
+| Type | Convention | Example | Notes |
+|------|------------|---------|-------|
+| **Feature directories** | `kebab-case` | `event-management/` | Feature/domain names |
+| **Component directories** | `kebab-case` | `event-card/` | When component has multiple files |
+| **Shared directories** | `kebab-case` | `shared/` | Shared across features |
+
+### Code Naming
+
+```typescript
+// ✅ CORRECT - Components
+export function EventCard() { }
+export const UserProfile = () => { };
+
+// ✅ CORRECT - Hooks
+export function useEventData() { }
+export function useUserProfile() { }
+
+// ✅ CORRECT - Utilities
+export function formatEvent() { }
+export function validateUserInput() { }
+
+// ✅ CORRECT - Types
+export type Event = { };
+export interface UserProfile { }
+
+// ✅ CORRECT - Services
+export class EventService { }
+```
+
+---
+
+## Import Path Configuration
+
+### Path Aliases Setup
+
+**MUST** configure path aliases in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@/components/*": ["./src/components/*"],
+      "@/hooks/*": ["./src/hooks/*"],
+      "@/pages/*": ["./src/pages/*"],
+      "@/types/*": ["./src/types/*"],
+      "@/utils/*": ["./src/utils/*"],
+      "@/lib/*": ["./src/lib/*"]
+    }
+  }
+}
+```
+
+**MUST** also configure in `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+      '@/components': path.resolve(__dirname, './src/components'),
+      '@/hooks': path.resolve(__dirname, './src/hooks'),
+      '@/pages': path.resolve(__dirname, './src/pages'),
+      '@/types': path.resolve(__dirname, './src/types'),
+      '@/utils': path.resolve(__dirname, './src/utils'),
+      '@/lib': path.resolve(__dirname, './src/lib'),
+    },
+  },
+});
+```
+
+### Import Patterns
+
+```tsx
+// ✅ CORRECT - Absolute imports from src
+import { EventCard } from '@/components/events/EventCard';
+import { useEventData } from '@/hooks/events/useEventData';
+import { formatEvent } from '@/utils/formatEvent';
+import type { Event } from '@/types/events';
+
+// ✅ CORRECT - pace-core imports
+import { Button, Card, DataTable } from '@jmruthers/pace-core';
+import { useUnifiedAuth, usePermissions } from '@jmruthers/pace-core';
+import { formatDate, formatCurrency } from '@jmruthers/pace-core';
+
+// ✅ CORRECT - Relative imports for nearby files (same directory)
+import { EventCardHeader } from './EventCardHeader';
+import { EventCardFooter } from './EventCardFooter';
+
+// ❌ WRONG - Deep relative imports
+import { EventCard } from '../../../components/events/EventCard';
+
+// ❌ WRONG - Importing from pace-core source
+import { Button } from '@jmruthers/pace-core/src/components/Button';
+```
+
+---
+
+## Component Organization
+
+### Component Structure
+
+**MUST** organize components by feature, not by type:
+
+```
+src/components/
+├── events/                    # ✅ Feature-based
+│   ├── EventCard.tsx
+│   ├── EventList.tsx
+│   └── EventForm.tsx
+│
+└── shared/                    # ✅ Shared app components
+    ├── AppLayout.tsx
+    └── Navigation.tsx
+```
+
+```
+src/components/
+├── buttons/                   # ❌ WRONG - Type-based
+├── inputs/                    # ❌ WRONG - Type-based
+└── cards/                     # ❌ WRONG - Type-based
+```
+
+**Why?** Use pace-core components for UI primitives (Button, Input, Card, etc.). Your components should be feature-specific compositions.
+
+### Component File Structure
+
+For simple components (single file):
+
+```
+src/components/events/EventCard.tsx
+```
+
+For complex components (multiple related files):
+
+```
+src/components/events/EventCard/
+├── EventCard.tsx              # Main component
+├── EventCardHeader.tsx        # Sub-components
+├── EventCardFooter.tsx
+├── EventCard.test.tsx         # Tests (colocated)
+├── EventCard.types.ts         # Component-specific types
+└── index.ts                   # Barrel export
+```
+
+### Component Composition Example
+
+```tsx
+// ✅ CORRECT - Use pace-core components
+import { Button, Card, Input } from '@jmruthers/pace-core';
+import { useEventData } from '@/hooks/events/useEventData';
+
+export function EventCard({ eventId }: { eventId: string }) {
+  const { event } = useEventData(eventId);
+  
+  return (
+    <Card>
+      <h2>{event.title}</h2>
+      <p>{event.description}</p>
+      <Button>View Details</Button>
+    </Card>
+  );
+}
+```
+
+---
+
+## Testing Structure
+
+### Test Colocation
+
+**MUST** colocate tests with source files:
+
+```
+src/
+├── components/
+│   └── events/
+│       ├── EventCard.tsx
+│       └── EventCard.test.tsx        # ✅ Colocated
+│
+├── hooks/
+│   ├── useEventData.ts
+│   └── useEventData.test.ts           # ✅ Colocated
+│
+└── utils/
+    ├── formatEvent.ts
+    └── formatEvent.test.ts            # ✅ Colocated
+```
+
+### Test File Naming
+
+- Unit tests: `*.test.ts` or `*.test.tsx`
+- Integration tests: `*.integration.test.ts`
+- E2E tests: Place in `tests/` directory
+
+### Test Organization Example
+
+```typescript
+// src/components/events/EventCard.test.tsx
+import { render, screen } from '@testing-library/react';
+import { EventCard } from './EventCard';
+
+describe('EventCard', () => {
+  it('renders event title', () => {
+    // Test implementation
+  });
+});
+```
+
+---
+
+## Database & Supabase Structure
+
+### Migration Files
+
+**MUST** place all migrations in `supabase/migrations/`:
+
+```
+supabase/
+└── migrations/
+    ├── 20250115143022_add_user_preferences.sql
+    ├── 20250116120000_create_events_table.sql
+    └── 20250117150000_add_rls_policies.sql
+```
+
+**MUST** follow naming convention: `YYYYMMDDHHMMSS_description.sql`
+
+### Edge Functions (if used)
+
+```
+supabase/
+└── functions/
+    ├── send-email/
+    │   ├── index.ts
+    │   └── package.json
+    └── process-payment/
+        ├── index.ts
+        └── package.json
+```
+
+### Supabase Client Setup
+
+**MUST** place Supabase client in `src/lib/supabase.ts`:
+
+```typescript
+// src/lib/supabase.ts
+import { createClient } from '@supabase/supabase-js';
+import type { Database } from '@/types/database';
+
+const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
+const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;
+
+export const supabaseClient = createClient<Database>(
+  supabaseUrl,
+  supabaseAnonKey
+);
+```
+
+---
+
+## Configuration Files
+
+### Required Configuration Files
+
+**MUST** have these configuration files in the root:
+
+| File | Purpose | Required? |
+|------|---------|-----------|
+| `package.json` | Dependencies and scripts | ✅ Yes |
+| `tsconfig.json` | TypeScript configuration | ✅ Yes |
+| `vite.config.ts` | Vite build configuration | ✅ Yes |
+| `vitest.config.ts` | Vitest test configuration | ✅ Yes |
+| `.gitignore` | Git ignore patterns | ✅ Yes |
+| `.eslintrc.js` or `eslint.config.js` | ESLint configuration | ✅ Yes |
+
+### Root Directory Rules
+
+**MUST** keep root directory clean:
+
+✅ **Allowed in root:**
+- Configuration files (`package.json`, `tsconfig.json`, etc.)
+- Documentation (`README.md`, `CHANGELOG.md`)
+- Build tool configs (`vite.config.ts`, etc.)
+- `.cursor/` directory
+- `.gitignore`, `.env.example`, etc.
+
+❌ **NOT allowed in root:**
+- Source files (`*.ts`, `*.tsx`)
+- Component files
+- Test files
+- Utility files
+
+---
+
+## Migration from Existing Projects
+
+### Common Migration Scenarios
+
+This section provides patterns for migrating common project structures to the standard pace-core structure.
+
+### Scenario 1: Flat Component Structure
+
+**Before:**
+```
+src/
+├── Button.tsx
+├── Card.tsx
+├── EventCard.tsx
+├── UserCard.tsx
+└── utils.ts
+```
+
+**After:**
+```
+src/
+├── components/
+│   ├── events/
+│   │   └── EventCard.tsx
+│   ├── users/
+│   │   └── UserCard.tsx
+│   └── shared/  # If Button/Card are app-specific (otherwise use pace-core)
+├── utils/
+│   └── index.ts
+```
+
+**Migration Steps:**
+1. Group components by feature/domain
+2. Move to `src/components/[feature]/`
+3. Remove duplicate pace-core components (use pace-core instead)
+4. Update imports to use path aliases
+
+### Scenario 2: Type-Based Organization
+
+**Before:**
+```
+src/
+├── components/
+│   ├── buttons/
+│   ├── inputs/
+│   └── cards/
+└── hooks/
+    ├── useButton.ts
+    └── useInput.ts
+```
+
+**After:**
+```
+src/
+├── components/
+│   ├── events/  # Feature-based
+│   └── users/   # Feature-based
+└── hooks/
+    ├── events/
+    └── users/
+```
+
+**Migration Steps:**
+1. Identify features/domains in your app
+2. Reorganize by feature, not type
+3. Use pace-core for UI primitives (Button, Input, Card)
+4. Keep only feature-specific components
+
+### Scenario 3: Monolithic File Structure
+
+**Before:**
+```
+src/
+├── App.tsx
+├── components.tsx  # All components in one file
+├── hooks.ts        # All hooks in one file
+└── utils.ts        # All utilities in one file
+```
+
+**After:**
+```
+src/
+├── App.tsx
+├── components/
+│   ├── events/
+│   └── users/
+├── hooks/
+│   ├── events/
+│   └── users/
+└── utils/
+    └── index.ts
+```
+
+**Migration Steps:**
+1. Split monolithic files by feature
+2. Create feature directories
+3. Move related code together
+4. Update imports
+
+### Scenario 4: Mixed Root/Src Structure
+
+**Before:**
+```
+your-app/
+├── components/     # In root
+├── src/
+│   └── pages/
+└── utils.ts        # In root
+```
+
+**After:**
+```
+your-app/
+└── src/
+    ├── components/
+    ├── pages/
+    └── utils/
+```
+
+**Migration Steps:**
+1. Move all source files to `src/`
+2. Consolidate into standard structure
+3. Update all import paths
+4. Update configuration files
+
+### Step-by-Step Migration Process
+
+#### Phase 1: Preparation
+
+1. **Audit Current Structure**
+   ```bash
+   # Review your current structure
+   tree -L 3 -I 'node_modules' src/
+   
+   # Find all imports
+   grep -r "import.*from" src/ | grep -E "\.\./|\.\.\/\.\." | head -20
+   ```
+
+2. **Create Backup Branch**
+   ```bash
+   git checkout -b migrate-project-structure
+   git commit -am "Backup before structure migration"
+   ```
+
+3. **Identify Features/Domains**
+   - List all features in your app
+   - Group related components/hooks/utils
+   - Identify pace-core duplicates
+
+#### Phase 2: Structure Creation
+
+1. **Create New Structure**
+   ```bash
+   mkdir -p src/{components,hooks,pages,types,utils,lib}
+   mkdir -p src/components/{events,users,shared}  # Your features
+   mkdir -p supabase/migrations
+   mkdir -p .cursor/rules
+   mkdir -p audit
+   ```
+
+2. **Move Files Incrementally**
+   - Start with one feature at a time
+   - Move components → `src/components/[feature]/`
+   - Move hooks → `src/hooks/[feature]/`
+   - Move pages → `src/pages/`
+   - Move types → `src/types/`
+   - Move utils → `src/utils/`
+
+#### Phase 3: Import Updates
+
+1. **Configure Path Aliases**
+   
+   Update `tsconfig.json`:
+   ```json
+   {
+     "compilerOptions": {
+       "baseUrl": ".",
+       "paths": {
+         "@/*": ["./src/*"],
+         "@/components/*": ["./src/components/*"],
+         "@/hooks/*": ["./src/hooks/*"],
+         "@/pages/*": ["./src/pages/*"],
+         "@/types/*": ["./src/types/*"],
+         "@/utils/*": ["./src/utils/*"]
+       }
+     }
+   }
+   ```
+   
+   Update `vite.config.ts`:
+   ```typescript
+   import path from 'path';
+   
+   export default defineConfig({
+     resolve: {
+       alias: {
+         '@': path.resolve(__dirname, './src'),
+         '@/components': path.resolve(__dirname, './src/components'),
+         // ... other aliases
+       },
+     },
+   });
+   ```
+
+2. **Update Imports**
+   
+   Use find-and-replace (one feature at a time):
+   ```bash
+   # Example: Update EventCard imports
+   find src -type f -name "*.tsx" -exec sed -i '' 's|from.*EventCard|from "@/components/events/EventCard"|g' {} +
+   ```
+
+   Or use a script:
+   ```typescript
+   // scripts/update-imports.ts
+   // Update imports programmatically
+   ```
+
+#### Phase 4: Cleanup
+
+1. **Remove Duplicate pace-core Components**
+   ```bash
+   # Check for pace-core duplicates
+   node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+   ```
+
+2. **Remove Empty Directories**
+   ```bash
+   find src -type d -empty -delete
+   ```
+
+3. **Update Tests**
+   - Update test imports to match new structure
+   - Ensure tests still pass
+
+#### Phase 5: Verification
+
+1. **Install Cursor Rules**
+   ```bash
+   node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
+   ```
+
+2. **Run Compliance Checks**
+   ```bash
+   # Check pace-core compliance
+   node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+   
+   ```
+
+3. **Verify Build**
+   ```bash
+   npm run build
+   npm run test
+   ```
+
+### Migration Checklist
+
+- [ ] Current structure audited
+- [ ] Backup branch created
+- [ ] Features/domains identified
+- [ ] New structure created
+- [ ] Files moved incrementally
+- [ ] Path aliases configured
+- [ ] Imports updated
+- [ ] Duplicate pace-core components removed
+- [ ] Tests updated and passing
+- [ ] Cursor rules installed
+- [ ] Compliance checks passing
+- [ ] Build successful
+
+### Common Migration Issues
+
+#### Issue: Circular Dependencies
+
+**Problem:** Moving files creates circular imports
+
+**Solution:**
+- Identify circular dependencies
+- Extract shared code to `src/utils/` or `src/types/`
+- Use barrel exports carefully
+
+#### Issue: Deep Relative Imports
+
+**Problem:** Many `../../../` imports
+
+**Solution:**
+- Use path aliases (`@/components/...`)
+- Update imports systematically
+- Use find-and-replace or script
+
+#### Issue: Test Failures
+
+**Problem:** Tests fail after moving files
+
+**Solution:**
+- Update test imports
+- Ensure path aliases work in test environment
+- Update test setup files
+
+### Migration Tools
+
+**Automated Import Updates:**
+```bash
+# Using jscodeshift (if available)
+npx jscodeshift -t transform-imports src/
+```
+
+**Manual Find-and-Replace:**
+```bash
+# Update specific import patterns
+find src -type f -name "*.tsx" -exec sed -i '' 's|old/path|new/path|g' {} +
+```
+
+**TypeScript Compiler:**
+```bash
+# Check for import errors
+npx tsc --noEmit
+```
+
+---
+
+## Structure Checklist
+
+Before committing code, verify your project structure:
+
+### Directory Structure
+- [ ] Standard directory structure followed
+- [ ] Root directory contains only config files
+- [ ] All source code in `src/`
+- [ ] Migrations in `supabase/migrations/`
+- [ ] Cursor rules installed in `.cursor/rules/`
+
+### File Organization
+- [ ] Components organized by feature, not type
+- [ ] Tests colocated with source files
+- [ ] Naming conventions followed
+- [ ] No duplicate pace-core components
+
+### Imports
+- [ ] Path aliases configured (`@/` prefix)
+- [ ] Absolute imports used (no deep relative paths)
+- [ ] pace-core imported from package, not source
+- [ ] No restricted imports (e.g., `@radix-ui/*`)
+
+### Configuration
+- [ ] `tsconfig.json` has path aliases
+- [ ] `vite.config.ts` has path aliases
+- [ ] ESLint configured with pace-core rules
+- [ ] All required config files present
+
+### Documentation
+- [ ] `README.md` documents project structure
+- [ ] Non-standard decisions documented
+- [ ] Migration notes (if applicable)
+
+---
+
+## Common Mistakes to Avoid
+
+### ❌ Don't: Organize by Component Type
+
+```
+src/components/
+├── buttons/        # ❌ Use pace-core Button instead
+├── inputs/         # ❌ Use pace-core Input instead
+└── cards/          # ❌ Use pace-core Card instead
+```
+
+### ❌ Don't: Create Duplicate Components
+
+```tsx
+// ❌ WRONG - Don't create local Button
+// src/components/Button.tsx
+export function Button() { }
+
+// ✅ CORRECT - Use pace-core
+import { Button } from '@jmruthers/pace-core';
+```
+
+### ❌ Don't: Use Deep Relative Imports
+
+```tsx
+// ❌ WRONG
+import { EventCard } from '../../../components/events/EventCard';
+
+// ✅ CORRECT
+import { EventCard } from '@/components/events/EventCard';
+```
+
+### ❌ Don't: Place Source Files in Root
+
+```
+your-app/
+├── App.tsx          # ❌ WRONG - Should be in src/
+├── components/      # ❌ WRONG - Should be in src/components/
+└── utils.ts         # ❌ WRONG - Should be in src/utils/
+```
+
+### ❌ Don't: Modify pace-core Code
+
+```tsx
+// ❌ WRONG - Don't import from pace-core source
+import { Button } from '@jmruthers/pace-core/src/components/Button';
+
+// ✅ CORRECT - Import from package
+import { Button } from '@jmruthers/pace-core';
+```
+
+---
+
+## Getting Help
+
+- **Documentation**: See [pace-core documentation](../../README.md)
+- **Standards**: Review other standards in this directory
+- **Cursor Rules**: Check `.cursor/rules/` for automated enforcement
+
+---
+
+## Related Documentation
+
+- [pace-core Compliance](./00-pace-core-compliance.md) - pace-core usage patterns
+- [Markup Quality](./08-markup-quality.md) - **CRITICAL: Required CSS configuration**
+- [Code Quality](./06-code-quality.md) - Code style and TypeScript standards
+- [Tech Stack](./07-tech-stack-compliance.md) - Tech stack requirements
+- [SOLID Principles](./03-solid-principles.md) - Architecture principles
+- [Cursor Rules Documentation](../../getting-started/cursor-rules.md)
+
+---
+
+**Last Updated:** 2025-01-28  
+**Version:** 1.0.0  
+**Applies to:** All consuming apps using `@jmruthers/pace-core`
+