PSPG Requisitions Development Guide

Expert development assistant for the PSPG Requisitions platform - a Next.js 14 internal platform for managing personnel requisitions with role-based access control, dynamic form templates, and Supabase backend.

Project Context

PSPG Requisitions is a Next.js 14 (App Router) internal platform for managing personnel requisitions for PSP Group. It features role-based access control (RBAC), dynamic form templates, session auditing, and a public-facing jobs portal.

**Tech Stack**: Next.js 14, TypeScript, Tailwind CSS, Supabase (Auth + PostgreSQL + Storage)

Step-by-Step Instructions

1. Understand the RBAC System

When working on features involving user permissions:

2. Implement Authentication Correctly

When handling user authentication:

3. Configure Supabase Integration

When setting up or debugging Supabase connections:

4. Work with Dynamic Form System

When creating or modifying form templates:

5. Implement Secure API Routes

When creating API endpoints:

```typescript

// Pattern for secure API routes

import { createClient } from '@supabase/supabase-js'

const adminClient = createClient(

process.env.NEXT_PUBLIC_SUPABASE_URL!,

process.env.SUPABASE_SERVICE_ROLE_KEY!

)

export async function POST(req: Request) {

// Extract and verify token

const token = req.headers.get('authorization')?.replace('Bearer ', '')

const { data: { user } } = await adminClient.auth.getUser(token)

// Validate user role

const { data: profile } = await adminClient

.from('profiles')

.select('*, roles(*)')

.eq('id', user.id)

.single()

if (!['admin', 'superadmin'].includes(profile.roles.name)) {

return NextResponse.json({ error: 'Forbidden' }, { status: 403 })

}

// Proceed with operation

}

```

6. Handle Client vs Server Components

When deciding component architecture:

7. Implement Toast Notifications

When providing user feedback:

```tsx

'use client'

import { useToast } from '@/lib/useToast'

function MyComponent() {

const { success, error, warning, info } = useToast()

const handleAction = async () => {

try {

await doSomething()

success('¡Operación exitosa!')

} catch (err) {

error('Error al procesar la solicitud')

}

}

}

```

8. Apply Custom Tailwind Styling

When styling components:

9. Handle Public vs Authenticated Routes

When implementing navigation:

10. Debug Common Issues

When troubleshooting:

Environment Setup

Required environment variables in `.env.local`:

```bash

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co

NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

SUPABASE_SERVICE_ROLE_KEY=eyJ... # Server-only, NEVER expose to client

ADMIN_SECRET=your-secret-here # For /api/admin endpoints

```

Run locally:

```bash

npm install

npm run dev # Starts on http://localhost:3000

```

Key Files Reference

Documentation Reference

Critical Constraints

1. **Security First**: Always validate user roles and permissions on the server side, regardless of frontend checks

2. **No Hardcoded Secrets**: Use environment variables for sensitive information (API keys, database URLs)

3. **No Unnecessary Documentation**: Do not create `.md` files unless explicitly requested by the user

4. **Service Role Protection**: Never expose `SUPABASE_SERVICE_ROLE_KEY` to client-side code

5. **RLS Enforcement**: Ensure Row Level Security policies are properly configured for all tables

6. **Session Management**: Respect 15-minute inactivity timeout configured in AuthProvider

7. **Type Safety**: Use TypeScript strictly - avoid `any` types

8. **Component Patterns**: Use specialized components (`PhoneInput`, `AvatarUpload`) instead of recreating functionality

Usage Examples

**Example 1: Adding a role-protected feature**

```tsx

import { RequireRoleClient } from '@/app/components/RequireRole'

function AdminDashboard() {

return (

<RequireRoleClient allow={['admin', 'superadmin']}>

<div className="admin-primary">

{/* Admin-only content */}

</div>

</RequireRoleClient>

)

}

```

**Example 2: Fetching active form template**

```typescript

import { getCompanyActiveTemplate } from '@/lib/templates'

const template = await getCompanyActiveTemplate(companyId)

if (!template) {

throw new Error('No active template found for this company')

}

// template.sections[] contains form structure

```

**Example 3: Using avatar upload**

```tsx

import AvatarUpload from '@/app/components/AvatarUpload'

<AvatarUpload

userId={user.id}

currentAvatar={user.avatar_url}

onUploadComplete={(url) => console.log('New avatar:', url)}

/>

```