Appointment Type Commands and Queries in ClinicFlow

Appointment types (AppointmentTypeDefinition) define the catalogue of clinical services a clinic offers. Each type carries a category, duration, an age eligibility policy, specialty restrictions, and a list of required clinical form templates that must be completed during the encounter. All write operations use soft-delete semantics — deactivation sets IsDeleted = true via SoftDeletableEntity.MarkAsDeleted() and is reversible with ReactivateAppointmentType.

Create and Update Commands

`CreateAppointmentTypeCommand`

Creates a new active appointment type definition. Returns: IRequest<Guid> — the new type’s Id.

public sealed record CreateAppointmentTypeCommand(
    AppointmentCategory Category,
    string Name,
    string Description,
    int DurationMinutes,
    int? MinimumAge,
    int? MaximumAge,
    bool RequiresGuardianConsent
) : IRequest<Guid>;

Category

AppointmentCategory

required

The clinical category. One of FirstConsultation (1), FollowUp (2), Emergency (3), Checkup (4), Procedure (5).

Name

string

required

Unique display name for the appointment type. The handler throws BusinessRuleValidationException (DomainErrors.AppointmentType.NameAlreadyExists) if the name is already in use. Cannot be null or whitespace.

Description

string

required

Human-readable description of the appointment type.

DurationMinutes

int

required

Expected consultation duration in minutes. Converted to EncounterDuration.FromMinutes(value).

MinimumAge

int?

Optional minimum patient age in years. null means no lower bound.

MaximumAge

int?

Optional maximum patient age in years. null means no upper bound.

When true, patients below the minimum age require a legal guardian to consent. Stored in AgeEligibilityPolicy.RequiresLegalGuardian.

Handler behaviour:

Checks name uniqueness via IAppointmentTypeDefinitionRepository.ExistsByNameAsync.
Constructs AgeEligibilityPolicy.Create(minAge, maxAge, requiresGuardian).
Calls AppointmentTypeDefinition.Create(category, name, description, duration, agePolicy) — new types are IsUnrestrictedBySpecialty = true by default.
Persists and returns the new Guid.

`UpdateAppointmentTypeCommand`

Updates the core details of an existing appointment type (category, name, description, duration). Does not modify the age policy or specialty restrictions — use dedicated commands for those. Returns: IRequest (no return value)

public sealed record UpdateAppointmentTypeCommand(
    Guid AppointmentTypeId,
    AppointmentCategory Category,
    string Name,
    string Description,
    int DurationMinutes
) : IRequest;

AppointmentTypeId

Guid

required

The type to update. Throws EntityNotFoundException if not found.

Category

AppointmentCategory

required

New category value.

Name

string

required

New name. Checked for uniqueness against other types (excluding AppointmentTypeId itself) via ExistsByNameExcludingAsync.

Description

string

required

New description.

DurationMinutes

int

required

New duration in minutes.

Activation Commands

`DeactivateAppointmentTypeCommand`

Soft-deletes an appointment type, removing it from the active catalogue. Returns: IRequest (no return value)

public sealed record DeactivateAppointmentTypeCommand(Guid AppointmentTypeId) : IRequest;

AppointmentTypeId

Guid

required

The type to deactivate. Throws BusinessRuleValidationException (DomainErrors.AppointmentType.AlreadyInactive) if already deactivated.

Handler behaviour: Loads the type from the active-only repository scope, calls appointmentType.Deactivate() which internally calls MarkAsDeleted().

`ReactivateAppointmentTypeCommand`

Restores a previously deactivated appointment type. Returns: IRequest (no return value)

public sealed record ReactivateAppointmentTypeCommand(Guid AppointmentTypeId) : IRequest;

AppointmentTypeId

Guid

required

The type to reactivate. Must currently be soft-deleted. Uses GetByIdIncludingDeletedAsync to find it.

Handler behaviour:

Loads the type including soft-deleted records via GetByIdIncludingDeletedAsync.
Re-checks name uniqueness against the active catalogue — throws BusinessRuleValidationException (DomainErrors.AppointmentType.NameAlreadyExists) if another active type now has the same name.
Calls appointmentType.Reactivate(), which calls UndoDeletion().

Specialty Restriction Commands

Specialty restrictions control which doctor specialties are eligible to perform a given appointment type. New types start as IsUnrestrictedBySpecialty = true (any doctor can schedule them). Use RestrictAppointmentTypeToSpecialties to narrow access.

`RestrictAppointmentTypeToSpecialtiesCommand`

Switches an unrestricted appointment type to specialty-restricted mode and sets the initial allowed specialty list. Returns: IRequest (no return value)

public sealed record RestrictAppointmentTypeToSpecialtiesCommand(
    Guid AppointmentTypeId,
    IReadOnlyCollection<Guid> SpecialtyIds
) : IRequest;

