Skip to main content

Billing Projects

Overview​

The Billing Projects feature allows administrators to create and manage billing project identifiers that can be associated with various resources in the Shakudo platform. Billing projects provide a way to organize and track resources (sessions, jobs, and services) for accounting, cost allocation, and reporting purposes. Each billing project has a unique name and ID that can be referenced when creating platform resources, enabling organizations to attribute resource usage to specific projects, teams, or cost centers.

Access & Location​

  • Route: ?panel=billing-projects
  • Navigation: Admin → Billing Projects
  • Access Requirements:
    • View: All authenticated users can view their own billing projects
    • View All: dashboard_admin and dashboard_maintainer roles can view all billing projects
    • Create: dashboard_admin role required
    • Deactivate: dashboard_admin role or project owner
  • Feature Flags: None

Key Capabilities​

Create Billing Projects​

Create new billing project identifiers that can be assigned to platform resources. Project names must follow specific naming conventions (alphanumeric characters with dashes, underscores, and dots) and must be unique within the platform.

Deactivate Billing Projects​

Soft-delete billing projects that are no longer needed. Deactivated projects remain in the system for historical tracking but cannot be used for new resource assignments. Only administrators or the project creator can deactivate a billing project.

Filter Resources by Billing Project​

Navigate directly from a billing project to view all associated resources (sessions, immediate jobs, scheduled jobs, and services) filtered by that project ID. This provides quick access to understand which resources are attributed to each billing project.

Search and Filter​

Search across billing project properties including name, ID, creator email, creation date, and deactivation date. The search functionality supports partial matches and date-based filtering.

User Interface​

Main View​

The main panel displays a data grid table showing all billing projects the user has access to. Active projects are shown by default, ordered with active projects first, then by creation date (newest first). Each row includes action buttons for deactivation and a dropdown menu for filtering related resources.

Dialogs & Modals​

  1. Create Billing Project Dialog

    • Purpose: Create a new billing project with a unique name
    • Fields:
      • Name (required): Alphanumeric string with dashes, underscores, and dots allowed
    • Validation Rules:
      • Must begin and end with alphanumeric characters
      • Cannot contain spaces
      • Maximum length of 128 characters
      • Name must be unique across all billing projects
      • Follows pattern: /^[a-z0-9A-Z\.\-\_\s]+$/g
    • Actions: Cancel or Create

  2. Deactivate Billing Project Dialog

    • Purpose: Confirm deactivation of a billing project
    • Content: Displays project name and confirmation message
    • Actions: Cancel or Deactivate

Tables & Data Grids​

  1. Billing Projects Table
    • Columns:
      • Actions (empty header): Deactivate button and resource filter dropdown menu
      • Name: Project name with copy-to-clipboard functionality, displays "deactivated" chip for inactive projects
      • ID: Project ID with copy-to-clipboard functionality
      • Created By: Email address of the user who created the project
      • Created On: Creation timestamp (format: YYYY-MM-DD HH:mm:ss)
      • Deactivated On (hidden by default): Deactivation timestamp
    • Row Actions:
      • Deactivate: Soft-deletes the project (visible only for active projects)
      • View Menu: Dropdown to filter sessions, immediate jobs, scheduled jobs, or services by this project
    • Filtering: Search bar filters across all columns including ID, name, creator email, and dates
    • Visual Styling: Deactivated projects are visually distinguished with altered row styling
    • Toolbar: Column visibility toggle and refresh button

Technical Details​

GraphQL Operations​

Queries:

  • getBillingProjects - Retrieves list of billing projects with optional filtering by user ID and active status. Results are ordered by active status (descending) then creation date (descending)
  • getBillingProjectByName - Checks if a billing project name already exists (used for validation during creation)

Mutations:

  • createBillingProject - Creates a new billing project with name, creator user ID, and creator email. Returns the created project with all fields
  • deactivateBillingProject - Sets the active field to false for a specified billing project ID. Does not delete the project from the database

Subscriptions:

  • None

