🔧 Technical Documentation
Member Hub
Local Setup

Member Hub Local Development Setup

This guide walks through setting up the MyNATCA Member Hub for local development, including all required dependencies and integrations.

Prerequisites

Required Software

  • Node.js: Version 18 or higher
  • npm: Version 9 or higher (comes with Node.js)
  • Git: For version control
  • Code Editor: VS Code recommended with Vue and Volar extensions

Required Services

  • Platform API: Must be running on localhost:1300
  • Auth0 Account: For authentication configuration
  • Supabase Project: For database access

Recommended VS Code Extensions

  • Vue - Official (Vue.volar): Vue 3 language support
  • ESLint: Code linting
  • Prettier: Code formatting
  • TypeScript Vue Plugin (Volar): TypeScript support in Vue files

Initial Setup

1. Clone Repository

# Clone the repository
git clone https://github.com/mynatca/hub.git
cd hub
 
# Or if already in mynatca parent directory
cd /Users/jason/dev/mynatca/hub

2. Install Dependencies

# Install all dependencies
npm install
 
# Verify installation
npm list --depth=0

Expected output should include:

3. Configure Environment Variables

Create a .env.local file in the project root:

# Copy example environment file
cp .env.example .env.local
 
# Edit with your configuration
nano .env.local

Environment Configuration:

# .env.local
 
# Auth0 Configuration (Development)
VITE_AUTH0_DOMAIN=natca-dev.us.auth0.com
VITE_AUTH0_CLIENT_ID=your_auth0_client_id_here
VITE_AUTH0_AUDIENCE=https://platform.natca.org
VITE_AUTH0_REDIRECT_URI=http://localhost:1302/callback
 
# Supabase Configuration
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key_here
 
# API Configuration
VITE_API_URL=http://localhost:1300
 
# Feature Flags
VITE_ENABLE_RACKSPACE_EMAIL=true
 
# Development Settings
VITE_LOG_LEVEL=debug

4. Configure Auth0 Application

In your Auth0 dashboard:

  1. Create Application (if not exists):

    • Type: Single Page Application
    • Name: MyNATCA Hub - Development

  2. Configure Settings:

    • Allowed Callback URLs: http://localhost:1302/callback
    • Allowed Logout URLs: http://localhost:1302
    • Allowed Web Origins: http://localhost:1302
    • Allowed Origins (CORS): http://localhost:1302

  3. Copy Credentials:

    • Domain: natca-dev.us.auth0.com
    • Client ID: Copy to VITE_AUTH0_CLIENT_ID in .env.local

5. Verify Platform API

The Hub requires the Platform API running on port 1300:

# In a separate terminal, start Platform
cd /Users/jason/dev/mynatca/platform
npm run dev
 
# Verify Platform is running
curl http://localhost:1300/api/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2025-10-05T12:00:00.000Z"
}

Development Server

Start Development Server

# Start Hub development server
npm run dev

The Hub will start on http://localhost:1302 (opens in a new tab) (changed from 1301 to avoid port conflicts).

Expected output:

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:1302/
  ➜  Network: use --host to expose
  ➜  press h to show help

Development Workflow

Recommended Terminal Setup:

# Terminal 1: Platform API
cd /Users/jason/dev/mynatca/platform
npm run dev
# Runs on http://localhost:1300
 
# Terminal 2: Member Hub
cd /Users/jason/dev/mynatca/hub
npm run dev
# Runs on http://localhost:1302

Hot Module Replacement (HMR)

Vite provides instant updates without full page reload:

  • Vue Component Changes: Updates instantly
  • CSS/SCSS Changes: Updates instantly
  • TypeScript Changes: Type-checked and updated
  • Route Changes: Requires page refresh

Project Structure

hub/
├── src/
│   ├── components/          # Vue components
│   │   ├── dashboard/
│   │   │   ├── WelcomeCard.vue
│   │   │   └── RackspaceEmailCard.vue
│   │   └── common/
│   │       └── AppBar.vue
│   ├── pages/               # Route pages
│   │   ├── index.vue        # Dashboard (main page)
│   │   ├── login.vue        # Login page
│   │   └── callback.vue     # Auth callback
│   ├── services/            # API services
│   │   ├── rackspaceEmailService.ts
│   │   └── memberService.ts
│   ├── stores/              # Pinia state stores
│   │   ├── auth.ts
│   │   └── member.ts
│   ├── composables/         # Reusable composition functions
│   │   └── useAuth0.ts
│   ├── router/              # Vue Router config
│   │   └── index.ts
│   ├── styles/              # Global styles
│   │   └── main.scss
│   ├── plugins/             # Vue plugins
│   │   └── vuetify.ts
│   └── main.ts              # App entry point
├── vite.config.ts           # Vite configuration
├── package.json             # Dependencies and scripts
├── tsconfig.json            # TypeScript config
├── .env.local               # Local environment variables (git-ignored)
└── .env.example             # Environment template

