> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cfosilvia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SNAPTRADE TYPE MIGRATION

# SnapTrade Account Type Migration

## Overview

Migrating SnapTrade accounts to use Plaid-style `type` + `subtype` columns for consistent UX across all account sources, while maintaining backward compatibility with existing `account_type` column.

## Strategy: Dual-Column Approach (Zero Breaking Changes)

### Database Schema

```sql theme={null}
-- EXISTING (keep as-is for backward compatibility):
account_type TEXT          -- "401K", "IRA", "I", etc.
source_account_type TEXT   -- Original from SnapTrade

-- NEW (add for Plaid-style categorization):
type TEXT                  -- "investment", "depository", etc.
subtype TEXT              -- "401k", "ira", "brokerage", etc.
source_type TEXT          -- Original Plaid-style type
source_subtype TEXT       -- Original Plaid-style subtype
```

### How It Works

#### On Account Creation (process-connection/route.ts)

```typescript theme={null}
// Set BOTH old and new columns
{
  account_type: "401K",              // Old (backward compat)
  source_account_type: "401K",       // Old source
  type: "investment",                // New
  subtype: "401k",                   // New
  source_type: "investment",         // New source
  source_subtype: "401k"             // New source
}
```

#### On Account Update (update-type/route.ts)

```typescript theme={null}
// Update BOTH when user changes type
{
  type: "investment",
  subtype: "401k",
  account_type: "401k"  // Keep this synced for old code
}
```

#### In UI (accounts/page.tsx)

```typescript theme={null}
// Read from new columns (with fallback to old)
const type = account.type || mappedFromAccountType
const subtype = account.subtype || mappedFromAccountType

// Show Plaid-style dropdowns
// Type: Investment, Depository, etc.
// Subtype: 401k, IRA, Brokerage, etc.
```

#### In Business Logic (account-type-utils.ts)

```typescript theme={null}
// Already handles both!
const accountType = account.type || account.account_type || 'unknown'
```

## Files Changed

### ✅ Already Updated

1. `/lib/account-type-mappings.ts` - Added SNAPTRADE\_TO\_PLAID\_MAPPING (CENTRAL SOURCE OF TRUTH)
2. `/app/accounts/page.tsx` - Dialog now uses type/subtype for SnapTrade
3. `/app/api/snaptrade/process-connection/route.ts` - Sets all columns on create
4. `/app/api/accounts/update-type/route.ts` - Updates both old and new columns
5. `/sql-queries/add-account-type-override-support.sql` - Migration script

### ⚠️ NOT Changed (Intentionally)

All existing code that reads `account_type` continues to work:

* Display components
* Calculation logic
* Categorization functions
* No breaking changes!

## Migration Steps

1. **Run SQL Migration**
   ```bash theme={null}
   # In Supabase SQL Editor
   # Run: sql-queries/add-account-type-override-support.sql
   ```

2. **Deploy Code Changes**
   * All files already updated
   * No additional code changes needed

3. **Existing Accounts Auto-Migrate**
   * SQL migration populates new columns
   * Old `account_type` remains unchanged
   * Both old and new code paths work

## Backward Compatibility

### Old Code Reads `account_type`

✅ Still works! Column is maintained and kept in sync.

### New Code Reads `type`/`subtype`

✅ Works! New columns are populated.

### Gradual Migration Path

* Can slowly update components to use `type`/`subtype` over time
* No rush to change everything at once
* `account_type` can be deprecated eventually, but not required

## Benefits

1. **Consistent UX** - SnapTrade accounts now show same UI as Plaid accounts
2. **No Breaking Changes** - Existing code continues working
3. **Flexible Migration** - Can update code gradually
4. **User Override Support** - Users can change Investment > Depository, etc.
5. **Subtype Granularity** - Users can pick 401k, IRA, Brokerage, etc.

## Example

### Before

* **UI**: Single dropdown with "401K", "IRA", "ROTH", "I" (confusing)
* **No subtypes**: Just raw SnapTrade types

### After

* **UI**: Two dropdowns
  * Type: Investment, Depository, Loan, etc.
  * Subtype: 401k, IRA, Brokerage, etc.
* **Consistent**: Same UX as Plaid and Manual accounts
* **Backward Compatible**: Old `account_type` still populated

## Maintaining the Type Mapping

**IMPORTANT:** The SnapTrade → Plaid type mapping is centralized in ONE place:

**Source of Truth:** `/lib/account-type-mappings.ts` → `SNAPTRADE_TO_PLAID_MAPPING`

**Used by:**

* `app/api/snaptrade/process-connection/route.ts` - Creates new accounts
* `app/accounts/page.tsx` - Initializes edit dialog
* `sql-queries/add-account-type-override-support.sql` - Migration backfill (reference only)

**To add a new SnapTrade account type:**

1. Add it to `SNAPTRADE_TO_PLAID_MAPPING` in `/lib/account-type-mappings.ts`
2. Done! All code will automatically use the new mapping
3. SQL migration is one-time only - no need to update

**Example:**

```typescript theme={null}
// In lib/account-type-mappings.ts
export const SNAPTRADE_TO_PLAID_MAPPING = {
  // ... existing mappings ...
  'NEW_TYPE': { type: 'investment', subtype: 'new subtype' },  // Add here
}
```

## Testing Checklist

* [ ] Run SQL migration in Supabase
* [ ] Edit a SnapTrade account - should see Type/Subtype dropdowns
* [ ] Change type from Investment to Depository - should work
* [ ] Old calculations still work (check dashboard, net worth, charts)
* [ ] New accounts get both old and new columns populated
* [ ] User overrides are tracked properly (type != source\_type)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.