---
title: "Organization Admin"
description: "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...."
last_updated: "2026-05-06T07:29:41.620964+00:00"
canonical_url: "https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/technical/section-3/organization-admin"
---

<details>
<summary>Relevant source files</summary>

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

- [apps/api/src/organization/organization.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.controller.ts)
- [apps/api/src/org-chart/org-chart.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.controller.ts)
- [apps/api/src/organization/organization.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.service.ts)
- [apps/api/src/context/context.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/context/context.controller.ts)
- [apps/api/src/org-chart/org-chart.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.service.ts)
- [apps/api/src/organization/dto/transfer-ownership.dto.ts](https://github.com/blade47/comp/blob/main/apps/api/src/organization/dto/transfer-ownership.dto.ts)
- [apps/api/src/context/context.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/context/context.service.ts)
- [apps/api/src/context/schemas/context-operations.ts](https://github.com/blade47/comp/blob/main/apps/api/src/context/schemas/context-operations.ts)
</details>

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.

<Callout title="Authentication & Authorization" variant="info">
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.
</Callout>

## 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:

| Method | Path                       | Description                                   | Authentication |
| :----- | :------------------------- | :-------------------------------------------- | :------------- |
| `GET`  | `/organization`            | Retrieve details of the authenticated organization. | Required       |
| `PATCH`| `/organization`            | Update specific properties of the organization. | Required       |
| `POST` | `/organization/transfer-ownership` | Transfer ownership of the organization to another member. | Required       |
| `DELETE`| `/organization`            | Delete the authenticated organization.        | Required       |
| `GET`  | `/organization/primary-color` | Retrieve 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](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.controller.ts#L20-L21), [apps/api/src/organization/organization.controller.ts:31-33](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.controller.ts#L31-L33), [apps/api/src/organization/organization.controller.ts:54-56](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.controller.ts#L54-L56), [apps/api/src/organization/organization.controller.ts:80-82](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.controller.ts#L80-L82), [apps/api/src/organization/organization.controller.ts:133-135](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.controller.ts#L133-L135), [apps/api/src/organization/organization.controller.ts:153-155](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.controller.ts#L153-L155)

### 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](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.service.ts#L19-L42), [apps/api/src/organization/organization.service.ts:44-84](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.service.ts#L44-L84), [apps/api/src/organization/organization.service.ts:86-110](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.service.ts#L86-L110), [apps/api/src/organization/organization.service.ts:112-211](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.service.ts#L112-L211), [apps/api/src/organization/organization.service.ts:212-261](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.service.ts#L212-L261)

### 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](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.controller.ts#L80-L131), [apps/api/src/organization/organization.service.ts:112-211](https://github.com/blade47/comp/blob/main/apps/api/src/organization/organization.service.ts#L112-L211)

### 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](https://github.com/blade47/comp/blob/main/apps/api/src/organization/dto/transfer-ownership.dto.ts#L1-L19)

## 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

| Method | Path                       | Description                                   | Authentication |
| :----- | :------------------------- | :-------------------------------------------- | :------------- |
| `GET`  | `/org-chart`               | Retrieve the organization chart.              | Required       |
| `PUT`  | `/org-chart`               | Create or update an interactive organization chart (nodes/edges). | Required       |
| `POST` | `/org-chart/upload`        | Upload an image to be used as the organization chart. | Required       |
| `DELETE`| `/org-chart`               | Delete the organization chart.                | Required       |

Sources: [apps/api/src/org-chart/org-chart.controller.ts:20-22](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.controller.ts#L20-L22), [apps/api/src/org-chart/org-chart.controller.ts:28-30](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.controller.ts#L28-L30), [apps/api/src/org-chart/org-chart.controller.ts:33-35](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.controller.ts#L33-L35), [apps/api/src/org-chart/org-chart.controller.ts:48-50](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.controller.ts#L48-L50), [apps/api/src/org-chart/org-chart.controller.ts:61-63](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.controller.ts#L61-L63)

### 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](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.service.ts#L20-L27), [apps/api/src/org-chart/org-chart.service.ts:32-53](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.service.ts#L32-L53), [apps/api/src/org-chart/org-chart.service.ts:55-97](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.service.ts#L55-L97), [apps/api/src/org-chart/org-chart.service.ts:99-166](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.service.ts#L99-L166), [apps/api/src/org-chart/org-chart.service.ts:168-193](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.service.ts#L168-L193), [apps/api/src/org-chart/org-chart.service.ts:195-209](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.service.ts#L195-L209), [apps/api/src/org-chart/org-chart.service.ts:211-224](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.service.ts#L211-L224)

### 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](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.controller.ts#L61-L69), [apps/api/src/org-chart/org-chart.service.ts:99-166](https://github.com/blade47/comp/blob/main/apps/api/src/org-chart/org-chart.service.ts#L99-L166)

## 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

| Method | Path                       | Description                                   | Authentication |
| :----- | :------------------------- | :-------------------------------------------- | :------------- |
| `GET`  | `/context`                 | Retrieve all context entries for the organization. | Required       |
| `GET`  | `/context/:id`             | Retrieve a specific context entry by ID.      | Required       |
| `POST` | `/context`                 | Create a new context entry.                   | Required       |
| `PATCH`| `/context/:id`             | Update an existing context entry.             | Required       |
| `DELETE`| `/context/:id`             | Delete a context entry.                       | Required       |

Sources: [apps/api/src/context/context.controller.ts:20-22](https://github.com/blade47/comp/blob/main/apps/api/src/context/context.controller.ts#L20-L22), [apps/api/src/context/context.controller.ts:28-30](https://github.com/blade47/comp/blob/main/apps/api/src/context/context.controller.ts#L28-L30), [apps/api/src/context/schemas/context-operations.ts:5-29](https://github.com/blade47/comp/blob/main/apps/api/src/context/schemas/context-operations.ts#L5-L29)

### 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](https://github.com/blade47/comp/blob/main/apps/api/src/context/context.service.ts#L13-L25), [apps/api/src/context/context.service.ts:27-46](https://github.com/blade47/comp/blob/main/apps/api/src/context/context.service.ts#L27-L46), [apps/api/src/context/context.service.ts:48-63](https://github.com/blade47/comp/blob/main/apps/api/src/context/context.service.ts#L48-L63), [apps/api/src/context/context.service.ts:65-85](https://github.com/blade47/comp/blob/main/apps/api/src/context/context.service.ts#L65-L85), [apps/api/src/context/context.service.ts:87-109](https://github.com/blade47/comp/blob/main/apps/api/src/context/context.service.ts#L87-L109)

## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/llms.txt) for all pages in this wiki.