Zymergi.Core 11.1.1-alpha

Zymergi.Core

Foundation library for Zymergi SaaS apps: persistence contracts, domain models, engine-neutral search, the IMarkdownRenderer contract, logging, HTTP helpers, and utilities. Other Zymergi.* packages implement these contracts for a specific database, search engine, or host.

Targets .NET 10. This package has no Zymergi project dependencies.

Install

dotnet add package Zymergi.Core

What you get

• Persistence — IEntity, IRegistrable, IRepository<T>, registry/handle uniqueness, ADO.NET helpers, DbUnitOfWork
• Search — ISearchProvider<T>, ISearchIndexer<T>, IIndexManager, filter AST, facets, SearchCapabilities
• Rendering contract — IMarkdownRenderer. HTML, Markdown, and XSLT implementations are in Zymergi.Rendering
• Storage & identity contracts — IBucket / ISimpleObject, IAuthManagementClient
• Logging & utilities — Loggor (Microsoft.Extensions.Logging.ILogger), string/XML/JSON/HTTP extension methods

JSON serialization uses Newtonsoft.Json. Persistence is raw ADO.NET, not Entity Framework. Prefer RemoveAsync() (soft delete) over DeleteAsync().

Usage

Application code depends on the interfaces in this package. MarkdigRenderer and the XSLT pool are in Zymergi.Rendering. Register a concrete adapter for the engine you use:

using Zymergi.Articles;

// Search — pick one adapter at startup
services.AddElasticSearch(config).AddElasticSearchIndex<ArticleSearchDocument>("articles", d => d.Id);
// or AddMeiliSearch / AddSqliteSearch

// Persistence — generic MariaDB repositories live in Zymergi.Data.MariaDb.
// Users, groups, and favorites are registered from Zymergi.Social.MariaDb.

Config

Configuration binding classes for appsettings.json. These types are deserialized by the .NET IConfiguration system and provide strongly-typed access to connection strings and ADO.NET provider factories.

Data

ADO.NET database access layer built on extension methods rather than an ORM. Provides parameterized query building, transaction management, and the generic repository contracts. Domain repository interfaces live in their domain packages.

Interfaces

Classes

Extension methods

Http

HTTP client utilities for remote data sources. Provides content helpers for JSON and multipart payloads and a generic HTTP-backed repository contract. CachedServiceBase lives in Zymergi.AspNetCore (namespace Zymergi.Http).

Identity

Provider-neutral auth management contracts. IAuthManagementClient defines a provider-neutral contract for user and role CRUD that is implemented by Zymergi.Identity.Auth0. ClaimsList and ClaimsExtensionMethods live in Zymergi.AspNetCore.

Interfaces

Core domain contracts that define the entity and repository model used throughout the system. Every persistable object implements IEntity; objects that need globally unique handles implement IRegistrable. Repositories follow a consistent contract with CRUD, pagination, soft-delete, and event support.

Json

Custom Newtonsoft.Json converters for handling non-standard JSON shapes.

Logging

Structured logging with performance tracking. Loggor (namespace Zymergi.Logging) is the central static logger. It writes through Microsoft.Extensions.Logging.ILogger from package Microsoft.Extensions.Logging.Abstractions. The host creates the four loggers and configures their sinks. LogEntry / LogRecord capture the when/where/who/what context. PerfTracker measures function execution time and logs results automatically.

using Microsoft.Extensions.Logging;
using Zymergi.Logging;

void Configure(ILoggerFactory factory)
{
    Loggor.Initialize(
        factory.CreateLogger("Usage"),
        factory.CreateLogger("Error"),
        factory.CreateLogger("Perf"),
        factory.CreateLogger("Diag"));
}

Loggor.WriteUsage(new LogEntry("viewed a page") { Product = "App", Layer = "Web" });

Initialize assigns UsageLogger, ErrorLogger, PerfLogger, and DiagLogger. Each Write* call logs only when that field is set. WriteDiagnostic also requires EnableDiagnostics. WriteError copies the innermost exception message onto ILogEntry.Message and passes the exception to ILogger.Log. The message template names the entry's fields ({Message}, {Product}, {Layer}, and the rest); caller text is a property value.

Models

Shared base types implementing the IEntity / IRegistrable hierarchy. EntityBase provides the shared UID and timestamp fields; RegistryItem adds handle, name, and type for entities tracked in the central registry.

Domain entity types live in feature packages: articles in Zymergi.Articles, users/groups/comments/submissions in Zymergi.Social.

Search

Engine-neutral, faceted document-search abstraction. Defines contracts that decouple application code from any specific search engine. Elasticsearch implements them in Zymergi.Search.Elastic, MeiliSearch in Zymergi.Search.Meili, and embedded SQLite in Zymergi.Search.Sqlite; a future engine implements the same contracts and proves itself against the shared conformance suite in tests/Zymergi.Search.Conformance.Tests.

Scope: structured, faceted search — full-text query + filters + facets + sort over a typed document. It is deliberately not the home for vector/semantic search, autocomplete, or recommendations; those would be separate contracts.

Contracts

One provider/indexer instance is bound to one index; the document id is extracted via a key selector supplied at construction, so TDocument stays a plain model.

Request model

Recency is best-effort — the one exception to the fail-loud rule. Unlike an unsupported facet (which throws UnsupportedSearchFeatureException), a provider that does not support recency (SearchCapabilities.SupportsRecency == false) ignores SearchRequest.Recency silently. An explicit Sort always takes precedence over it.

Result model

Schema & errors

Engine differences & conventions

These are engine-neutral guarantees; where engines legitimately differ, SearchCapabilities and SearchResult.TotalAccuracy report it explicitly rather than hiding it:

• Total accuracy — Elasticsearch (track_total_hits) and SQLite (COUNT) return exact totals; MeiliSearch reports an estimate (SupportsExactTotalCount = false, TotalCountAccuracy.Estimate).
• Highlighting — Elasticsearch returns multiple fragments per field; MeiliSearch and SQLite (FTS5 highlight()) return the whole field with match tags as a single fragment (the in-memory reference approximates the latter). All fit SearchHit.Highlights (a list per field), but snippet granularity differs.
• Relevance score — SearchHit.Score carries the engine's score (_score for Elasticsearch, _rankingScore for MeiliSearch, negated bm25() rank for SQLite); the in-memory reference leaves it null.
• Range semantics — RangeFilter is half-open by default (MinInclusive = true, MaxInclusive = false), i.e. [min, max), consistent with RangeFacet bands. Set the flags explicitly for other bounds.
• Paging / limits — Offset/Limit and facet MaxValues are passed through as requested; there are no framework-imposed upper bounds, but an engine may cap them (e.g. MeiliSearch maxValuesPerFacet defaults to 100, surfaced via SearchCapabilities.MaxFacetValues).

Article search lives in the Zymergi.Articles package (not here).

Storage

Cloud object storage abstractions. Defines provider-neutral contracts for bucket-based CRUD. The AWS S3 implementation lives in Zymergi.Storage.Aws.

Utilities

General-purpose extension methods used across the solution. These are the primary API surface for common operations on strings, collections, XML, JSON, streams, and dates.

RSS/Atom helpers (SyndicationFeedExtensionMethods) live in Zymergi.Rendering.

Related packages

Source: bitbucket.org/zymergy/zymergi.saas