Component Structure​

  • Main Component: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/BillingProjects/BillingProjectsPanel.tsx
  • Dialogs:
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/BillingProjects/BillingProjectsCreateDialog.tsx
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/BillingProjects/BillingProjectsDeactivateDialog.tsx
  • Supporting Components:
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/BillingProjects/BillingProjectTableMenu.tsx
  • Custom Hook: /root/gitrepos/monorepo/apps/hyperplane-dashboard/hooks/useBillingProjects.ts
  • Role Configuration: /root/gitrepos/monorepo/apps/hyperplane-dashboard/constants/Roles/billing-projects.ts

Role-Based Access Control​

The feature implements granular RBAC:

  • Email Filter: Only dashboard_admin and dashboard_maintainer roles can view all projects; other users see only their own projects
  • Create Action: Restricted to dashboard_admin role
  • Deactivate Action: Available to dashboard_admin role or the user who created the project

Data Model​

Billing projects include the following fields:

  • id: Unique identifier (string)
  • name: Project name (string, max 128 characters)
  • active: Boolean flag indicating if project is active
  • hyperplaneUserId: ID of the user who created the project
  • hyperplaneUserEmail: Email of the user who created the project
  • creationDate: Timestamp when project was created
  • deactivationTime: Timestamp when project was deactivated (null if active)

Common Workflows​

Creating a New Billing Project​

  1. Navigate to Admin → Billing Projects panel
  2. Click the "Create Billing Project" button (requires admin role)
  3. Enter a unique project name following the validation rules
  4. Click "Create" to save the billing project
  5. The new project appears in the table and can be immediately used for resource assignment

Associating Resources with Billing Projects​

  1. When creating a session, job, or service, select the billing project from the dropdown
  2. The resource will be tagged with the billing project ID
  3. Use the billing project table menu to view all resources associated with a specific project

Viewing Resources by Billing Project​

  1. In the Billing Projects table, click the dropdown menu (chevron icon) on any project row
  2. Select the resource type to filter: Sessions, Immediate Jobs, Scheduled Jobs, or Services
  3. The dashboard navigates to the respective panel with filters applied to show only resources associated with that billing project

Deactivating a Billing Project​

  1. Locate the project in the Billing Projects table
  2. Click the deactivate icon (HighlightOff) next to the project name
  3. Confirm the deactivation in the dialog
  4. The project is marked as inactive and displays a "deactivated" chip
  5. Deactivated projects cannot be used for new resource assignments but remain visible for historical tracking

Searching for Billing Projects​

  1. Use the search bar at the top of the table
  2. Enter search terms matching name, ID, creator email, or date
  3. Results filter automatically with a 300ms debounce
  4. Clear the search by clicking the X icon in the search field
  5. Click "Refresh" to reload data with current filters
  • Sessions - Data science environments can be tagged with billing project IDs
  • Immediate Jobs - Pipeline jobs can be associated with billing projects for cost tracking
  • Scheduled Jobs - Recurring pipeline jobs can be assigned billing project identifiers
  • Services (Microservices) - Deployed services can be tagged with billing projects

Notes & Tips​

  • Billing project names cannot contain spaces - use dashes, underscores, or dots as separators
  • Project names must start and end with alphanumeric characters
  • Once created, billing project names cannot be changed - only deactivation is supported
  • Deactivated projects remain in the system permanently for audit and historical tracking purposes
  • Use descriptive naming conventions that align with your organization's cost center or project structure
  • The dropdown menu in each table row provides quick navigation to view all resources associated with that project
  • Search functionality supports date formats when filtering by creation or deactivation dates
  • Copy-to-clipboard buttons are provided for both project names and IDs for easy reference
  • When a billing project is deactivated, existing resources retain their association but new resources cannot be created with that project ID
  • Regular users can only see and manage their own billing projects unless they have admin or maintainer roles
  • The table displays active projects by default, but the column visibility toggle allows viewing deactivation dates for historical analysis
Last updated on by chyuen-devsentient