Domains in comby: default

The default domains in comby form the foundational structure of the system. Each domain represents a specific area of concern in the application, enabling modular design and easy extension. These default domains cater to essential functionality such as user management, organizational structures, group and identity management. Together, they provide a comprehensive framework for building robust, multi-tenant, and event-sourced applications.

Comby default consists of two main components:

• the defaults for the domain (or default domains) and
• the defaults for the REST API (or default API).

Here is a representation that illustrates everything in green belongs to the default. Additional user-specific domains are represented under custom domain and custom API which of course have access to default. For example, developers are able to reuse the existing Permission layer or access the runtime information. Here it is just an illustration where default live when used in the application.

Developers are free to use default in their application. It is not necessary to use them; however, without them, developers work solely with the bare Facade. In this case, features such as the Admin Dashboard, API Explorer, multi-tenancy, RBAC (Role-Based Access Control), REST API and others are not available. However, there are use cases where this approach makes sense. For example, in edge computing or IoT applications.

INFO

Developers can either use the defaults as a whole or not at all. The default components only work together as a complete set. If a developer chooses to use only Account and Tenant, the features mentioned above will not be available.

Account

The Account domain focuses on managing user credentials, sessions, and states. It supports various lifecycle states such as registered, active, blocked, and removed, while providing capabilities for password management, one-time tokens, and secure session handling. Accounts are central to user authentication and the management of individual user actions within the system.

Tenant

The Tenant domain represents organizations or logical groupings, serving as the foundation for multi-tenant architecture. Tenants encapsulate metadata such as names, secrets, and additional properties, enabling resource isolation and configuration management for different organizational contexts. This domain supports the creation, update, and deletion of tenants, acting as the primary boundary for tenant-specific resources.

Group

The Group domain is designed to manage role-based permissions and organizational structures within a tenant. Groups store runtime permissions, allowing granular control over access to system features. Identities, which represent users, can belong to one or more groups, enabling complex permission hierarchies and role management within a tenant.

Identity

The Identity domain captures tenant-specific user representations. It links to accounts for authentication, supports profiles with details such as names, emails, and avatars, and manages tokens for API access and group memberships. Identities form the basis for tenant-level user management, allowing users to belong to specific tenants with well-defined roles and permissions.

Invitation

The Invitation domain handles the lifecycle of user invitations, enabling seamless onboarding into tenants or groups. It tracks the creation, sending, acceptance, or decline of invitations, while ensuring secure workflows with tokens. Invitations bridge external users into the system, simplifying the process of joining tenants or groups.

Asset

The Asset domain provides a framework for managing resources such as files or documents. It tracks metadata, including name, size, content type, and storage paths, and supports tagging, access control, and integration with external storage systems. Assets are essential for handling tenant or user-specific data, ensuring secure and organized resource management.

Webhook

The Webhook domain enables integration with external systems through event-driven notifications. It stores webhook URLs, the types of events they respond to, and their active status. Webhooks allow external systems to react to domain events in real time, fostering connectivity and automation with third-party platforms.

Auth

The Auth domain provides authentication and authorization mechanisms for user management. It supports user authentication, session management with tokens, and role-based access control (RBAC) for securing resources. This domain is essential for enforcing security policies and managing user permissions within the system.

Runtime

The Runtime domain provides tools for runtime system introspection and management. It exposes lists of commands, queries, events, and aggregates, supports Server-Sent Events (SSE) for real-time monitoring, and facilitates system debugging and administrative tasks. This domain is integral to maintaining and observing the health and behavior of the application in live environments.

Default's Environment Variables

The default domains in comby can be configured using environment variables. These variables allow developers to customize the behavior of the default domains without modifying the codebase. Here are some common environment variables used in the default domains:

INFO

If you want to overwrite the environment variables, you need to prefix the variable with COMBY_. For example, if you want to overwrite the SYSTEM_TENANT_UUID, you can set it as COMBY_SYSTEM_TENANT_UUID.

System-Tenant environment variables

// SYSTEM_TENANT_UUID represents the unique identifier for the system tenant,
// which can act across tenants in a multi-tenant system.
SYSTEM_TENANT_UUID string = "e7b828ac-eb9d-4d30-87c1-59fd9c0df047"

// SYSTEM_TENANT_NAME represents the name of the system tenant.
SYSTEM_TENANT_NAME string = "__SYSTEM__"

