Empower Social 🌟

Less Scrolling. More Living.

A personalized event recommendation engine that uses psychology-backed assessments to match users with meaningful real-world activities and communities.

📖 Table of Contents

Overview
Features
Tech Stack
Project Structure
Getting Started
Key Documentation
Recent Updates
Development

🎯 Overview

Empower Social is a web application that helps people find events, activities, and communities that match their personality, motivations, and social needs—not just their interests. By combining validated psychological assessments (TIPI for Big Five traits, Situational Motivation Scale) with AI-powered recommendation generation, Empower provides personalized suggestions that truly resonate.

How It Works

User completes a 7-page intake survey (~5 minutes)
- Demographics and location
- Personality assessment (Big Five traits)
- Social connection metrics
- Core motivations
- Interest categories and specific activities
- Activity preferences and affinity groups
Backend processes and calculates scores
- Personality dimensions (Extraversion, Conscientiousness, Openness)
- Social need scoring (prioritizes community for isolated users)
- Motivation factors (Intrinsic, Social, Achievement)
AI generates personalized recommendations
- GPT-4-turbo creates conceptual activity recommendations
- Recommendations consider personality fit, social needs, motivations, and practical constraints
- Cached for performance, regenerated on profile updates
User views and manages recommendations
- Card-based display with personalized explanations
- Ability to regenerate recommendations
- Edit profile/survey to update preferences

✨ Features

Core Functionality ✅

Comprehensive intake survey (7 pages, ~5 minutes)
Psychology-backed assessments
- TIPI (Ten-Item Personality Inventory) for Big Five traits
- Situational Motivation Scale for core motivations
Smart score calculation (automated via Airtable formulas)
AI-powered recommendations (GPT-4-turbo with personalized prompts)
User authentication (email-based login for returning users)
Profile editing (update survey responses and regenerate recommendations)
Recommendation regeneration (bypasses cache for fresh results)
Responsive design (mobile-friendly UI)

Data Management ✅

Airtable integration (cloud-based database)
- Users table
- Survey_Responses table
- Calculated_Scores table (formula fields)
- GPT_Prompts table (audit trail)
Data validation (frontend and backend)
Empty field handling (proper cleanup for optional fields)
Multi-select field support (interests, affinity groups)

Code Quality ✅

ESLint configuration (code style enforcement)
Pre-commit hooks (Husky for linting before commits)
Error handling (comprehensive try-catch blocks)
Logging (structured error and info logs)

🛠 Tech Stack

Frontend

Vanilla HTML/CSS/JavaScript (no frameworks)
Responsive CSS (mobile-first design)
Modern typography (Montserrat + DM Sans)

Backend

Node.js (v14+)
Express.js (RESTful API)
Airtable API (database)
OpenAI API (GPT-4-turbo for recommendations)

Database

Airtable (cloud-based relational database)
- Linked records for relationships
- Formula fields for automatic calculations
- Lookup fields for data aggregation

Deployment

AWS Amplify (hosting and auto-deployment)
GitHub (version control and CI/CD)

Development Tools

ESLint (code linting)
Husky (Git hooks)
npm (package management)
Playwright (end-to-end testing)

📁 Project Structure

