Development Workflow

Development Workflow

Prerequisites

Before starting development, ensure you have the following installed:

Required Software

• Node.js: Version 18 or higher

  • Check version: node --version
  • Download: https://nodejs.org/

• PostgreSQL: Version 14 or higher

  • Check version: psql --version
  • Download: https://www.postgresql.org/download/

• Git: For version control

  • Check version: git --version
  • Download: https://git-scm.com/downloads

• npm or yarn: Package manager (npm comes with Node.js)

Optional but Recommended

• PostGIS Extension: For geospatial features
• Prisma Studio: Database GUI (included with Prisma)
• VS Code: Recommended IDE with TypeScript support
• Docker: For containerized PostgreSQL (optional)

Initial Setup

1. Clone the Repository

git clone https://github.com/benmed00/research-platform.git
cd research-platform

2. Install Dependencies

npm install

This will:

• Install all npm packages
• Run postinstall script to generate Prisma client

3. Set Up Database

Create PostgreSQL Database

-- Connect to PostgreSQL
psql -U postgres

-- Create database
CREATE DATABASE research_platform;

-- (Optional) Install PostGIS extension
\c research_platform
CREATE EXTENSION IF NOT EXISTS postgis;

Configure Environment Variables

Create a .env file in the project root:

# Copy example if available, or create new
cp .env.example .env  # If example exists

Edit .env with your database credentials:

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/research_platform?schema=public"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key-here"

Generate NEXTAUTH_SECRET:

openssl rand -base64 32

4. Initialize Database

# Generate Prisma client
npm run db:generate

# Push schema to database (creates tables)
npm run db:push

# Seed database with initial data
npm run db:seed

Default Admin Credentials (after seeding):

• Email: admin@research-platform.ma
• Password: admin123

⚠️ Change the default password in production!

Development Commands

Start Development Server

npm run dev

The application will be available at:

• URL: http://localhost:3000
• Hot Reload: Enabled (changes auto-reload)

Build for Production

npm run build

Creates optimized production build in .next/ directory.

Start Production Server

npm run start

Runs production server (requires npm run build first).

Linting

npm run lint

Runs ESLint to check code quality and style.

Database Commands

Prisma Commands

# Generate Prisma client (after schema changes)
npm run db:generate

# Push schema changes to database
npm run db:push

# Create migration (recommended for production)
npm run db:migrate

# Open Prisma Studio (database GUI)
npm run db:studio

# Seed database
npm run db:seed

# Reset database (⚠️ deletes all data)
npm run db:reset

# Check database connection
npm run db:check

Database Workflow

During Development:

1. Modify prisma/schema.prisma
2. Run npm run db:push (quick, for development)
3. Test changes

For Production:

1. Modify prisma/schema.prisma
2. Run npm run db:migrate (creates migration file)
3. Review migration file
4. Apply migration to production database

Git Workflow

Update File Headers

Before committing, update file metadata headers:

npm run headers:update

This updates all TypeScript files with current metadata.

Create Feature Branch

npm run git:branch feature/your-feature-name

Or manually:

git checkout -b feature/your-feature-name

Create Commits

Automated (Recommended):

npm run git:commit-grouped

This automatically groups related changes into logical commits.

Manual:

git add .
git commit -m "feat: add new feature"

Follow Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• style: - Code style
• refactor: - Refactoring
• test: - Tests
• chore: - Maintenance

Push Branch

npm run git:push

Or manually:

git push -u origin feature/your-feature-name

Verify Git Setup

npm run git:verify

Checks Git configuration and setup.

Development Environment

Environment Variables

Development (.env):

DATABASE_URL="postgresql://user:pass@localhost:5432/research_platform"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="dev-secret-key"

Production (set in hosting platform):

• Use secure, randomly generated secrets
• Use production database URL
• Set NEXTAUTH_URL to production domain

TypeScript Configuration

Location: tsconfig.json

Key Settings:

• Strict mode enabled
• Path aliases: @/* → ./src/*
• ES2020 target
• Module resolution: bundler

Usage:

// Use path aliases
import { Button } from "@/components/ui/button"
import { prisma } from "@/lib/prisma"

Code Structure

Follow these patterns:

1. API Routes: src/app/api/[resource]/route.ts
2. Pages: src/app/dashboard/[module]/page.tsx
3. Components: src/components/[feature]/component.tsx
4. Utilities: src/lib/[utility].ts
5. Types: src/types/[types].ts

Testing Workflow

Manual Testing

1. Start development server: npm run dev
2. Open browser: http://localhost:3000
3. Test features: Navigate and test functionality
4. Check console: Browser and terminal for errors

Database Testing

Prisma Studio:

npm run db:studio

Opens GUI at http://localhost:5555

Direct Database Access:

psql -U username -d research_platform

API Testing

Using Browser:

• Navigate to API routes directly
• Check Network tab in DevTools

Using curl:

# Get missions (requires authentication)
curl http://localhost:3000/api/missions \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Common Development Tasks

Adding a New Module

1. Create database models in prisma/schema.prisma
2. Run migration: npm run db:push
3. Create API routes: src/app/api/[module]/route.ts
4. Create pages: src/app/dashboard/[module]/page.tsx
5. Create components: src/components/[module]/
6. Add validation: src/lib/validations.ts
7. Update navigation: src/components/layout/sidebar.tsx

Adding a New API Endpoint

1. Create route file: src/app/api/[resource]/route.ts
2. Implement handlers: GET, POST, PUT, DELETE
3. Add authentication: Use requireAuth() or requireAdmin()
4. Add validation: Use Zod schemas
5. Test endpoint: Use browser or API client

Adding a New Page

1. Create page file: src/app/dashboard/[module]/page.tsx
2. Fetch data: Use Prisma in Server Component
3. Create UI: Use components from src/components/
4. Add navigation: Update sidebar if needed
5. Test page: Navigate and verify functionality

Adding a New Component

1. Create component: src/components/[feature]/component.tsx
2. Use TypeScript: Define props interface
3. Style with Tailwind: Use utility classes
4. Export component: export default Component
5. Use in pages: Import and use component

Debugging

Common Issues

Database Connection Error:

• Check PostgreSQL is running
• Verify DATABASE_URL in .env
• Check database exists
• Verify credentials

Prisma Client Error:

npm run db:generate

Module Not Found:

rm -rf node_modules package-lock.json
npm install

TypeScript Errors:

• Check tsconfig.json configuration
• Verify imports use correct paths
• Run npm run lint for hints

Build Errors:

• Check for TypeScript errors
• Verify all imports are correct
• Check environment variables are set

Debug Tools

Browser DevTools:

• Console for JavaScript errors
• Network tab for API calls
• React DevTools for component inspection

Terminal:

• Next.js shows compilation errors
• Prisma shows database errors
• Check terminal output for details

Prisma Studio:

npm run db:studio

Visual database browser for debugging data issues.

Code Quality

Linting

Run linter:

npm run lint

Auto-fix (when possible):

npm run lint -- --fix

Code Style

Follow these conventions:

• Use 2 spaces for indentation
• Use single quotes for strings
• Add trailing commas
• Use semicolons
• Use TypeScript strict mode

ESLint Configuration: .eslintrc.json

File Headers

All TypeScript files should include metadata headers:

/**
 * @file filename.ts
 * @description Brief description
 * @author Author name
 * @created YYYY-MM-DD
 * @updated YYYY-MM-DD
 * @updates Count
 * @lines Line count
 * @size Size in KB
 */

Update headers:

npm run headers:update

Performance Optimization

Development Performance

• Fast Refresh: Enabled by default
• Incremental Compilation: TypeScript incremental builds
• SWC Minification: Faster than Babel

Database Performance

• Connection Pooling: Prisma handles automatically
• Query Optimization: Use select to fetch only needed fields
• Indexes: Already defined in schema
• Aggregations: Use groupBy instead of fetching all records

Build Optimization

• Code Splitting: Automatic by Next.js
• Tree Shaking: Automatic
• Image Optimization: Use Next.js Image component
• Bundle Analysis: Use @next/bundle-analyzer (if needed)

Deployment Preparation

Pre-Deployment Checklist

• All tests pass
• Linter passes (npm run lint)
• Build succeeds (npm run build)
• Environment variables configured
• Database migrations ready
• Default password changed
• Documentation updated

Production Build

# Build for production
npm run build

# Test production build locally
npm run start

Environment Variables (Production)

Set in hosting platform:

• DATABASE_URL: Production database
• NEXTAUTH_URL: Production domain
• NEXTAUTH_SECRET: Strong random secret

Useful Scripts Reference

# Development
npm run dev              # Start dev server
npm run build           # Build for production
npm run start           # Start production server
npm run lint            # Run linter

# Database
npm run db:generate     # Generate Prisma client
npm run db:push          # Push schema to database
npm run db:migrate       # Create migration
npm run db:studio        # Open Prisma Studio
npm run db:seed          # Seed database
npm run db:reset         # Reset database

# Git
npm run headers:update   # Update file headers
npm run git:branch       # Create feature branch
npm run git:commit-grouped # Create grouped commits
npm run git:push         # Push branch
npm run git:verify       # Verify Git setup

Getting Help

Documentation

• Project Docs: /docs directory
• Wiki: /wiki directory (this documentation)
• README: Root README.md

Resources

• Next.js Docs: https://nextjs.org/docs
• Prisma Docs: https://www.prisma.io/docs
• TypeScript Docs: https://www.typescriptlang.org/docs
• Tailwind Docs: https://tailwindcss.com/docs

Support

• GitHub Issues: Report bugs or request features
• Project Maintainers: Contact for questions

---

Follow this workflow to ensure consistent, high-quality development practices throughout the project.