Accounts Domain

The Accounts domain handles multi-tenancy, user management, and authentication through Auth0 integration.

Entity Hierarchy

Key Concepts

Multi-Tenancy Model

Users can belong to multiple accounts, each with a specific role:

Account Selection Flow

• Session stores selectedAccountId - all queries scope to this account
• Switching accounts updates the session, not the user record
• Sessions are stored in Redis with TTL-based expiration

Business Rules

1. Users must belong to at least one account
2. Users with multiple accounts must select one before proceeding
3. Admins can manage members; members can view only
4. New users must complete registration before accessing features
5. Account names should stay in sync with Auth0 org names
6. Sessions expire after inactivity (TTL-based)

Common Operations

Getting Current User Session

import { getSession } from '@repo/core';

const session = await getSession();
// session.userId - current user
// session.selectedAccountId - active account

Creating a New Account

import { CreateAccount } from '@repo/core';

const useCase = new CreateAccount();
const account = await useCase.execute({
  name: 'Acme Corp',
  adminEmail: 'admin@acme.com',
});

Adding a User to an Account

import { AddUserToAccount } from '@repo/core';

const useCase = new AddUserToAccount();
await useCase.execute({
  accountId: 'account-123',
  email: 'user@example.com',
  role: 'member',
});

Switching Accounts

import { SwitchAccount } from '@repo/core';

const useCase = new SwitchAccount();
await useCase.execute({
  accountId: 'account-456',
});
// Session now scoped to new account

Auth0 Integration

Account creation and user management sync with Auth0:

Important Considerations

• Auth0 API calls cannot be rolled back in transactions
• If Neo4j write succeeds but Auth0 fails, handle orphaned records
• Use background jobs for Auth0 sync when possible

Related Files