Skip to main content
doc0blade47/compdocumentation home
Sign in

Organization Admin

Last updated Oct 11, 2026
Relevant source files

The following files were used as context for generating this wiki page:

This page outlines the functionalities and architecture related to "Organization Admin" within the API, focusing on managing organization-level settings, organizational charts, and contextual data. It covers the API endpoints, service logic, and data structures involved in these administrative tasks, providing a comprehensive overview for developers and administrators.

The core components for organization administration are handled by the OrganizationController and OrganizationService, which manage details like organization name, logo, and ownership. Additionally, the OrgChartController and OrgChartService facilitate the creation, update, and deletion of organizational charts, including image uploads. The ContextController and ContextService provide mechanisms for managing organization-specific contextual data.

Authentication & Authorization

All administrative endpoints generally require authentication, typically handled by the HybridAuthGuard. This guard supports both API key authentication (via X-API-Key header) and session-based JWT authentication. For session-based authentication, the X-Organization-Id header is often required to specify the target organization.

Organization Management

The OrganizationController exposes API endpoints for managing an organization's core properties, including retrieving details, updating information, transferring ownership, and deleting the organization. The OrganizationService encapsulates the business logic and database interactions for these operations.

API Endpoints

The following table summarizes the API endpoints available for organization management:

MethodPathDescriptionAuthentication
GET/organizationRetrieve details of the authenticated organization.Required
PATCH/organizationUpdate specific properties of the organization.Required
POST/organization/transfer-ownershipTransfer ownership of the organization to another member.Required
DELETE/organizationDelete the authenticated organization.Required
GET/organization/primary-colorRetrieve the organization's primary color. Can use an access token for public access.Optional (token)

Sources: apps/api/src/organization/organization.controller.ts:20-21, apps/api/src/organization/organization.controller.ts:31-33, apps/api/src/organization/organization.controller.ts:54-56, apps/api/src/organization/organization.controller.ts:80-82, apps/api/src/organization/organization.controller.ts:133-135, apps/api/src/organization/organization.controller.ts:153-155

Service Logic

The OrganizationService handles the core business logic for organization operations:

  • findById(id: string): Retrieves an organization by its ID, selecting specific fields such as id, name, slug, logo, metadata, website, primaryColor, and more. Throws NotFoundException if the organization does not exist.
  • updateById(id: string, updateData: UpdateOrganizationDto): Updates an existing organization's details. It first verifies the organization's existence and then applies the provided updateData.
  • deleteById(id: string): Deletes an organization after verifying its existence.
  • transferOwnership(organizationId: string, currentUserId: string, newOwnerId: string): This critical operation transfers the owner role from the currentUserId to newOwnerId within the specified organizationId. It performs several validations:
    • Ensures newOwnerId is provided.
    • Verifies the currentUserId is a member of the organization.
    • Confirms the currentUserId holds the owner role.
    • Checks that the newOwnerId corresponds to an active member of the organization.
    • Prevents transferring ownership to the current owner.
    • Updates roles for both members in a database transaction: the current owner loses owner and gains admin (if not already present), and the new owner gains owner.
  • getPrimaryColor(organizationId: string, token?: string): Retrieves the primaryColor of an organization. It supports an optional token parameter for public access, which resolves the organization ID via an access grant. If a token is provided and valid, it bypasses standard authentication.

Sources: apps/api/src/organization/organization.service.ts:19-42, apps/api/src/organization/organization.service.ts:44-84, apps/api/src/organization/organization.service.ts:86-110, apps/api/src/organization/organization.service.ts:112-211, apps/api/src/organization/organization.service.ts:212-261

Ownership Transfer Flow

The ownership transfer process involves several steps, including validation and role updates, ensuring that only authorized users can perform this critical action.

Sources: apps/api/src/organization/organization.controller.ts:80-131, apps/api/src/organization/organization.service.ts:112-211

Data Transfer Objects

The TransferOwnershipDto defines the request body for transferring ownership, while TransferOwnershipResponseDto describes the response structure.

Sources: apps/api/src/organization/dto/transfer-ownership.dto.ts:1-19

Org Chart Management

The OrgChartController provides endpoints for managing an organization's chart, allowing for both interactive chart data and image uploads. The OrgChartService handles the storage and retrieval, including integration with AWS S3 for image assets.

API Endpoints

MethodPathDescriptionAuthentication
GET/org-chartRetrieve the organization chart.Required
PUT/org-chartCreate or update an interactive organization chart (nodes/edges).Required
POST/org-chart/uploadUpload an image to be used as the organization chart.Required
DELETE/org-chartDelete the organization chart.Required

