Accounts

The accounts module models the people and organisations that own everything else in the product: boards, groups, sessions, collections. It is consumed by the API (the account behind every authenticated request), the admin back-office (roles, search, pagination, impersonation audit) and the auth adapter, which pushes identity snapshots from the identity provider into the store.

Import from @workspace/training/domain/accounts and @workspace/training/application/accounts.

Domain

Account

Account is a discriminated union on type: Person or Organisation. The base fields are shared.

Two fields carry rules worth knowing:

• avatarTrusted: an admin reviewed and approved the avatar. Peers only see avatarUrl once it is true. The gating happens at the DTO boundary, not in this module.
• onboardedAt: when the account first completed onboarding. null means never onboarded. A set value with isAccountOnboarded false means a newly required field is missing and a catch-up dialogue is due.
• signupSource: the app the account was created from, fixed at creation and never changed. It records the origin of the account; rules read its audience instead, see Audience and space.
• handle and handleLocked: the public identifier of the account and its lock; see Public handle.
• certified: certified by us from the back-office, the blue badge of the author catalog; see Catalog. The gold premium badge is read from the running grants and never stored.

Public handle

The handle is the readable, stable address of an account (/authors/ffb), used by the author page instead of the technical id. It is optional: an account without one has no author page, and publishing to the catalogue requires one.

• Unique across the app, regardless of case. The handle is stored lower-cased (normalizeAccountHandle trims and lower-cases it), so FFB and ffb are the same handle and two accounts cannot hold them.
• Format. Groups of [a-z0-9] joined by single hyphens, 3 to 30 characters: no leading or trailing hyphen, no doubled hyphen. The table checks the same format.
• Reserved words. RESERVED_ACCOUNT_HANDLES lists the handles no account may take: route segments (admin, api, new, me, settings, …) and names that would pass for the platform. The list lives in the domain only.
• Set once, then locked. Setting the handle turns handleLocked on. The service refuses any later change, even to the same handle, until an admin turns the lock off (unlockHandle, the back-office Unlock action); the owner can then set it once more, and it locks again. The profile update never writes the handle.

Signup source

Audience and space

The audience says who the account is for, teachers or learners, and the space is the app that opens its content to it. Rules and screens read these two, never signupSource: each app shows its content to the accounts whose space it is and the others a screen pointing to their app; the API does not filter on the space.

For now the audience follows from the signup source, in audienceOf only. When the two may differ (a learner who becomes a teacher), an audience stored on the account replaces this derivation and the callers stay the same.

Owner

Owner is the public projection of an account attached to a resource (a group, a board). It never carries the email or the role.

User role

Roles are read from the database row, never from identity-provider claims. Authorization stays in the consuming app; see Service Context.

Preferences

AccountPreferences is the per-account UI state persisted server-side. Each member is optional and nullable, and null means an explicit reset.

The column is jsonb and is not migrated when a member is dropped: a shareTemplates key still stored on older accounts is stripped when the wire schema parses the preferences, and disappears from the row on the account's next preferences write.

Onboarding

The onboarding rules live in one place so the onboarding redirect, the catch-up dialogue and the database backfill agree.

onboardedAt does not participate: it records that onboarding happened once, not that the account is complete today.

Names

computeDisplayName({
  type: "person",
  firstName: "ada",
  lastName: "d'arc",
  email: "ada@example.com",
}); // => "Ada D'Arc"

computeDisplayName({
  type: "person",
  firstName: null,
  lastName: null,
  email: "ada@example.com",
}); // => "ada" (email prefix fallback)

computeDisplayName({
  type: "organisation",
  organisationName: " Bridge Club de Lyon ",
  email: "club@example.com",
}); // => "Bridge Club de Lyon"

export function onboardingState(account: Account) {
  const missing = computeMissingFields(account);
  // => { name: false, country: true, accountLanguage: false, appLanguage: false, auctionSystem: false }
  const onboarded = isAccountOnboarded(account); // => false while any field is missing
  const signature = computeSignatureName(account); // => "Ada" for a person with a first name
  return { missing, onboarded, signature };
}

User search result

Application

AccountsService

createAccountsService(deps: AccountsServiceDeps): AccountsService

The service is the one place that emits account:created and account:updated on the event bus port, and the only entry point to accounts: the API, the admin back-office, the CLI and the database scripts read and write accounts through it, never through the repository. getOwn and update take a ServiceContext to refuse a foreign account, search takes one to name its viewer, and the directory reads (getManyByIds, listPaginated, resolveIdsByEmails) take the caller's and ignore it: they serve back-office and import surfaces whose authorization the consuming app decides. Elsewhere the account id is the subject itself, resolved by the caller from the verified session or from the identity provider.

// The adapter in packages/database implements both ports; an event bus (mitt
// in the apps) receives account:created / account:updated.
export function buildAccounts(
  accounts: AccountsRepository,
  accountsRead: AccountsReadRepository,
  eventBus: DomainEventBus
): AccountsService {
  return createAccountsService({ accounts, accountsRead, eventBus });
}