AppointmentTypeId

Guid

required

The type to restrict. Throws DomainValidationException (DomainErrors.AppointmentType.AlreadyRestricted) if already restricted.

SpecialtyIds

IReadOnlyCollection<Guid>

required

Non-empty list of MedicalSpecialty.Id values. Duplicates and empty Guids are rejected. Must contain at least one entry (DomainErrors.AppointmentType.RequiresAtLeastOneSpecialty).

`MakeAppointmentTypeUnrestrictedCommand`

Removes all specialty restrictions, making the type available to all doctor specialties. Returns: IRequest (no return value)

public sealed record MakeAppointmentTypeUnrestrictedCommand(Guid AppointmentTypeId) : IRequest;

AppointmentTypeId

Guid

required

The type to make unrestricted. Throws DomainValidationException (DomainErrors.AppointmentType.AlreadyUnrestricted) if already unrestricted. Clears AllowedSpecialtyIds and sets IsUnrestrictedBySpecialty = true.

`AddAllowedSpecialtyToAppointmentTypeCommand`

Adds a single specialty to the allowed list of an already-restricted appointment type. Returns: IRequest (no return value)

public sealed record AddAllowedSpecialtyToAppointmentTypeCommand(
    Guid AppointmentTypeId,
    Guid SpecialtyId
) : IRequest;

AppointmentTypeId

Guid

required

The restricted appointment type to update. Throws DomainValidationException (DomainErrors.AppointmentType.CannotAddSpecialtyToGlobalType) if the type is unrestricted.

SpecialtyId

Guid

required

The MedicalSpecialty.Id to allow. Throws if already present (DomainErrors.AppointmentType.SpecialtyAlreadyAllowed) or if the Guid is empty.

`RemoveAllowedSpecialtyFromAppointmentTypeCommand`

Removes a single specialty from the allowed list. At least one specialty must remain. Returns: IRequest (no return value)

public sealed record RemoveAllowedSpecialtyFromAppointmentTypeCommand(
    Guid AppointmentTypeId,
    Guid SpecialtyId
) : IRequest;

AppointmentTypeId

Guid

required

The restricted appointment type. Throws DomainValidationException (DomainErrors.AppointmentType.CannotRemoveSpecialtyFromGlobalType) if unrestricted.

SpecialtyId

Guid

required

The specialty to remove. Throws if not found (DomainErrors.AppointmentType.SpecialtyNotFound) or if it is the last remaining specialty (DomainErrors.AppointmentType.RequiresAtLeastOneSpecialty).

Clinical Form Template Commands

Required templates define which clinical forms must be completed for an appointment of this type during the encounter.

`AddRequiredTemplateToAppointmentTypeCommand`

Associates a clinical form template with an appointment type, making it required for all future appointments of that type. Returns: IRequest (no return value)

public sealed record AddRequiredTemplateToAppointmentTypeCommand(
    Guid AppointmentTypeId,
    Guid TemplateId
) : IRequest;

AppointmentTypeId

Guid

required

The appointment type to update.

TemplateId

Guid

required

The ClinicalFormTemplate.Id to require. The handler resolves the template via IClinicalFormTemplateRepository. Throws EntityNotFoundException if not found. Throws DomainValidationException (DomainErrors.AppointmentType.TemplateAlreadyRequired) if already attached (matched by Id or Code).

`RemoveRequiredTemplateFromAppointmentTypeCommand`

Removes a clinical form template requirement from an appointment type. Returns: IRequest (no return value)

public sealed record RemoveRequiredTemplateFromAppointmentTypeCommand(
    Guid AppointmentTypeId,
    Guid TemplateId
) : IRequest;

AppointmentTypeId

Guid

required

The appointment type to update.

TemplateId

Guid

required

The ClinicalFormTemplate.Id to remove. Throws DomainValidationException (DomainErrors.AppointmentType.TemplateNotFound) if not currently required.

Age Policy Command

`ChangeAppointmentTypeAgePolicyCommand`

Replaces the age eligibility policy on an existing appointment type. Returns: IRequest (no return value)

public sealed record ChangeAppointmentTypeAgePolicyCommand(
    Guid AppointmentTypeId,
    int? MinimumAge,
    int? MaximumAge,
    bool RequiresGuardianConsent
) : IRequest;

AppointmentTypeId

Guid

required

The type whose age policy to change.

MinimumAge

int?

New minimum age in years. null removes the lower bound. Stored in AgeEligibilityPolicy.MinimumAge.

MaximumAge

int?

New maximum age in years. null removes the upper bound. Stored in AgeEligibilityPolicy.MaximumAge.

New guardian consent requirement. Stored in AgeEligibilityPolicy.RequiresLegalGuardian.

