User Activity Management System (Python/Flask)

A web application for viewing and managing user profiles and activity timelines, built with Python Flask, connected to an AWS PostgreSQL database.

This is the Python version of the original TypeScript/Angular application, with all features preserved.

---

📋 Table of Contents

• Overview
• Features
• Technology Stack
• Quick Start
• Step-by-Step Installation
• Configuration
• Using the Application
• Project Structure
• API Endpoints
• Troubleshooting
• Development Notes

---

Overview

The User Activity Management System provides a clean interface to:

• View all users from the database
• Search users by email, username, or first name
• View detailed activity timelines for each user, including:
  • Joined groups
  • Applied to groups
  • Created invites
  • Redeemed invites
  • Expressions
  • User posts

---

Features

🏠 Home Page

• Welcome page with system overview
• Quick navigation to main features

👥 All Users Page

• Display all users from the database
• Search functionality (email, username, first name)
• Quick access to view each user's timeline
• Displays user profiles with key information

📅 User Timeline Page

• Comprehensive activity timeline for each user
• 6 types of activities:
  • 👥 Joined Group (Green) - When user joins a group
  • 📝 Applied to Group (Blue) - Group applications with status
  • ✉️ Created Invite (Orange) - Invites created by the user
  • 🎟️ Redeemed Invite (Purple) - Invites redeemed by the user
  • 💭 Expression (Cyan) - User expressions (can exist without groups)
  • 📄 User Post (Pink) - Posts created by the user
• Chronological display with timestamps
• Color-coded activity types
• Group information (when applicable)

---

Technology Stack

• Backend: Python 3.8+ with Flask
• Frontend: HTML5, CSS3, JavaScript (Vanilla)
• Database: PostgreSQL (AWS RDS)
• API Communication: RESTful API with CORS enabled
• Icons: Font Awesome 6

---

Quick Start

Using Setup Scripts (Recommended)

On macOS/Linux:

# 1. Navigate to project directory
cd User-Interface-for-Group-Activity-Python

# 2. Run setup (one time only)
chmod +x setup.sh run.sh
./setup.sh

# 3. Kill any process using port 5000 (if needed)
lsof -ti:5000 | xargs kill -9 2>/dev/null || true

# 4. Run the application
./run.sh

# 5. Open browser to: http://localhost:5000

On Windows:

REM 1. Navigate to project directory
cd User-Interface-for-Group-Activity-Python

REM 2. Run setup (one time only)
setup.bat

REM 3. Kill any process using port 5000 (if needed)
REM Check what's using port 5000: netstat -ano | findstr :5000
REM Then kill it: taskkill /PID <PID> /F

REM 4. Run the application
run.bat

REM 5. Open browser to: http://localhost:5000

To stop the application: Press Ctrl + C in the terminal

Note about Port 5000:

• On macOS, AirPlay Receiver uses port 5000 by default
• Step 3 ensures the port is free before starting the application
• Alternative: Disable AirPlay Receiver in System Settings → General → AirDrop & Handoff

---

Step-by-Step Installation

Prerequisites

Before you begin, verify you have Python installed:

On macOS/Linux:

python3 --version

On Windows:

python --version

Required: Python 3.8 or higher

If Python is not installed:

• Download from: https://www.python.org/downloads/
• Important for Windows: Check "Add Python to PATH" during installation

---

Step 1: Navigate to Project Directory

cd User-Interface-for-Group-Activity-Python

Verify you're in the correct directory by checking for these files:

# On macOS/Linux
ls

# On Windows
dir

You should see: app.py, mock_data.py, requirements.txt, templates/, static/

---

Step 2: Create Virtual Environment

On macOS/Linux:

python3 -m venv venv

On Windows:

python -m venv venv

What this does: Creates an isolated Python environment in a folder called venv

---

Step 3: Activate Virtual Environment

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

How to verify: You should see (venv) at the beginning of your command prompt:

(venv) $

---

Step 4: Install Dependencies

On macOS/Linux:

pip3 install -r requirements.txt

On Windows:

pip install -r requirements.txt

Expected output:

Collecting Flask==3.0.0
Collecting Flask-Cors==4.0.0
Collecting psycopg2-binary==2.9.9
Collecting Werkzeug==3.0.1
...
Successfully installed Flask-3.0.0 Flask-Cors-4.0.0 psycopg2-binary-2.9.9 Werkzeug-3.0.1

This installs:

• Flask (web framework)
• Flask-CORS (CORS support)
• psycopg2-binary (PostgreSQL adapter)
• Werkzeug (WSGI utility library)

