Azka.BaseProject 10.0.0-rc.1

Azka.BaseProject

Reusable base project primitives for Azka applications. This package provides auditable document entities, multi-tenant document fields, a core repository abstraction, soft-delete behavior, public ID lookup, and SSO user contracts for filling audit metadata.

Azka.BaseProject is intended to sit above the Azka core framework and database provider packages. It gives application projects a consistent base model and repository shape, while the application still owns concrete entities, database registration, and SSO user resolution.

What This Package Provides

• Core Document Entity - CoreEntity with internal ID, public ID, document lifecycle fields, and audit metadata
• Multi-Tenant Entity Base - CoreEntityMultiTenant with company and company branch scoping fields
• Core Repository Contract - ICoreRepository<T> extends Azka repository contracts with public ID lookup
• Core Repository Base - CoreRepository<T> for common active-document queries, add, update, and soft delete
• Soft Delete Filtering - Read operations automatically exclude rows where DeletedAt is set
• Audit Metadata Handling - Add, update, and delete operations resolve the current user through IUserSsoService
• SSO User Contract - UserSso and IUserSsoService abstractions for authenticated user data and access checks
• Document Lifecycle Enum - DocumentType for draft, original, and archived document states

What This Package Does Not Provide

• A concrete SSO implementation
• Application-specific permission rules
• Database table migrations or schema scripts
• Automatic dependency injection registration
• A complete application Unit of Work

Applications are expected to implement IUserSsoService, create concrete entities and repositories, and register the database provider such as Azka.PostgreSQL.

Installation

dotnet add package Azka.BaseProject

This package references the Azka core framework and Azka PostgreSQL provider from the solution package graph.

Core Concepts

Core Entity

Inherit from CoreEntity when an entity needs the standard document fields used by Azka application projects.

using Azka.BaseProject;
using Azka.Common.Annotations;

[Table("public", "products")]
public class Product : CoreEntity
{
    [Column("name")]
    public string Name { get; set; } = string.Empty;

    [Column("description")]
    public string? Description { get; set; }
}

CoreEntity includes:

Multi-Tenant Entity

Use CoreEntityMultiTenant when the document should be scoped by company and optionally by company branch.

using Azka.BaseProject;
using Azka.Common.Annotations;

[Table("public", "purchase_orders")]
public class PurchaseOrder : CoreEntityMultiTenant
{
    [Column("document_number")]
    public string DocumentNumber { get; set; } = string.Empty;

    [Column("total_amount")]
    public decimal TotalAmount { get; set; }
}

CoreEntityMultiTenant adds:

Both properties are nullable strings. The base repository does not automatically apply company or branch filters; application repositories or services should add those filters through specifications according to the current user's access rules.

Document Lifecycle

DocumentType represents the lifecycle state of a document.

Repository

Create application repositories by inheriting from CoreRepository<T>.

using Azka.BaseProject;
using Azka.Common.Database;

public interface IProductRepository : ICoreRepository<Product>
{
}

public sealed class ProductRepository : CoreRepository<Product>, IProductRepository
{
    public ProductRepository(
        IDatabaseContext databaseContext,
        IUserSsoService userSsoService)
        : base(databaseContext, userSsoService)
    {
    }
}

CoreRepository<T> delegates persistence and querying to IDatabaseContext, then applies application-level behavior:

• Read operations wrap incoming specifications with DeletedAt == null.
• GetByIdAsync(...) returns an active document by internal primary key.
• GetByPublicIdAsync(...) returns an active document by public Guid.
• AddAsync(...) fills CreatedAt and CreatedBy.
• UpdateAsync(...) fills UpdatedAt and UpdatedBy.
• DeleteAsync(...) performs a soft delete by filling DeletedAt and DeletedBy.

Repository API Reference

ICoreRepository<T> extends Azka.Common.Abstractions.Repositories.IViewRepository<T> and adds core document write methods, internal ID lookup, and public ID lookup.

Constructor:

Query methods:

Write methods:

The repository uses internal specifications for common filters:

Repository Usage

using Azka.Common.Abstractions.Specifications;

public sealed class ProductByNameSpecification : Specification<Product>
{
    public ProductByNameSpecification(string name)
    {
        Query.Where(product => product.Name == name);
    }
}

public sealed class ProductService
{
    private readonly IProductRepository _products;

    public ProductService(IProductRepository products)
    {
        _products = products;
    }

    public Task<Product?> FindByNameAsync(string name, CancellationToken cancellationToken = default)
    {
        return _products.FirstOrDefaultAsync(
            new ProductByNameSpecification(name),
            cancellationToken);
    }

    public Task<Product> FindByPublicIdAsync(Guid publicId, CancellationToken cancellationToken = default)
    {
        return _products.GetByPublicIdAsync(publicId, cancellationToken);
    }
}

SSO User Service

Applications must implement IUserSsoService so repositories can resolve audit metadata and services can check access permissions.

using Azka.BaseProject;

public sealed class AppUserSso : UserSso
{
}

public sealed class UserSsoService : IUserSsoService
{
    public Task<UserSso> GetCurrentUserAsync(CancellationToken cancellationToken = default)
    {
        UserSso user = new AppUserSso
        {
            UserName = "admin",
            Email = "admin@example.com",
            FullName = "Application Admin",
            CompanyCode = "AZKA",
            CompanyBranchCode = "HQ"
        };

        return Task.FromResult(user);
    }

    public Task<bool> IsAllowAccessAsync(string permission, CancellationToken cancellationToken = default)
    {
        return Task.FromResult(true);
    }

    public Task<bool> IsAllowAccessAllCompany()
    {
        return Task.FromResult(false);
    }

    public Task<bool> IsAllowAccessAllCompanyBranch()
    {
        return Task.FromResult(false);
    }
}

Register the implementation in dependency injection with your repositories and database provider.

builder.Services.AddScoped<IUserSsoService, UserSsoService>();
builder.Services.AddScoped<IProductRepository, ProductRepository>();

SSO API Reference

IUserSsoService is the application-owned contract used by this package to resolve the authenticated user and permission checks.

UserSso contains the authenticated user's identity and scope information:

Database Mapping

Because CoreEntity already maps standard fields with Azka attributes, database tables should include the matching columns.

CREATE TABLE public.products
(
    id bigint PRIMARY KEY,
    public_id uuid NOT NULL,
    original_id bigint NULL,
    source_id bigint NULL,
    is_saved boolean NOT NULL,
    document_type integer NOT NULL,
    created_at timestamp with time zone NOT NULL,
    created_by text NOT NULL,
    updated_at timestamp with time zone NULL,
    updated_by text NULL,
    deleted_at timestamp with time zone NULL,
    deleted_by text NULL,
    name text NOT NULL,
    description text NULL
);

CREATE SEQUENCE products_id_seq START 1;

CoreEntity.Id uses [GeneratedNumber], so the PostgreSQL provider expects the standard generated-number sequence convention:

{table_name}_{column_name}_seq

For the products.id example, the expected sequence is products_id_seq.

Soft Delete Behavior

DeleteAsync(...) does not physically remove the row. It loads the active document, fills deletion metadata, and updates the record.

var affectedRows = await _products.DeleteAsync(productId, cancellationToken);

After deletion, repository read operations exclude the record because CoreRepository<T> applies the active-document specification.

Requirements

• .NET 10.0 or higher
• Azka core framework
• Azka PostgreSQL provider

Links

• Azka Documentation
• Azka NuGet Package
• Azka.PostgreSQL NuGet Package