Empower-Social/
├── backend/
│   ├── routes/
│   │   ├── login.js              # User authentication
│   │   ├── recommendations.js    # Recommendation endpoints
│   │   └── survey.js             # Survey submission/retrieval
│   ├── services/
│   │   ├── airtable.js           # Airtable database operations
│   │   ├── openai-conceptual.js  # GPT prompt generation
│   │   ├── recommendations-v2.js # Recommendation generation logic
│   │   └── events.js             # Event-related utilities
│   ├── scripts/                  # Utility scripts
│   └── server.js                 # Express server entry point
│
├── frontend/
│   ├── assets/
│   │   ├── css/                  # Stylesheets
│   │   └── js/
│   │       └── recommendations.js # Frontend recommendation logic
│   ├── profile/
│   │   ├── login.html            # Login page
│   │   └── recommendations.html  # Recommendations display
│   ├── survey/
│   │   └── intake-survey.html    # Main survey form
│   ├── config.js                 # Frontend configuration
│   └── index.html                # Landing page
│
├── docs/
│   ├── SURVEY_FIELDS_REFERENCE.md    # Complete survey field documentation
│   ├── GPT_PROMPT_TEMPLATE.md        # GPT prompt structure
│   ├── AIRTABLE_SETUP_GUIDE.md       # Database setup instructions
│   ├── API_SETUP_GUIDE.md            # API key configuration
│   ├── AMPLIFY_SETUP.md              # Deployment guide
│   ├── EMPOWER_SYSTEM_GUIDE.md       # System overview
│   └── RECOMMENDATION_SYSTEM_DEVELOPMENT.md  # Development documentation
│
├── tests/
│   ├── config.spec.js            # Configuration tests
│   ├── welcome-page.spec.js      # Landing page tests
│   ├── survey-flow.spec.js       # Survey flow tests
│   ├── recommendations-page.spec.js  # Recommendations tests
│   ├── login-flow.spec.js        # Login tests
│   ├── integration-flow.spec.js  # End-to-end tests
│   ├── accessibility.spec.js      # Accessibility tests
│   └── README.md                 # Test documentation
│
├── package.json                  # Root package.json (ESLint, Husky, Playwright)
├── playwright.config.js          # Playwright test configuration
├── .eslintrc.json               # ESLint configuration
├── .husky/                      # Git hooks
└── README.md                    # This file

🚀 Getting Started

Prerequisites

Node.js (v14 or higher)
npm (comes with Node.js)
Airtable account and API key
OpenAI API key
AWS Amplify account (for deployment)

Installation

Clone the repository

git clone https://github.com/empowersocialapp/Empower-Social-2.git
cd Empower-Social

Install backend dependencies
```
cd backend
npm install
```
Install root dependencies (for ESLint/Husky)
```
cd ..
npm install
```

Set up environment variables

Create backend/.env file:

AIRTABLE_API_KEY=your_airtable_api_key
AIRTABLE_BASE_ID=your_base_id
OPENAI_API_KEY=your_openai_api_key
PORT=3000

Set up Airtable database

See docs/AIRTABLE_SETUP_GUIDE.md for detailed instructions on:
- Creating tables (Users, Survey_Responses, Calculated_Scores, GPT_Prompts)
- Setting up fields and formulas
- Configuring linked records
Start the backend server
```
cd backend
npm start
```

Open the frontend

Open frontend/index.html in your browser, or serve it via a local server:

# Using Python
cd frontend
python -m http.server 8000

# Or using Node.js http-server
npx http-server frontend -p 8000

Configuration

Frontend API endpoint: Edit frontend/config.js to point to your backend URL
Backend CORS: Configure in backend/server.js if needed
Airtable field names: Must match exactly as specified in docs/SURVEY_FIELDS_REFERENCE.md

📚 Key Documentation

For Developers

Survey Fields Reference - Complete technical specification of all survey fields, calculations, and data handling
GPT Prompt Template - Structure and examples of GPT prompts used for recommendations
Airtable Setup Guide - Step-by-step database setup instructions
API Setup Guide - Configuration for Airtable and OpenAI APIs
Amplify Setup - Deployment instructions for AWS Amplify

For Understanding the System

Empower System Guide - High-level overview of how the system works
Cursor Context - Project context for AI assistants
Backend Verification - Backend testing and verification

🔄 Recent Updates

December 2025

✅ Added Playwright test suite - Comprehensive end-to-end testing with 108 tests across 3 browsers
✅ Added configuration tests - Tests for config.js environment detection and API setup
✅ Added descriptive file headers - All code files now include comprehensive headers documenting purpose, inputs, outputs, and dependencies
✅ Improved code documentation - Enhanced inline comments throughout codebase
✅ Updated documentation - README and docs updated to reflect current project state