---

Step 5: Run the Application

On macOS/Linux:

python3 app.py

On Windows:

python app.py

Expected output:

If database connects successfully:

✅ Connected to AWS PostgreSQL database
Database: wander_app
Host: 3.20.185.35

🚀 Server starting on port 5000
📊 Using REAL AWS DATABASE

 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://0.0.0.0:5000

If database connection fails (this is OK!):

❌ Database connection failed: ...

⚠️  Using MOCK DATA mode
To connect to real database:
1. Connect to VPN if required
2. Verify AWS RDS security group allows your IP
3. Test connection with a PostgreSQL client

🚀 Server starting on port 5000
📊 Running in MOCK DATA mode

 * Running on http://0.0.0.0:5000

✅ Both scenarios are fine! The mock data mode lets you explore all features without a database connection.

---

Step 6: Open in Browser

1. Open your web browser (Chrome, Firefox, Safari, or Edge)
2. Navigate to: http://localhost:5000

You should see the home page with "User Activity Management System" heading and navigation bar.

---

Step 7: Stop the Application

When you're done:

1. Go to the terminal where the server is running
2. Press: Ctrl + C
3. (Optional) Deactivate virtual environment: deactivate

---

Configuration

Database Connection Setup

The application is configured to connect to an AWS PostgreSQL database by default.

To modify database credentials, edit app.py and update the DB_CONFIG dictionary:

DB_CONFIG = {
    'host': 'YOUR_DATABASE_HOST',
    'port': 5432,
    'database': 'YOUR_DATABASE_NAME',
    'user': 'YOUR_DATABASE_USERNAME',
    'password': 'YOUR_DATABASE_PASSWORD',
    'sslmode': 'require'
}

Important:

• Replace the placeholder values with your actual database credentials
• Keep the sslmode configuration for AWS RDS connections
• Do NOT commit your credentials to version control
• Consider using environment variables for production

Mock Data Mode

If the database connection fails, the application automatically falls back to mock data mode. This allows you to explore all features without a database connection.

The mock data includes:

• 5 sample users
• 7 sample groups
• Multiple activities of all 6 types

Mock data is defined in mock_data.py and can be customized as needed.

Database Schema

Your PostgreSQL database should have the following tables:

• users - User profiles
• groups - Group information
• group_members - Group membership records
• group_applications - Application records
• group_invite_codes - Invite codes created
• group_invite_redemptions - Invite redemption records
• expressions - User expressions
• user_post - User posts

---

Using the Application

Navigation

The application has three main pages accessible from the top navigation bar:

1. 🏠 Home - Landing page with overview
2. 👥 All Users - Browse and search users
3. 📅 User Timeline - View user activity timelines

---

1. Home Page

Access: http://localhost:5000 or http://localhost:5000/home

What you'll see:

• Welcome message
• System overview
• Feature list
• Database connection status
• Quick action buttons

Try:

• Click "View All Users" button to see user list
• Click "View User Timelines" button to search timelines

---

2. All Users Page

Access: Click "All Users" in navigation or go to http://localhost:5000/users

Features:

Viewing All Users

• When page loads, all users are displayed as cards
• Each card shows:
  • Username
  • Email
  • First Name
  • User Focus
  • Interests
  • Connection Type
  • Age Preference
  • Summary

Searching Users

By Email:

1. Enter email (or part of it) in the "Email" field
2. Click "Search"
3. Results filter to show matching users

Example: Type gmail.com to find all users with Gmail addresses

By Username:

1. Enter username (or part of it) in the "Username" field
2. Click "Search"
3. Results filter to show matching users

Example: Type sarah to find user "sarahsmith"

By First Name:

1. Enter first name (or part of it) in the "First Name" field
2. Click "Search"
3. Results filter to show matching users

Example: Type John to find all users named John

Show All Users:

• Click "Show All Users" button to reset and display all users

Viewing a User's Timeline

• Click the "View Timeline" button on any user card
• You'll be taken to that user's complete activity timeline

---

3. User Timeline Page

Access: Click "User Timeline" in navigation or go to http://localhost:5000/timeline

Features:

Method 1: Search for User

1. Enter search criteria in any of the fields:
   • Email (e.g., gaoyangyijun@gmail.com)
   • Username (e.g., johndoe)
   • First Name (e.g., John)
2. Click "Search Timeline"
3. User info appears at top
4. Timeline displays below with all activities

Method 2: Direct Link from Users Page

• Click "View Timeline" on any user card in the All Users page
• Timeline loads automatically

Understanding the Timeline

Activity Types and Colors:

👥 Joined Group (Green)

• When: User joins a group
• Shows: Group name, location, time, join date

📝 Applied to Group (Blue)

• When: User applies to join a group
• Shows: Group name, application status (pending/approved/rejected), decision date

✉️ Created Invite (Orange)

• When: User creates an invite code for a group
• Shows: Invite code, expiration date, number of times used

🎟️ Redeemed Invite (Purple)

• When: User redeems someone else's invite code
• Shows: Invite ID, redemption ID, group joined

💭 Expression (Cyan)

• When: User answers questions or shares thoughts
• Shows: Topic, AI question, user's answer, context
• Note: Can exist without being tied to a group

📄 User Post (Pink)

• When: User creates a post in a group
• Shows: Post content, group name, timestamps

Timeline Features:

• Activities are sorted chronologically (newest first)
• Each activity shows the exact timestamp
• Hover over activity cards for highlighting effect
• Scroll to see all activities

---

Example Usage Scenarios

Scenario 1: Find a User and View Their Activity

1. Go to "All Users" page
2. Search by email: gaoyangyijun@gmail.com
3. Click "View Timeline" on John Doe's card
4. See all his activities:
   • Groups he joined
   • Invites he created
   • Posts he made
   • His expressions

Scenario 2: Search Timeline Directly

1. Go to "User Timeline" page
2. Enter username: johndoe
3. Click "Search Timeline"
4. View his complete activity history

Scenario 3: Browse All Users

1. Go to "All Users" page
2. Scroll through user cards
3. Compare different users' profiles
4. View timelines of multiple users

---

Project Structure

User-Interface-for-Group-Activity-Python/
├── app.py                      # Main Flask application (backend)
├── mock_data.py                # Mock data for testing
├── requirements.txt            # Python dependencies
├── README.md                   # This file
├── .gitignore                  # Git ignore rules
├── setup.sh / setup.bat       # Setup scripts
├── run.sh / run.bat           # Run scripts
├── templates/                 # HTML templates (frontend)
│   ├── base.html             # Base template with navigation
│   ├── home.html             # Home page
│   ├── users.html            # All users page
│   └── timeline.html         # Timeline page
└── static/                   # Static files
    └── css/
        └── style.css         # Global styles

---

API Endpoints

The Flask backend provides the following RESTful API endpoints:

User Endpoints

Method	Endpoint	Description	Query Parameters
GET	/api/users	Get all users	None
GET	/api/users/search	Search users	query (search term), type (email/username/first_name)
GET	/api/users/<userId>/timeline	Get timeline for specific user	None
GET	/api/users/timeline/search	Search user timeline	email, username, first_name (at least one required)

Example API Requests

Get all users:

curl http://localhost:5000/api/users

Search users by email:

curl "http://localhost:5000/api/users/search?query=example@email.com&type=email"

Get user timeline:

curl http://localhost:5000/api/users/1/timeline

Search timeline by email:

curl "http://localhost:5000/api/users/timeline/search?email=gaoyangyijun@gmail.com"

---

Troubleshooting

Issue 1: Port 5000 Already in Use

Error: Address already in use

Solution:

On macOS/Linux:

lsof -ti:5000 | xargs kill -9
python3 app.py

On Windows:

netstat -ano | findstr :5000
taskkill /PID <PID> /F
python app.py

Replace <PID> with the actual process ID shown.

---

Issue 2: "python3: command not found" (macOS/Linux)

Solution: Try using python instead:

python --version
python -m venv venv
python app.py

---

Issue 3: "Module not found" Error

Error: ModuleNotFoundError: No module named 'flask'

Solution:

# Make sure virtual environment is activated
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# Reinstall dependencies
pip install -r requirements.txt

---

Issue 4: Virtual Environment Not Activating

Solution: Delete and recreate it:

On macOS/Linux:

rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt

On Windows:

rmdir /s venv
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

---

Issue 5: Database Connection Failed

Error: Database connection failed

This is OK! The application automatically switches to mock data mode.

Why it happens:

• Database server might be down
• Your IP might not be whitelisted in AWS Security Groups
• Network issues
• Incorrect credentials

To fix (optional):

1. Verify your database host is accessible
2. Check database credentials in app.py
3. Ensure your IP address is whitelisted in AWS Security Groups
4. Test connection using a PostgreSQL client (e.g., DBeaver)

To use mock data: No action needed - it's automatic!

---

Issue 6: Page Won't Load in Browser

Error: "Site can't be reached"

Check:

1. Is the server running? Look for "Running on http://0.0.0.0:5000" in terminal
2. Is the URL correct? Should be http://localhost:5000
3. Try http://127.0.0.1:5000 instead
4. Check if port 5000 is blocked by firewall

---

Issue 7: "Permission denied" (macOS/Linux)

Solution: Make scripts executable:

chmod +x setup.sh run.sh
./setup.sh

---

Issue 8: Users Don't Load / Search Returns Nothing

Solutions:

1. Refresh the page
2. Check browser console for errors (F12)
3. Check terminal for error messages
4. Verify server is running
5. Try clicking "Show All Users" button

---

Development Notes

Running in Development Mode

The application runs in debug mode by default:

app.run(debug=True, host='0.0.0.0', port=5000)

This enables:

• Auto-reload on code changes
• Detailed error messages
• Interactive debugger

For production, set debug=False

---

Customizing Mock Data

Edit mock_data.py to add more test users, groups, or activities:

mock_users = [
    {
        'user_id': '6',
        'username': 'newuser',
        'email': 'newuser@example.com',
        'first_name': 'New',
        # ... other fields
    }
]

---

Changing the Port

Edit app.py and change the port number:

app.run(debug=True, host='0.0.0.0', port=5001)  # Changed from 5000 to 5001

Then access at: http://localhost:5001

---

Environment Variables (Production)

For production deployment, use environment variables for sensitive data:

import os

DB_CONFIG = {
    'host': os.environ.get('DB_HOST'),
    'port': int(os.environ.get('DB_PORT', 5432)),
    'database': os.environ.get('DB_NAME'),
    'user': os.environ.get('DB_USER'),
    'password': os.environ.get('DB_PASSWORD'),
    'sslmode': 'require'
}

---

Production Deployment

For production use:

1. Use a production WSGI server:

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app

2. Set debug to False in app.py

3. Use environment variables for credentials

4. Set up reverse proxy (nginx or Apache)

5. Enable HTTPS

---

Browser Compatibility

Tested and working on:

• ✅ Chrome (recommended)
• ✅ Firefox
• ✅ Safari
• ✅ Edge

---

System Requirements

Minimum:

• Python 3.8 or higher
• 100 MB free disk space
• 512 MB RAM
• Any modern web browser

Recommended:

• Python 3.10 or higher
• 500 MB free disk space
• 1 GB RAM
• Chrome or Firefox browser

Operating Systems:

• ✅ macOS 10.14 or higher
• ✅ Windows 10 or higher
• ✅ Linux (Ubuntu 18.04+, Debian 10+, CentOS 7+, etc.)

---

Testing Checklist

After installation, verify these work:

• Server starts without errors
• Home page loads at http://localhost:5000
• Navigation bar is visible with 3 links
• "All Users" page shows user cards
• Email search works
• Username search works
• First name search works
• "View Timeline" button works
• Timeline displays colored activities
• All 6 activity types are visible
• Timeline search works
• Server stops cleanly with Ctrl+C

---

Quick Reference

Common Commands

Start Application:

# Automated
./run.sh              # macOS/Linux
run.bat               # Windows

# Manual
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows
python app.py

Stop Application:

Press Ctrl + C

Reinstall Everything:

# Delete virtual environment
rm -rf venv           # macOS/Linux
rmdir /s venv         # Windows

# Run setup again
./setup.sh            # macOS/Linux
setup.bat             # Windows

Access Application:

http://localhost:5000

---

Support

If you encounter issues not covered in this guide:

1. Check the terminal output - Error messages usually explain the problem
2. Review the Troubleshooting section above
3. Verify your Python version - Must be 3.8 or higher
4. Try the manual installation - Sometimes automated scripts have issues
5. Check port availability - Port 5000 must be free

---

Migration from TypeScript/Angular

This application is a complete Python/Flask port of the original TypeScript/Angular version. All features have been preserved:

What changed:

• Backend: Node.js/Express → Python/Flask
• Frontend: Angular → HTML/CSS/JavaScript (Vanilla)
• Port: 3000 → 5000

What stayed the same:

• ✅ All features and functionality
• ✅ User interface and design
• ✅ API endpoints (same structure)
• ✅ Database queries (identical SQL)
• ✅ 6 activity types with same colors

---

License

This project was created for educational purposes.

---

Success!

If you can:

• ✅ Start the server
• ✅ Open http://localhost:5000 in your browser
• ✅ See the home page
• ✅ Navigate between pages
• ✅ Search for users
• ✅ View timelines with colored activities

Congratulations! Your installation is complete and working! 🎉

Enjoy using the User Activity Management System!