Handler behaviour: Constructs AgeEligibilityPolicy.Create(minAge, maxAge, requiresGuardian) and calls appointmentType.ChangeAgePolicy(agePolicy). Passing null for both ages with false for guardian consent is equivalent to AgeEligibilityPolicy.NoRestriction.

Queries

`GetAllActiveAppointmentTypesQuery`

Returns all non-deleted appointment types. Returns: IRequest<IReadOnlyList<AppointmentTypeDto>>

public sealed record GetAllActiveAppointmentTypesQuery
    : IRequest<IReadOnlyList<AppointmentTypeDto>>;

This query has no parameters. It calls IAppointmentTypeDefinitionRepository.GetAllActiveAsync() which filters out soft-deleted records.

`GetAppointmentTypeByIdQuery`

Returns a single appointment type by its primary key. Returns: IRequest<AppointmentTypeDto>

public sealed record GetAppointmentTypeByIdQuery(Guid AppointmentTypeId)
    : IRequest<AppointmentTypeDto>;

AppointmentTypeId

Guid

required

The type’s primary key. Throws EntityNotFoundException if not found or if soft-deleted.

`GetAppointmentTypesByCategoryQuery`

Returns all active appointment types for a specific clinical category. Returns: IRequest<IReadOnlyList<AppointmentTypeDto>>

public sealed record GetAppointmentTypesByCategoryQuery(AppointmentCategory Category)
    : IRequest<IReadOnlyList<AppointmentTypeDto>>;

Category

AppointmentCategory

required

The category to filter by. One of FirstConsultation (1), FollowUp (2), Emergency (3), Checkup (4), Procedure (5).

`GetEligibleAppointmentTypesQuery`

Returns all active appointment types whose age policy allows a patient of the given age. Returns: IRequest<IReadOnlyList<AppointmentTypeDto>>

public sealed record GetEligibleAppointmentTypesQuery(int PatientAgeInYears)
    : IRequest<IReadOnlyList<AppointmentTypeDto>>;

PatientAgeInYears

int

required

The patient’s age in full years. Used to filter types via IAppointmentTypeDefinitionRepository.GetEligibleByAgeAsync(ageInYears).

Use this query to populate the appointment type picker on the scheduling form. It respects MinimumAge and MaximumAge bounds automatically, returning only types the patient is age-eligible for.

AppointmentTypeDto Response Shape

All queries return AppointmentTypeDto or IReadOnlyList<AppointmentTypeDto>.

public sealed record AppointmentTypeDto(
    Guid Id,
    string Category,
    string Name,
    string Description,
    int DurationMinutes,
    int? MinimumAge,
    int? MaximumAge,
    bool RequiresLegalGuardian,
    bool IsUnrestrictedBySpecialty,
    IReadOnlyCollection<Guid> AllowedSpecialtyIds,
    IReadOnlyCollection<ClinicalFormTemplateDto> RequiredTemplates
);

Guid

The type’s primary key.

Category

string

The category name as a string (e.g., "FirstConsultation"). Serialized from AppointmentCategory.ToString().

Name

string

The unique display name.

Description

string

Human-readable description.

DurationMinutes

int

Expected consultation duration in minutes (from EncounterDuration.Minutes).

MinimumAge

int?

The minimum patient age in years required by AgeEligibilityPolicy. null means no lower bound.

MaximumAge

int?

The maximum patient age in years allowed by AgeEligibilityPolicy. null means no upper bound.

RequiresLegalGuardian

bool

When true, a legal guardian must be present and consent must be verified before scheduling.

IsUnrestrictedBySpecialty

bool

When true, any doctor regardless of specialty can schedule this type. When false, AllowedSpecialtyIds is authoritative.

AllowedSpecialtyIds

IReadOnlyCollection<Guid>

Populated only when IsUnrestrictedBySpecialty = false. Contains MedicalSpecialty.Id values of permitted specialties.

RequiredTemplates

IReadOnlyCollection<ClinicalFormTemplateDto>

Clinical form templates that must be completed during appointments of this type. See ClinicalFormTemplateDto below.

AgeEligibilityPolicy Fields

The AgeEligibilityPolicy value object is flattened into AppointmentTypeDto and CreateAppointmentTypeCommand/ChangeAppointmentTypeAgePolicyCommand. Its three fields are:

Field	Type	Description
`MinimumAge`	`int?`	Minimum patient age in full years. `null` = unrestricted.
`MaximumAge`	`int?`	Maximum patient age in full years. `null` = unrestricted.
`RequiresLegalGuardian`	`bool`	Whether guardian consent must be verified before scheduling.

AgeEligibilityPolicy.NoRestriction is a static sentinel with all three fields unset (both ages null, guardian false). It is the default applied when Create is called with all-null age arguments.