November 2025

✅ Fixed recommendation caching - Recommendations now properly regenerate when users edit their profiles
✅ Fixed data saving issues - Close friends count, free time, travel distance, and affinity selections now save correctly
✅ Fixed interests auto-select - Interests no longer reset to all selected when editing survey
✅ Improved navigation - Standardized all navigation paths to use absolute paths for AWS Amplify compatibility
✅ Fixed JavaScript errors - Converted inline onclick handlers to event listeners, fixed syntax errors
✅ Added code quality tools - ESLint configuration and pre-commit hooks (Husky)
✅ Created comprehensive documentation - Survey fields reference document for technical specifications
✅ Added recommendation feedback system - Users can evaluate recommendations (Interested/Maybe/Not for Me)
✅ Added evaluation summary - Summary appears after all recommendations are evaluated

Key Bug Fixes

Cache invalidation: Recommendations now bypass cache on regenerate/edit
Empty field handling: Proper cleanup of empty strings and arrays
Multi-select preservation: Empty arrays preserved for Airtable multi-select fields
Event listener migration: All buttons now use event listeners instead of inline handlers
Path standardization: All navigation uses absolute paths (/path/to/file.html)

💻 Development

Code Style

Indentation: 2 spaces
Semicolons: Required
Quotes: Single quotes preferred
Trailing spaces: Not allowed
ESLint: Run npm run lint to check, npm run lint:fix to auto-fix

Git Workflow

Pre-commit hook runs ESLint automatically
Commit messages should be descriptive
Push to main branch triggers AWS Amplify deployment

Testing

Automated Tests (Playwright):

# Run all tests
npm test

# Run tests in UI mode (interactive)
npm run test:ui

# Run specific test file
npx playwright test tests/config.spec.js

Test Coverage:

✅ Configuration tests (config.spec.js) - API configuration and environment detection
✅ Welcome page tests (welcome-page.spec.js) - Landing page functionality
✅ Survey flow tests (survey-flow.spec.js) - Complete survey journey
✅ Recommendations tests (recommendations-page.spec.js) - Recommendation display and interaction
✅ Login flow tests (login-flow.spec.js) - User authentication
✅ Integration tests (integration-flow.spec.js) - End-to-end user journeys
✅ Accessibility tests (accessibility.spec.js) - WCAG compliance

Manual Testing:

Test survey submission: Fill out all 7 pages and verify data saves correctly
Test recommendation generation: Verify recommendations appear after submission
Test profile editing: Edit survey and verify recommendations regenerate
Test login: Use username to login as returning user
Test empty fields: Submit survey with optional fields empty
Test feedback buttons: Evaluate recommendations (Interested/Maybe/Not for Me)

Debugging

Backend logs: Check backend.log or console output
Frontend console: Check browser developer console for JavaScript errors
Airtable: Verify records are created correctly in Airtable UI
API responses: Check network tab in browser dev tools

📝 License

See LICENSE file for details.

🤝 Contributing

This is a private repository. For questions or issues, contact the project maintainer.

📧 Support

For technical questions or issues:

Check the documentation in the docs/ folder
Review docs/SURVEY_FIELDS_REFERENCE.md for data handling questions
Check docs/GPT_PROMPT_TEMPLATE.md for recommendation generation questions

Last Updated: December 2025
Version: 1.1.0

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.husky		.husky
backend		backend
docs		docs
frontend		frontend
tests		tests
.env.example		.env.example
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
BACKEND_VERIFICATION.md		BACKEND_VERIFICATION.md
CURSOR_CONTEXT.md		CURSOR_CONTEXT.md
LICENSE		LICENSE
README.md		README.md
amplify.yml		amplify.yml
package-lock.json		package-lock.json
package.json		package.json
playwright.config.js		playwright.config.js

License

empowersocialapp/Empower-Social-2

Folders and files

Latest commit

History

Repository files navigation