// SYSTEM_TENANT_GROUP_ADMIN_UUID represents the unique identifier for the system tenant group
// allowed to perform administrative tasks across tenants.
SYSTEM_TENANT_GROUP_ADMIN_UUID string = "c81dd852-b7f9-4b89-8968-2160be21f74a"

// SYSTEM_TENANT_GROUP_ADMIN_NAME represents the name of the system tenant admin group.
SYSTEM_TENANT_GROUP_ADMIN_NAME string = "system-admin"

// SYSTEM_TENANT_IDENTITY_UUID represents the unique identifier for the system tenant's identity,
// seeded within the system tenant.
SYSTEM_TENANT_IDENTITY_UUID string = "e7b828ac-b3e7-4156-b3b7-0cffeeaf1bda"

// SYSTEM_TENANT_IDENTITY_NAME represents the system tenant identity name.
SYSTEM_TENANT_IDENTITY_NAME string = "System-Tenant-Identity"

// SYSTEM_TENANT_ACCOUNT_ADMIN_EMAIL represents the email for the system admin account.
SYSTEM_TENANT_ACCOUNT_ADMIN_EMAIL string = "admin@comby.io"

// SYSTEM_TENANT_ACCOUNT_ADMIN_PASSWORD represents the password for the system admin account.
// `SYSTEM_TENANT_ACCOUNT_ADMIN_PASSWORD` is a variable that holds the password for the system admin
// account in the `comby` package. It is used to set the password for the system admin account within
// the system. The value of this variable is currently set to "Placeholder@1" as a default password.
// This password is used for authentication purposes when accessing the system admin account.
SYSTEM_TENANT_ACCOUNT_ADMIN_PASSWORD string = "Placeholder@1"

Account environment variables

// DEFAULT_ACCOUNT_REGISTRATION_MODE defines how default's account registration is allowed.
//
// - "invitation_only": Registration only allowed with valid invitation token.
// - "public": Registration allowed for everyone without invitation token.
// - "disabled": Registration is completely disabled.
DEFAULT_ACCOUNT_REGISTRATION_MODE string = "invitation_only"

Invitation environment variables

// DEFAULT_INVITATION_REACTOR_ENABLED defines whether the default invitation reactor is enabled by default (true by default).
	DEFAULT_INVITATION_REACTOR_ENABLED bool = true

Session and Refresh Token Duration

// DEFAULT_SESSION_DURATION_SECONDS defines the session lifetime in seconds.
// Default: 2592000 (30 days)
DEFAULT_SESSION_DURATION_SECONDS int64 = 2592000

// DEFAULT_REFRESH_TOKEN_DURATION_SECONDS defines the refresh token lifetime in seconds.
// Default: 31536000 (365 days / 1 year)
DEFAULT_REFRESH_TOKEN_DURATION_SECONDS int64 = 31536000

// DEFAULT_REFRESH_TOKEN_NOT_BEFORE_SECONDS defines the "not before" window in seconds.
// The refresh token becomes usable this many seconds BEFORE the linked session expires.
// Default: 604800 (7 days)
DEFAULT_REFRESH_TOKEN_NOT_BEFORE_SECONDS int64 = 604800

Default Readmodel / Reactor Ordering

// DEFAULT_ORDER_READMODEL defines the default order for read model event handlers.
DEFAULT_ORDER_READMODEL int = -20

// DEFAULT_ORDER_REACTOR defines the default order for reactor event handlers.
DEFAULT_ORDER_REACTOR int = -10

RegisterDefaults Options

When calling comby.RegisterDefaults(), you can pass options to customize behavior:

WithIncludeHistoryForDomains

Enable history event tracking for specific default domains. History events provide a complete audit trail of all changes to an aggregate.

import "github.com/gradientzero/comby/v2/domain/internal"

comby.RegisterDefaults(ctx, fc,
    internal.WithIncludeHistoryForDomains("Account", "Tenant", "Identity"),
)

Available domains: Account, Asset, Group, Identity, Invitation, Tenant, Webhook, Workspace

When enabled, you can query history via API:

GET /api/accounts/{accountUuid}?includeHistory=true

See Readmodel History Events for detailed documentation.

WithAuthorizationDisabled

Disable the authorization/permission system (useful for testing or internal services):

comby.RegisterDefaults(ctx, fc,
    internal.WithAuthorizationDisabled(true),
)

WithDefaultSeedEnabled

Control whether default seed data (system tenant, admin account) is created:

comby.RegisterDefaults(ctx, fc,
    internal.WithDefaultSeedEnabled(false), // Disable seeding
)