ClinicalFormTemplateDto

Embedded in AppointmentTypeDto.RequiredTemplates.

public sealed record ClinicalFormTemplateDto(
    Guid Id,
    string Code,
    string Name,
    string Description,
    string JsonSchemaDefinition,
    bool IsDeleted
);

Guid

The template’s primary key.

Code

string

Unique business key (e.g., "BLOOD_PRESS"). Used for stable programmatic reference.

Name

string

Human-readable template name.

Description

string

Description of what the form captures.

JsonSchemaDefinition

string

Raw JSON Schema Draft-07 string used to validate form submissions at runtime.

IsDeleted

bool

Whether the template has been soft-deleted. A required template may reference a soft-deleted template if it was added before deletion.

AppointmentCategory Enum

public enum AppointmentCategory
{
    FirstConsultation = 1,  // Initial visit with a new patient
    FollowUp          = 2,  // Return visit to review diagnosis/treatment
    Emergency         = 3,  // Urgent unscheduled visit
    Checkup           = 4,  // Routine preventive examination
    Procedure         = 5,  // Medical or surgical procedure
}

Users & Authentication

Appointments

Clinic Management

Records & Compliance

Appointment Type Commands and Queries in ClinicFlow

Create and Update Commands

`CreateAppointmentTypeCommand`

`UpdateAppointmentTypeCommand`

Activation Commands

`DeactivateAppointmentTypeCommand`

`ReactivateAppointmentTypeCommand`

Specialty Restriction Commands

`RestrictAppointmentTypeToSpecialtiesCommand`

`MakeAppointmentTypeUnrestrictedCommand`

`AddAllowedSpecialtyToAppointmentTypeCommand`

`RemoveAllowedSpecialtyFromAppointmentTypeCommand`

Clinical Form Template Commands

`AddRequiredTemplateToAppointmentTypeCommand`

`RemoveRequiredTemplateFromAppointmentTypeCommand`

Age Policy Command

`ChangeAppointmentTypeAgePolicyCommand`

Queries

`GetAllActiveAppointmentTypesQuery`

`GetAppointmentTypeByIdQuery`

`GetAppointmentTypesByCategoryQuery`

`GetEligibleAppointmentTypesQuery`

AppointmentTypeDto Response Shape

AgeEligibilityPolicy Fields

ClinicalFormTemplateDto

AppointmentCategory Enum

Build docs developers (and LLMs) love

Users & Authentication

Appointments

Clinic Management

Records & Compliance

Documentation Index

​Create and Update Commands

​CreateAppointmentTypeCommand

​UpdateAppointmentTypeCommand

​Activation Commands

​DeactivateAppointmentTypeCommand

​ReactivateAppointmentTypeCommand

​Specialty Restriction Commands

​RestrictAppointmentTypeToSpecialtiesCommand

​MakeAppointmentTypeUnrestrictedCommand

​AddAllowedSpecialtyToAppointmentTypeCommand

​RemoveAllowedSpecialtyFromAppointmentTypeCommand

​Clinical Form Template Commands

​AddRequiredTemplateToAppointmentTypeCommand

​RemoveRequiredTemplateFromAppointmentTypeCommand

​Age Policy Command

​ChangeAppointmentTypeAgePolicyCommand

​Queries

​GetAllActiveAppointmentTypesQuery

​GetAppointmentTypeByIdQuery

​GetAppointmentTypesByCategoryQuery

​GetEligibleAppointmentTypesQuery

​AppointmentTypeDto Response Shape

​AgeEligibilityPolicy Fields

​ClinicalFormTemplateDto

​AppointmentCategory Enum

Build docs developers (and LLMs) love

Create and Update Commands

`CreateAppointmentTypeCommand`

`UpdateAppointmentTypeCommand`

Activation Commands

`DeactivateAppointmentTypeCommand`

`ReactivateAppointmentTypeCommand`

Specialty Restriction Commands

`RestrictAppointmentTypeToSpecialtiesCommand`

`MakeAppointmentTypeUnrestrictedCommand`

`AddAllowedSpecialtyToAppointmentTypeCommand`

`RemoveAllowedSpecialtyFromAppointmentTypeCommand`

Clinical Form Template Commands

`AddRequiredTemplateToAppointmentTypeCommand`

`RemoveRequiredTemplateFromAppointmentTypeCommand`

Age Policy Command

`ChangeAppointmentTypeAgePolicyCommand`

Queries

`GetAllActiveAppointmentTypesQuery`

`GetAppointmentTypeByIdQuery`

`GetAppointmentTypesByCategoryQuery`

`GetEligibleAppointmentTypesQuery`

AppointmentTypeDto Response Shape

AgeEligibilityPolicy Fields

ClinicalFormTemplateDto

AppointmentCategory Enum