Skip to main content

Organization Service API

The Organization Service handles tenant management and seed data for Asset360. All public methods return Result values built with neverthrow, providing structured domain errors for routers and use cases.

Location: worker/services/organization/service.ts

Dependencies​

  • OrganizationRepository – persistence for organization entities
  • Shared domain error helpers – validation, not-found, and business-logic error factories
  • createLogger – structured logging for default seeding and error reporting

Public API​

ensureDefaultOrganizations(): Promise<void> : Idempotently seeds the System/Public organizations. Uses Result-based helpers internally and logs failures without throwing.

createOrganization(data: CreateOrganizationRequest): Promise<Result<OrganizationEntity, DomainError>> : Validates via Zod schemas, enforces slug uniqueness, and returns the created organization or a ValidationError.

getOrganizationById(id: string): Promise<Result<OrganizationEntity, DomainError>> : Schema-validates IDs, returns NotFoundError for missing organizations, and wraps repository failures as BusinessLogicError.

getOrganizationBySlug(slug: string): Promise<Result<OrganizationEntity, DomainError>> : Ensures slugs are well-formed and unique. Missing records return a scoped NotFoundError with a descriptive message.

updateOrganization(id: string, data: UpdateOrganizationRequest): Promise<Result<OrganizationEntity, DomainError>> : Combines structural validation with business invariants (existence + slug uniqueness). Errors surface as ValidationError, NotFoundError, or BusinessLogicError.

deleteOrganization(id: string): Promise<Result<void, DomainError>> : Validates ID format, ensures the organization exists, and deletes it. Missing organizations return NotFoundError.

getAllOrganizations(): Promise<Result<OrganizationEntity[], DomainError>> getActiveOrganizations(): Promise<Result<OrganizationEntity[], DomainError>> : Query helpers that wrap repository calls and return BusinessLogicError on failure.

Error Semantics​

  • createValidationError(field, message) – invalid IDs, duplicate slugs, malformed input
  • createNotFoundError("Organization", id) – lookups that miss
  • toBusinessLogicError(error, message) – repository failures and unexpected exceptions

Usage Example​

const organizationResult =
  await services.organization.getOrganizationBySlug("system");
const organization = await organizationResult.match(
  async (value) => value,
  async (error) => {
    throw mapDomainErrorToTRPC(error);
  },
);

ensureDefaultOrganizations is invoked during bootstrap (for example, in service factory setup) to guarantee platform-wide orgs exist.

Last Validated: 2025-11-10 against commit 0342a62e