Re_Backend/docs/FRESH_DATABASE_SETUP.md

Fresh Database Setup Guide

🎯 Overview

This guide walks you through setting up a completely fresh database for the Royal Enfield Workflow Management System.

Use this when:

• First-time installation
• Major schema changes require full rebuild
• Moving to production environment
• Resetting development database

---

⚡ Quick Start (Automated)

Linux/Mac:

cd Re_Backend
chmod +x scripts/fresh-database-setup.sh
./scripts/fresh-database-setup.sh

Windows:

cd Re_Backend
scripts\fresh-database-setup.bat

The automated script will:

1. ✅ Drop existing database (with confirmation)
2. ✅ Create fresh database
3. ✅ Install PostgreSQL extensions
4. ✅ Run all migrations in order
5. ✅ Seed admin configuration
6. ✅ Verify database structure

---

📋 Manual Setup (Step-by-Step)

Prerequisites

# Check PostgreSQL
psql --version
# Required: PostgreSQL 16.x

# Check Redis
redis-cli ping
# Expected: PONG

# Check Node.js
node --version
# Required: 18.x or higher

# Configure environment
cp env.example .env
# Edit .env with your settings

---

Step 1: Drop Existing Database

# Connect to PostgreSQL
psql -U postgres

# Drop database if exists
DROP DATABASE IF EXISTS royal_enfield_workflow;

# Exit psql
\q

---

Step 2: Create Fresh Database

# Create new database
psql -U postgres -c "CREATE DATABASE royal_enfield_workflow OWNER postgres;"

# Verify
psql -U postgres -l | grep royal_enfield

---

Step 3: Install Extensions

psql -U postgres -d royal_enfield_workflow <<EOF
-- UUID extension
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- Text search
CREATE EXTENSION IF NOT EXISTS "pg_trgm";

-- JSONB operators
CREATE EXTENSION IF NOT EXISTS "btree_gin";
EOF

---

Step 4: Run Migrations

cd Re_Backend
npm install  # If not already done
npm run migrate

Expected Output:

✅ Migration: 2025103000-create-users.ts
✅ Migration: 2025103001-create-workflow-requests.ts
✅ Migration: 2025103002-create-approval-levels.ts
✅ Migration: 2025103003-create-participants.ts
✅ Migration: 2025103004-create-documents.ts
✅ Migration: 20251031_01_create_subscriptions.ts
✅ Migration: 20251031_02_create_activities.ts
✅ Migration: 20251031_03_create_work_notes.ts
✅ Migration: 20251031_04_create_work_note_attachments.ts
✅ Migration: 20251104-create-tat-alerts.ts
✅ Migration: 20251104-create-holidays.ts
✅ Migration: 20251104-create-admin-config.ts
✅ Migration: 20251111-create-conclusion-remarks.ts
✅ Migration: 20251111-create-notifications.ts

---

Step 5: Seed Admin Configuration

npm run seed:config

This creates default settings for:

• Email notifications
• TAT thresholds
• Business hours
• Holiday calendar
• AI provider settings

---

Step 6: Assign Admin User

Option A: Via SQL Script (Replace YOUR_EMAIL first)

# Edit the script
nano scripts/assign-admin-user.sql
# Change: YOUR_EMAIL@royalenfield.com

# Run it
psql -d royal_enfield_workflow -f scripts/assign-admin-user.sql

Option B: Via Direct SQL

psql -d royal_enfield_workflow

UPDATE users 
SET role = 'ADMIN'
WHERE email = 'your-email@royalenfield.com';

-- Verify
SELECT email, role FROM users WHERE role = 'ADMIN';

---

Step 7: Verify Setup

# Check all tables created
psql -d royal_enfield_workflow -c "\dt"

# Check user role enum
psql -d royal_enfield_workflow -c "\dT+ user_role_enum"

# Check your user
psql -d royal_enfield_workflow -c "SELECT email, role FROM users WHERE email = 'your-email@royalenfield.com';"

---

Step 8: Start Backend

npm run dev

Expected output:

🚀 Server started on port 5000
🗄️  Database connected
🔴 Redis connected
📡 WebSocket server ready

---

📊 Database Schema (Fresh Setup)

Tables Created (in order):

1. ✅ users - User accounts with RBAC (role field)
2. ✅ workflow_requests - Workflow requests
3. ✅ approval_levels - Approval workflow steps
4. ✅ participants - Request participants
5. ✅ documents - Document attachments
6. ✅ subscriptions - User notification preferences
7. ✅ activities - Audit trail
8. ✅ work_notes - Collaboration messages
9. ✅ work_note_attachments - Work note files
10. ✅ tat_alerts - TAT/SLA alerts
11. ✅ holidays - Holiday calendar
12. ✅ admin_config - System configuration
13. ✅ conclusion_remarks - AI-generated conclusions
14. ✅ notifications - Notification queue

---

🔑 User Roles (RBAC)

Default Role: USER

All new users automatically get USER role on first login.

Assign MANAGEMENT Role

-- Single user
UPDATE users SET role = 'MANAGEMENT' 
WHERE email = 'manager@royalenfield.com';

-- Multiple users
UPDATE users SET role = 'MANAGEMENT'
WHERE email IN (
  'manager1@royalenfield.com',
  'manager2@royalenfield.com'
);

