GETTING_STARTED.md

Getting Started Checklist

Complete list of steps to get the Restricted Email Blocklist system up and running.

✅ Phase 1: Prerequisites (5 min)

• Node.js 18+ installed (node --version)
• PostgreSQL 12+ installed and running
• Terminal/Command prompt available
• Code editor open with the project

✅ Phase 2: Database Setup (3 min)

# 1. Verify PostgreSQL is running
pg_isready

# 2. Create database (if not exists)
createdb restricted_emails_db

# 3. Note: Migrations will create all tables automatically

Status: ✓ Database ready

✅ Phase 3: Backend Setup (3 min)

# 1. Navigate to backend
cd backend

# 2. Install dependencies
npm install

# 3. Create environment file
cp .env.example .env

# 4. Run database migrations (creates tables + seed data)
npm run db:migrate

# 5. Start backend server
npm run dev

Check: Backend should log "✓ Server running on http://localhost:3000"

Status: ✓ Backend running

✅ Phase 4: Frontend Setup (2 min)

# 1. Open NEW TERMINAL (keep backend running)
cd frontend

# 2. Install dependencies
npm install

# 3. Start frontend dev server
npm run dev

Check: Frontend should log "http://localhost:3001"

Status: ✓ Frontend running

✅ Phase 5: Verify Everything Works (2 min)

1. Open Browser

   • Visit: http://localhost:3001
   • Should see: Dark dashboard titled "Restricted Email Blocklist"

2. Click "Add Entry"

   • Pattern: testemail
   • Type: Exact Match
   • Click Create
   • Should appear in table

3. Test API

   curl http://localhost:3000/api/blocklist | head -20

   • Should return JSON with entries

4. Test Validation

   curl -X POST http://localhost:3000/api/blocklist/validate \
     -H "Content-Type: application/json" \
     -d '{"email":"testemail@example.com"}'

   • Should return "isBlocked": true

Status: ✓ System fully functional

---

🎯 Try These Examples

Example 1: Block All Admins

1. Click "Add Entry"
2. Pattern: admin
3. Type: Exact Match
4. Click Create
5. Try validating: curl ... testemail admin@example.com
6. Response: "isBlocked": true

Example 2: Block a Domain

1. Click "Add Entry"
2. Pattern: blocked.com
3. Type: Domain
4. Click Create
5. Notice you can select "All Domains" or specific domains

Example 3: Bulk Import

1. Click "Bulk Import"
2. Click "Load Template"
3. Add more lines with different patterns
4. Click "Import"
5. See all entries added to table

Example 4: Export CSV

1. Click "Export CSV"
2. File downloads as restricted-emails-<timestamp>.csv
3. Can re-import later

---

📝 Quick API Tests

List all entries:

curl http://localhost:3000/api/blocklist?pageSize=5

Get single entry:

curl http://localhost:3000/api/blocklist/{entry-id}

Create entry:

curl -X POST http://localhost:3000/api/blocklist \
  -H "Content-Type: application/json" \
  -d '{"pattern":"test","type":"exact","reason":"Test"}'

Validate email:

curl -X POST http://localhost:3000/api/blocklist/validate \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'

View audit log:

curl http://localhost:3000/api/blocklist/audit/all

---

🧪 Run Tests

cd backend

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test file
npm test -- emailBlocklist.test.ts

---

🔧 Stop All Services

# Stop backend: Ctrl+C in backend terminal
# Stop frontend: Ctrl+C in frontend terminal
# Stop PostgreSQL: brew services stop postgresql@15

---

🚀 Next: Integration with Your App

See register-example.ts for complete example code showing:

1. How to import the blocklist service
2. How to check if email is blocked
3. How to return proper error messages
4. How to log blocked attempts

Key code snippet:

const blockCheck = await blocklistService.isEmailBlocked(email);
if (blockCheck.isBlocked) {
  return res.status(403).json({
    error: blockCheck.reason || 'Email is restricted'
  });
}

---

📚 Documentation Files

File	Purpose
QUICKSTART.md	Fast setup guide (you are here)
README.md	Complete documentation
DEPLOYMENT.md	Production deployment guide
PROJECT_STRUCTURE.md	Detailed file organization

---

🎓 Learning Path

1. Get it running ← You are here
2. Try the examples above
3. Read the full API docs in README.md
4. Review integration code in register-example.ts
5. Deploy to production using DEPLOYMENT.md

---

🆘 Common Issues & Solutions

Issue	Solution
"PostgreSQL not running"	brew services start postgresql@15
"Port 3000 in use"	Change PORT in .env or kill process: lsof -i :3000 | kill...
"Database doesn't exist"	Run: npm run db:migrate
"Module not found"	Run: npm install in both folders
"CORS error in frontend"	Ensure backend is running on :3000
"Can't connect to database"	Check .env credentials, PostgreSQL running

---

✨ Dashboard Tips

• Search: Type in search box to filter by pattern
• Filter Type: Select Exact/Domain/Regex from dropdown
• Filter Domain: Enter domain name to show only rules for that domain
• Sort: Click table headers (when implemented)
• Edit: Click pencil icon on row
• Delete: Click trash icon on row (with confirmation)
• Pagination: Use Previous/Next buttons at bottom

---

🔐 Security Notes for Development

⚠️ These files are for development ONLY:

• .env - Contains local database credentials
• NODE_ENV=development - Enables verbose logging
• Default CORS opens to http://localhost:3001

For production, see DEPLOYMENT.md with hardening steps.

---

✅ You're Good to Go!

You now have a fully functional Restricted Email Blocklist system:

• ✅ Admin dashboard
• ✅ REST API
• ✅ Email validation
• ✅ Audit logging
• ✅ Bulk operations
• ✅ Multi-domain support

Next Step: Integrate with your registration endpoint using the code example, then deploy to production!

---

For more details, see README.md →