// Called once per authenticated request: no ServiceContext, the account id
// comes from the verified session. The identity provider (auth adapter) gives
// the user as its creation event would; without a signup source, no account is created.
export function currentAccount(
  accounts: AccountsService,
  userId: string,
  identityProvider: IdentityProvider
): Promise<Account> {
  return accounts.ensureAccount(userId, identityProvider);
}

export function completeOnboarding(
  accounts: AccountsService,
  accountId: string
): Promise<Account> {
  return accounts.completeOnboarding(accountId, {
    type: "person",
    firstName: "Ada",
    lastName: "Lovelace",
    country: "FR",
    accountLanguage: "fr",
    appLanguage: "fr",
    auctionSystem: "sef",
  });
}

export function updateOrganisation(
  accounts: AccountsService,
  accountId: string
): Promise<Account> {
  // Throws AccessDeniedError on another account, ValidationError(ORGANISATION_NAME_REQUIRED) on a blank name.
  return accounts.update(
    accountId,
    { type: "organisation", organisationName: "Bridge Club de Lyon" },
    { userId: accountId }
  );
}

export function promote(
  accounts: AccountsService,
  accountId: string
): Promise<Account> {
  return accounts.updateRole(accountId, USER_ROLE.ADMIN);
}

isUserRole("translator"); // => true
isUserRole("owner"); // => false

ImpersonationService

createImpersonationService(deps: { impersonationLog: ImpersonationLogRepository }): ImpersonationService

Writes the audit trail of admin impersonation. Who may impersonate whom is decided by the consuming app before anything is recorded: the API checks the admin role and refuses an admin target, then records. The API exposes the service as impersonationService in the authenticated context.

ImpersonationEvent is a union on action. Both members name the impersonation, the admin and the target; each keeps only the session it happens in, and an optional field left out stays out of the entry.

applyAccountIdentitySnapshot

applyAccountIdentitySnapshot(accounts: AccountsService, snapshot: IdentitySnapshot, ctx?: ApplyIdentitySnapshotContext): Promise<void>

The transport-agnostic entry for identity events. Provider parsing stays in the auth adapter; this function only applies the staleness guard, then writes through the service: upsertFromIdentitySnapshot when the snapshot carries a signupSource, updateFromIdentitySnapshot otherwise. Without a signup source a snapshot only updates an existing account: the app the user opens creates it, naming itself through ensureAccount.

The guard: the function looks up the account the snapshot would write to (attached, or detached with the same email). When that account has an updatedAt newer than snapshot.updatedAt, the write is skipped and a debug line is logged with ctx.eventType. An out-of-order or replayed event therefore never clobbers fresher data, and replaying the same snapshot twice converges to the same state.

role is applied on creation only; an existing account's role is never overwritten by a snapshot. ApplyIdentitySnapshotContext holds one optional eventType: string used for logging.

// From the auth adapter's webhook handler or a batch sync. The snapshot is
// skipped when it is older than the account it would overwrite, and only
// creates the account when it carries a signupSource.
export function onIdentityEvent(
  accounts: AccountsService,
  snapshot: IdentitySnapshot
): Promise<void> {
  return applyAccountIdentitySnapshot(accounts, snapshot, {
    eventType: "user.updated",
  });
}

DTOs

UpdateAccountDTO is a union on type, so a person update cannot carry an organisation name and vice versa. auctionSystem is the system identifier string, not the full object.

Every field but type is optional.

CreatingIdentitySnapshot is IdentitySnapshot & { signupSource: SignupSource }: the only snapshot shape allowed to create an account. The webhook, the API's lazy creation, the admin's first request and the CLI sync all hand the service an IdentitySnapshot.

IdentityProvider is the provider read directly, implemented by the auth adapter: getIdentity(identityProviderUserId) returns the user as the provider holds it now, signup source and role included, null for a user without a primary email, and rejects when the provider cannot be reached; listIdentities() returns every user, those without a primary email left out.

Ports

Accounts bind the canonical surface of Queries. The ports name the identity provider's id identityProviderUserId; only the adapter knows which column stores it.

No account method is bespoke. Detaching an identity and re-attaching a detached account are each one conditional update, whose criteria and patch are a single statement; the identity upsert is an update by forIdentity followed, when it matched nothing, by a writeOne, and the unique email and identity refuse the second of two concurrent inserts. Lazy creation and the identity webhook insert the same row under the same id and may race: the service catches ACCOUNT_ALREADY_EXISTS and reads back the account the other inserted, so account:created is emitted once.

createFakeAccountsRepositories(seed?, options?) from @workspace/training/testing returns { accounts, accountsRead } over one in-memory row set with the table's semantics, plus rows and identityOf(accountId) for assertions; a seeded account is attached to an identity equal to its id. options.auctionSystems lists the systems a patched auctionSystemId resolves against.

ImpersonationLogRepository

Append-only audit trail of admin impersonation, written through ImpersonationService only. It has no read side: nothing in the product reads the log back. createFakeImpersonationLogRepository() from @workspace/training/testing is its in-memory fake.

Errors

See Errors for the AppError family.