-- By department
UPDATE users SET role = 'MANAGEMENT'
WHERE department = 'Management' AND is_active = true;

Assign ADMIN Role

-- Single user
UPDATE users SET role = 'ADMIN'
WHERE email = 'admin@royalenfield.com';

-- Multiple admins
UPDATE users SET role = 'ADMIN'
WHERE email IN (
  'admin1@royalenfield.com',
  'admin2@royalenfield.com'
);

-- By department
UPDATE users SET role = 'ADMIN'
WHERE department = 'IT' AND is_active = true;

---

🔍 Verification Queries

Check All Tables

SELECT tablename 
FROM pg_tables 
WHERE schemaname = 'public' 
ORDER BY tablename;

Check Role Distribution

SELECT 
  role,
  COUNT(*) as user_count,
  COUNT(CASE WHEN is_active = true THEN 1 END) as active_users
FROM users 
GROUP BY role
ORDER BY 
  CASE role
    WHEN 'ADMIN' THEN 1
    WHEN 'MANAGEMENT' THEN 2
    WHEN 'USER' THEN 3
  END;

Check Admin Users

SELECT 
  email,
  display_name,
  department,
  role,
  created_at,
  last_login
FROM users 
WHERE role = 'ADMIN' AND is_active = true
ORDER BY email;

Check Extended SSO Fields

SELECT 
  email,
  display_name,
  manager,
  job_title,
  postal_address,
  mobile_phone,
  array_length(ad_groups, 1) as ad_group_count
FROM users 
WHERE email = 'your-email@royalenfield.com';

---

🧪 Test Your Setup

1. Create Test User (via API)

curl -X POST http://localhost:5000/api/v1/auth/okta/callback \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@royalenfield.com",
    "displayName": "Test User",
    "oktaSub": "test-sub-123"
  }'

2. Check User Created with Default Role

SELECT email, role FROM users WHERE email = 'test@royalenfield.com';
-- Expected: role = 'USER'

3. Update to ADMIN

UPDATE users SET role = 'ADMIN' WHERE email = 'test@royalenfield.com';

4. Verify API Access

# Login and get token
curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "test@royalenfield.com", ...}'

# Try admin endpoint (should work if ADMIN role)
curl http://localhost:5000/api/v1/admin/configurations \
  -H "Authorization: Bearer YOUR_TOKEN"

---

📦 Migration Files (Execution Order)

Order	Migration File	Purpose
1	2025103000-create-users.ts	Users table with role + SSO fields
2	2025103001-create-workflow-requests.ts	Workflow requests
3	2025103002-create-approval-levels.ts	Approval levels
4	2025103003-create-participants.ts	Participants
5	2025103004-create-documents.ts	Documents
6	20251031_01_create_subscriptions.ts	Subscriptions
7	20251031_02_create_activities.ts	Activities/Audit trail
8	20251031_03_create_work_notes.ts	Work notes
9	20251031_04_create_work_note_attachments.ts	Work note attachments
10	20251104-create-tat-alerts.ts	TAT alerts
11	20251104-create-holidays.ts	Holidays
12	20251104-create-admin-config.ts	Admin configuration
13	20251111-create-conclusion-remarks.ts	Conclusion remarks
14	20251111-create-notifications.ts	Notifications

---

⚠️ Important Notes

is_admin Field REMOVED

❌ OLD (Don't use):

if (user.is_admin) { ... }

✅ NEW (Use this):

if (user.role === 'ADMIN') { ... }

Default Values

Field	Default Value	Notes
role	USER	Everyone starts as USER
is_active	true	Accounts active by default
All SSO fields	null	Optional, populated from Okta

Automatic Behaviors

• 🔄 First Login: User created with role=USER
• 🔒 Admin Assignment: Manual via SQL or API
• 📧 Email: Required and unique
• 🆔 oktaSub: Required and unique from SSO

---

🚨 Troubleshooting

Migration Fails

# Check which migrations ran
psql -d royal_enfield_workflow -c "SELECT * FROM SequelizeMeta ORDER BY name;"

# Rollback if needed
npm run migrate:undo

# Re-run
npm run migrate

User Not Created on Login

-- Check if user exists
SELECT * FROM users WHERE email = 'your-email@royalenfield.com';

-- Check Okta sub
SELECT * FROM users WHERE okta_sub = 'your-okta-sub';

Role Not Working

-- Verify role
SELECT email, role, is_active FROM users WHERE email = 'your-email@royalenfield.com';

-- Check role enum
\dT+ user_role_enum

---

📞 Quick Commands Reference

# Fresh setup (automated)
./scripts/fresh-database-setup.sh

# Make yourself admin
psql -d royal_enfield_workflow -c "UPDATE users SET role = 'ADMIN' WHERE email = 'your@email.com';"

# Check your role
psql -d royal_enfield_workflow -c "SELECT email, role FROM users WHERE email = 'your@email.com';"

# Start server
npm run dev

# Check logs
tail -f logs/application.log

---

✅ Success Checklist

• PostgreSQL 16.x installed
• Redis running
• .env configured
• Database created
• All migrations completed (14 tables)
• Admin config seeded
• At least one ADMIN user assigned
• Backend server starts without errors
• Can login and access admin endpoints

---

Your fresh database is now production-ready! 🎉