System Architecture
Core Features
Data Management
Frontend Components
Extensibility
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.
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.
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.
The following table summarizes the API endpoints available for organization management:
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
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:
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
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
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
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.
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
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.
ALLOWED_UPLOAD_MIME_TYPES (PNG, JPEG, GIF, WebP, SVG, BMP, TIFF, PDF).MAX_FILE_SIZE_BYTES limit (100MB).uploaded chart type and the S3 key.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).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
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
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.
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
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
| 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) |
newOwnerIdcurrentUserId is a member of the organization.currentUserId holds the owner role.newOwnerId corresponds to an active member of the organization.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.| Upload an image to be used as the organization chart. |
| Required |
DELETE | /org-chart | Delete the organization chart. | Required |
deleteS3Object(s3Key: string): Private helper method to delete an object from S3.| Create a new context entry. |
| Required |
PATCH | /context/:id | Update an existing context entry. | Required |
DELETE | /context/:id | Delete a context entry. | Required |