---
title: 'Multi-User Support'
description: 'Configure multi-user support with separate brokerage accounts'
---

## Overview

The application supports multiple users, each with their own brokerage account numbers and transaction data. Users authenticate via Google OAuth and can set up their brokerage account number in their profile.

## Database Schema Changes

### New Tables

#### `trading_analysis.users`
Stores user information from OAuth:

| Column | Type | Description |
|--------|------|-------------|
| `id` | Primary Key | User identifier |
| `email` | Unique | User email address |
| `name` | String | User's full name |
| `google_sub` | String | Google OAuth subject ID |
| `picture_url` | String | Profile picture URL |
| `brokerage_account_number` | String | User's primary account |
| `is_active` | Boolean | Account active status |
| `created_at` | Timestamp | Creation date |
| `updated_at` | Timestamp | Last update date |

#### `trading_analysis.brokerage_accounts`
Cross-reference table for account numbers:

| Column | Type | Description |
|--------|------|-------------|
| `id` | Primary Key | Account identifier |
| `account_number` | Unique | Brokerage account number |
| `account_display_name` | String | Optional friendly name |
| `user_id` | Foreign Key | Links to users table |
| `is_primary` | Boolean | Primary account flag |
| `created_at` | Timestamp | Creation date |
| `updated_at` | Timestamp | Last update date |

### Updated Tables

All existing tables have been updated with a `brokerage_account_id` foreign key:
- `raw_transactions`
- `matched_trades`
- `dividend_transactions`
- `monthly_trading_summary`
- `monthly_dividend_summary`
- `monthly_combined_summary`
- `processing_log`

## Migration Process

To migrate an existing database to support multiple users:

### Step 1: Run the Migration Script

```bash
python migrate_to_multiuser.py
```

### Step 2: Set Environment Variables (optional)

```bash
export DEFAULT_MIGRATION_EMAIL="your-admin@example.com"
export DEFAULT_MIGRATION_NAME="Admin User"
export DEFAULT_BROKERAGE_ACCOUNT="YOUR_ACCOUNT_NUMBER"
```

<Info>
  The migration script will create default values if these environment variables are not set.
</Info>

### What the Migration Does

<Steps>
  <Step title="Create new tables">
    Creates `users` and `brokerage_accounts` tables
  </Step>
  <Step title="Add foreign keys">
    Adds `brokerage_account_id` columns to existing tables
  </Step>
  <Step title="Create default user">
    Creates a default user and account for existing data
  </Step>
  <Step title="Update transactions">
    Updates all existing transactions to reference the default account
  </Step>
  <Step title="Recreate views">
    Recreates database views to work with the new schema
  </Step>
</Steps>

## Application Changes

### User Profile Management

<CardGroup cols={2}>
  <Card title="Profile Page" icon="user">
    Users can now set their brokerage account number in their profile
  </Card>
  <Card title="Account Validation" icon="check">
    CSV uploads require a valid brokerage account number
  </Card>
  <Card title="Multiple Accounts" icon="building-columns">
    Users can have multiple brokerage accounts (future feature)
  </Card>
  <Card title="Data Isolation" icon="lock">
    Users only see their own transaction data
  </Card>
</CardGroup>

### Upload Process

1. **User Validation**: Checks that user has a brokerage account before allowing uploads
2. **Account Association**: All uploaded transactions are associated with the user's account
3. **Processing**: Modified `trading_analysis.py` to accept `--account-id` parameter

### Authentication Flow

<Steps>
  <Step title="Login">
    User logs in via Google OAuth
  </Step>
  <Step title="User Creation">
    User record is created/updated in the database
  </Step>
  <Step title="Set Account">
    User sets their brokerage account number in profile
  </Step>
  <Step title="Link Account">
    Brokerage account record is created and linked to user
  </Step>
  <Step title="Upload Data">
    CSV uploads are associated with the user's account
  </Step>
</Steps>

## Database Queries

### User-Specific Data

All queries now need to filter by `brokerage_account_id`:

```sql
-- Get user's transactions
SELECT * FROM trading_analysis.raw_transactions rt
JOIN trading_analysis.brokerage_accounts ba ON rt.brokerage_account_id = ba.id
WHERE ba.user_id = ?;

-- Get user's trading performance
SELECT * FROM trading_analysis.v_trading_performance
WHERE user_email = 'user@example.com';
```

### Updated Views

Views now include user context:

- `v_current_positions` - Shows account and user information
- `v_trading_performance` - Includes user email and account number

## Configuration

### Environment Variables

```bash
# Migration Configuration
DEFAULT_MIGRATION_EMAIL=your-admin@example.com
DEFAULT_MIGRATION_NAME=Admin User
DEFAULT_BROKERAGE_ACCOUNT=YOUR_ACCOUNT_NUMBER

# OAuth Configuration (existing)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
AUTHORIZED_USERS=user1@example.com,user2@example.com
```

## Security Considerations

<Warning>
  User data isolation is critical for multi-user environments. Always verify queries filter by the correct account ID.
</Warning>

1. **User Isolation**: Users can only see their own transaction data
2. **Account Validation**: Brokerage account numbers are validated before processing
3. **OAuth Integration**: User authentication is handled by Google OAuth
4. **Data Protection**: User data is isolated by account ID in all database operations

## Future Enhancements

<CardGroup cols={2}>
  <Card title="Multiple Accounts" icon="layer-group">
    Support for users with multiple brokerage accounts
  </Card>
  <Card title="Account Sharing" icon="share-nodes">
    Allow users to share specific accounts with other users
  </Card>
  <Card title="Admin Interface" icon="user-shield">
    Administrative interface for managing users and accounts
  </Card>
  <Card title="Data Export" icon="download">
    User-specific data export functionality
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Migration Fails">
    - Ensure database connection is working
    - Verify you have proper permissions
    - Check for existing foreign key constraints
    - Review migration logs for specific errors
  </Accordion>
  
  <Accordion title="User Profile Issues">
    - Check that OAuth is configured correctly
    - Verify user email is in AUTHORIZED_USERS
    - Check application logs for authentication errors
  </Accordion>
  
  <Accordion title="Upload Failures">
    - Verify user has set brokerage account number in profile
    - Check CSV format matches expected schema
    - Review processing logs in `trading_analysis.log`
  </Accordion>
  
  <Accordion title="Data Not Showing">
    - Ensure queries are filtering by correct account ID
    - Verify user-account association is correct
    - Check database views are updated
  </Accordion>
</AccordionGroup>

### Database Verification

```sql
-- Check user-account associations
SELECT u.email, u.brokerage_account_number, ba.account_number, ba.is_primary
FROM trading_analysis.users u 
LEFT JOIN trading_analysis.brokerage_accounts ba ON u.id = ba.user_id;

-- Check transaction associations
SELECT COUNT(*) as transaction_count, ba.account_number, u.email
FROM trading_analysis.raw_transactions rt
JOIN trading_analysis.brokerage_accounts ba ON rt.brokerage_account_id = ba.id
JOIN trading_analysis.users u ON ba.user_id = u.id
GROUP BY ba.account_number, u.email;
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Portfolio Management" icon="chart-line" href="/features/portfolio-management">
    Set up portfolio tracking for your account
  </Card>
  <Card title="CSV Upload" icon="file-csv" href="/features/csv-upload">
    Learn how to upload transaction data
  </Card>
</CardGroup>