Coding Standards

Critical Fullstack Rules

• JWT Token Handling: Always use API client service - never make direct HTTP calls without proper token management
• Server-Side Validation: All authorization decisions must happen server-side - frontend never enforces security rules
• Tenant Context Access: Always use TenantContextService.getCurrentUser() - never access user context directly from JWT
• Database Queries: All Prisma queries automatically filtered through middleware - never bypass with raw queries
• Error Handling: Use standard error handlers with audit logging - never expose internal security details to frontend
• Route Protection: Only validate authentication (logged in?) in frontend - authorization (what access?) handled by API
• Path Aliases Only: NEVER use relative imports (../../../) - always use path aliases (@lib/, @ui/, @hooks/*, etc.)
• Shadcn/UI Components: ALWAYS check reference implementation at /Users/ayoub/Downloads/shadcn-admin-main/src/components/ui/ before creating or modifying UI components

Frontend Import Standards

CRITICAL: Never Use Relative Imports

// ❌ WRONG - Never use relative imports
import { Button } from '../../../ui/button'
import { useAuth } from '../../hooks/useAuth'
import { formatDate } from '../../../lib/utils'

// ✅ CORRECT - Always use path aliases
import { Button } from '@ui/shadcn/ui/button'
import { useAuth } from '@hooks/useAuth'
import { formatDate } from '@lib/utils'

Available Path Aliases

Core Aliases (alphabetically sorted):

• @/* - Project root (use sparingly)
• @components/* - UI components (./src/components/*)
• @features/* - Feature modules (./features/*)
• @hooks/* - Custom React hooks (./src/hooks/*)
• @layout/* - Layout components (./layout/*)
• @lib/* - Library code, utilities, services (./src/lib/*)
• @menu-items/* - Menu configuration (./menu-items/*)
• @pages/* - Page components (./src/pages/*)
• @providers/* - Context providers (./providers/*)
• @theme/* - Theme configuration (./theme/*)
• @ui/* - Shadcn/ui and custom UI components (./ui/*)

Nested Access via @lib:

Instead of separate aliases, use @lib/* for nested paths:

• Auth utilities: @lib/auth/* (not @auth/*)
• Type definitions: @lib/types/* (not @types/*)
• Utils: @lib/utils or @lib/utils/* (not @utils/*)

Adding New Path Aliases

When adding a new path alias:

1. Add to apps/frontend/tsconfig.json paths section
2. Add to apps/frontend/vite.config.ts alias section
3. Both must be updated or imports will fail at build time

Example:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@new-alias/*": ["./src/new-directory/*"]
    }
  }
}

// vite.config.ts
export default defineConfig({
  resolve: {
    alias: {
      '@new-alias': path.resolve(__dirname, './src/new-directory'),
    }
  }
})

Shadcn/UI Component Standards

CRITICAL: Always Check Reference Implementation

Before creating or modifying any shadcn/ui component, always verify against the reference implementation.

Reference Location: /Users/ayoub/Downloads/shadcn-admin-main/src/components/ui/

Process for Adding/Modifying Components

1. Check if component exists in shadcn-admin reference directory
2. Copy the exact implementation from reference file
3. Adapt import paths to match our project aliases:
   • @/lib/utils → @lib/utils
   • @/components/ui/* → @ui/shadcn/ui/*
4. Only modify if absolutely necessary for project-specific needs
5. Document any deviations in component file comments

Example Workflow

# 1. Check reference implementation
cat /Users/ayoub/Downloads/shadcn-admin-main/src/components/ui/button.tsx

# 2. Copy to project
cp /Users/ayoub/Downloads/shadcn-admin-main/src/components/ui/button.tsx \
   apps/frontend/ui/shadcn/ui/button.tsx

# 3. Update imports in the copied file
# 4. Verify it matches reference behavior

Components to Reference

Always check reference for:

• Form Components: Button, Input, Select, Checkbox, Radio, Label, Textarea
• Layout Components: Card, Dialog, Sheet, Popover, Dropdown Menu, Separator
• Data Display: Table, DataTable, Pagination, Badge, Avatar
• Navigation: Sidebar, Navigation Menu, Breadcrumbs, Tabs
• Feedback: Tooltip, Toast, Alert, Progress
• Advanced: Command, Calendar, Date Picker, Combobox

Why This Matters

• ✅ Ensures consistent UI/UX across application
• ✅ Prevents reinventing components that already exist
• ✅ Maintains compatibility with shadcn-admin design patterns
• ✅ Reduces bugs from custom implementations
• ✅ Saves development time
• ✅ Ensures accessibility and responsive behavior match reference

Naming Conventions

Element	Frontend	Backend	Example
Components	PascalCase	-	ClientList.tsx
Services	camelCase + 'Service'	PascalCase + 'Service'	clientService.ts / ClientsService
API Routes	-	kebab-case	/api/clients
Guards	-	PascalCase + 'Guard'	TenantAccessGuard