Groups App

Overview

The Groups App (internally called TRIPS) is a full-featured group travel coordination platform. It lets Travel Tamers clients form groups around trip ideas, propose and vote on journey legs (flight segments, hotel stays, excursions), post threaded comments with image attachments, and ultimately export finalized itineraries to Slack channels.

Unlike the marketing site (static) or the API (JSON), this is a traditional server-rendered MPA using Express 5 with EJS templates and Bootstrap 5.3 for styling. The Gold (#E8B83D) and Navy (#0F2440) design system carries through with full dark mode support via a 3-way theme toggle (light/dark/system) using [data-theme="dark"] CSS custom properties.

Source of Truth: The Groups App owns all social data — posts, comments, votes, and images. The main TT-API handles contacts, deals, and bookings. Nexus consumes Groups data via the Service API for its social feed aggregation.

Tech Stack

Database Schema

The Groups App uses its own PostgreSQL database (groups_db) with 13 tables. All primary keys are UUIDs generated by gen_random_uuid(). Timestamps use TIMESTAMPTZ with auto-updating updated_at triggers. Migrations are raw SQL files tracked in a schema_migrations table.

Core Tables

Supporting Tables

Group Lifecycle

forming

New group created. Members can join, but quorum not yet met.

viable

Member count reaches min_members threshold. Auto-transitions when enough join.

planning

Owner advances status. Legs are finalized via voting, dates are set.

departed

Trip is underway. Can export to Slack channel for real-time coordination.

completed

Trip finished. Group becomes read-only archive.

Voting Modes: Groups support unanimous (all members must vote yes) or threshold (configurable percentage, default 66%). When all members have voted on a leg, the system auto-resolves it to approved or rejected.

Migrations

Routes & Endpoints

The app has 7 route files mounted in server.js. Page routes serve EJS templates; API routes return JSON. All state-changing routes require CSRF tokens (except /api/*).

Auth Routes /auth

Feed Routes /feed

Group Routes /groups

Group Management

Cover Images

Membership

Legs (Journey Segments)

Comments

User Routes /users

Notification Routes /notifications

JSON APIs

Session-Authenticated API

/api/*

Requires logged-in session. Used by client-side JavaScript.

• GET /api/groups — list user's + public groups
• GET /api/groups/:id — group detail with legs, members
• GET /api/stats — aggregate stats

Service API (Nexus Integration)

/api/service/*

Authenticated via X-Service-Token header (timing-safe comparison).

• GET /api/service/social-feed — aggregated activity feed
• GET /api/service/social-stats — engagement metrics
• GET /api/service/groups — all groups (no session)

Authentication & Security

The Groups App uses session-based authentication with PostgreSQL-backed session storage. No JWTs — this is a traditional server-rendered app where sessions are the correct pattern.

Session Management

• Store: connect-pg-simple persists sessions in PostgreSQL (survives server restarts)
• Cookie: connect.sid with httpOnly, secure (in production), sameSite: lax
• Secret: SESSION_SECRET env var (required, server exits without it)
• Session fixation: Sessions are regenerated on login and signup

Password Security

• Passwords hashed with bcryptjs (cost factor 10)
• Password reset tokens are cryptographically random, expire in 1 hour
• Reset endpoint rate-limited to 5 requests per 15 minutes per IP
• Reset response is always the same message (prevents email enumeration)

CSRF Protection

Every session gets a 32-byte random CSRF token stored in req.session.csrfToken. All POST/PUT/PATCH/DELETE requests must include the token as _csrf form field or X-CSRF-Token header. API routes (/api/*) are exempt since they use other auth mechanisms.

<!-- In every EJS form -->
<input type="hidden" name="_csrf" value="<%= csrfToken %>">

Rate Limiting

Role-Based Access

Group membership has three roles with escalating permissions:

UUID Validation: All :id route parameters are validated against a strict UUID regex pattern. Invalid UUIDs return 404 immediately, preventing injection attacks and database errors.

Views & Templates

The app uses EJS templates with express-ejs-layouts for layout inheritance. All templates live under trips/views/ with a clear hierarchy.

Template Structure

views/
  layouts/
    main.ejs            # Base HTML layout (head, navbar, flash, footer)
  pages/
    home.ejs            # Landing page with featured groups
    feed.ejs            # Browse groups with search/filter
    my-groups.ejs       # User's groups dashboard
    group-detail.ejs    # Full group view (legs, comments, viability)
    group-form.ejs      # Create/edit group form
    group-settings.ejs  # Unified settings (members, questions, invites)
    leg-form.ejs        # Propose a journey leg
    join-request.ejs    # Join request form with custom questions
    manage-requests.ejs # Approve/deny join requests
    manage-questions.ejs# Configure join questions
    profile.ejs         # User profile page
    profile-edit.ejs    # Edit profile form
    notifications.ejs   # Notification center
    auth/
      login.ejs         # Login form
      signup.ejs        # Registration form
      forgot-password.ejs
      reset-password.ejs
    errors/
      404.ejs           # Not found page
      500.ejs           # Server error page
  partials/
    navbar.ejs          # Top navigation bar
    footer.ejs          # Page footer
    flash.ejs           # Flash message display (success, error, info)
    group-card.ejs      # Group card component (used in feed)
    leg-card.ejs        # Leg card with vote counts
    comment-thread.ejs  # Threaded comment component
    viability-meter.ejs # Visual progress toward min_members

Template Helpers

Every template has access to these globally-injected helper functions:

Dark Mode & Accessibility (R11)

The Groups App now features a comprehensive dark mode implementation with a 3-way theme toggle in the navbar: light, dark, and system (follows OS preference). This replaced the earlier broken dark: Tailwind class approach.

Theme Mechanism

Gold Color Correction

The gold accent was corrected from #C9A84C to #E8B83D across 4 files for better contrast and visual consistency:

• routes/auth.js
• routes/groups.js
• utils/notify.js
• favicon.svg and hero-bg.svg

Accessibility Improvements

AI Image Generation

Group owners and admins can generate cover images using the Replicate FLUX API. The system builds a prompt from the group's name, destination, and description, then calls the FLUX model to create a travel-themed cover image.

Prompt Construction

buildCoverPrompt() combines group name, destination, and description into a structured prompt optimized for travel imagery.

Replicate API Call

The prompt is sent to the FLUX model on Replicate. Users can also provide a custom prompt override.

Image Downloaded & Saved

The generated image is downloaded and saved to public/uploads/group-covers/{groupId}.webp.

Database Updated

The group's cover_image_url is updated to the local path.

Fallback: If REPLICATE_API_TOKEN is not set, the generate-cover endpoint will return an error flash message. Groups use a default SVG cover (public/images/default-cover.svg) until a cover is generated or uploaded.

Users can also upload their own cover images, which are processed through sharp to resize (max 1200px wide) and convert to WebP at 85% quality.

SSH Tunnel (Local Development)

The Groups App's PostgreSQL database runs inside a Docker container on the VPS. For local development, you connect via an SSH tunnel that forwards a local port to the container's internal network address.

Architecture Detail

Local → VPS → Docker Network

# Open the SSH tunnel (runs in background)
ssh -f -N -L 5433:172.20.0.2:5432 vps

# Local port 5433 → VPS internal Docker network → PostgreSQL container
# DATABASE_URL=postgresql://user:pass@localhost:5433/groups_db

The tunnel maps local port 5433 to the PostgreSQL container at 172.20.0.2:5432 on the VPS Docker bridge network. This avoids exposing the database port publicly while allowing full local development.

Important: The SSH tunnel must be running before starting the dev server. If the tunnel drops, all database queries will fail. Use ssh -f -N to run it as a background process, or add it to your shell profile.

Development

Quick Start

# 1. Start SSH tunnel to VPS PostgreSQL
ssh -f -N -L 5433:172.20.0.2:5432 vps

# 2. Install dependencies
cd trips/
npm install

# 3. Run database migrations
npm run migrate

# 4. Seed sample data
npm run seed

# 5. Start dev server (nodemon with hot reload)
npm run dev
# App at http://localhost:3000

Available Commands

Project Structure

trips/
  server.js            # Express entry point (237 lines)
  config/
    db.js              # PostgreSQL pool configuration
    session.js         # Session middleware config
  routes/              # 7 route files
    auth.js            # Login, signup, password reset
    feed.js            # Group browsing and search
    groups.js          # Group CRUD, membership, legs, comments (1120 lines)
    users.js           # Profile management, avatar upload
    notifications.js   # Notification center
    api.js             # Session-authenticated JSON API
    serviceApi.js      # Service token API for Nexus
  controllers/         # Business logic (separated from routes)
  models/              # 10 database models
    User.js            # User CRUD, password hashing, reset tokens
    Group.js           # Group CRUD, viability checks, invite tokens
    Member.js          # Membership, roles, ownership transfer
    Leg.js             # Journey legs, voting lifecycle
    LegVote.js         # Vote casting, auto-resolution
    Comment.js         # Threaded comments with images
    Notification.js    # In-app notification system
    JoinRequest.js     # Membership request queue
    JoinQuestion.js    # Custom join questions
    Invitation.js      # Email invitation tracking
  middleware/
    auth.js            # requireAuth, optionalAuth, requireGroupRole
    validate.js        # express-validator rules for forms
    upload.js          # multer config for covers, comments, avatars
    errorHandler.js    # 404 and 500 error handlers
    validateUUID.js    # UUID format validation
  utils/
    flash.js           # Flash message helpers
    helpers.js         # Date formatting, truncation, sanitization
    email.js           # Email sending utility
    flux.js            # Replicate FLUX API integration
    notify.js          # In-app notification dispatch
    slack.js           # Slack API (channel export, user lookup)
    groupsSync.js      # Sync events to TT-API (member joins/leaves)
  views/               # 27 EJS templates
  public/
    css/style.css      # Custom Gold/Navy design system + dark mode via [data-theme="dark"] CSS custom properties
    css/tailwind.css   # Generated Tailwind output
    js/app.js          # Client-side JavaScript
  migrations/          # 17 SQL migration files
  seeds/               # Database seed scripts
  tests/               # Jest test files

Environment Variables

Testing

The Groups App has a comprehensive Jest test suite with 130 tests covering authentication flows, group operations, membership, voting, comments, and API endpoints. Tests use Supertest for HTTP-level integration testing.

Running Tests

# Run the full test suite
npm test

# Run a specific test file
npm test -- tests/setup.test.js

# Jest flags used:
#   --runInBand       (sequential execution, avoids DB conflicts)
#   --detectOpenHandles (identify leaking connections)
#   --forceExit       (exit after tests complete)

CSRF Test Helper

Tests that perform state-changing operations need a valid CSRF token. The test suite includes a helper at tests/helpers/csrf.js that extracts the CSRF token from a GET request and includes it in subsequent POST requests.

// tests/helpers/csrf.js pattern
const agent = supertest.agent(app);
// 1. GET a page to establish session + get CSRF token
const res = await agent.get('/auth/login');
const csrfToken = extractCsrf(res.text);
// 2. Include token in POST
await agent.post('/auth/login')
  .send({ email, password, _csrf: csrfToken });

Never bypass CSRF in tests. The test suite uses the real CSRF middleware to ensure security is validated end-to-end. If a test fails on CSRF, fix the test helper, not the middleware.

Deployment

The Groups App runs as a Docker container on the VPS behind Traefik, serving groups.traveltamers.com. The Dockerfile uses Node 20 with a non-root user for security.

Deployment Pipeline

Code pushed or manual deploy

Changes pushed to main branch or manual SSH deployment to VPS.

Files synced to VPS

Code deployed to /opt/groups-by-travel-tamers/ on the VPS.

Docker rebuild

Docker image rebuilt with Node 20, non-root user. Dependencies installed in container.

Migrations run

Pending SQL migrations applied to groups_db via the migration runner.

Health check verified

GET /health returns {"status":"ok","app":"groups"}. Health endpoint is before session middleware, so it requires no auth.

Production Infrastructure

# Docker container: groups
# Serves: groups.traveltamers.com
# Port: 3000 (internal)
# VPS path: /opt/groups-by-travel-tamers/
# Database: groups_db (PostgreSQL 16 in Docker)
# Traefik handles:
#   - SSL termination (Let's Encrypt)
#   - HTTP → HTTPS redirect
#   - Host-based routing

Health Endpoint

The /health route is mounted before session and CSRF middleware, so it can be called by monitoring tools without authentication:

// Response: 200 OK
{
  "status": "ok",
  "app": "groups",
  "timestamp": 1710000000000
}

Monitoring: The VPS health check script runs every 5 minutes via cron and alerts the #monitoring Slack channel if the Groups App health endpoint fails. Manual rollback is available by SSH-ing to the VPS and restarting with the previous Docker image.