Configuration Files

Vite Configuration

The vite.config.ts file configures the development server and build process:

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import vuetify from 'vite-plugin-vuetify';
import { fileURLToPath, URL } from 'node:url';
 
export default defineConfig({
  plugins: [
    vue(),
    vuetify({
      autoImport: true, // Auto-import Vuetify components
      styles: { configFile: 'src/styles/settings.scss' }
    })
  ],
 
  server: {
    port: 1302, // Changed from 1301 to avoid conflicts
    proxy: {
      '/api': {
        target: 'http://localhost:1300', // Platform API
        changeOrigin: true,
        secure: false,
        credentials: 'include', // Include cookies
        configure: (proxy, options) => {
          proxy.on('error', (err, req, res) => {
            console.log('Proxy error:', err);
          });
          proxy.on('proxyReq', (proxyReq, req, res) => {
            console.log('Proxying:', req.method, req.url);
          });
        }
      }
    }
  },
 
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
 
  build: {
    target: 'esnext',
    sourcemap: true
  }
});

Key Configuration:

  • Port 1302: Development server port (changed from 1301)
  • API Proxy: Routes /api/* to Platform on localhost:1300
  • Auto-import: Vuetify components imported automatically
  • Path Alias: @/ resolves to src/ directory

TypeScript Configuration

// tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "jsx": "preserve",
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "lib": ["ESNext", "DOM"],
    "skipLibCheck": true,
    "types": ["vite/client", "node"],
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ],
  "exclude": ["node_modules", "dist"]
}

Development Features

Rackspace Email Card

The new Rackspace Email Card allows members to manage @natca.net email addresses.

Location: /src/components/dashboard/RackspaceEmailCard.vue

Development Testing:

  1. Eligibility Check:

    • Test with membertypeid = 6 (eligible)
    • Test with other membertypeid (should hide card)
    • Test with Active status (eligible)
    • Test with Retired status (eligible)
    • Test with other status (should hide card)

  2. Email Availability:

  3. Email Creation:

    • Click available email option
    • Verify confirmation modal appears
    • Confirm creation
    • Verify API call to /api/rackspace/create-email
    • Verify one-time password display
    • Verify copy-to-clipboard functionality
    • Verify member store refresh

  4. Password Reset:

    • With existing email, click "Reset Password"
    • Verify confirmation modal with warning
    • Confirm reset
    • Verify API call to /api/rackspace/reset-password
    • Verify new password display

Testing API Proxy

The Vite dev server proxies all /api/* requests to Platform:

# Test proxy in browser console or terminal
 
# Health check (proxied to Platform)
curl http://localhost:1302/api/health
 
# Check email availability (requires authentication)
curl -X POST http://localhost:1302/api/rackspace/check-availability \
  -H "Content-Type: application/json" \
  -d '{"memberNumber":"12345"}' \
  --cookie-jar cookies.txt
 
# Create email (requires authentication)
curl -X POST http://localhost:1302/api/rackspace/create-email \
  -H "Content-Type: application/json" \
  -d '{"memberNumber":"12345","emailFormat":"jdoss"}' \
  -b cookies.txt

Vue Devtools

Install Vue Devtools browser extension for debugging:

  1. Chrome: Vue Devtools (opens in a new tab)
  2. Firefox: Vue Devtools (opens in a new tab)

Features:

  • Inspect component hierarchy
  • View Pinia store state
  • Track component events
  • View router state
  • Performance monitoring

Common Development Tasks

Adding New Component

# Create component file
touch src/components/dashboard/NewCard.vue
<!-- src/components/dashboard/NewCard.vue -->
<template>
  <v-card variant="tonal" class="mb-4">
    <v-card-title>New Feature</v-card-title>
    <v-card-text>
      {{ message }}
    </v-card-text>
  </v-card>
</template>
 
<script setup lang="ts">
import { ref } from 'vue';
 
const message = ref('Hello from new card!');
</script>

Adding New Service

# Create service file
touch src/services/newService.ts
// src/services/newService.ts
class NewService {
  private baseUrl = '/api/new';
 
  async getData(): Promise<any> {
    const response = await fetch(`${this.baseUrl}/data`, {
      credentials: 'include'
    });
 
    if (!response.ok) {
      throw new Error('Failed to fetch data');
    }
 
    return response.json();
  }
}
 
export const newService = new NewService();

Adding New Route

// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router';
 
const router = createRouter({
  history: createWebHistory(),
  routes: [
    // ... existing routes
    {
      path: '/new-page',
      name: 'newPage',
      component: () => import('@/pages/NewPage.vue'),
      meta: { requiresAuth: true }
    }
  ]
});

Debugging

Browser DevTools

// In browser console
 
// Check authentication state
const auth = useAuthStore();
console.log('Authenticated:', auth.isAuthenticated);
console.log('User:', auth.user);
 
// Check member data
const member = useMemberStore();
console.log('Member:', member.memberData);
 
// Test Rackspace service
import { rackspaceEmailService } from '@/services/rackspaceEmailService';
const result = await rackspaceEmailService.checkAvailability('12345');
console.log('Availability:', result);

Network Debugging

Monitor API calls in browser DevTools Network tab:

  1. Open DevTools (F12)
  2. Go to Network tab
  3. Filter by "api" to see proxied requests
  4. Check request/response headers
  5. Verify cookies are being sent

Console Logging

Add debug logging to components:

// In component setup
import { watch } from 'vue';
 
watch(availability, (newVal) => {
  console.log('Availability changed:', newVal);
});
 
watch(() => props.memberNumber, (newVal) => {
  console.log('Member number changed:', newVal);
}, { immediate: true });

Troubleshooting

Port Already in Use

Problem: Port 1302 is already in use

Solution:

# Find process using port 1302
lsof -i :1302
 
# Kill the process
kill -9 <PID>
 
# Or use a different port
npm run dev -- --port 1303

Proxy Connection Refused

Problem: API requests fail with connection refused

Solution:

  1. Verify Platform is running on port 1300
  2. Check Platform health: curl http://localhost:1300/api/health
  3. Verify proxy config in vite.config.ts
  4. Restart both Platform and Hub servers

Authentication Not Working

Problem: Login redirects to error page

Solution:

  1. Verify Auth0 callback URL: http://localhost:1302/callback
  2. Check Auth0 allowed origins: http://localhost:1302
  3. Verify .env.local has correct Auth0 credentials
  4. Check browser console for errors
  5. Verify Platform session management is working

Module Not Found

Problem: TypeScript/Import errors

Solution:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
 
# Clear Vite cache
rm -rf .vite
npm run dev

Vuetify Components Not Rendering

Problem: Vuetify components show as plain divs

Solution:

  1. Verify Vuetify plugin is loaded in main.ts
  2. Check vite.config.ts has vuetify plugin with autoImport
  3. Restart dev server
  4. Clear browser cache

Environment Variables Not Loading

Problem: import.meta.env.VITE_* returns undefined

Solution:

  1. Verify .env.local exists in project root
  2. Ensure variables start with VITE_ prefix
  3. Restart dev server (required after .env changes)
  4. Check for syntax errors in .env file

Testing

Manual Testing Checklist

  • Login flow works correctly
  • Dashboard loads after authentication
  • Rackspace Email Card displays for eligible members
  • Email availability check returns results
  • Email creation works and shows password
  • Password reset works and shows new password
  • Copy to clipboard functions work
  • Error messages display appropriately
  • Loading states show during API calls
  • Session persists across page refresh

API Testing

Use the following curl commands to test endpoints:

# Health check
curl http://localhost:1302/api/health
 
# Check session (after login)
curl http://localhost:1302/api/auth/session \
  -H "Cookie: platform.session=your_session_cookie"
 
# Check email availability
curl -X POST http://localhost:1302/api/rackspace/check-availability \
  -H "Content-Type: application/json" \
  -H "Cookie: platform.session=your_session_cookie" \
  -d '{"memberNumber":"12345"}'

Port Configuration

Important: The Hub development server runs on port 1302 (changed from 1301).

Port Change Summary

The port was changed in the following files:

  1. vite.config.ts:
server: {
  port: 1302, // Changed from 1301
  // ...
}
  1. package.json:
{
  "scripts": {
    "preview": "vite preview --port 1302" // Changed from 1301
  }
}

Why Port 1302?

Port 1302 was chosen to avoid conflicts with other MyNATCA ecosystem services:

  • Platform API: Port 1300
  • Discord Bot: Port 1301 (if applicable)
  • Member Hub: Port 1302

Next Steps

After completing local setup:

  1. Review Architecture: Read Hub Architecture to understand the codebase structure
  2. Explore Features: Test the Rackspace Email functionality
  3. Check Deployment Guide: Review Hub Deployment for production deployment
  4. Review Platform API: Familiarize yourself with Platform API endpoints

Related Documentation

Happy coding! The Hub development environment provides hot module replacement and instant feedback for rapid feature development.

ArchitectureDeployment