Sources: apps/api/src/org-chart/org-chart.controller.ts:20-22, apps/api/src/org-chart/org-chart.controller.ts:28-30, apps/api/src/org-chart/org-chart.controller.ts:33-35, apps/api/src/org-chart/org-chart.controller.ts:48-50, apps/api/src/org-chart/org-chart.controller.ts:61-63

Service Logic and S3 Integration

The OrgChartService manages the lifecycle of organization charts, distinguishing between interactive charts (stored as nodes and edges) and uploaded charts (stored as images in S3).

  • findByOrganization(organizationId: string): Retrieves the organization chart for a given organization. If the chart is an uploaded type with an uploadedImageUrl, it generates a presigned S3 URL for temporary access to the image.
  • upsertInteractive(organizationId: string, data: UpsertOrgChartDto): Creates or updates an interactive chart. If a previous chart was an uploaded image, it triggers the deletion of the old S3 object after the database update succeeds to prevent orphaned S3 files.
  • uploadImage(organizationId: string, data: UploadOrgChartDto): Handles the upload of an image file to S3.
    • Validates the file type against ALLOWED_UPLOAD_MIME_TYPES (PNG, JPEG, GIF, WebP, SVG, BMP, TIFF, PDF).
    • Enforces a MAX_FILE_SIZE_BYTES limit (100MB).
    • Deletes any existing uploaded image from S3 before uploading the new one.
    • Uploads the base64 encoded image data to S3, generating a unique key.
    • Updates the database record to reflect the uploaded chart type and the S3 key.
    • Returns a presigned URL for the newly uploaded image.
  • delete(organizationId: string): Deletes the organization chart record from the database. If an S3 image was associated, it also deletes the corresponding object from S3.
  • getSignedUrl(s3Key: string): Private helper method to generate a presigned URL for an S3 object, expiring in 15 minutes (SIGNED_URL_EXPIRY).
  • deleteS3Object(s3Key: string): Private helper method to delete an object from S3.

Sources: apps/api/src/org-chart/org-chart.service.ts:20-27, apps/api/src/org-chart/org-chart.service.ts:32-53, apps/api/src/org-chart/org-chart.service.ts:55-97, apps/api/src/org-chart/org-chart.service.ts:99-166, apps/api/src/org-chart/org-chart.service.ts:168-193, apps/api/src/org-chart/org-chart.service.ts:195-209, apps/api/src/org-chart/org-chart.service.ts:211-224

Org Chart Image Upload Flow

The process for uploading an organizational chart image involves client-side preparation, API interaction, and S3 storage.

Sources: apps/api/src/org-chart/org-chart.controller.ts:61-69, apps/api/src/org-chart/org-chart.service.ts:99-166

Context Management

The ContextController and ContextService provide a way to manage organization-specific contextual data. While not strictly "admin" in the sense of managing the organization itself, it allows administrators to define and manage data relevant to their organization's operations.

API Endpoints

MethodPathDescriptionAuthentication
GET/contextRetrieve all context entries for the organization.Required
GET/context/:idRetrieve a specific context entry by ID.Required
POST/contextCreate a new context entry.Required
PATCH/context/:idUpdate an existing context entry.Required
DELETE/context/:idDelete a context entry.Required

Sources: apps/api/src/context/context.controller.ts:20-22, apps/api/src/context/context.controller.ts:28-30, apps/api/src/context/schemas/context-operations.ts:5-29

Service Logic

The ContextService provides standard CRUD operations for context entries:

  • findAllByOrganization(organizationId: string): Fetches all context entries associated with a given organizationId, ordered by creation date.
  • findById(id: string, organizationId: string): Retrieves a single context entry by its ID, ensuring it belongs to the specified organizationId. Throws NotFoundException if not found.
  • create(organizationId: string, createContextDto: CreateContextDto): Creates a new context entry, associating it with the organizationId.
  • updateById(id: string, organizationId: string, updateContextDto: UpdateContextDto): Updates an existing context entry. It first validates the entry's existence and ownership before applying updates.
  • deleteById(id: string, organizationId: string): Deletes a context entry after verifying its existence and ownership.

Sources: apps/api/src/context/context.service.ts:13-25, apps/api/src/context/context.service.ts:27-46, apps/api/src/context/context.service.ts:48-63, apps/api/src/context/context.service.ts:65-85, apps/api/src/context/context.service.ts:87-109

Was this page helpful?