Organize backend into product executable and shared Go modules

backend/shared/README.md

@@ -0,0 +1,12 @@
+# Shared backend library
+
+This is a Go library module, not an executable. It provides database connections,
+transactions and repository primitives, errors, structured logging, generic HTTP
+responses, configuration and rate-limit helpers. It contains no customer, session,
+verification or Sendico domain models and imports no executable SXCHNGE module.
+
+`product` consumes it through a local module replacement. A future backoffice
+executable can consume the same infrastructure independently.
+
+Run `go test -race ./...` and `go vet ./...` here, or use the root Make targets to
+validate all implemented backend modules.

backend/shared/config/param.go

@@ -0,0 +1,74 @@
+package mutil
+
+import (
+	"os"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"go.uber.org/zap"
+)
+
+func GetConfigValue(logger mlogger.Logger, varName, envVarName string, value, envValue *string) string {
+	if value != nil && envValue != nil {
+		logger.Warn("Both variable and environment variable are set, using environment variable value",
+			zap.String("variable", varName), zap.String("environment_variable", envVarName), zap.String("value", *value), zap.String("env_value", os.Getenv(*envValue)))
+	}
+
+	if envValue != nil {
+		return os.Getenv(*envValue)
+	}
+
+	if value != nil {
+		return *value
+	}
+
+	return ""
+}
+
+func GetConfigIntValue(logger mlogger.Logger, varName, envVarName string, value *int, envValue *string) int {
+	if value != nil && envValue != nil {
+		logger.Warn("Both variable and environment variable are set, using environment variable value",
+			zap.String("variable", varName), zap.String("environment_variable", envVarName), zap.Int("value", *value), zap.String("env_value", os.Getenv(*envValue)))
+	}
+
+	if envValue != nil {
+		envStr := os.Getenv(*envValue)
+		if envStr != "" {
+			if parsed, err := time.ParseDuration(envStr + "s"); err == nil {
+				return int(parsed.Seconds())
+			}
+			logger.Warn("Invalid environment variable value for timeout", zap.String("environment_variable", envVarName), zap.String("value", envStr))
+		}
+	}
+
+	if value != nil {
+		return *value
+	}
+
+	return 30 // Default timeout in seconds
+}
+
+func GetConfigBoolValue(logger mlogger.Logger, varName, envVarName string, value *bool, envValue *string) bool {
+	if value != nil && envValue != nil {
+		logger.Warn("Both variable and environment variable are set, using environment variable value",
+			zap.String("variable", varName), zap.String("environment_variable", envVarName), zap.Bool("value", *value), zap.String("env_value", os.Getenv(*envValue)))
+	}
+
+	if envValue != nil {
+		envStr := os.Getenv(*envValue)
+		switch envStr {
+		case "true", "1":
+			return true
+		case "false", "0":
+			return false
+		default:
+			logger.Warn("Invalid environment variable value for boolean", zap.String("environment_variable", envVarName), zap.String("value", envStr))
+		}
+	}
+
+	if value != nil {
+		return *value
+	}
+
+	return false // Default for boolean
+}

backend/shared/database/config.go

@@ -0,0 +1,13 @@
+package db
+
+import (
+	sharedmodel "git.sendico.io/tech/sxchnge/shared/model"
+)
+
+type DBDriver string
+
+const (
+	Mongo DBDriver = "mongodb"
+)
+
+type Config = sharedmodel.DriverConfig[DBDriver]

backend/shared/database/connection.go

@@ -0,0 +1,59 @@
+package db
+
+import (
+	"context"
+
+	mongoimpl "git.sendico.io/tech/sxchnge/shared/database/internal/mongo"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/readpref"
+)
+
+// Connection represents a low-level database connection lifecycle.
+type Connection interface {
+	Disconnect(ctx context.Context) error
+	Ping(ctx context.Context) error
+}
+
+// MongoConnection provides direct access to the underlying mongo client.
+type MongoConnection struct {
+	client   *mongo.Client
+	database string
+}
+
+func (c *MongoConnection) Client() *mongo.Client {
+	return c.client
+}
+
+func (c *MongoConnection) Database() *mongo.Database {
+	return c.client.Database(c.database)
+}
+
+func (c *MongoConnection) Disconnect(ctx context.Context) error {
+	return c.client.Disconnect(ctx)
+}
+
+func (c *MongoConnection) Ping(ctx context.Context) error {
+	return c.client.Ping(ctx, readpref.Primary())
+}
+
+// ConnectMongo returns a low-level MongoDB connection without constructing repositories.
+func ConnectMongo(logger mlogger.Logger, config *Config) (*MongoConnection, error) {
+	if config == nil {
+		return nil, merrors.InvalidArgument("database configuration is nil", "config")
+	}
+	if config.Driver != Mongo {
+		return nil, merrors.InvalidArgument("unsupported database driver: "+string(config.Driver), "config.driver")
+	}
+
+	client, _, settings, err := mongoimpl.ConnectClient(logger, config.Settings)
+	if err != nil {
+		return nil, err
+	}
+
+	return &MongoConnection{
+		client:   client,
+		database: settings.Database,
+	}, nil
+}

backend/shared/database/dependencies/dependencies.go

@@ -0,0 +1,34 @@
+package mongo
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database"
+	"git.sendico.io/tech/sxchnge/shared/database/transaction"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+// Dependencies resolves local DB/transaction primitives for edge-local store wiring only.
+type Dependencies struct {
+	Database     *mongo.Database
+	Transactions transaction.Factory
+}
+
+type DatabaseProvider interface {
+	MongoDatabase() *mongo.Database
+}
+
+func ResolveDependencies(dbf db.Factory) (*Dependencies, error) {
+	if dbf == nil {
+		return nil, merrors.InvalidArgument("database factory is required", "dbFactory")
+	}
+
+	provider, ok := dbf.(DatabaseProvider)
+	if !ok || provider.MongoDatabase() == nil {
+		return nil, merrors.Internal("mongo database provider is not available for edge-local storage wiring")
+	}
+
+	return &Dependencies{
+		Database:     provider.MongoDatabase(),
+		Transactions: dbf.TransactionFactory(),
+	}, nil
+}

backend/shared/database/factory.go

@@ -0,0 +1,26 @@
+package db
+
+import (
+	mongoimpl "git.sendico.io/tech/sxchnge/shared/database/internal/mongo"
+	"git.sendico.io/tech/sxchnge/shared/database/transaction"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"git.sendico.io/tech/sxchnge/shared/logging"
+)
+
+// Factory exposes the local connection and transaction lifecycle.
+type Factory interface {
+	TransactionFactory() transaction.Factory
+
+	CloseConnection()
+}
+
+// NewConnection builds a Factory backed by the configured driver.
+func NewConnection(logger mlogger.Logger, config *Config) (Factory, error) {
+	if config == nil {
+		return nil, merrors.InvalidArgument("database configuration is required", "config")
+	}
+	if config.Driver == Mongo {
+		return mongoimpl.NewConnection(logger, config.Settings)
+	}
+	return nil, merrors.InvalidArgument("unknown database driver: "+string(config.Driver), "config.driver")
+}

backend/shared/database/internal/builder/accumulator.go

@@ -0,0 +1,90 @@
+package builderimp
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type literalAccumulatorImp struct {
+	op    builder.MongoOperation
+	value any
+}
+
+func (a *literalAccumulatorImp) Build() bson.D {
+	return bson.D{{Key: string(a.op), Value: a.value}}
+}
+
+func NewAccumulator(op builder.MongoOperation, value any) builder.Accumulator {
+	return &literalAccumulatorImp{op: op, value: value}
+}
+
+func AddToSet(value builder.Expression) builder.Expression {
+	return newUnaryExpression(builder.AddToSet, value)
+}
+
+func Size(value builder.Expression) builder.Expression {
+	return newUnaryExpression(builder.Size, value)
+}
+
+func Ne(left, right builder.Expression) builder.Expression {
+	return newBinaryExpression(builder.Ne, left, right)
+}
+
+func Sum(value any) builder.Accumulator {
+	return NewAccumulator(builder.Sum, value)
+}
+
+func Avg(value any) builder.Accumulator {
+	return NewAccumulator(builder.Avg, value)
+}
+
+func Min(value any) builder.Accumulator {
+	return NewAccumulator(builder.Min, value)
+}
+
+func Max(value any) builder.Accumulator {
+	return NewAccumulator(builder.Max, value)
+}
+
+func Eq(left, right builder.Expression) builder.Expression {
+	return newBinaryExpression(builder.Eq, left, right)
+}
+
+func Gt(left, right builder.Expression) builder.Expression {
+	return newBinaryExpression(builder.Gt, left, right)
+}
+
+func Add(left, right builder.Accumulator) builder.Accumulator {
+	return newBinaryAccumulator(builder.Add, left, right)
+}
+
+func Subtract(left, right builder.Accumulator) builder.Accumulator {
+	return newBinaryAccumulator(builder.Subtract, left, right)
+}
+
+func Multiply(left, right builder.Accumulator) builder.Accumulator {
+	return newBinaryAccumulator(builder.Multiply, left, right)
+}
+
+func Divide(left, right builder.Accumulator) builder.Accumulator {
+	return newBinaryAccumulator(builder.Divide, left, right)
+}
+
+type binaryAccumulator struct {
+	op    builder.MongoOperation
+	left  builder.Accumulator
+	right builder.Accumulator
+}
+
+func newBinaryAccumulator(op builder.MongoOperation, left, right builder.Accumulator) builder.Accumulator {
+	return &binaryAccumulator{
+		op:    op,
+		left:  left,
+		right: right,
+	}
+}
+
+func (b *binaryAccumulator) Build() bson.D {
+	args := []any{b.left.Build(), b.right.Build()}
+	return bson.D{{Key: string(b.op), Value: args}}
+}

backend/shared/database/internal/builder/alias.go

@@ -0,0 +1,87 @@
+package builderimp
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type aliasImp struct {
+	lhs builder.Field
+	rhs any
+}
+
+func (a *aliasImp) Field() builder.Field {
+	return a.lhs
+}
+
+func (a *aliasImp) Build() bson.D {
+	return bson.D{{Key: a.lhs.Build(), Value: a.rhs}}
+}
+
+// 1. Null alias (_id: null)
+func NewNullAlias(lhs builder.Field) builder.Alias {
+	return &aliasImp{lhs: lhs, rhs: nil}
+}
+
+func NewAlias(lhs builder.Field, rhs any) builder.Alias {
+	return &aliasImp{lhs: lhs, rhs: rhs}
+}
+
+// 2. Simple alias (_id: "$taskRef")
+func NewSimpleAlias(lhs, rhs builder.Field) builder.Alias {
+	return &aliasImp{lhs: lhs, rhs: rhs.Build()}
+}
+
+// 3. Complex alias (_id: { aliasName: "$originalField", ... })
+type ComplexAlias struct {
+	lhs builder.Field
+	rhs []builder.Alias // Correcting handling of slice of aliases
+}
+
+func (a *ComplexAlias) Field() builder.Field {
+	return a.lhs
+}
+
+func (a *ComplexAlias) Build() bson.D {
+	fieldMap := bson.M{}
+
+	for _, alias := range a.rhs {
+		aliasDoc := alias.Build()
+		for _, field := range aliasDoc {
+			fieldMap[field.Key] = field.Value
+		}
+	}
+
+	return bson.D{{Key: a.lhs.Build(), Value: fieldMap}}
+}
+
+func NewComplexAlias(lhs builder.Field, rhs []builder.Alias) builder.Alias {
+	return &ComplexAlias{lhs: lhs, rhs: rhs}
+}
+
+type aliasesImp struct {
+	aliases []builder.Alias
+}
+
+func (a *aliasesImp) Field() builder.Field {
+	if len(a.aliases) > 0 {
+		return a.aliases[0].Field()
+	}
+	return NewFieldImp("")
+}
+
+func (a *aliasesImp) Build() bson.D {
+	results := make([]bson.D, 0)
+	for _, alias := range a.aliases {
+		results = append(results, alias.Build())
+	}
+	aliases := bson.D{}
+	for _, r := range results {
+		aliases = append(aliases, r...)
+	}
+	return aliases
+}
+
+func NewAliases(aliases ...builder.Alias) builder.Alias {
+	return &aliasesImp{aliases: aliases}
+}

backend/shared/database/internal/builder/array.go

@@ -0,0 +1,27 @@
+package builderimp
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type arrayImp struct {
+	elements []builder.Expression
+}
+
+// Build renders the literal array:
+//
+//	[ <expr1>, <expr2>, … ]
+func (b *arrayImp) Build() bson.A {
+	arr := make(bson.A, len(b.elements))
+	for i, expr := range b.elements {
+		// each expr.Build() returns the raw value or sub‐expression
+		arr[i] = expr.Build()
+	}
+	return arr
+}
+
+// NewArray constructs a new array expression from the given sub‐expressions.
+func NewArray(exprs ...builder.Expression) *arrayImp {
+	return &arrayImp{elements: exprs}
+}

backend/shared/database/internal/builder/expression.go

@@ -0,0 +1,108 @@
+package builderimp
+
+import (
+	"reflect"
+
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type literalExpression struct {
+	value any
+}
+
+func NewLiteralExpression(value any) builder.Expression {
+	return &literalExpression{value: value}
+}
+
+func (e *literalExpression) Build() any {
+	return bson.D{{Key: string(builder.Literal), Value: e.value}}
+}
+
+type variadicExpression struct {
+	op    builder.MongoOperation
+	parts []builder.Expression
+}
+
+func (e *variadicExpression) Build() any {
+	args := make([]any, 0, len(e.parts))
+	for _, p := range e.parts {
+		args = append(args, p.Build())
+	}
+	return bson.D{{Key: string(e.op), Value: args}}
+}
+
+func newVariadicExpression(op builder.MongoOperation, exprs ...builder.Expression) builder.Expression {
+	return &variadicExpression{
+		op:    op,
+		parts: exprs,
+	}
+}
+
+func newBinaryExpression(op builder.MongoOperation, left, right builder.Expression) builder.Expression {
+	return &variadicExpression{
+		op:    op,
+		parts: []builder.Expression{left, right},
+	}
+}
+
+type unaryExpression struct {
+	op  builder.MongoOperation
+	rhs builder.Expression
+}
+
+func (e *unaryExpression) Build() any {
+	return bson.D{{Key: string(e.op), Value: e.rhs.Build()}}
+}
+
+func newUnaryExpression(op builder.MongoOperation, right builder.Expression) builder.Expression {
+	return &unaryExpression{
+		op:  op,
+		rhs: right,
+	}
+}
+
+type matchExpression struct {
+	op  builder.MongoOperation
+	rhs builder.Expression
+}
+
+func (e *matchExpression) Build() any {
+	return bson.E{Key: string(e.op), Value: e.rhs.Build()}
+}
+
+func newMatchExpression(op builder.MongoOperation, right builder.Expression) builder.Expression {
+	return &matchExpression{
+		op:  op,
+		rhs: right,
+	}
+}
+
+func InRef(value builder.Field) builder.Expression {
+	return newMatchExpression(builder.In, NewValue(NewRefFieldImp(value).Build()))
+}
+
+type inImpl struct {
+	values []any
+}
+
+func (e *inImpl) Build() any {
+	return bson.D{{Key: string(builder.In), Value: e.values}}
+}
+
+func In(values ...any) builder.Expression {
+	var flattenedValues []any
+
+	for _, v := range values {
+		switch reflect.TypeOf(v).Kind() {
+		case reflect.Slice:
+			slice := reflect.ValueOf(v)
+			for i := range slice.Len() {
+				flattenedValues = append(flattenedValues, slice.Index(i).Interface())
+			}
+		default:
+			flattenedValues = append(flattenedValues, v)
+		}
+	}
+	return &inImpl{values: flattenedValues}
+}

backend/shared/database/internal/builder/field.go

@@ -0,0 +1,71 @@
+package builderimp
+
+import (
+	"strings"
+
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+)
+
+type FieldImp struct {
+	fields []string
+}
+
+func (b *FieldImp) Dot(field string) builder.Field {
+	newFields := make([]string, len(b.fields), len(b.fields)+1)
+	copy(newFields, b.fields)
+	newFields = append(newFields, field)
+	return &FieldImp{fields: newFields}
+}
+
+func (b *FieldImp) CopyWith(field string) builder.Field {
+	copiedFields := make([]string, 0, len(b.fields)+1)
+	copiedFields = append(copiedFields, b.fields...)
+	copiedFields = append(copiedFields, field)
+	return &FieldImp{
+		fields: copiedFields,
+	}
+}
+
+func (b *FieldImp) Build() string {
+	return strings.Join(b.fields, ".")
+}
+
+func NewFieldImp(baseName string) builder.Field {
+	return &FieldImp{
+		fields: []string{baseName},
+	}
+}
+
+type RefField struct {
+	imp builder.Field
+}
+
+func (b *RefField) Build() string {
+	return "$" + b.imp.Build()
+}
+
+func (b *RefField) CopyWith(field string) builder.Field {
+	return &RefField{
+		imp: b.imp.CopyWith(field),
+	}
+}
+
+func (b *RefField) Dot(field string) builder.Field {
+	return &RefField{
+		imp: b.imp.Dot(field),
+	}
+}
+
+func NewRefFieldImp(field builder.Field) builder.Field {
+	return &RefField{
+		imp: field,
+	}
+}
+
+func NewRootRef() builder.Field {
+	return NewFieldImp("$$ROOT")
+}
+
+func NewRemoveRef() builder.Field {
+	return NewFieldImp("$$REMOVE")
+}

backend/shared/database/internal/builder/func.go

@@ -0,0 +1,137 @@
+package builderimp
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type condImp struct {
+	condition builder.Expression
+	ifTrue    any
+	ifFalse   any
+}
+
+func (c *condImp) Build() any {
+	return bson.D{
+		{Key: string(builder.Cond), Value: bson.D{
+			{Key: "if", Value: c.condition.Build()},
+			{Key: "then", Value: c.ifTrue},
+			{Key: "else", Value: c.ifFalse},
+		}},
+	}
+}
+
+func NewCond(condition builder.Expression, ifTrue, ifFalse any) builder.Expression {
+	return &condImp{
+		condition: condition,
+		ifTrue:    ifTrue,
+		ifFalse:   ifFalse,
+	}
+}
+
+// setUnionImp implements builder.Expression but takes only builder.Array inputs.
+type setUnionImp struct {
+	inputs []builder.Expression
+}
+
+// Build renders the $setUnion stage:
+//
+//	{ $setUnion: [ <array1>, <array2>, … ] }
+func (s *setUnionImp) Build() any {
+	arr := make(bson.A, len(s.inputs))
+	for i, arrayExpr := range s.inputs {
+		arr[i] = arrayExpr.Build()
+	}
+	return bson.D{
+		{Key: string(builder.SetUnion), Value: arr},
+	}
+}
+
+// NewSetUnion constructs a new $setUnion expression from the given Arrays.
+func NewSetUnion(arrays ...builder.Expression) builder.Expression {
+	return &setUnionImp{inputs: arrays}
+}
+
+type assignmentImp struct {
+	field      builder.Field
+	expression builder.Expression
+}
+
+func (a *assignmentImp) Build() bson.D {
+	// Assign it to the given field name
+	return bson.D{
+		{Key: a.field.Build(), Value: a.expression.Build()},
+	}
+}
+
+// NewAssignment creates a projection assignment of the form:
+//
+//	<field>: <expression>
+func NewAssignment(field builder.Field, expression builder.Expression) builder.Projection {
+	return &assignmentImp{
+		field:      field,
+		expression: expression,
+	}
+}
+
+type computeImp struct {
+	field      builder.Field
+	expression builder.Expression
+}
+
+func (a *computeImp) Build() any {
+	return bson.D{
+		{Key: a.field.Build(), Value: a.expression.Build()},
+	}
+}
+
+func NewCompute(field builder.Field, expression builder.Expression) builder.Expression {
+	return &computeImp{
+		field:      field,
+		expression: expression,
+	}
+}
+
+func NewIfNull(expression, replacement builder.Expression) builder.Expression {
+	return newBinaryExpression(builder.IfNull, expression, replacement)
+}
+
+func NewPush(expression builder.Expression) builder.Expression {
+	return newUnaryExpression(builder.Push, expression)
+}
+
+func NewAnd(exprs ...builder.Expression) builder.Expression {
+	return newVariadicExpression(builder.And, exprs...)
+}
+
+func NewOr(exprs ...builder.Expression) builder.Expression {
+	return newVariadicExpression(builder.Or, exprs...)
+}
+
+func NewEach(exprs ...builder.Expression) builder.Expression {
+	return newVariadicExpression(builder.Each, exprs...)
+}
+
+func NewLt(left, right builder.Expression) builder.Expression {
+	return newBinaryExpression(builder.Lt, left, right)
+}
+
+func NewNot(expression builder.Expression) builder.Expression {
+	return newUnaryExpression(builder.Not, expression)
+}
+
+func NewSum(expression builder.Expression) builder.Expression {
+	return newUnaryExpression(builder.Sum, expression)
+}
+
+func NewMin(expression builder.Expression) builder.Expression {
+	return newUnaryExpression(builder.Min, expression)
+}
+
+func First(expr builder.Expression) builder.Expression {
+	return newUnaryExpression(builder.First, expr)
+}
+
+func NewType(expr builder.Expression) builder.Expression {
+	return newUnaryExpression(builder.Type, expr)
+}

backend/shared/database/internal/builder/gaccumulator.go

@@ -0,0 +1,35 @@
+package builderimp
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type groupAccumulatorImp struct {
+	field builder.Field
+	acc   builder.Accumulator
+}
+
+// NewGroupAccumulator creates a new GroupAccumulator for the given field using the specified operator and value.
+func NewGroupAccumulator(field builder.Field, acc builder.Accumulator) builder.GroupAccumulator {
+	return &groupAccumulatorImp{
+		field: field,
+		acc:   acc,
+	}
+}
+
+func (g *groupAccumulatorImp) Field() builder.Field {
+	return g.field
+}
+
+func (g *groupAccumulatorImp) Accumulator() builder.Accumulator {
+	return g.acc
+}
+
+// Build returns a bson.E element for this group accumulator.
+func (g *groupAccumulatorImp) Build() bson.D {
+	return bson.D{{
+		Key:   g.field.Build(),
+		Value: g.acc.Build(),
+	}}
+}

backend/shared/database/internal/builder/patch.go

@@ -0,0 +1,104 @@
+package builderimp
+
+import (
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type patchBuilder struct {
+	updates bson.D
+}
+
+func set(field builder.Field, value any) bson.E {
+	return bson.E{Key: string(builder.Set), Value: bson.D{{Key: field.Build(), Value: value}}}
+}
+
+func (u *patchBuilder) Set(field builder.Field, value any) builder.Patch {
+	u.updates = append(u.updates, set(field, value))
+	return u
+}
+
+func (u *patchBuilder) Inc(field builder.Field, value any) builder.Patch {
+	u.updates = append(u.updates, bson.E{Key: string(builder.Inc), Value: bson.D{{Key: field.Build(), Value: value}}})
+	return u
+}
+
+func (u *patchBuilder) Unset(field builder.Field) builder.Patch {
+	u.updates = append(u.updates, bson.E{Key: string(builder.Unset), Value: bson.D{{Key: field.Build(), Value: ""}}})
+	return u
+}
+
+func (u *patchBuilder) Rename(field builder.Field, newName string) builder.Patch {
+	u.updates = append(u.updates, bson.E{Key: string(builder.Rename), Value: bson.D{{Key: field.Build(), Value: newName}}})
+	return u
+}
+
+func (u *patchBuilder) Push(field builder.Field, value any) builder.Patch {
+	u.updates = append(u.updates, bson.E{Key: string(builder.Push), Value: bson.D{{Key: field.Build(), Value: value}}})
+	return u
+}
+
+func (u *patchBuilder) Pull(field builder.Field, value any) builder.Patch {
+	u.updates = append(u.updates, bson.E{Key: string(builder.Pull), Value: bson.D{{Key: field.Build(), Value: value}}})
+	return u
+}
+
+func (u *patchBuilder) AddToSet(field builder.Field, value any) builder.Patch {
+	u.updates = append(u.updates, bson.E{Key: string(builder.AddToSet), Value: bson.D{{Key: field.Build(), Value: value}}})
+	return u
+}
+
+func (u *patchBuilder) Build() bson.D {
+	updates := append(bson.D{}, u.updates...)
+	updates = append(updates, set(NewFieldImp(storable.UpdatedAtField), time.Now()))
+	return mergePatchOperations(updates)
+}
+
+func NewPatchImp() builder.Patch {
+	return &patchBuilder{updates: bson.D{}}
+}
+
+func mergePatchOperations(updates bson.D) bson.D {
+	operators := make([]string, 0, len(updates))
+	merged := make(map[string]bson.D, len(updates))
+	for _, update := range updates {
+		fields, ok := update.Value.(bson.D)
+		if !ok {
+			operators = appendMissingOperator(operators, update.Key)
+			merged[update.Key] = append(merged[update.Key], bson.E{Key: update.Key, Value: update.Value})
+			continue
+		}
+		operators = appendMissingOperator(operators, update.Key)
+		for _, field := range fields {
+			merged[update.Key] = setPatchField(merged[update.Key], field)
+		}
+	}
+
+	out := make(bson.D, 0, len(operators))
+	for _, operator := range operators {
+		out = append(out, bson.E{Key: operator, Value: merged[operator]})
+	}
+	return out
+}
+
+func appendMissingOperator(operators []string, operator string) []string {
+	for _, existing := range operators {
+		if existing == operator {
+			return operators
+		}
+	}
+	return append(operators, operator)
+}
+
+func setPatchField(fields bson.D, field bson.E) bson.D {
+	for i := range fields {
+		if fields[i].Key == field.Key {
+			fields[i] = field
+			return fields
+		}
+	}
+	return append(fields, field)
+}

backend/shared/database/internal/builder/patch_test.go

@@ -0,0 +1,98 @@
+package builderimp
+
+import (
+	"testing"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+func TestPatchBuilderBuildMergesSetOperations(t *testing.T) {
+	patch := NewPatchImp().
+		Set(NewFieldImp("name"), "alice").
+		Inc(NewFieldImp("version"), 1).
+		Set(NewFieldImp("status"), "active")
+
+	built := patch.Build()
+
+	if got := countPatchOperator(built, string(builder.Set)); got != 1 {
+		t.Fatalf("$set operator count = %d, want 1: %#v", got, built)
+	}
+	if got := countPatchOperator(built, string(builder.Inc)); got != 1 {
+		t.Fatalf("$inc operator count = %d, want 1: %#v", got, built)
+	}
+	setFields := patchOperatorFields(t, built, string(builder.Set))
+	for _, key := range []string{"name", "status", storable.UpdatedAtField} {
+		if countPatchField(setFields, key) != 1 {
+			t.Fatalf("$set field %s must be present once: %#v", key, setFields)
+		}
+	}
+}
+
+func TestPatchBuilderBuildOwnsUpdatedAt(t *testing.T) {
+	manualUpdatedAt := time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC)
+	patch := NewPatchImp().
+		Set(NewFieldImp(storable.UpdatedAtField), manualUpdatedAt).
+		Set(NewFieldImp("status"), "active")
+
+	built := patch.Build()
+	setFields := patchOperatorFields(t, built, string(builder.Set))
+
+	if got := countPatchField(setFields, storable.UpdatedAtField); got != 1 {
+		t.Fatalf("updatedAt field count = %d, want 1: %#v", got, setFields)
+	}
+	value, ok := patchFieldValue(setFields, storable.UpdatedAtField).(time.Time)
+	if !ok {
+		t.Fatalf("updatedAt value type = %T, want time.Time", patchFieldValue(setFields, storable.UpdatedAtField))
+	}
+	if value.Equal(manualUpdatedAt) {
+		t.Fatalf("updatedAt must be repository-owned, got manual value %s", value.Format(time.RFC3339Nano))
+	}
+}
+
+func patchOperatorFields(t *testing.T, built bson.D, operator string) bson.D {
+	t.Helper()
+	for _, entry := range built {
+		if entry.Key != operator {
+			continue
+		}
+		fields, ok := entry.Value.(bson.D)
+		if !ok {
+			t.Fatalf("%s value type = %T, want bson.D", operator, entry.Value)
+		}
+		return fields
+	}
+	t.Fatalf("%s operator missing: %#v", operator, built)
+	return nil
+}
+
+func countPatchOperator(built bson.D, operator string) int {
+	count := 0
+	for _, entry := range built {
+		if entry.Key == operator {
+			count++
+		}
+	}
+	return count
+}
+
+func countPatchField(fields bson.D, key string) int {
+	count := 0
+	for _, field := range fields {
+		if field.Key == key {
+			count++
+		}
+	}
+	return count
+}
+
+func patchFieldValue(fields bson.D, key string) any {
+	for _, field := range fields {
+		if field.Key == key {
+			return field.Value
+		}
+	}
+	return nil
+}

backend/shared/database/internal/builder/pipeline.go

@@ -0,0 +1,133 @@
+package builderimp
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"git.sendico.io/tech/sxchnge/shared/service"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+type unwindOpts = builder.UnwindOpts
+
+// UnwindOption is the same type defined in the builder package.
+type UnwindOption = builder.UnwindOption
+
+// NewUnwindOpts applies all UnwindOption's to a fresh unwindOpts.
+func NewUnwindOpts(opts ...UnwindOption) *unwindOpts {
+	cfg := &unwindOpts{}
+	for _, opt := range opts {
+		opt(cfg)
+	}
+	return cfg
+}
+
+type PipelineImp struct {
+	pipeline mongo.Pipeline
+}
+
+func (b *PipelineImp) Match(filter builder.Query) builder.Pipeline {
+	b.pipeline = append(b.pipeline, filter.BuildPipeline())
+	return b
+}
+
+func (b *PipelineImp) Lookup(from mservice.Type, localField, foreignField, as builder.Field) builder.Pipeline {
+	b.pipeline = append(b.pipeline, bson.D{{Key: string(builder.Lookup), Value: bson.D{
+		{Key: string(builder.MKFrom), Value: from},
+		{Key: string(builder.MKLocalField), Value: localField.Build()},
+		{Key: string(builder.MKForeignField), Value: foreignField.Build()},
+		{Key: string(builder.MKAs), Value: as.Build()},
+	}}})
+	return b
+}
+
+func (b *PipelineImp) LookupWithPipeline(
+	from mservice.Type,
+	nested builder.Pipeline,
+	as builder.Field,
+	let *map[string]builder.Field,
+) builder.Pipeline {
+	lookupStage := bson.D{
+		{Key: string(builder.MKFrom), Value: from},
+		{Key: string(builder.MKPipeline), Value: nested.Build()},
+		{Key: string(builder.MKAs), Value: as.Build()},
+	}
+
+	// only add "let" if provided and not empty
+	if let != nil && len(*let) > 0 {
+		letDoc := bson.D{}
+		for varName, fld := range *let {
+			letDoc = append(letDoc, bson.E{Key: varName, Value: fld.Build()})
+		}
+		lookupStage = append(lookupStage, bson.E{Key: string(builder.MKLet), Value: letDoc})
+	}
+
+	b.pipeline = append(b.pipeline, bson.D{{Key: string(builder.Lookup), Value: lookupStage}})
+	return b
+}
+
+func (b *PipelineImp) Unwind(path builder.Field, opts ...UnwindOption) builder.Pipeline {
+	cfg := NewUnwindOpts(opts...)
+
+	var stageValue interface{}
+	// if no options, shorthand
+	if !cfg.PreserveNullAndEmptyArrays && cfg.IncludeArrayIndex == "" {
+		stageValue = path.Build()
+	} else {
+		d := bson.D{{Key: string(builder.MKPath), Value: path.Build()}}
+		if cfg.PreserveNullAndEmptyArrays {
+			d = append(d, bson.E{Key: string(builder.MKPreserveNullAndEmptyArrays), Value: true})
+		}
+		if cfg.IncludeArrayIndex != "" {
+			d = append(d, bson.E{Key: string(builder.MKIncludeArrayIndex), Value: cfg.IncludeArrayIndex})
+		}
+		stageValue = d
+	}
+
+	b.pipeline = append(b.pipeline, bson.D{{Key: string(builder.Unwind), Value: stageValue}})
+	return b
+}
+
+func (b *PipelineImp) Count(field builder.Field) builder.Pipeline {
+	b.pipeline = append(b.pipeline, bson.D{{Key: string(builder.Count), Value: field.Build()}})
+	return b
+}
+
+func (b *PipelineImp) Group(groupBy builder.Alias, accumulators ...builder.GroupAccumulator) builder.Pipeline {
+	groupDoc := groupBy.Build()
+	for _, acc := range accumulators {
+		groupDoc = append(groupDoc, acc.Build()...)
+	}
+
+	b.pipeline = append(b.pipeline, bson.D{
+		{Key: string(builder.Group), Value: groupDoc},
+	})
+	return b
+}
+
+func (b *PipelineImp) Project(projections ...builder.Projection) builder.Pipeline {
+	projDoc := bson.D{}
+	for _, pr := range projections {
+		projDoc = append(projDoc, pr.Build()...)
+	}
+	b.pipeline = append(b.pipeline, bson.D{{Key: string(builder.Project), Value: projDoc}})
+	return b
+}
+
+func (b *PipelineImp) ReplaceRoot(newRoot builder.Expression) builder.Pipeline {
+	b.pipeline = append(b.pipeline, bson.D{{Key: string(builder.ReplaceRoot), Value: bson.D{
+		{Key: string(builder.MKNewRoot), Value: newRoot.Build()},
+	}}})
+	return b
+}
+
+func (b *PipelineImp) Build() mongo.Pipeline {
+	return b.pipeline
+}
+
+func NewPipelineImp(stages ...bson.D) builder.Pipeline {
+	pipeline := make(mongo.Pipeline, len(stages))
+	copy(pipeline, stages)
+	return &PipelineImp{
+		pipeline: pipeline,
+	}
+}

backend/shared/database/internal/builder/pipeline_test.go

@@ -0,0 +1,576 @@
+package builderimp
+
+import (
+	"testing"
+
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"git.sendico.io/tech/sxchnge/shared/service"
+	"github.com/stretchr/testify/assert"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func TestNewPipelineImp(t *testing.T) {
+	pipeline := NewPipelineImp()
+
+	assert.NotNil(t, pipeline)
+	assert.IsType(t, &PipelineImp{}, pipeline)
+
+	// Build should return empty pipeline initially
+	built := pipeline.Build()
+	assert.NotNil(t, built)
+	assert.Len(t, built, 0)
+}
+
+func TestNewPipelineImpSeedsComposableStages(t *testing.T) {
+	sortStage := bson.D{{Key: "$sort", Value: bson.D{{Key: "createdAt", Value: -1}}}}
+	pipeline := NewPipelineImp(sortStage)
+
+	result := pipeline.Count(&MockField{build: "total"})
+
+	assert.Same(t, pipeline, result)
+	assert.Equal(t, mongo.Pipeline{
+		sortStage,
+		bson.D{{Key: "$count", Value: "total"}},
+	}, pipeline.Build())
+}
+
+func TestPipelineImp_Match(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockQuery := &MockQuery{
+		buildPipeline: bson.D{{Key: "$match", Value: bson.D{{Key: "field", Value: "value"}}}},
+	}
+
+	result := pipeline.Match(mockQuery)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+	assert.Equal(t, bson.D{{Key: "$match", Value: bson.D{{Key: "field", Value: "value"}}}}, built[0])
+}
+
+func TestPipelineImp_Lookup(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockLocalField := &MockField{build: "localField"}
+	mockForeignField := &MockField{build: "foreignField"}
+	mockAsField := &MockField{build: "asField"}
+
+	result := pipeline.Lookup(mservice.Site, mockLocalField, mockForeignField, mockAsField)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Lookup), Value: bson.D{
+		{Key: string(builder.MKFrom), Value: mservice.Site},
+		{Key: string(builder.MKLocalField), Value: "localField"},
+		{Key: string(builder.MKForeignField), Value: "foreignField"},
+		{Key: string(builder.MKAs), Value: "asField"},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_LookupWithPipeline_WithoutLet(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockNestedPipeline := &MockPipeline{
+		build: mongo.Pipeline{bson.D{{Key: "$match", Value: bson.D{{Key: "nested", Value: true}}}}},
+	}
+	mockAsField := &MockField{build: "asField"}
+
+	result := pipeline.LookupWithPipeline(mservice.Site, mockNestedPipeline, mockAsField, nil)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Lookup), Value: bson.D{
+		{Key: string(builder.MKFrom), Value: mservice.Site},
+		{Key: string(builder.MKPipeline), Value: mockNestedPipeline.build},
+		{Key: string(builder.MKAs), Value: "asField"},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_LookupWithPipeline_WithLet(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockNestedPipeline := &MockPipeline{
+		build: mongo.Pipeline{bson.D{{Key: "$match", Value: bson.D{{Key: "nested", Value: true}}}}},
+	}
+	mockAsField := &MockField{build: "asField"}
+	mockLetField := &MockField{build: "$_id"}
+
+	letVars := map[string]builder.Field{
+		"projRef": mockLetField,
+	}
+
+	result := pipeline.LookupWithPipeline(mservice.Site, mockNestedPipeline, mockAsField, &letVars)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Lookup), Value: bson.D{
+		{Key: string(builder.MKFrom), Value: mservice.Site},
+		{Key: string(builder.MKPipeline), Value: mockNestedPipeline.build},
+		{Key: string(builder.MKAs), Value: "asField"},
+		{Key: string(builder.MKLet), Value: bson.D{{Key: "projRef", Value: "$_id"}}},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_LookupWithPipeline_WithEmptyLet(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockNestedPipeline := &MockPipeline{
+		build: mongo.Pipeline{bson.D{{Key: "$match", Value: bson.D{{Key: "nested", Value: true}}}}},
+	}
+	mockAsField := &MockField{build: "asField"}
+
+	emptyLetVars := map[string]builder.Field{}
+
+	pipeline.LookupWithPipeline(mservice.Site, mockNestedPipeline, mockAsField, &emptyLetVars)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	// Should not include let field when empty
+	expected := bson.D{{Key: string(builder.Lookup), Value: bson.D{
+		{Key: string(builder.MKFrom), Value: mservice.Site},
+		{Key: string(builder.MKPipeline), Value: mockNestedPipeline.build},
+		{Key: string(builder.MKAs), Value: "asField"},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_Unwind_Simple(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockField := &MockField{build: "$array"}
+
+	result := pipeline.Unwind(mockField)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Unwind), Value: "$array"}}
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_Unwind_WithPreserveNullAndEmptyArrays(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockField := &MockField{build: "$array"}
+
+	// Mock the UnwindOption function
+	preserveOpt := func(opts *builder.UnwindOpts) {
+		opts.PreserveNullAndEmptyArrays = true
+	}
+
+	pipeline.Unwind(mockField, preserveOpt)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Unwind), Value: bson.D{
+		{Key: string(builder.MKPath), Value: "$array"},
+		{Key: string(builder.MKPreserveNullAndEmptyArrays), Value: true},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_Unwind_WithIncludeArrayIndex(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockField := &MockField{build: "$array"}
+
+	// Mock the UnwindOption function
+	indexOpt := func(opts *builder.UnwindOpts) {
+		opts.IncludeArrayIndex = "arrayIndex"
+	}
+
+	pipeline.Unwind(mockField, indexOpt)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Unwind), Value: bson.D{
+		{Key: string(builder.MKPath), Value: "$array"},
+		{Key: string(builder.MKIncludeArrayIndex), Value: "arrayIndex"},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_Unwind_WithBothOptions(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockField := &MockField{build: "$array"}
+
+	// Mock the UnwindOption functions
+	preserveOpt := func(opts *builder.UnwindOpts) {
+		opts.PreserveNullAndEmptyArrays = true
+	}
+	indexOpt := func(opts *builder.UnwindOpts) {
+		opts.IncludeArrayIndex = "arrayIndex"
+	}
+
+	pipeline.Unwind(mockField, preserveOpt, indexOpt)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Unwind), Value: bson.D{
+		{Key: string(builder.MKPath), Value: "$array"},
+		{Key: string(builder.MKPreserveNullAndEmptyArrays), Value: true},
+		{Key: string(builder.MKIncludeArrayIndex), Value: "arrayIndex"},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_Count(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockField := &MockField{build: "totalCount"}
+
+	result := pipeline.Count(mockField)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Count), Value: "totalCount"}}
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_Group(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockAlias := &MockAlias{
+		build: bson.D{{Key: "_id", Value: "$field"}},
+		field: &MockField{build: "_id"},
+	}
+	mockAccumulator := &MockGroupAccumulator{
+		build: bson.D{{Key: "count", Value: bson.D{{Key: "$sum", Value: 1}}}},
+	}
+
+	result := pipeline.Group(mockAlias, mockAccumulator)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Group), Value: bson.D{
+		{Key: "_id", Value: "$field"},
+		{Key: "count", Value: bson.D{{Key: "$sum", Value: 1}}},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_Group_MultipleAccumulators(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockAlias := &MockAlias{
+		build: bson.D{{Key: "_id", Value: "$field"}},
+		field: &MockField{build: "_id"},
+	}
+	mockAccumulator1 := &MockGroupAccumulator{
+		build: bson.D{{Key: "count", Value: bson.D{{Key: "$sum", Value: 1}}}},
+	}
+	mockAccumulator2 := &MockGroupAccumulator{
+		build: bson.D{{Key: "total", Value: bson.D{{Key: "$sum", Value: "$amount"}}}},
+	}
+
+	pipeline.Group(mockAlias, mockAccumulator1, mockAccumulator2)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Group), Value: bson.D{
+		{Key: "_id", Value: "$field"},
+		{Key: "count", Value: bson.D{{Key: "$sum", Value: 1}}},
+		{Key: "total", Value: bson.D{{Key: "$sum", Value: "$amount"}}},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_Project(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockProjection := &MockProjection{
+		build: bson.D{{Key: "field1", Value: 1}},
+	}
+
+	result := pipeline.Project(mockProjection)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Project), Value: bson.D{
+		{Key: "field1", Value: 1},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_Project_MultipleProjections(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockProjection1 := &MockProjection{
+		build: bson.D{{Key: "field1", Value: 1}},
+	}
+	mockProjection2 := &MockProjection{
+		build: bson.D{{Key: "field2", Value: 0}},
+	}
+
+	pipeline.Project(mockProjection1, mockProjection2)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.Project), Value: bson.D{
+		{Key: "field1", Value: 1},
+		{Key: "field2", Value: 0},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_ChainedOperations(t *testing.T) {
+	pipeline := NewPipelineImp()
+
+	// Create mocks
+	mockQuery := &MockQuery{
+		buildPipeline: bson.D{{Key: "$match", Value: bson.D{{Key: "status", Value: "active"}}}},
+	}
+	mockLocalField := &MockField{build: "userId"}
+	mockForeignField := &MockField{build: "_id"}
+	mockAsField := &MockField{build: "user"}
+	mockUnwindField := &MockField{build: "$user"}
+	mockProjection := &MockProjection{
+		build: bson.D{{Key: "name", Value: "$user.name"}},
+	}
+
+	// Chain operations
+	result := pipeline.
+		Match(mockQuery).
+		Lookup(mservice.Accounts, mockLocalField, mockForeignField, mockAsField).
+		Unwind(mockUnwindField).
+		Project(mockProjection)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 4)
+
+	// Verify each stage
+	assert.Equal(t, bson.D{{Key: "$match", Value: bson.D{{Key: "status", Value: "active"}}}}, built[0])
+
+	expectedLookup := bson.D{{Key: string(builder.Lookup), Value: bson.D{
+		{Key: string(builder.MKFrom), Value: mservice.Accounts},
+		{Key: string(builder.MKLocalField), Value: "userId"},
+		{Key: string(builder.MKForeignField), Value: "_id"},
+		{Key: string(builder.MKAs), Value: "user"},
+	}}}
+	assert.Equal(t, expectedLookup, built[1])
+
+	assert.Equal(t, bson.D{{Key: string(builder.Unwind), Value: "$user"}}, built[2])
+
+	expectedProject := bson.D{{Key: string(builder.Project), Value: bson.D{
+		{Key: "name", Value: "$user.name"},
+	}}}
+	assert.Equal(t, expectedProject, built[3])
+}
+
+func TestNewUnwindOpts(t *testing.T) {
+	t.Run("NoOptions", func(t *testing.T) {
+		opts := NewUnwindOpts()
+
+		assert.NotNil(t, opts)
+		assert.False(t, opts.PreserveNullAndEmptyArrays)
+		assert.Empty(t, opts.IncludeArrayIndex)
+	})
+
+	t.Run("WithPreserveOption", func(t *testing.T) {
+		preserveOpt := func(opts *builder.UnwindOpts) {
+			opts.PreserveNullAndEmptyArrays = true
+		}
+
+		opts := NewUnwindOpts(preserveOpt)
+
+		assert.True(t, opts.PreserveNullAndEmptyArrays)
+		assert.Empty(t, opts.IncludeArrayIndex)
+	})
+
+	t.Run("WithIndexOption", func(t *testing.T) {
+		indexOpt := func(opts *builder.UnwindOpts) {
+			opts.IncludeArrayIndex = "index"
+		}
+
+		opts := NewUnwindOpts(indexOpt)
+
+		assert.False(t, opts.PreserveNullAndEmptyArrays)
+		assert.Equal(t, "index", opts.IncludeArrayIndex)
+	})
+
+	t.Run("WithBothOptions", func(t *testing.T) {
+		preserveOpt := func(opts *builder.UnwindOpts) {
+			opts.PreserveNullAndEmptyArrays = true
+		}
+		indexOpt := func(opts *builder.UnwindOpts) {
+			opts.IncludeArrayIndex = "index"
+		}
+
+		opts := NewUnwindOpts(preserveOpt, indexOpt)
+
+		assert.True(t, opts.PreserveNullAndEmptyArrays)
+		assert.Equal(t, "index", opts.IncludeArrayIndex)
+	})
+}
+
+// Mock implementations for testing
+
+type MockQuery struct {
+	buildPipeline bson.D
+}
+
+func (m *MockQuery) And(filters ...builder.Query) builder.Query          { return m }
+func (m *MockQuery) Or(filters ...builder.Query) builder.Query           { return m }
+func (m *MockQuery) Filter(field builder.Field, value any) builder.Query { return m }
+func (m *MockQuery) Expression(value builder.Expression) builder.Query   { return m }
+func (m *MockQuery) Comparison(field builder.Field, operator builder.MongoOperation, value any) builder.Query {
+	return m
+}
+func (m *MockQuery) RegEx(field builder.Field, pattern, options string) builder.Query { return m }
+func (m *MockQuery) In(field builder.Field, values ...any) builder.Query              { return m }
+func (m *MockQuery) NotIn(field builder.Field, values ...any) builder.Query           { return m }
+func (m *MockQuery) Sort(field builder.Field, ascending bool) builder.Query           { return m }
+func (m *MockQuery) Limit(limit *int64) builder.Query                                 { return m }
+func (m *MockQuery) Offset(offset *int64) builder.Query                               { return m }
+func (m *MockQuery) Archived(isArchived *bool) builder.Query                          { return m }
+func (m *MockQuery) BuildPipeline() bson.D                                            { return m.buildPipeline }
+func (m *MockQuery) BuildQuery() bson.D                                               { return bson.D{} }
+func (m *MockQuery) BuildOptions() *options.FindOptionsBuilder                        { return &options.FindOptionsBuilder{} }
+
+type MockField struct {
+	build string
+}
+
+func (m *MockField) Dot(field string) builder.Field      { return &MockField{build: m.build + "." + field} }
+func (m *MockField) CopyWith(field string) builder.Field { return &MockField{build: field} }
+func (m *MockField) Build() string                       { return m.build }
+
+type MockPipeline struct {
+	build mongo.Pipeline
+}
+
+func (m *MockPipeline) Match(filter builder.Query) builder.Pipeline { return m }
+func (m *MockPipeline) Lookup(from mservice.Type, localField, foreignField, as builder.Field) builder.Pipeline {
+	return m
+}
+func (m *MockPipeline) LookupWithPipeline(from mservice.Type, pipeline builder.Pipeline, as builder.Field, let *map[string]builder.Field) builder.Pipeline {
+	return m
+}
+func (m *MockPipeline) Unwind(path builder.Field, opts ...UnwindOption) builder.Pipeline { return m }
+func (m *MockPipeline) Count(field builder.Field) builder.Pipeline                       { return m }
+func (m *MockPipeline) Group(groupBy builder.Alias, accumulators ...builder.GroupAccumulator) builder.Pipeline {
+	return m
+}
+func (m *MockPipeline) Project(projections ...builder.Projection) builder.Pipeline { return m }
+func (m *MockPipeline) ReplaceRoot(newRoot builder.Expression) builder.Pipeline    { return m }
+func (m *MockPipeline) Build() mongo.Pipeline                                      { return m.build }
+
+type MockAlias struct {
+	build bson.D
+	field builder.Field
+}
+
+func (m *MockAlias) Field() builder.Field { return m.field }
+func (m *MockAlias) Build() bson.D        { return m.build }
+
+type MockGroupAccumulator struct {
+	build bson.D
+}
+
+func (m *MockGroupAccumulator) Build() bson.D { return m.build }
+
+type MockProjection struct {
+	build bson.D
+}
+
+func (m *MockProjection) Build() bson.D { return m.build }
+
+func TestPipelineImp_ReplaceRoot(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockExpr := &MockExpression{build: "$newRoot"}
+
+	result := pipeline.ReplaceRoot(mockExpr)
+
+	// Should return self for chaining
+	assert.Same(t, pipeline, result)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.ReplaceRoot), Value: bson.D{
+		{Key: string(builder.MKNewRoot), Value: "$newRoot"},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_ReplaceRoot_WithNestedField(t *testing.T) {
+	pipeline := NewPipelineImp()
+	mockExpr := &MockExpression{build: "$document.data"}
+
+	pipeline.ReplaceRoot(mockExpr)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.ReplaceRoot), Value: bson.D{
+		{Key: string(builder.MKNewRoot), Value: "$document.data"},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+func TestPipelineImp_ReplaceRoot_WithExpression(t *testing.T) {
+	pipeline := NewPipelineImp()
+	// Mock a complex expression like { $mergeObjects: [...] }
+	mockExpr := &MockExpression{build: bson.D{{Key: "$mergeObjects", Value: bson.A{"$field1", "$field2"}}}}
+
+	pipeline.ReplaceRoot(mockExpr)
+
+	built := pipeline.Build()
+	assert.Len(t, built, 1)
+
+	expected := bson.D{{Key: string(builder.ReplaceRoot), Value: bson.D{
+		{Key: string(builder.MKNewRoot), Value: bson.D{{Key: "$mergeObjects", Value: bson.A{"$field1", "$field2"}}}},
+	}}}
+
+	assert.Equal(t, expected, built[0])
+}
+
+type MockExpression struct {
+	build any
+}
+
+func (m *MockExpression) Build() any { return m.build }

backend/shared/database/internal/builder/projection.go

@@ -0,0 +1,97 @@
+package builderimp
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// projectionExprImp is a concrete implementation of builder.Projection
+// that projects a field using a custom expression.
+type projectionExprImp struct {
+	expr  builder.Expression // The expression for this projection.
+	field builder.Field      // The field name for the projected field.
+}
+
+// Field returns the field being projected.
+func (p *projectionExprImp) Field() builder.Field {
+	return p.field
+}
+
+// Expression returns the expression for the projection.
+func (p *projectionExprImp) Expression() builder.Expression {
+	return p.expr
+}
+
+// Build returns the built expression. If no expression is provided, returns 1.
+func (p *projectionExprImp) Build() bson.D {
+	if p.expr == nil {
+		return bson.D{{Key: p.field.Build(), Value: 1}}
+	}
+	return bson.D{{Key: p.field.Build(), Value: p.expr.Build()}}
+}
+
+// NewProjectionExpr creates a new Projection for a given field and expression.
+func NewProjectionExpr(field builder.Field, expr builder.Expression) builder.Projection {
+	return &projectionExprImp{field: field, expr: expr}
+}
+
+// aliasProjectionImp is a concrete implementation of builder.Projection
+// that projects an alias (renaming a field or expression).
+type aliasProjectionImp struct {
+	alias builder.Alias // The alias for this projection.
+}
+
+// Field returns the field being projected (via the alias).
+func (p *aliasProjectionImp) Field() builder.Field {
+	return p.alias.Field()
+}
+
+// Expression returns no additional expression for an alias projection.
+func (p *aliasProjectionImp) Expression() builder.Expression {
+	return nil
+}
+
+// Build returns the built alias expression.
+func (p *aliasProjectionImp) Build() bson.D {
+	return p.alias.Build()
+}
+
+// NewAliasProjection creates a new Projection that renames or wraps an existing field or expression.
+func NewAliasProjection(alias builder.Alias) builder.Projection {
+	return &aliasProjectionImp{alias: alias}
+}
+
+// sinkProjectionImp is a simple include/exclude projection (0 or 1).
+type sinkProjectionImp struct {
+	field builder.Field // The field name for the projected field.
+	val   int           // 1 to include, 0 to exclude.
+}
+
+// Expression returns no expression for a sink projection.
+func (p *sinkProjectionImp) Expression() builder.Expression {
+	return nil
+}
+
+// Build returns the include/exclude projection.
+func (p *sinkProjectionImp) Build() bson.D {
+	return bson.D{{Key: p.field.Build(), Value: p.val}}
+}
+
+// NewSinkProjection creates a new Projection that includes (true) or excludes (false) a field.
+func NewSinkProjection(field builder.Field, include bool) builder.Projection {
+	val := 0
+	if include {
+		val = 1
+	}
+	return &sinkProjectionImp{field: field, val: val}
+}
+
+// IncludeField returns a projection including the given field.
+func IncludeField(field builder.Field) builder.Projection {
+	return NewSinkProjection(field, true)
+}
+
+// ExcludeField returns a projection excluding the given field.
+func ExcludeField(field builder.Field) builder.Projection {
+	return NewSinkProjection(field, false)
+}

backend/shared/database/internal/builder/query.go

@@ -0,0 +1,162 @@
+package builderimp
+
+import (
+	"reflect"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+type QueryImp struct {
+	filter bson.D
+	sort   bson.D
+	limit  *int64
+	offset *int64
+}
+
+func (b *QueryImp) Filter(field builder.Field, value any) builder.Query {
+	b.filter = append(b.filter, bson.E{Key: field.Build(), Value: value})
+	return b
+}
+
+func (b *QueryImp) And(filters ...builder.Query) builder.Query {
+	andFilters := bson.A{}
+	for _, f := range filters {
+		andFilters = append(andFilters, f.BuildQuery())
+	}
+	b.filter = append(b.filter, bson.E{Key: string(builder.And), Value: andFilters})
+	return b
+}
+
+func (b *QueryImp) Or(filters ...builder.Query) builder.Query {
+	orFilters := bson.A{}
+	for _, f := range filters {
+		orFilters = append(orFilters, f.BuildQuery())
+	}
+	b.filter = append(b.filter, bson.E{Key: string(builder.Or), Value: orFilters})
+	return b
+}
+
+func (b *QueryImp) Comparison(field builder.Field, operator builder.MongoOperation, value any) builder.Query {
+	b.filter = append(b.filter, bson.E{Key: field.Build(), Value: bson.M{string(operator): value}})
+	return b
+}
+
+func (b *QueryImp) Expression(value builder.Expression) builder.Query {
+	b.filter = append(b.filter, bson.E{Key: string(builder.Expr), Value: value.Build()})
+	return b
+}
+
+func (b *QueryImp) RegEx(field builder.Field, pattern, options string) builder.Query {
+	b.filter = append(b.filter, bson.E{Key: field.Build(), Value: bson.Regex{Pattern: pattern, Options: options}})
+	return b
+}
+
+func (b *QueryImp) opIn(field builder.Field, op builder.MongoOperation, values ...any) builder.Query {
+	// Mongo requires $in and $nin operands to be arrays. Keep an empty input as
+	// a non-nil slice so the BSON encoder emits [] instead of null.
+	flattenedValues := make([]any, 0, len(values))
+
+	for _, v := range values {
+		valueType := reflect.TypeOf(v)
+		if valueType == nil {
+			flattenedValues = append(flattenedValues, nil)
+			continue
+		}
+		switch valueType.Kind() {
+		case reflect.Slice:
+			slice := reflect.ValueOf(v)
+			for i := range slice.Len() {
+				flattenedValues = append(flattenedValues, slice.Index(i).Interface())
+			}
+		default:
+			flattenedValues = append(flattenedValues, v)
+		}
+	}
+
+	b.filter = append(b.filter, bson.E{Key: field.Build(), Value: bson.M{string(op): flattenedValues}})
+	return b
+}
+
+func (b *QueryImp) NotIn(field builder.Field, values ...any) builder.Query {
+	return b.opIn(field, builder.NotIn, values...)
+}
+
+func (b *QueryImp) In(field builder.Field, values ...any) builder.Query {
+	return b.opIn(field, builder.In, values...)
+}
+
+func (b *QueryImp) Archived(isArchived *bool) builder.Query {
+	if isArchived == nil {
+		return b
+	}
+	return b.And(NewQueryImp().Filter(NewFieldImp(storable.IsArchivedField), *isArchived))
+}
+
+func (b *QueryImp) Sort(field builder.Field, ascending bool) builder.Query {
+	order := 1
+	if !ascending {
+		order = -1
+	}
+	b.sort = append(b.sort, bson.E{Key: field.Build(), Value: order})
+	return b
+}
+
+func (b *QueryImp) BuildPipeline() bson.D {
+	query := bson.D{}
+
+	if len(b.filter) > 0 {
+		query = append(query, bson.E{Key: string(builder.Match), Value: b.filter})
+	}
+
+	if len(b.sort) > 0 {
+		query = append(query, bson.E{Key: string(builder.Sort), Value: b.sort})
+	}
+
+	if b.limit != nil {
+		query = append(query, bson.E{Key: string(builder.Limit), Value: *b.limit})
+	}
+
+	if b.offset != nil {
+		query = append(query, bson.E{Key: string(builder.Skip), Value: *b.offset})
+	}
+
+	return query
+}
+
+func (b *QueryImp) BuildQuery() bson.D {
+	return b.filter
+}
+
+func (b *QueryImp) Limit(limit *int64) builder.Query {
+	b.limit = limit
+	return b
+}
+
+func (b *QueryImp) Offset(offset *int64) builder.Query {
+	b.offset = offset
+	return b
+}
+
+func (b *QueryImp) BuildOptions() *options.FindOptionsBuilder {
+	opts := options.Find()
+	if b.limit != nil {
+		opts.SetLimit(*b.limit)
+	}
+	if b.offset != nil {
+		opts.SetSkip(*b.offset)
+	}
+	if len(b.sort) > 0 {
+		opts.SetSort(b.sort)
+	}
+	return opts
+}
+
+func NewQueryImp() builder.Query {
+	return &QueryImp{
+		filter: bson.D{},
+		sort:   bson.D{},
+	}
+}

backend/shared/database/internal/builder/query_test.go

@@ -0,0 +1,31 @@
+package builderimp
+
+import (
+	"testing"
+
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"github.com/stretchr/testify/require"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+func TestEmptySetComparisonsRemainBSONArrays(t *testing.T) {
+	field := NewFieldImp("organizationRef")
+
+	require.Equal(t,
+		bson.D{{Key: "organizationRef", Value: bson.M{string(builder.NotIn): []any{}}}},
+		NewQueryImp().NotIn(field).BuildQuery(),
+	)
+	require.Equal(t,
+		bson.D{{Key: "organizationRef", Value: bson.M{string(builder.In): []any{}}}},
+		NewQueryImp().In(field).BuildQuery(),
+	)
+}
+
+func TestSetComparisonsAcceptNilElements(t *testing.T) {
+	field := NewFieldImp("organizationRef")
+
+	require.Equal(t,
+		bson.D{{Key: "organizationRef", Value: bson.M{string(builder.NotIn): []any{"", nil}}}},
+		NewQueryImp().NotIn(field, "", nil).BuildQuery(),
+	)
+}

backend/shared/database/internal/builder/value.go

@@ -0,0 +1,17 @@
+package builderimp
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+)
+
+type valueImp struct {
+	value any
+}
+
+func (v *valueImp) Build() any {
+	return v.value
+}
+
+func NewValue(value any) builder.Value {
+	return &valueImp{value: value}
+}

backend/shared/database/internal/mongo/db.go

@@ -0,0 +1,240 @@
+package mongo
+
+import (
+	"context"
+	"fmt"
+	sharedmodel "git.sendico.io/tech/sxchnge/shared/model"
+	"net"
+	"os"
+	"strings"
+
+	mutil "git.sendico.io/tech/sxchnge/shared/config"
+	"git.sendico.io/tech/sxchnge/shared/database/internal/transaction"
+	"git.sendico.io/tech/sxchnge/shared/database/transaction"
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"github.com/go-viper/mapstructure/v2"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/readpref"
+	"go.uber.org/zap"
+)
+
+// Config represents configuration
+type Config struct {
+	Port              *string  `mapstructure:"port"`
+	PortEnv           *string  `mapstructure:"port_env"`
+	User              *string  `mapstructure:"user"`
+	UserEnv           *string  `mapstructure:"user_env"`
+	PasswordEnv       string   `mapstructure:"password_env"`
+	Database          *string  `mapstructure:"database"`
+	DatabaseEnv       *string  `mapstructure:"database_env"`
+	Host              *string  `mapstructure:"host"`
+	HostEnv           *string  `mapstructure:"host_env"`
+	Hosts             []string `mapstructure:"hosts,omitempty"`
+	HostsEnvPrefix    *string  `mapstructure:"hosts_env_prefix,omitempty"`
+	HostsEnvPrefixEnv *string  `mapstructure:"hosts_env_prefix_env,omitempty"`
+	PortsEnvPrefix    *string  `mapstructure:"ports_env_prefix,omitempty"`
+	PortsEnvPrefixEnv *string  `mapstructure:"ports_env_prefix_env,omitempty"`
+	URI               *string  `mapstructure:"uri,omitempty"`
+	URIEnv            *string  `mapstructure:"uri_env,omitempty"`
+	AuthSource        *string  `mapstructure:"auth_source,omitempty"`
+	AuthSourceEnv     *string  `mapstructure:"auth_source_env,omitempty"`
+	AuthMechanism     *string  `mapstructure:"auth_mechanism,omitempty"`
+	AuthMechanismEnv  *string  `mapstructure:"auth_mechanism_env,omitempty"`
+	ReplicaSet        *string  `mapstructure:"replica_set,omitempty"`
+	ReplicaSetEnv     *string  `mapstructure:"replica_set_env,omitempty"`
+}
+
+type DBSettings struct {
+	Host          string
+	Hosts         []string
+	Port          string
+	User          string
+	Password      string
+	Database      string
+	AuthSource    string
+	AuthMechanism string
+	ReplicaSet    string
+	URI           string
+}
+
+func Config2DBSettings(logger mlogger.Logger, config *Config) *DBSettings {
+	p := new(DBSettings)
+	p.Port = mutil.GetConfigValue(logger, "port", "port_env", config.Port, config.PortEnv)
+	p.Database = mutil.GetConfigValue(logger, "database", "database_env", config.Database, config.DatabaseEnv)
+	p.Password = os.Getenv(config.PasswordEnv)
+	p.User = mutil.GetConfigValue(logger, "user", "user_env", config.User, config.UserEnv)
+	p.Host = mutil.GetConfigValue(logger, "host", "host_env", config.Host, config.HostEnv)
+	p.AuthSource = mutil.GetConfigValue(logger, "auth_source", "auth_source_env", config.AuthSource, config.AuthSourceEnv)
+	p.AuthMechanism = mutil.GetConfigValue(logger, "auth_mechanism", "auth_mechanism_env", config.AuthMechanism, config.AuthMechanismEnv)
+	p.ReplicaSet = mutil.GetConfigValue(logger, "replica_set", "replica_set_env", config.ReplicaSet, config.ReplicaSetEnv)
+	p.URI = mutil.GetConfigValue(logger, "uri", "uri_env", config.URI, config.URIEnv)
+
+	hostPrefix := mutil.GetConfigValue(logger, "hosts_env_prefix", "hosts_env_prefix_env", config.HostsEnvPrefix, config.HostsEnvPrefixEnv)
+	portPrefix := mutil.GetConfigValue(logger, "ports_env_prefix", "ports_env_prefix_env", config.PortsEnvPrefix, config.PortsEnvPrefixEnv)
+
+	if hostPrefix == "" && p.ReplicaSet != "" {
+		hostPrefix = "MONGO_HOSTS_"
+	}
+	if portPrefix == "" && p.ReplicaSet != "" {
+		portPrefix = "MONGO_PORTS_"
+	}
+
+	p.Hosts = collectReplicaHosts(config.Hosts, p.ReplicaSet, p.Port, hostPrefix, portPrefix)
+	return p
+}
+
+func decodeConfig(logger mlogger.Logger, settings sharedmodel.SettingsT) (*Config, *DBSettings, error) {
+	var config Config
+	if err := mapstructure.Decode(settings, &config); err != nil {
+		logger.Warn("Failed to decode settings", zap.Error(err))
+		return nil, nil, err
+	}
+	dbSettings := Config2DBSettings(logger, &config)
+	return &config, dbSettings, nil
+}
+
+func dialMongo(logger mlogger.Logger, dbSettings *DBSettings) (*mongo.Client, error) {
+	opts := buildOptions(dbSettings)
+
+	client, err := mongo.Connect(opts)
+	if err != nil {
+		logger.Error("Unable to connect to database", zap.Error(err))
+		return nil, err
+	}
+
+	if dbSettings.URI != "" {
+		logger.Info("Connected successfully", zap.Bool("uri_provided", true))
+	} else {
+		logger.Info("Connected successfully", zap.String("user", dbSettings.User),
+			zap.Strings("hosts", opts.Hosts), zap.String("port", dbSettings.Port),
+			zap.String("database", dbSettings.Database), zap.String("replica_set", dbSettings.ReplicaSet))
+	}
+
+	if err := client.Ping(context.Background(), readpref.Primary()); err != nil {
+		logger.Error("Unable to ping database", zap.Error(err))
+		_ = client.Disconnect(context.Background())
+		return nil, err
+	}
+
+	return client, nil
+}
+
+func ConnectClient(logger mlogger.Logger, settings sharedmodel.SettingsT) (*mongo.Client, *Config, *DBSettings, error) {
+	config, dbSettings, err := decodeConfig(logger, settings)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+
+	client, err := dialMongo(logger, dbSettings)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+
+	return client, config, dbSettings, nil
+}
+
+// DB represents the structure of the database
+type DB struct {
+	logger mlogger.Logger
+	config *DBSettings
+	client *mongo.Client
+}
+
+func (db *DB) db() *mongo.Database {
+	return db.client.Database(db.config.Database)
+}
+
+func (db *DB) MongoDatabase() *mongo.Database {
+	return db.db()
+}
+
+func (db *DB) TransactionFactory() transaction.Factory {
+	return transactionimp.CreateFactory(db.client)
+}
+
+func collectReplicaHosts(configuredHosts []string, replicaSet, defaultPort, hostPrefix, portPrefix string) []string {
+	normalize := func(host, port string) string {
+		host = strings.TrimSpace(host)
+		port = strings.TrimSpace(port)
+		if host == "" {
+			return ""
+		}
+		// If host already has a port, keep it; otherwise apply provided/default port.
+		if _, _, err := net.SplitHostPort(host); err == nil {
+			return host
+		}
+		if port != "" {
+			return net.JoinHostPort(host, port)
+		}
+		if defaultPort != "" {
+			return net.JoinHostPort(host, defaultPort)
+		}
+		return host
+	}
+
+	appendHost := func(list []string, host, port string) []string {
+		if normalized := normalize(host, port); normalized != "" {
+			return append(list, normalized)
+		}
+		return list
+	}
+
+	var hosts []string
+	for _, h := range configuredHosts {
+		hosts = appendHost(hosts, h, "")
+	}
+
+	if replicaSet == "" || hostPrefix == "" {
+		return hosts
+	}
+
+	index := 0
+	for {
+		hostEnv := os.Getenv(fmt.Sprintf("%s%d", hostPrefix, index))
+		portEnv := ""
+		if portPrefix != "" {
+			portEnv = os.Getenv(fmt.Sprintf("%s%d", portPrefix, index))
+		}
+
+		if hostEnv == "" && index == 0 {
+			hostEnv = os.Getenv(fmt.Sprintf("%s%d", hostPrefix, 1))
+			if portPrefix != "" {
+				portEnv = os.Getenv(fmt.Sprintf("%s%d", portPrefix, 1))
+			}
+			if hostEnv == "" {
+				break
+			}
+			index = 1
+		} else if hostEnv == "" {
+			break
+		}
+
+		hosts = appendHost(hosts, hostEnv, portEnv)
+		index++
+	}
+
+	return hosts
+}
+
+func (db *DB) CloseConnection() {
+	if err := db.client.Disconnect(context.Background()); err != nil {
+		db.logger.Warn("Failed to close connection", zap.Error(err))
+	}
+	db.logger.Info("Database connection closed")
+}
+
+// NewConnection creates a new database connection
+func NewConnection(logger mlogger.Logger, settings sharedmodel.SettingsT) (*DB, error) {
+	client, _, dbSettings, err := ConnectClient(logger, settings)
+	if err != nil {
+		return nil, err
+	}
+
+	db := &DB{
+		logger: logger.Named("db"),
+		config: dbSettings,
+		client: client,
+	}
+
+	return db, nil
+}

backend/shared/database/internal/mongo/mongo.go

@@ -0,0 +1,49 @@
+package mongo
+
+import (
+	"net"
+	"strings"
+
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func buildOptions(s *DBSettings) *options.ClientOptions {
+	opts := options.Client()
+
+	if s.URI != "" {
+		return opts.ApplyURI(s.URI)
+	}
+
+	hosts := make([]string, 0, len(s.Hosts)+1)
+	for _, h := range s.Hosts {
+		if trimmed := strings.TrimSpace(h); trimmed != "" {
+			hosts = append(hosts, trimmed)
+		}
+	}
+
+	if len(hosts) == 0 && s.Host != "" {
+		host := s.Host
+		if _, _, err := net.SplitHostPort(host); err != nil && s.Port != "" {
+			host = net.JoinHostPort(host, s.Port)
+		}
+		hosts = append(hosts, host)
+	}
+
+	if len(hosts) > 0 {
+		opts.SetHosts(hosts)
+	}
+
+	if s.ReplicaSet != "" {
+		opts.SetReplicaSet(s.ReplicaSet)
+	}
+
+	cred := options.Credential{
+		AuthMechanism: s.AuthMechanism,
+		AuthSource:    s.AuthSource,
+		Username:      s.User,
+		Password:      s.Password,
+	}
+	opts.SetAuth(cred)
+
+	return opts
+}

backend/shared/database/internal/repository/index.go

@@ -0,0 +1,143 @@
+package repositoryimp
+
+import (
+	"context"
+	"fmt"
+
+	ri "git.sendico.io/tech/sxchnge/shared/database/repository/index"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func (r *MongoRepository) CreateIndex(def *ri.Definition) error {
+	if r.collection == nil {
+		return merrors.NoData("data collection is not set")
+	}
+	if len(def.Keys) == 0 {
+		return merrors.InvalidArgument("Index definition has no keys", "index.keys")
+	}
+
+	// ----- build BSON keys --------------------------------------------------
+	keys := bson.D{}
+	for _, k := range def.Keys {
+		var value any
+		switch {
+		case k.Type != "":
+			value = k.Type // text, 2dsphere, …
+		case k.Sort == ri.Desc:
+			value = int8(-1)
+		default:
+			value = int8(1) // default to Asc
+		}
+		keys = append(keys, bson.E{Key: k.Field, Value: value})
+	}
+
+	opts := options.Index().
+		SetUnique(def.Unique)
+	if def.TTL != nil {
+		opts.SetExpireAfterSeconds(*def.TTL)
+	}
+	if def.Name != "" {
+		opts.SetName(def.Name)
+	}
+	if def.PartialFilter != nil {
+		opts.SetPartialFilterExpression(def.PartialFilter.BuildQuery())
+	}
+	if def.Sparse {
+		opts.SetSparse(def.Sparse)
+	}
+
+	_, err := r.collection.Indexes().CreateOne(
+		context.Background(),
+		mongo.IndexModel{Keys: keys, Options: opts},
+	)
+	return err
+}
+
+func (r *MongoRepository) DropIndex(ctx context.Context, name string) error {
+	if r.collection == nil {
+		return merrors.NoData("data collection is not set")
+	}
+	if name == "" {
+		return merrors.InvalidArgument("index name is required", "index.name")
+	}
+	return r.collection.Indexes().DropOne(ctx, name)
+}
+
+func (r *MongoRepository) ListIndexDefinitions(ctx context.Context) ([]*ri.Definition, error) {
+	if r.collection == nil {
+		return nil, merrors.NoData("data collection is not set")
+	}
+	cursor, err := r.collection.Indexes().List(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = cursor.Close(ctx) }()
+
+	defs := make([]*ri.Definition, 0)
+	for cursor.Next(ctx) {
+		var doc mongoIndexDocument
+		if err := cursor.Decode(&doc); err != nil {
+			return nil, err
+		}
+		defs = append(defs, indexDefinitionFromDocument(doc))
+	}
+	if err := cursor.Err(); err != nil {
+		return nil, err
+	}
+	return defs, nil
+}
+
+type mongoIndexDocument struct {
+	Name               string `bson:"name"`
+	Key                bson.D `bson:"key"`
+	Unique             bool   `bson:"unique"`
+	Sparse             bool   `bson:"sparse"`
+	ExpireAfterSeconds *int32 `bson:"expireAfterSeconds,omitempty"`
+}
+
+func indexDefinitionFromDocument(doc mongoIndexDocument) *ri.Definition {
+	keys := make([]ri.Key, 0, len(doc.Key))
+	for _, key := range doc.Key {
+		keys = append(keys, indexKeyFromBSON(key))
+	}
+	return &ri.Definition{
+		Keys:   keys,
+		Unique: doc.Unique,
+		Sparse: doc.Sparse,
+		TTL:    doc.ExpireAfterSeconds,
+		Name:   doc.Name,
+	}
+}
+
+func indexKeyFromBSON(key bson.E) ri.Key {
+	out := ri.Key{Field: key.Key}
+	switch typed := key.Value.(type) {
+	case string:
+		out.Type = ri.IndexType(typed)
+	case int:
+		out.Sort = indexSort(typed)
+	case int8:
+		out.Sort = indexSort(typed)
+	case int16:
+		out.Sort = indexSort(typed)
+	case int32:
+		out.Sort = indexSort(typed)
+	case int64:
+		out.Sort = indexSort(typed)
+	case float64:
+		out.Sort = indexSort(typed)
+	default:
+		out.Type = ri.IndexType(fmt.Sprint(typed))
+	}
+	return out
+}
+
+func indexSort[T ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~float64](value T) ri.Sort {
+	if value < 0 {
+		return ri.Desc
+	}
+	return ri.Asc
+}

backend/shared/database/internal/repository/index_integration_test.go

@@ -0,0 +1,95 @@
+//go:build integration
+// +build integration
+
+package repositoryimp_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/database/repository"
+	ri "git.sendico.io/tech/sxchnge/shared/database/repository/index"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/mongodb"
+	"github.com/testcontainers/testcontainers-go/wait"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func TestCreateIndex_WithPartialFilter(t *testing.T) {
+	startCtx, startCancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer startCancel()
+
+	mongoContainer, err := mongodb.Run(startCtx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForListeningPort("27017/tcp").WithStartupTimeout(2*time.Minute)),
+	)
+	require.NoError(t, err)
+
+	mongoURI, err := mongoContainer.ConnectionString(startCtx)
+	require.NoError(t, err)
+
+	client, err := mongo.Connect(options.Client().ApplyURI(mongoURI))
+	require.NoError(t, err)
+	defer client.Disconnect(context.Background())
+
+	database := client.Database("test_partial_index_" + t.Name())
+	defer database.Drop(context.Background())
+
+	repo := repository.CreateMongoRepository(database, "partial_index_items")
+
+	def := &ri.Definition{
+		Keys: []ri.Key{
+			{Field: "field", Sort: ri.Asc},
+		},
+		Unique:        true,
+		Name:          "partial_unique_field_true",
+		PartialFilter: repository.Filter("flag", true),
+	}
+
+	require.NoError(t, repo.CreateIndex(def))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	defs, err := repo.ListIndexDefinitions(ctx)
+	require.NoError(t, err)
+	listed := false
+	for _, listedDef := range defs {
+		if listedDef.Name == def.Name {
+			listed = true
+			assert.True(t, listedDef.Unique)
+			assert.Equal(t, []ri.Key{{Field: "field", Sort: ri.Asc}}, listedDef.Keys)
+		}
+	}
+	assert.True(t, listed, "created index was not returned by ListIndexDefinitions")
+
+	cursor, err := database.Collection(repo.Collection()).Indexes().List(ctx)
+	require.NoError(t, err)
+	defer cursor.Close(ctx)
+
+	found := false
+	for cursor.Next(ctx) {
+		var idx bson.M
+		require.NoError(t, cursor.Decode(&idx))
+		if idx["name"] == def.Name {
+			found = true
+			assert.Equal(t, true, idx["unique"])
+			assert.Equal(t, bson.M{"field": int32(1)}, idx["key"])
+			partial, ok := idx["partialFilterExpression"].(bson.M)
+			require.True(t, ok)
+			assert.Equal(t, bson.M{"flag": true}, partial)
+		}
+	}
+	assert.True(t, found, "partial unique index was not created")
+
+	termCtx, termCancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer termCancel()
+	_ = mongoContainer.Terminate(termCtx)
+}

backend/shared/database/internal/repository/index_test.go

@@ -0,0 +1,52 @@
+package repositoryimp
+
+import (
+	"testing"
+
+	ri "git.sendico.io/tech/sxchnge/shared/database/repository/index"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+func TestIndexDefinitionFromDocumentMapsIndexMetadata(t *testing.T) {
+	ttl := int32(3600)
+	def := indexDefinitionFromDocument(mongoIndexDocument{
+		Name:               "account_ref_unique",
+		Key:                bson.D{{Key: "accountRef", Value: int32(1)}, {Key: "version", Value: int64(-1)}},
+		Unique:             true,
+		Sparse:             true,
+		ExpireAfterSeconds: &ttl,
+	})
+
+	if def.Name != "account_ref_unique" || !def.Unique || !def.Sparse {
+		t.Fatalf("unexpected definition metadata: %#v", def)
+	}
+	if def.TTL == nil || *def.TTL != ttl {
+		t.Fatalf("TTL = %v, want %d", def.TTL, ttl)
+	}
+	wantKeys := []ri.Key{
+		{Field: "accountRef", Sort: ri.Asc},
+		{Field: "version", Sort: ri.Desc},
+	}
+	if len(def.Keys) != len(wantKeys) {
+		t.Fatalf("keys = %#v, want %#v", def.Keys, wantKeys)
+	}
+	for i := range wantKeys {
+		if def.Keys[i] != wantKeys[i] {
+			t.Fatalf("keys[%d] = %#v, want %#v", i, def.Keys[i], wantKeys[i])
+		}
+	}
+}
+
+func TestIndexDefinitionFromDocumentMapsTypedIndex(t *testing.T) {
+	def := indexDefinitionFromDocument(mongoIndexDocument{
+		Name: "text_index",
+		Key:  bson.D{{Key: "description", Value: "text"}},
+	})
+
+	if len(def.Keys) != 1 {
+		t.Fatalf("keys = %#v", def.Keys)
+	}
+	if def.Keys[0] != (ri.Key{Field: "description", Type: ri.IndexTypeText}) {
+		t.Fatalf("key = %#v", def.Keys[0])
+	}
+}

backend/shared/database/internal/repository/repository.go

@@ -0,0 +1,253 @@
+package repositoryimp
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	rd "git.sendico.io/tech/sxchnge/shared/database/repository/decoder"
+	"git.sendico.io/tech/sxchnge/shared/database/transaction"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+type MongoRepository struct {
+	collectionName string
+	collection     *mongo.Collection
+}
+
+func idFilter(id bson.ObjectID) bson.D {
+	return bson.D{
+		{Key: storable.IDField, Value: id},
+	}
+}
+
+func NewMongoRepository(db *mongo.Database, collection string) *MongoRepository {
+	return &MongoRepository{
+		collectionName: collection,
+		collection:     db.Collection(collection),
+	}
+}
+
+func (r *MongoRepository) Collection() string {
+	return r.collectionName
+}
+
+func prepareForWrite(obj storable.Storable) bson.ObjectID {
+	id := obj.GetID()
+	if id == nil || id.IsZero() {
+		obj.SetID(bson.NewObjectID())
+		id = obj.GetID()
+	}
+	obj.Update()
+	return *id
+}
+
+func (r *MongoRepository) Insert(ctx context.Context, obj storable.Storable, getFilter builder.Query) error {
+	prepareForWrite(obj)
+	_, err := r.collection.InsertOne(ctx, obj)
+	if mongo.IsDuplicateKeyError(err) {
+		if getFilter != nil {
+			if err = r.FindOneByFilter(ctx, getFilter, obj); err != nil {
+				return err
+			}
+		}
+		return merrors.DataConflict("duplicate_key")
+	}
+	return err
+}
+
+func (r *MongoRepository) InsertMany(ctx context.Context, objects []storable.Storable) error {
+	if len(objects) == 0 {
+		return nil
+	}
+
+	docs := make([]interface{}, len(objects))
+	for i, obj := range objects {
+		prepareForWrite(obj)
+		docs[i] = obj
+	}
+
+	_, err := r.collection.InsertMany(ctx, docs)
+	return err
+}
+
+func (r *MongoRepository) findOneByFilterImp(ctx context.Context, filter bson.D, errMessage string, result storable.Storable) error {
+	err := r.collection.FindOne(ctx, filter).Decode(result)
+	if errors.Is(err, mongo.ErrNoDocuments) {
+		return merrors.NoData(errMessage)
+	}
+	return err
+}
+
+func (r *MongoRepository) Get(ctx context.Context, id bson.ObjectID, result storable.Storable) error {
+	if id.IsZero() {
+		return merrors.InvalidArgument("zero id provided while fetching "+result.Collection(), "id")
+	}
+	return r.findOneByFilterImp(ctx, idFilter(id), fmt.Sprintf("%s with ID = %s not found", result.Collection(), id.Hex()), result)
+}
+
+type QueryFunc func(ctx context.Context, collection *mongo.Collection) (*mongo.Cursor, error)
+
+func (r *MongoRepository) executeQuery(ctx context.Context, queryFunc QueryFunc, decoder rd.DecodingFunc) error {
+	cursor, err := queryFunc(ctx, r.collection)
+	if errors.Is(err, mongo.ErrNoDocuments) {
+		return merrors.NoData("no_items_in_array")
+	}
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = cursor.Close(ctx)
+	}()
+
+	for cursor.Next(ctx) {
+		if err = decoder(cursor); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (r *MongoRepository) Aggregate(ctx context.Context, pipeline builder.Pipeline, decoder rd.DecodingFunc) error {
+	queryFunc := func(ctx context.Context, collection *mongo.Collection) (*mongo.Cursor, error) {
+		return collection.Aggregate(ctx, pipeline.Build())
+	}
+	return r.executeQuery(ctx, queryFunc, decoder)
+}
+
+func (r *MongoRepository) FindManyByFilter(ctx context.Context, query builder.Query, decoder rd.DecodingFunc) error {
+	queryFunc := func(ctx context.Context, collection *mongo.Collection) (*mongo.Cursor, error) {
+		return collection.Find(ctx, query.BuildQuery(), query.BuildOptions())
+	}
+	return r.executeQuery(ctx, queryFunc, decoder)
+}
+
+func (r *MongoRepository) FindAllByFilter(ctx context.Context, query builder.Query, result any) error {
+	if query == nil {
+		cursor, err := r.collection.Find(ctx, bson.D{})
+		if err != nil {
+			return err
+		}
+		defer func() {
+			_ = cursor.Close(ctx)
+		}()
+		return cursor.All(ctx, result)
+	}
+	cursor, err := r.collection.Find(ctx, query.BuildQuery(), query.BuildOptions())
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = cursor.Close(ctx)
+	}()
+	return cursor.All(ctx, result)
+}
+
+func (r *MongoRepository) FindOneByFilter(ctx context.Context, query builder.Query, result storable.Storable) error {
+	return r.findOneByFilterImp(ctx, query.BuildQuery(), result.Collection()+" not found by filter", result)
+}
+
+func (r *MongoRepository) Update(ctx context.Context, obj storable.Storable) error {
+	obj.Update()
+	return r.collection.FindOneAndReplace(ctx, idFilter(*obj.GetID()), obj).Err()
+}
+
+func (r *MongoRepository) ReplaceOneByFilter(ctx context.Context, query builder.Query, obj storable.Storable) (bool, error) {
+	if query == nil {
+		return false, merrors.InvalidArgument("filter is required", "filter")
+	}
+	if obj == nil {
+		return false, merrors.InvalidArgument("object is required", "obj")
+	}
+	result, err := r.collection.ReplaceOne(ctx, query.BuildQuery(), obj)
+	if mongo.IsDuplicateKeyError(err) {
+		return false, merrors.DataConflict("duplicate_key")
+	}
+	if err != nil {
+		return false, err
+	}
+	return result.MatchedCount > 0, nil
+}
+
+func (r *MongoRepository) Upsert(ctx context.Context, obj storable.Storable) error {
+	id := prepareForWrite(obj)
+	_, err := r.collection.ReplaceOne(ctx, idFilter(id), obj, options.Replace().SetUpsert(true))
+	return err
+}
+
+func (r *MongoRepository) Patch(ctx context.Context, id bson.ObjectID, patch builder.Patch) error {
+	if id.IsZero() {
+		return merrors.InvalidArgument("zero id provided while patching", "id")
+	}
+	_, err := r.collection.UpdateByID(ctx, id, patch.Build())
+	return err
+}
+
+func (r *MongoRepository) PatchMany(ctx context.Context, query builder.Query, patch builder.Patch) (int, error) {
+	result, err := r.collection.UpdateMany(ctx, query.BuildQuery(), patch.Build())
+	if err != nil {
+		return 0, err
+	}
+	return int(result.ModifiedCount), nil
+}
+
+func (r *MongoRepository) ListIDs(ctx context.Context, query builder.Query) ([]bson.ObjectID, error) {
+	filter := query.BuildQuery()
+	findOptions := query.BuildOptions().SetProjection(bson.M{storable.IDField: 1})
+
+	cursor, err := r.collection.Find(ctx, filter, findOptions)
+	if err != nil {
+		return nil, err
+	}
+	defer func() {
+		_ = cursor.Close(ctx)
+	}()
+
+	var ids []bson.ObjectID
+	for cursor.Next(ctx) {
+		var doc struct {
+			ID bson.ObjectID `bson:"_id"`
+		}
+		if err := cursor.Decode(&doc); err != nil {
+			return nil, err
+		}
+		ids = append(ids, doc.ID)
+	}
+	if err := cursor.Err(); err != nil {
+		return nil, err
+	}
+
+	return ids, nil
+}
+
+func (r *MongoRepository) Delete(ctx context.Context, id bson.ObjectID) error {
+	_, err := r.collection.DeleteOne(ctx, idFilter(id))
+	return err
+}
+
+func (r *MongoRepository) DeleteMany(ctx context.Context, query builder.Query) error {
+	_, err := r.collection.DeleteMany(ctx, query.BuildQuery())
+	return err
+}
+
+func (r *MongoRepository) Name() string {
+	return r.collection.Name()
+}
+
+func (r *MongoRepository) WithTransaction(ctx context.Context, cb transaction.Callback) (any, error) {
+	if cb == nil {
+		return nil, merrors.InvalidArgument("transaction callback is required", "callback")
+	}
+	session, err := r.collection.Database().Client().StartSession()
+	if err != nil {
+		return nil, err
+	}
+	defer session.EndSession(ctx)
+	return session.WithTransaction(ctx, cb)
+}

backend/shared/database/internal/repository/repository_comprehensive_test.go

@@ -0,0 +1,510 @@
+//go:build integration
+// +build integration
+
+package repositoryimp_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/database/internal/builder"
+	"git.sendico.io/tech/sxchnge/shared/database/internal/repository"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/mongodb"
+	"github.com/testcontainers/testcontainers-go/wait"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func TestMongoRepository_Insert(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("Insert_WithoutID", func(t *testing.T) {
+		testObj := &TestObject{Name: "testInsert"}
+		// ID should be nil/zero initially
+		assert.True(t, testObj.GetID().IsZero())
+
+		err := repository.Insert(ctx, testObj, nil)
+		require.NoError(t, err)
+
+		// ID should be assigned after insert
+		assert.False(t, testObj.GetID().IsZero())
+		assert.NotEmpty(t, testObj.CreatedAt)
+		assert.NotEmpty(t, testObj.UpdatedAt)
+	})
+
+	t.Run("Insert_WithExistingID", func(t *testing.T) {
+		existingID := bson.NewObjectID()
+		testObj := &TestObject{Name: "testInsertWithID"}
+		testObj.SetID(existingID)
+
+		err := repository.Insert(ctx, testObj, nil)
+		require.NoError(t, err)
+
+		// ID should remain the same
+		assert.Equal(t, existingID, *testObj.GetID())
+	})
+
+	t.Run("Insert_DuplicateKey", func(t *testing.T) {
+		// Insert first object
+		testObj1 := &TestObject{Name: "duplicate"}
+		err := repository.Insert(ctx, testObj1, nil)
+		require.NoError(t, err)
+
+		// Try to insert object with same ID
+		testObj2 := &TestObject{Name: "duplicate2"}
+		testObj2.SetID(*testObj1.GetID())
+
+		err = repository.Insert(ctx, testObj2, nil)
+		assert.Error(t, err)
+		assert.True(t, errors.Is(err, merrors.ErrDataConflict))
+	})
+
+	t.Run("Insert_DuplicateKeyWithGetFilter", func(t *testing.T) {
+		// Insert first object
+		testObj1 := &TestObject{Name: "duplicateWithFilter"}
+		err := repository.Insert(ctx, testObj1, nil)
+		require.NoError(t, err)
+
+		// Try to insert object with same ID, but with getFilter
+		testObj2 := &TestObject{Name: "duplicateWithFilter2"}
+		testObj2.SetID(*testObj1.GetID())
+
+		getFilter := builderimp.NewQueryImp().Comparison(builderimp.NewFieldImp("_id"), builder.Eq, *testObj1.GetID())
+
+		err = repository.Insert(ctx, testObj2, getFilter)
+		assert.Error(t, err)
+		assert.True(t, errors.Is(err, merrors.ErrDataConflict))
+
+		// But testObj2 should be populated with the existing object data
+		assert.Equal(t, testObj1.Name, testObj2.Name)
+	})
+}
+
+func TestMongoRepository_Update(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("Update_ExistingObject", func(t *testing.T) {
+		// Insert object first
+		testObj := &TestObject{Name: "originalName"}
+		err := repository.Insert(ctx, testObj, nil)
+		require.NoError(t, err)
+
+		originalUpdatedAt := testObj.UpdatedAt
+
+		// Update the object
+		testObj.Name = "updatedName"
+		time.Sleep(10 * time.Millisecond) // Ensure time difference
+
+		err = repository.Update(ctx, testObj)
+		require.NoError(t, err)
+
+		// Verify the object was updated
+		result := &TestObject{}
+		err = repository.Get(ctx, *testObj.GetID(), result)
+		require.NoError(t, err)
+		assert.Equal(t, "updatedName", result.Name)
+		assert.True(t, result.UpdatedAt.After(originalUpdatedAt))
+	})
+
+	t.Run("Update_NonExistentObject", func(t *testing.T) {
+		nonExistentID := bson.NewObjectID()
+		testObj := &TestObject{Name: "nonExistent"}
+		testObj.SetID(nonExistentID)
+
+		err := repository.Update(ctx, testObj)
+		assert.Error(t, err)
+		assert.True(t, errors.Is(err, mongo.ErrNoDocuments))
+	})
+}
+
+func TestMongoRepository_Delete(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("Delete_ExistingObject", func(t *testing.T) {
+		// Insert object first
+		testObj := &TestObject{Name: "toDelete"}
+		err := repository.Insert(ctx, testObj, nil)
+		require.NoError(t, err)
+
+		// Delete the object
+		err = repository.Delete(ctx, *testObj.GetID())
+		require.NoError(t, err)
+
+		// Verify the object was deleted
+		result := &TestObject{}
+		err = repository.Get(ctx, *testObj.GetID(), result)
+		assert.Error(t, err)
+		assert.True(t, errors.Is(err, merrors.ErrNoData))
+	})
+
+	t.Run("Delete_NonExistentObject", func(t *testing.T) {
+		nonExistentID := bson.NewObjectID()
+
+		err := repository.Delete(ctx, nonExistentID)
+		// Delete should not return error even if object doesn't exist
+		assert.NoError(t, err)
+	})
+}
+
+func TestMongoRepository_FindOneByFilter(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("FindOneByFilter_MatchingFilter", func(t *testing.T) {
+		// Insert test objects
+		testObjs := []*TestObject{
+			{Name: "findMe"},
+			{Name: "dontFindMe"},
+			{Name: "findMeToo"},
+		}
+
+		for _, obj := range testObjs {
+			err := repository.Insert(ctx, obj, nil)
+			require.NoError(t, err)
+		}
+
+		// Find by filter
+		query := builderimp.NewQueryImp().Comparison(builderimp.NewFieldImp("name"), builder.Eq, "findMe")
+		result := &TestObject{}
+
+		err := repository.FindOneByFilter(ctx, query, result)
+		require.NoError(t, err)
+		assert.Equal(t, "findMe", result.Name)
+	})
+
+	t.Run("FindOneByFilter_NoMatch", func(t *testing.T) {
+		query := builderimp.NewQueryImp().Comparison(builderimp.NewFieldImp("name"), builder.Eq, "nonExistentName")
+		result := &TestObject{}
+
+		err := repository.FindOneByFilter(ctx, query, result)
+		assert.Error(t, err)
+		assert.True(t, errors.Is(err, merrors.ErrNoData))
+	})
+}
+
+func TestMongoRepository_FindManyByFilter(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("FindManyByFilter_MultipleResults", func(t *testing.T) {
+		// Insert test objects
+		testObjs := []*TestObject{
+			{Name: "findMany1"},
+			{Name: "findMany2"},
+			{Name: "dontFind"},
+		}
+
+		for _, obj := range testObjs {
+			err := repository.Insert(ctx, obj, nil)
+			require.NoError(t, err)
+		}
+
+		// Find objects with names starting with "findMany"
+		query := builderimp.NewQueryImp().RegEx(builderimp.NewFieldImp("name"), "^findMany", "")
+
+		var results []*TestObject
+		decoder := func(cursor *mongo.Cursor) error {
+			var obj TestObject
+			if err := cursor.Decode(&obj); err != nil {
+				return err
+			}
+			results = append(results, &obj)
+			return nil
+		}
+
+		err := repository.FindManyByFilter(ctx, query, decoder)
+		require.NoError(t, err)
+		assert.Len(t, results, 2)
+
+		names := make([]string, len(results))
+		for i, obj := range results {
+			names[i] = obj.Name
+		}
+		assert.Contains(t, names, "findMany1")
+		assert.Contains(t, names, "findMany2")
+	})
+
+	t.Run("FindManyByFilter_NoResults", func(t *testing.T) {
+		query := builderimp.NewQueryImp().Comparison(builderimp.NewFieldImp("name"), builder.Eq, "nonExistentPattern")
+
+		var results []*TestObject
+		decoder := func(cursor *mongo.Cursor) error {
+			var obj TestObject
+			if err := cursor.Decode(&obj); err != nil {
+				return err
+			}
+			results = append(results, &obj)
+			return nil
+		}
+
+		err := repository.FindManyByFilter(ctx, query, decoder)
+		require.NoError(t, err)
+		assert.Empty(t, results)
+	})
+}
+
+func TestMongoRepository_DeleteMany(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("DeleteMany_MultipleDocuments", func(t *testing.T) {
+		// Insert test objects
+		testObjs := []*TestObject{
+			{Name: "deleteMany1"},
+			{Name: "deleteMany2"},
+			{Name: "keepMe"},
+		}
+
+		for _, obj := range testObjs {
+			err := repository.Insert(ctx, obj, nil)
+			require.NoError(t, err)
+		}
+
+		// Delete objects with names starting with "deleteMany"
+		query := builderimp.NewQueryImp().RegEx(builderimp.NewFieldImp("name"), "^deleteMany", "")
+
+		err := repository.DeleteMany(ctx, query)
+		require.NoError(t, err)
+
+		// Verify deletions
+		queryAll := builderimp.NewQueryImp()
+		var results []*TestObject
+		decoder := func(cursor *mongo.Cursor) error {
+			var obj TestObject
+			if err := cursor.Decode(&obj); err != nil {
+				return err
+			}
+			results = append(results, &obj)
+			return nil
+		}
+
+		err = repository.FindManyByFilter(ctx, queryAll, decoder)
+		require.NoError(t, err)
+		assert.Len(t, results, 1)
+		assert.Equal(t, "keepMe", results[0].Name)
+	})
+}
+
+func TestMongoRepository_Name(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "mycollection")
+
+	t.Run("Name_ReturnsCollectionName", func(t *testing.T) {
+		name := repository.Name()
+		assert.Equal(t, "mycollection", name)
+	})
+}
+
+func TestMongoRepository_UpdateTimestamp(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("Update_Should_Update_Timestamp", func(t *testing.T) {
+		// Create test object
+		obj := &TestObject{
+			Name: "Test Object",
+		}
+
+		// Set ID and initial timestamps
+		obj.SetID(bson.NewObjectID())
+		originalCreatedAt := obj.CreatedAt
+		originalUpdatedAt := obj.UpdatedAt
+
+		// Insert the object
+		err := repository.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+
+		// Wait a moment to ensure timestamp difference
+		time.Sleep(10 * time.Millisecond)
+
+		// Update the object
+		obj.Name = "Updated Object"
+		err = repository.Update(ctx, obj)
+		require.NoError(t, err)
+
+		// Verify timestamps
+		assert.Equal(t, originalCreatedAt, obj.CreatedAt, "CreatedAt should not change")
+		assert.True(t, obj.UpdatedAt.After(originalUpdatedAt), "UpdatedAt should be updated")
+
+		// Verify the object was actually updated in the database
+		var retrieved TestObject
+		err = repository.Get(ctx, *obj.GetID(), &retrieved)
+		require.NoError(t, err)
+
+		assert.Equal(t, "Updated Object", retrieved.Name, "Name should be updated")
+		assert.WithinDuration(t, originalCreatedAt, retrieved.CreatedAt, time.Second, "CreatedAt should not change in DB")
+		assert.True(t, retrieved.UpdatedAt.After(originalUpdatedAt), "UpdatedAt should be updated in DB")
+		assert.WithinDuration(t, obj.UpdatedAt, retrieved.UpdatedAt, time.Second, "UpdatedAt should match between object and DB")
+	})
+}

backend/shared/database/internal/repository/repository_filter.go

@@ -0,0 +1,59 @@
+package repositoryimp
+
+import (
+	"context"
+	"errors"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func (r *MongoRepository) FindFirstByFilter(ctx context.Context, query builder.Query, result storable.Storable) error {
+	opts := query.BuildOptions().SetLimit(1)
+	cursor, err := r.collection.Find(ctx, query.BuildQuery(), opts)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = cursor.Close(ctx)
+	}()
+	if !cursor.Next(ctx) {
+		if err := cursor.Err(); err != nil {
+			return err
+		}
+		return merrors.NoData(result.Collection() + " not found by filter")
+	}
+	return cursor.Decode(result)
+}
+
+func (r *MongoRepository) CountByFilter(ctx context.Context, query builder.Query) (int64, error) {
+	return r.collection.CountDocuments(ctx, query.BuildQuery())
+}
+
+func (r *MongoRepository) PatchOneByFilter(ctx context.Context, query builder.Query, patch builder.Patch, result storable.Storable) (bool, error) {
+	if query == nil {
+		return false, merrors.InvalidArgument("filter is required", "filter")
+	}
+	if patch == nil {
+		return false, merrors.InvalidArgument("patch is required", "patch")
+	}
+	if result == nil {
+		return false, merrors.InvalidArgument("result is required", "result")
+	}
+	err := r.collection.FindOneAndUpdate(
+		ctx,
+		query.BuildQuery(),
+		patch.Build(),
+		options.FindOneAndUpdate().SetReturnDocument(options.After),
+	).Decode(result)
+	if errors.Is(err, mongo.ErrNoDocuments) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	return true, nil
+}

backend/shared/database/internal/repository/repository_insertmany_test.go

@@ -0,0 +1,153 @@
+//go:build integration
+// +build integration
+
+package repositoryimp_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/database/internal/repository"
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/mongodb"
+	"github.com/testcontainers/testcontainers-go/wait"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func TestMongoRepository_InsertMany(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("InsertMany_Success", func(t *testing.T) {
+		objects := []storable.Storable{
+			&TestObject{Name: "test1"},
+			&TestObject{Name: "test2"},
+			&TestObject{Name: "test3"},
+		}
+
+		err := repository.InsertMany(ctx, objects)
+		require.NoError(t, err)
+
+		// Verify all objects were inserted and have IDs
+		for _, obj := range objects {
+			assert.NotNil(t, obj.GetID())
+			assert.False(t, obj.GetID().IsZero())
+
+			// Verify we can retrieve each object
+			result := &TestObject{}
+			err := repository.Get(ctx, *obj.GetID(), result)
+			require.NoError(t, err)
+			assert.Equal(t, obj.(*TestObject).Name, result.Name)
+		}
+	})
+
+	t.Run("InsertMany_EmptySlice", func(t *testing.T) {
+		objects := []storable.Storable{}
+
+		err := repository.InsertMany(ctx, objects)
+		require.NoError(t, err)
+	})
+
+	t.Run("InsertMany_WithExistingIDs", func(t *testing.T) {
+		id1 := bson.NewObjectID()
+		id2 := bson.NewObjectID()
+
+		objects := []storable.Storable{
+			&TestObject{Base: storable.Base{ID: id1}, Name: "preassigned1"},
+			&TestObject{Base: storable.Base{ID: id2}, Name: "preassigned2"},
+		}
+
+		err := repository.InsertMany(ctx, objects)
+		require.NoError(t, err)
+
+		// Verify objects were inserted with pre-assigned IDs
+		result1 := &TestObject{}
+		err = repository.Get(ctx, id1, result1)
+		require.NoError(t, err)
+		assert.Equal(t, "preassigned1", result1.Name)
+
+		result2 := &TestObject{}
+		err = repository.Get(ctx, id2, result2)
+		require.NoError(t, err)
+		assert.Equal(t, "preassigned2", result2.Name)
+	})
+
+	t.Run("InsertMany_MixedTypes", func(t *testing.T) {
+		objects := []storable.Storable{
+			&TestObject{Name: "test1"},
+			&AnotherObject{Description: "desc1"},
+			&TestObject{Name: "test2"},
+		}
+
+		err := repository.InsertMany(ctx, objects)
+		require.NoError(t, err)
+
+		// Verify all objects were inserted
+		for _, obj := range objects {
+			assert.NotNil(t, obj.GetID())
+			assert.False(t, obj.GetID().IsZero())
+		}
+	})
+
+	t.Run("InsertMany_DuplicateKey", func(t *testing.T) {
+		id := bson.NewObjectID()
+
+		// Insert first object
+		obj1 := &TestObject{Base: storable.Base{ID: id}, Name: "original"}
+		err := repository.Insert(ctx, obj1, nil)
+		require.NoError(t, err)
+
+		// Try to insert multiple objects including one with duplicate ID
+		objects := []storable.Storable{
+			&TestObject{Name: "test1"},
+			&TestObject{Base: storable.Base{ID: id}, Name: "duplicate"},
+		}
+
+		err = repository.InsertMany(ctx, objects)
+		assert.Error(t, err)
+		assert.True(t, mongo.IsDuplicateKeyError(err))
+	})
+
+	t.Run("InsertMany_UpdateTimestamps", func(t *testing.T) {
+		objects := []storable.Storable{
+			&TestObject{Name: "test1"},
+			&TestObject{Name: "test2"},
+		}
+
+		err := repository.InsertMany(ctx, objects)
+		require.NoError(t, err)
+
+		// Verify timestamps were set
+		for _, obj := range objects {
+			testObj := obj.(*TestObject)
+			assert.NotZero(t, testObj.CreatedAt)
+			assert.NotZero(t, testObj.UpdatedAt)
+		}
+	})
+}

backend/shared/database/internal/repository/repository_patch_test.go

@@ -0,0 +1,288 @@
+//go:build integration
+// +build integration
+
+package repositoryimp_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/database/internal/repository"
+	"git.sendico.io/tech/sxchnge/shared/database/repository"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/mongodb"
+	"github.com/testcontainers/testcontainers-go/wait"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func TestMongoRepository_PatchOperations(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repo := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("Patch_SingleDocument", func(t *testing.T) {
+		obj := &TestObject{Name: "old"}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+		original := obj.UpdatedAt
+
+		patch := repository.Patch().Set(repository.Field("name"), "new")
+		err = repo.Patch(ctx, *obj.GetID(), patch)
+		require.NoError(t, err)
+
+		var result TestObject
+		err = repo.Get(ctx, *obj.GetID(), &result)
+		require.NoError(t, err)
+		assert.Equal(t, "new", result.Name)
+		assert.True(t, result.UpdatedAt.After(original))
+	})
+
+	t.Run("PatchMany_MultipleDocuments", func(t *testing.T) {
+		objs := []*TestObject{{Name: "match"}, {Name: "match"}, {Name: "other"}}
+		for _, o := range objs {
+			err := repo.Insert(ctx, o, nil)
+			require.NoError(t, err)
+		}
+
+		query := repository.Query().Comparison(repository.Field("name"), builder.Eq, "match")
+		patch := repository.Patch().Set(repository.Field("name"), "patched")
+		modified, err := repo.PatchMany(ctx, query, patch)
+		require.NoError(t, err)
+		assert.Equal(t, 2, modified)
+
+		verify := repository.Query().Comparison(repository.Field("name"), builder.Eq, "patched")
+		var results []TestObject
+		decoder := func(cursor *mongo.Cursor) error {
+			var obj TestObject
+			if err := cursor.Decode(&obj); err != nil {
+				return err
+			}
+			results = append(results, obj)
+			return nil
+		}
+		err = repo.FindManyByFilter(ctx, verify, decoder)
+		require.NoError(t, err)
+		assert.Len(t, results, 2)
+	})
+
+	t.Run("PatchOneByFilter_MatchesAndReturnsUpdatedDocument", func(t *testing.T) {
+		obj := &TestObject{Name: "patch-one-match", Tags: []string{"before"}}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+		originalUpdatedAt := obj.UpdatedAt
+
+		query := repository.Query().Filter(repository.Field("name"), "patch-one-match")
+		patch := repository.Patch().
+			Set(repository.Field("name"), "patch-one-updated").
+			Push(repository.Field("tags"), "after")
+		var result TestObject
+		matched, err := repo.PatchOneByFilter(ctx, query, patch, &result)
+
+		require.NoError(t, err)
+		require.True(t, matched)
+		require.Equal(t, *obj.GetID(), *result.GetID())
+		require.Equal(t, "patch-one-updated", result.Name)
+		require.Equal(t, []string{"before", "after"}, result.Tags)
+		require.True(t, result.UpdatedAt.After(originalUpdatedAt))
+
+		var persisted TestObject
+		err = repo.Get(ctx, *obj.GetID(), &persisted)
+		require.NoError(t, err)
+		require.Equal(t, result.Name, persisted.Name)
+		require.Equal(t, result.Tags, persisted.Tags)
+	})
+
+	t.Run("PatchOneByFilter_NoMatch", func(t *testing.T) {
+		patch := repository.Patch().Set(repository.Field("name"), "not-applied")
+		var result TestObject
+
+		matched, err := repo.PatchOneByFilter(ctx, repository.Query().Filter(repository.Field("name"), "missing-patch-one"), patch, &result)
+
+		require.NoError(t, err)
+		require.False(t, matched)
+		require.Empty(t, result.Name)
+	})
+
+	t.Run("PatchOneByFilter_InvalidArguments", func(t *testing.T) {
+		var result TestObject
+		_, err := repo.PatchOneByFilter(ctx, nil, repository.Patch().Set(repository.Field("name"), "x"), &result)
+		require.Error(t, err)
+		require.True(t, errors.Is(err, merrors.ErrInvalidArg))
+
+		_, err = repo.PatchOneByFilter(ctx, repository.Query().Filter(repository.Field("name"), "x"), nil, &result)
+		require.Error(t, err)
+		require.True(t, errors.Is(err, merrors.ErrInvalidArg))
+
+		_, err = repo.PatchOneByFilter(ctx, repository.Query().Filter(repository.Field("name"), "x"), repository.Patch().Set(repository.Field("name"), "y"), nil)
+		require.Error(t, err)
+		require.True(t, errors.Is(err, merrors.ErrInvalidArg))
+	})
+
+	t.Run("Patch_PushArray", func(t *testing.T) {
+		obj := &TestObject{Name: "test", Tags: []string{"tag1"}}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+
+		patch := repository.Patch().Push(repository.Field("tags"), "tag2")
+		err = repo.Patch(ctx, *obj.GetID(), patch)
+		require.NoError(t, err)
+
+		var result TestObject
+		err = repo.Get(ctx, *obj.GetID(), &result)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"tag1", "tag2"}, result.Tags)
+	})
+
+	t.Run("Patch_PullArray", func(t *testing.T) {
+		obj := &TestObject{Name: "test", Tags: []string{"tag1", "tag2", "tag3"}}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+
+		patch := repository.Patch().Pull(repository.Field("tags"), "tag2")
+		err = repo.Patch(ctx, *obj.GetID(), patch)
+		require.NoError(t, err)
+
+		var result TestObject
+		err = repo.Get(ctx, *obj.GetID(), &result)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"tag1", "tag3"}, result.Tags)
+	})
+
+	t.Run("Patch_AddToSetArray", func(t *testing.T) {
+		obj := &TestObject{Name: "test", Tags: []string{"tag1"}}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+
+		// Add new tag
+		patch := repository.Patch().AddToSet(repository.Field("tags"), "tag2")
+		err = repo.Patch(ctx, *obj.GetID(), patch)
+		require.NoError(t, err)
+
+		var result TestObject
+		err = repo.Get(ctx, *obj.GetID(), &result)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"tag1", "tag2"}, result.Tags)
+
+		// Try to add duplicate tag - should not add
+		patch = repository.Patch().AddToSet(repository.Field("tags"), "tag1")
+		err = repo.Patch(ctx, *obj.GetID(), patch)
+		require.NoError(t, err)
+
+		err = repo.Get(ctx, *obj.GetID(), &result)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"tag1", "tag2"}, result.Tags)
+	})
+
+	t.Run("Patch_PushToEmptyArray", func(t *testing.T) {
+		obj := &TestObject{Name: "test", Tags: []string{}}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+
+		patch := repository.Patch().Push(repository.Field("tags"), "tag1")
+		err = repo.Patch(ctx, *obj.GetID(), patch)
+		require.NoError(t, err)
+
+		var result TestObject
+		err = repo.Get(ctx, *obj.GetID(), &result)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"tag1"}, result.Tags)
+	})
+
+	t.Run("Patch_PullFromEmptyArray", func(t *testing.T) {
+		obj := &TestObject{Name: "test", Tags: []string{}}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+
+		patch := repository.Patch().Pull(repository.Field("tags"), "nonexistent")
+		err = repo.Patch(ctx, *obj.GetID(), patch)
+		require.NoError(t, err)
+
+		var result TestObject
+		err = repo.Get(ctx, *obj.GetID(), &result)
+		require.NoError(t, err)
+		assert.Equal(t, []string{}, result.Tags)
+	})
+
+	t.Run("Patch_PullNonExistentElement", func(t *testing.T) {
+		obj := &TestObject{Name: "test", Tags: []string{"tag1", "tag2"}}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+
+		patch := repository.Patch().Pull(repository.Field("tags"), "nonexistent")
+		err = repo.Patch(ctx, *obj.GetID(), patch)
+		require.NoError(t, err)
+
+		var result TestObject
+		err = repo.Get(ctx, *obj.GetID(), &result)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"tag1", "tag2"}, result.Tags)
+	})
+
+	t.Run("Patch_ChainedArrayOperations", func(t *testing.T) {
+		obj := &TestObject{Name: "test", Tags: []string{"tag1"}}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+
+		// Note: MongoDB doesn't allow multiple operations on the same array field in a single update
+		// This test demonstrates that chained array operations on the same field will fail
+		patch := repository.Patch().
+			Push(repository.Field("tags"), "tag2").
+			AddToSet(repository.Field("tags"), "tag3").
+			Pull(repository.Field("tags"), "tag1")
+		err = repo.Patch(ctx, *obj.GetID(), patch)
+		require.Error(t, err) // This should fail due to MongoDB's limitation
+		assert.Contains(t, err.Error(), "conflict")
+	})
+
+	t.Run("PatchMany_ArrayOperations", func(t *testing.T) {
+		objs := []*TestObject{
+			{Name: "obj1", Tags: []string{"tag1"}},
+			{Name: "obj2", Tags: []string{"tag2"}},
+			{Name: "obj3", Tags: []string{"tag3"}},
+		}
+		for _, o := range objs {
+			err := repo.Insert(ctx, o, nil)
+			require.NoError(t, err)
+		}
+
+		query := repository.Query().Comparison(repository.Field("name"), builder.In, []string{"obj1", "obj2"})
+		patch := repository.Patch().Push(repository.Field("tags"), "common")
+		modified, err := repo.PatchMany(ctx, query, patch)
+		require.NoError(t, err)
+		assert.Equal(t, 2, modified)
+
+		// Verify the changes
+		for _, name := range []string{"obj1", "obj2"} {
+			var result TestObject
+			err = repo.FindOneByFilter(ctx, repository.Query().Comparison(repository.Field("name"), builder.Eq, name), &result)
+			require.NoError(t, err)
+			assert.Contains(t, result.Tags, "common")
+		}
+	})
+}

backend/shared/database/internal/repository/repository_test.go

@@ -0,0 +1,188 @@
+//go:build integration
+// +build integration
+
+package repositoryimp_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/database/internal/builder"
+	"git.sendico.io/tech/sxchnge/shared/database/internal/repository"
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/mongodb"
+	"github.com/testcontainers/testcontainers-go/wait"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+type TestObject struct {
+	storable.Base `bson:",inline" json:",inline"`
+	Name          string   `bson:"name"`
+	Tags          []string `bson:"tags"`
+}
+
+func (t *TestObject) Collection() string {
+	return "testObject"
+}
+
+type AnotherObject struct {
+	storable.Base `bson:",inline" json:",inline"`
+	Description   string `bson:"description"`
+}
+
+func (a *AnotherObject) Collection() string {
+	return "anotherObject"
+}
+
+func terminate(ctx context.Context, t *testing.T, container *mongodb.MongoDBContainer) {
+	err := container.Terminate(ctx)
+	require.NoError(t, err, "failed to terminate MongoDB container")
+}
+
+func disconnect(ctx context.Context, t *testing.T, client *mongo.Client) {
+	err := client.Disconnect(ctx)
+	require.NoError(t, err, "failed to disconnect from MongoDB")
+}
+
+func TestMongoRepository_Get(t *testing.T) {
+	// Use a context with timeout, so if container spinning or DB ops hang,
+	// the test won't run indefinitely.
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("Get_Success", func(t *testing.T) {
+		testObj := &TestObject{Name: "testName"}
+		err := repository.Insert(ctx, testObj, nil)
+		require.NoError(t, err)
+
+		result := &TestObject{}
+		err = repository.Get(ctx, testObj.ID, result)
+		require.NoError(t, err)
+		assert.Equal(t, testObj.Name, result.Name)
+		assert.Equal(t, testObj.ID, result.ID)
+	})
+
+	t.Run("Get_NotFound", func(t *testing.T) {
+		nonExistentID := bson.NewObjectID()
+		result := &TestObject{}
+
+		err := repository.Get(ctx, nonExistentID, result)
+		assert.Error(t, err)
+		assert.True(t, errors.Is(err, merrors.ErrNoData))
+	})
+
+	t.Run("Get_InvalidID", func(t *testing.T) {
+		invalidID := bson.ObjectID{} // zero value
+		result := &TestObject{}
+
+		err := repository.Get(ctx, invalidID, result)
+		assert.Error(t, err)
+		assert.True(t, errors.Is(err, merrors.ErrInvalidArg))
+	})
+
+	t.Run("Get_DifferentTypes", func(t *testing.T) {
+		anotherObj := &AnotherObject{Description: "testDescription"}
+		err := repository.Insert(ctx, anotherObj, nil)
+		require.NoError(t, err)
+
+		result := &AnotherObject{}
+		err = repository.Get(ctx, anotherObj.ID, result)
+		require.NoError(t, err)
+		assert.Equal(t, anotherObj.Description, result.Description)
+		assert.Equal(t, anotherObj.ID, result.ID)
+	})
+}
+
+func TestMongoRepository_ListIDs(t *testing.T) {
+	// Use a context with timeout, so if container spinning or DB ops hang,
+	// the test won't run indefinitely.
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repository := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("ListIDs_Success", func(t *testing.T) {
+		// Insert test data
+		testObjs := []*TestObject{
+			{Name: "testName1"},
+			{Name: "testName2"},
+			{Name: "testName3"},
+		}
+		for _, obj := range testObjs {
+			err := repository.Insert(ctx, obj, nil)
+			require.NoError(t, err)
+		}
+
+		// Define a query to match all objects
+		query := builderimp.NewQueryImp()
+
+		// Call ListIDs
+		ids, err := repository.ListIDs(ctx, query)
+		require.NoError(t, err)
+
+		// Assert the IDs are correct
+		require.Len(t, ids, len(testObjs))
+		for _, obj := range testObjs {
+			assert.Contains(t, ids, obj.ID)
+		}
+	})
+
+	t.Run("ListIDs_EmptyResult", func(t *testing.T) {
+		// Define a query that matches no objects
+		query := builderimp.NewQueryImp().Comparison(builderimp.NewFieldImp("name"), builder.Eq, "nonExistentName")
+
+		// Call ListIDs
+		ids, err := repository.ListIDs(ctx, query)
+		require.NoError(t, err)
+
+		// Assert no IDs are returned
+		assert.Empty(t, ids)
+	})
+}

backend/shared/database/internal/repository/repository_upsert_test.go

@@ -0,0 +1,99 @@
+//go:build integration
+// +build integration
+
+package repositoryimp_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/database/internal/repository"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/mongodb"
+	"github.com/testcontainers/testcontainers-go/wait"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func TestMongoRepository_Upsert(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	mongoContainer, err := mongodb.Run(ctx,
+		"mongo:latest",
+		mongodb.WithUsername("root"),
+		mongodb.WithPassword("password"),
+		testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
+	)
+	require.NoError(t, err, "failed to start MongoDB container")
+	defer terminate(ctx, t, mongoContainer)
+
+	mongoURI, err := mongoContainer.ConnectionString(ctx)
+	require.NoError(t, err, "failed to get MongoDB connection string")
+
+	clientOptions := options.Client().ApplyURI(mongoURI)
+	client, err := mongo.Connect(clientOptions)
+	require.NoError(t, err, "failed to connect to MongoDB")
+	defer disconnect(ctx, t, client)
+
+	db := client.Database("testdb")
+	repo := repositoryimp.NewMongoRepository(db, "testcollection")
+
+	t.Run("Upsert_InsertsWhenIDIsZero", func(t *testing.T) {
+		obj := &TestObject{Name: "inserted-via-upsert"}
+		require.True(t, obj.GetID().IsZero())
+
+		err := repo.Upsert(ctx, obj)
+		require.NoError(t, err)
+		assert.False(t, obj.GetID().IsZero())
+		assert.NotZero(t, obj.CreatedAt)
+		assert.NotZero(t, obj.UpdatedAt)
+
+		var stored TestObject
+		err = repo.Get(ctx, *obj.GetID(), &stored)
+		require.NoError(t, err)
+		assert.Equal(t, "inserted-via-upsert", stored.Name)
+	})
+
+	t.Run("Upsert_UpdatesExistingDocument", func(t *testing.T) {
+		obj := &TestObject{Name: "before-upsert"}
+		err := repo.Insert(ctx, obj, nil)
+		require.NoError(t, err)
+
+		createdAt := obj.CreatedAt
+		updatedAt := obj.UpdatedAt
+		time.Sleep(10 * time.Millisecond)
+
+		obj.Name = "after-upsert"
+		err = repo.Upsert(ctx, obj)
+		require.NoError(t, err)
+
+		assert.Equal(t, createdAt, obj.CreatedAt)
+		assert.True(t, obj.UpdatedAt.After(updatedAt))
+
+		var stored TestObject
+		err = repo.Get(ctx, *obj.GetID(), &stored)
+		require.NoError(t, err)
+		assert.Equal(t, "after-upsert", stored.Name)
+		assert.WithinDuration(t, createdAt, stored.CreatedAt, time.Second)
+		assert.True(t, stored.UpdatedAt.After(updatedAt))
+	})
+
+	t.Run("Upsert_InsertsWhenIDDoesNotExist", func(t *testing.T) {
+		obj := &TestObject{Name: "upsert-with-preassigned-id"}
+		obj.SetID(bson.NewObjectID())
+
+		err := repo.Upsert(ctx, obj)
+		require.NoError(t, err)
+
+		var stored TestObject
+		err = repo.Get(ctx, *obj.GetID(), &stored)
+		require.NoError(t, err)
+		assert.Equal(t, "upsert-with-preassigned-id", stored.Name)
+		assert.Equal(t, *obj.GetID(), stored.ID)
+	})
+}

backend/shared/database/internal/transaction/factory.go

@@ -0,0 +1,18 @@
+package transactionimp
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/transaction"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+type MongoTransactionFactory struct {
+	client *mongo.Client
+}
+
+func (mtf *MongoTransactionFactory) CreateTransaction() transaction.Transaction {
+	return Create(mtf.client)
+}
+
+func CreateFactory(client *mongo.Client) transaction.Factory {
+	return &MongoTransactionFactory{client: client}
+}

backend/shared/database/internal/transaction/transaction.go

@@ -0,0 +1,34 @@
+package transactionimp
+
+import (
+	"context"
+
+	"git.sendico.io/tech/sxchnge/shared/database/transaction"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+type MongoTransaction struct {
+	client *mongo.Client
+}
+
+func (mt *MongoTransaction) Execute(ctx context.Context, cb transaction.Callback) (any, error) {
+	// Reuse an outer customer workflow transaction when a token store joins it.
+	if transaction.ActiveMongoTransaction(ctx) {
+		return cb(ctx)
+	}
+	session, err := mt.client.StartSession()
+	if err != nil {
+		return nil, err
+	}
+	defer session.EndSession(ctx)
+
+	callback := func(c context.Context) (any, error) {
+		return cb(c)
+	}
+
+	return session.WithTransaction(ctx, callback)
+}
+
+func Create(client *mongo.Client) *MongoTransaction {
+	return &MongoTransaction{client: client}
+}

backend/shared/database/query/archive.go

@@ -0,0 +1,37 @@
+package mutil
+
+import (
+	"context"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository"
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"git.sendico.io/tech/sxchnge/shared/logging/fields"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.uber.org/zap"
+)
+
+func SetArchived[T storable.Storable](ctx context.Context, logger mlogger.Logger, newArchived bool, objectRef bson.ObjectID, repo repository.Repository) error {
+	objs, err := GetObjects[T](ctx, logger, repository.IDFilter(objectRef), nil, repo)
+	if err != nil {
+		logger.Warn("Failed to fetch object", zap.Error(err), mzap.ObjRef("object_ref", objectRef))
+		return err
+	}
+
+	if len(objs) == 0 {
+		logger.Warn("No objects found to archive", mzap.ObjRef("object_ref", objectRef))
+		return nil
+	}
+
+	// Archive the first object found
+	obj := objs[0]
+	if archivable, ok := any(obj).(interface{ SetArchived(bool) }); ok {
+		archivable.SetArchived(newArchived)
+		if err := repo.Update(ctx, obj); err != nil {
+			logger.Warn("Failed to update object archived status", zap.Error(err), mzap.ObjRef("object_ref", objectRef))
+			return err
+		}
+	}
+
+	return nil
+}

backend/shared/database/query/array.go

@@ -0,0 +1,26 @@
+package mutil
+
+import (
+	"context"
+	sharedmodel "git.sendico.io/tech/sxchnge/shared/model"
+
+	"git.sendico.io/tech/sxchnge/shared/database/repository"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.uber.org/zap"
+)
+
+func GetObjects[T any](ctx context.Context, logger mlogger.Logger, filter builder.Query, cursor *sharedmodel.ViewCursor, repo repository.Repository) ([]T, error) {
+	entities := make([]T, 0)
+	decoder := func(cur *mongo.Cursor) error {
+		var next T
+		if e := cur.Decode(&next); e != nil {
+			logger.Warn("Failed to decode entity", zap.Error(e))
+			return e
+		}
+		entities = append(entities, next)
+		return nil
+	}
+	return entities, repo.FindManyByFilter(ctx, repository.ApplyCursor(filter, cursor), decoder)
+}

backend/shared/database/query/db.go

@@ -0,0 +1,20 @@
+package mutil
+
+import (
+	"context"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository"
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.uber.org/zap"
+)
+
+func GetObjectByID(ctx context.Context, logger mlogger.Logger, id string, val storable.Storable, repo repository.Repository) error {
+	p, err := bson.ObjectIDFromHex(id)
+	if err != nil {
+		logger.Warn("Failed to decode object reference", zap.String("reference", id), zap.String("collection", val.Collection()))
+		return err
+	}
+	return repo.Get(ctx, p, val)
+}

backend/shared/database/record/id.go

@@ -0,0 +1,37 @@
+package storable
+
+import (
+	"time"
+
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+const (
+	IDField         = "_id"
+	IsArchivedField = "isArchived"
+	UpdatedAtField  = "updatedAt"
+)
+
+type Base struct {
+	ID        bson.ObjectID `bson:"_id" json:"id"`
+	CreatedAt time.Time     `bson:"createdAt" json:"createdAt"` // Timestamp for when the comment was created
+	UpdatedAt time.Time     `bson:"updatedAt" json:"updatedAt"` // Timestamp for when the comment was last updated (optional)
+}
+
+func (b *Base) GetID() *bson.ObjectID {
+	return &b.ID
+}
+
+func (b *Base) SetID(objID bson.ObjectID) {
+	b.ID = objID
+	b.CreatedAt = time.Now()
+	b.UpdatedAt = time.Now()
+}
+
+func (b *Base) Update() {
+	b.UpdatedAt = time.Now()
+}
+
+func (b *Base) Collection() string {
+	return "base"
+}

backend/shared/database/record/ref.go

@@ -0,0 +1,11 @@
+package storable
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+const (
+	RefField = "ref"
+)
+
+type Ref struct {
+	Ref bson.ObjectID `bson:"ref" json:"ref"`
+}

backend/shared/database/record/storable.go

@@ -0,0 +1,10 @@
+package storable
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+type Storable interface {
+	GetID() *bson.ObjectID
+	SetID(objID bson.ObjectID)
+	Update()
+	Collection() string
+}

backend/shared/database/repository/builder/accumulator.go

@@ -0,0 +1,11 @@
+package builder
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+type Accumulator interface {
+	Build() bson.D
+}
+
+type GroupAccumulator interface {
+	Build() bson.D
+}

backend/shared/database/repository/builder/alias.go

@@ -0,0 +1,8 @@
+package builder
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+type Alias interface {
+	Field() Field
+	Build() bson.D
+}

backend/shared/database/repository/builder/array.go

@@ -0,0 +1,7 @@
+package builder
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+type Array interface {
+	Build() bson.A
+}

backend/shared/database/repository/builder/expression.go

@@ -0,0 +1,5 @@
+package builder
+
+type Expression interface {
+	Build() any
+}

backend/shared/database/repository/builder/field.go

@@ -0,0 +1,7 @@
+package builder
+
+type Field interface {
+	Dot(field string) Field
+	CopyWith(field string) Field
+	Build() string
+}

backend/shared/database/repository/builder/keyword.go

@@ -0,0 +1,16 @@
+package builder
+
+type MongoKeyword string
+
+const (
+	MKAs                         MongoKeyword = "as"
+	MKForeignField               MongoKeyword = "foreignField"
+	MKFrom                       MongoKeyword = "from"
+	MKIncludeArrayIndex          MongoKeyword = "includeArrayIndex"
+	MKLet                        MongoKeyword = "let"
+	MKLocalField                 MongoKeyword = "localField"
+	MKPath                       MongoKeyword = "path"
+	MKPipeline                   MongoKeyword = "pipeline"
+	MKPreserveNullAndEmptyArrays MongoKeyword = "preserveNullAndEmptyArrays"
+	MKNewRoot                    MongoKeyword = "newRoot"
+)

backend/shared/database/repository/builder/operators.go

@@ -0,0 +1,57 @@
+package builder
+
+type MongoOperation string
+
+const (
+	// Comparison operators
+	Gt     MongoOperation = "$gt"
+	Lt     MongoOperation = "$lt"
+	Gte    MongoOperation = "$gte"
+	Lte    MongoOperation = "$lte"
+	Eq     MongoOperation = "$eq"
+	Ne     MongoOperation = "$ne"
+	In     MongoOperation = "$in"
+	NotIn  MongoOperation = "$nin"
+	Exists MongoOperation = "$exists"
+
+	// Logical operators
+	And MongoOperation = "$and"
+	Or  MongoOperation = "$or"
+	Not MongoOperation = "$not"
+
+	AddToSet    MongoOperation = "$addToSet"
+	Avg         MongoOperation = "$avg"
+	Pull        MongoOperation = "$pull"
+	Count       MongoOperation = "$count"
+	Cond        MongoOperation = "$cond"
+	Each        MongoOperation = "$each"
+	Expr        MongoOperation = "$expr"
+	First       MongoOperation = "$first"
+	Group       MongoOperation = "$group"
+	IfNull      MongoOperation = "$ifNull"
+	Limit       MongoOperation = "$limit"
+	Literal     MongoOperation = "$literal"
+	Lookup      MongoOperation = "$lookup"
+	Match       MongoOperation = "$match"
+	Max         MongoOperation = "$max"
+	Min         MongoOperation = "$min"
+	Push        MongoOperation = "$push"
+	Project     MongoOperation = "$project"
+	Set         MongoOperation = "$set"
+	Inc         MongoOperation = "$inc"
+	Unset       MongoOperation = "$unset"
+	Rename      MongoOperation = "$rename"
+	ReplaceRoot MongoOperation = "$replaceRoot"
+	SetUnion    MongoOperation = "$setUnion"
+	Size        MongoOperation = "$size"
+	Sort        MongoOperation = "$sort"
+	Skip        MongoOperation = "$skip"
+	Sum         MongoOperation = "$sum"
+	Type        MongoOperation = "$type"
+	Unwind      MongoOperation = "$unwind"
+
+	Add      MongoOperation = "$add"
+	Subtract MongoOperation = "$subtract"
+	Multiply MongoOperation = "$multiply"
+	Divide   MongoOperation = "$divide"
+)

backend/shared/database/repository/builder/patch.go

@@ -0,0 +1,16 @@
+package builder
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+// Patch defines operations for constructing partial update documents.
+// Each builder method returns the same Patch instance to allow chaining.
+type Patch interface {
+	Set(field Field, value any) Patch
+	Inc(field Field, value any) Patch
+	Unset(field Field) Patch
+	Rename(field Field, newName string) Patch
+	Push(field Field, value any) Patch
+	Pull(field Field, value any) Patch
+	AddToSet(field Field, value any) Patch
+	Build() bson.D
+}

backend/shared/database/repository/builder/pipeline.go

@@ -0,0 +1,24 @@
+package builder
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/service"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+type Pipeline interface {
+	Match(filter Query) Pipeline
+	Lookup(from mservice.Type, localField, foreignField, as Field) Pipeline
+	LookupWithPipeline(
+		from mservice.Type,
+		pipeline Pipeline, // your nested pipeline
+		as Field,
+		let *map[string]Field, //  optional e.g. {"projRef": Field("$_id")}
+	) Pipeline
+	// unwind with functional options
+	Unwind(path Field, opts ...UnwindOption) Pipeline
+	Count(field Field) Pipeline
+	Group(groupBy Alias, accumulators ...GroupAccumulator) Pipeline
+	Project(projections ...Projection) Pipeline
+	ReplaceRoot(newRoot Expression) Pipeline
+	Build() mongo.Pipeline
+}

backend/shared/database/repository/builder/projection.go

@@ -0,0 +1,7 @@
+package builder
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+type Projection interface {
+	Build() bson.D
+}

backend/shared/database/repository/builder/query.go

@@ -0,0 +1,24 @@
+package builder
+
+import (
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+type Query interface {
+	Filter(field Field, value any) Query
+	And(filters ...Query) Query
+	Or(filters ...Query) Query
+	Expression(value Expression) Query
+	Comparison(field Field, operator MongoOperation, value any) Query
+	RegEx(field Field, pattern, options string) Query
+	In(field Field, values ...any) Query
+	NotIn(field Field, values ...any) Query
+	Sort(field Field, ascending bool) Query
+	Limit(limit *int64) Query
+	Offset(offset *int64) Query
+	Archived(isArchived *bool) Query
+	BuildPipeline() bson.D
+	BuildQuery() bson.D
+	BuildOptions() *options.FindOptionsBuilder
+}

backend/shared/database/repository/builder/unwind.go

@@ -0,0 +1,23 @@
+package builder
+
+// UnwindOption is a functional option for configuring the $unwind stage.
+type UnwindOption func(*UnwindOpts)
+
+type UnwindOpts struct {
+	PreserveNullAndEmptyArrays bool
+	IncludeArrayIndex          string
+}
+
+// WithPreserveNullAndEmptyArrays tells $unwind to keep docs where the array is null/empty.
+func WithPreserveNullAndEmptyArrays() UnwindOption {
+	return func(o *UnwindOpts) {
+		o.PreserveNullAndEmptyArrays = true
+	}
+}
+
+// WithIncludeArrayIndex adds an array‐index field named idxField to each unwound doc.
+func WithIncludeArrayIndex(idxField string) UnwindOption {
+	return func(o *UnwindOpts) {
+		o.IncludeArrayIndex = idxField
+	}
+}

backend/shared/database/repository/builder/value.go

@@ -0,0 +1,5 @@
+package builder
+
+type Value interface {
+	Build() any
+}

backend/shared/database/repository/builders.go

@@ -0,0 +1,253 @@
+package repository
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/internal/builder"
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	sharedmodel "git.sendico.io/tech/sxchnge/shared/model"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+func Query() builder.Query {
+	return builderimp.NewQueryImp()
+}
+
+func Filter(field string, value any) builder.Query {
+	return Query().Filter(Field(field), value)
+}
+
+func Field(baseName string) builder.Field {
+	return builderimp.NewFieldImp(baseName)
+}
+
+func Ref(field builder.Field) builder.Field {
+	return builderimp.NewRefFieldImp(field)
+}
+
+func RootRef() builder.Field {
+	return builderimp.NewRootRef()
+}
+
+func RemoveRef() builder.Field {
+	return builderimp.NewRemoveRef()
+}
+
+func Pipeline(stages ...bson.D) builder.Pipeline {
+	return builderimp.NewPipelineImp(stages...)
+}
+
+func IDField() builder.Field {
+	return Field(storable.IDField)
+}
+
+func NameField() builder.Field {
+	return Field(sharedmodel.NameField)
+}
+
+func DescrtiptionField() builder.Field {
+	return Field(sharedmodel.DescriptionField)
+}
+
+func IsArchivedField() builder.Field {
+	return Field(storable.IsArchivedField)
+}
+
+func IDFilter(ref bson.ObjectID) builder.Query {
+	return Query().Filter(IDField(), ref)
+}
+
+func ArchivedFilter() builder.Query {
+	return IsArchivedFilter(true)
+}
+
+func NotArchivedFilter() builder.Query {
+	return IsArchivedFilter(false)
+}
+
+func IsArchivedFilter(isArchived bool) builder.Query {
+	return Query().Filter(IsArchivedField(), isArchived)
+}
+
+func AccountField() builder.Field {
+	return Field("accountRef")
+}
+
+func AccountFilter(ref bson.ObjectID) builder.Query {
+	return Query().Filter(AccountField(), ref)
+}
+
+func StatusRefField() builder.Field {
+	return Field("statusRef")
+}
+
+func StatusRefFilter(ref bson.ObjectID) builder.Query {
+	return Query().Filter(StatusRefField(), ref)
+}
+
+func PriorityRefField() builder.Field {
+	return Field("priorityRef")
+}
+
+func PriorityRefFilter(ref bson.ObjectID) builder.Query {
+	return Query().Filter(PriorityRefField(), ref)
+}
+
+func IndexField() builder.Field {
+	return Field("index")
+}
+
+func IndexFilter(index int) builder.Query {
+	return Query().Filter(IndexField(), index)
+}
+
+func IndexOpFilter(index int, operation builder.MongoOperation) builder.Query {
+	return Query().Comparison(IndexField(), operation, index)
+}
+
+func Patch() builder.Patch {
+	return builderimp.NewPatchImp()
+}
+
+func Accumulator(operator builder.MongoOperation, value any) builder.Accumulator {
+	return builderimp.NewAccumulator(operator, value)
+}
+
+func GroupAccumulator(field builder.Field, acc builder.Accumulator) builder.GroupAccumulator {
+	return builderimp.NewGroupAccumulator(field, acc)
+}
+
+func Literal(value any) builder.Expression {
+	return builderimp.NewLiteralExpression(value)
+}
+
+func Projection(alias builder.Alias) builder.Projection {
+	return builderimp.NewAliasProjection(alias)
+}
+
+func IncludeField(field builder.Field) builder.Projection {
+	return builderimp.IncludeField(field)
+}
+
+func ExcludeField(field builder.Field) builder.Projection {
+	return builderimp.ExcludeField(field)
+}
+
+func ProjectionExpr(field builder.Field, expr builder.Expression) builder.Projection {
+	return builderimp.NewProjectionExpr(field, expr)
+}
+
+func NullAlias(lhs builder.Field) builder.Alias {
+	return builderimp.NewNullAlias(lhs)
+}
+
+func SimpleAlias(lhs, rhs builder.Field) builder.Alias {
+	return builderimp.NewSimpleAlias(lhs, rhs)
+}
+
+func ComplexAlias(lhs builder.Field, rhs []builder.Alias) builder.Alias {
+	return builderimp.NewComplexAlias(lhs, rhs)
+}
+
+func Aliases(aliases ...builder.Alias) builder.Alias {
+	return builderimp.NewAliases(aliases...)
+}
+
+func AddToSet(value builder.Expression) builder.Expression {
+	return builderimp.AddToSet(value)
+}
+
+func Size(value builder.Expression) builder.Expression {
+	return builderimp.Size(value)
+}
+
+func InRef(value builder.Field) builder.Expression {
+	return builderimp.InRef(value)
+}
+
+func In(values ...any) builder.Expression {
+	return builderimp.In(values)
+}
+
+func Cond(condition builder.Expression, ifTrue, ifFalse any) builder.Expression {
+	return builderimp.NewCond(condition, ifTrue, ifFalse)
+}
+
+func And(exprs ...builder.Expression) builder.Expression {
+	return builderimp.NewAnd(exprs...)
+}
+
+func Or(exprs ...builder.Expression) builder.Expression {
+	return builderimp.NewOr(exprs...)
+}
+
+func Type(expr builder.Expression) builder.Expression {
+	return builderimp.NewType(expr)
+}
+
+func Not(expression builder.Expression) builder.Expression {
+	return builderimp.NewNot(expression)
+}
+
+func Sum(expression builder.Expression) builder.Expression {
+	return builderimp.NewSum(expression)
+}
+
+func Assign(field builder.Field, expression builder.Expression) builder.Projection {
+	return builderimp.NewAssignment(field, expression)
+}
+
+func SetUnion(exprs ...builder.Expression) builder.Expression {
+	return builderimp.NewSetUnion(exprs...)
+}
+
+func Eq(left, right builder.Expression) builder.Expression {
+	return builderimp.Eq(left, right)
+}
+
+func Gt(left, right builder.Expression) builder.Expression {
+	return builderimp.Gt(left, right)
+}
+
+func Lt(left, right builder.Expression) builder.Expression {
+	return builderimp.NewLt(left, right)
+}
+
+func Array(expressions ...builder.Expression) builder.Array {
+	return builderimp.NewArray(expressions...)
+}
+
+func IfNull(cond, replacement builder.Expression) builder.Expression {
+	return builderimp.NewIfNull(cond, replacement)
+}
+
+func Each(exprs ...builder.Expression) builder.Expression {
+	return builderimp.NewEach(exprs...)
+}
+
+func Push(expression builder.Expression) builder.Expression {
+	return builderimp.NewPush(expression)
+}
+
+func Min(expression builder.Expression) builder.Expression {
+	return builderimp.NewMin(expression)
+}
+
+func Ne(left, right builder.Expression) builder.Expression {
+	return builderimp.Ne(left, right)
+}
+
+func Compute(field builder.Field, expression builder.Expression) builder.Expression {
+	return builderimp.NewCompute(field, expression)
+}
+
+func First(expr builder.Expression) builder.Expression {
+	return builderimp.First(expr)
+}
+
+func Value(value any) builder.Value {
+	return builderimp.NewValue(value)
+}
+
+func Exists(field builder.Field, exists bool) builder.Query {
+	return Query().Comparison(field, builder.Exists, exists)
+}

backend/shared/database/repository/cursor.go

@@ -0,0 +1,19 @@
+package repository
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	sharedmodel "git.sendico.io/tech/sxchnge/shared/model"
+)
+
+// ApplyCursor adds pagination and archival filters to the provided query.
+func ApplyCursor(query builder.Query, cursor *sharedmodel.ViewCursor) builder.Query {
+	if cursor == nil {
+		return query
+	}
+
+	query = query.Limit(cursor.Limit)
+	query = query.Offset(cursor.Offset)
+	query = query.Archived(cursor.IsArchived)
+
+	return query
+}

backend/shared/database/repository/decoder/decoder.go

@@ -0,0 +1,5 @@
+package repository
+
+import "go.mongodb.org/mongo-driver/v2/mongo"
+
+type DecodingFunc = func(r *mongo.Cursor) error

backend/shared/database/repository/index/index.go

@@ -0,0 +1,25 @@
+package repository
+
+import "git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+
+type Sort int8
+
+const (
+	Asc  Sort = 1
+	Desc Sort = -1
+)
+
+type Key struct {
+	Field string
+	Sort  Sort      // 1 or -1. 0 means “use Type”.
+	Type  IndexType // optional: "text", "2dsphere", ...
+}
+
+type Definition struct {
+	Keys          []Key         // mandatory, at least one element
+	Unique        bool          // unique constraint?
+	Sparse        bool          // sparse?
+	TTL           *int32        // seconds; nil means “no TTL”
+	Name          string        // optional explicit name
+	PartialFilter builder.Query // optional: partialFilterExpression for conditional indexes
+}

backend/shared/database/repository/index/types.go

@@ -0,0 +1,36 @@
+package repository
+
+// IndexType represents a supported MongoDB index type.
+type IndexType string
+
+const (
+	// IndexTypeNotSet is a default index type
+	IndexTypeNotSet IndexType = ""
+
+	// IndexTypeSingleField is a single-field index.
+	IndexTypeSingleField IndexType = "single"
+
+	// IndexTypeCompound is a compound index on multiple fields.
+	IndexTypeCompound IndexType = "compound"
+
+	// IndexTypeMultikey is an index on array fields (created automatically when needed).
+	IndexTypeMultikey IndexType = "multikey"
+
+	// IndexTypeText is a text index for full-text search.
+	IndexTypeText IndexType = "text"
+
+	// IndexTypeGeo2D is a legacy 2D geospatial index for planar geometry.
+	IndexTypeGeo2D IndexType = "2d"
+
+	// IndexTypeGeo2DSphere is a 2dsphere geospatial index for GeoJSON data.
+	IndexTypeGeo2DSphere IndexType = "2dsphere"
+
+	// IndexTypeHashed is a hashed index for sharding and efficient equality queries.
+	IndexTypeHashed IndexType = "hashed"
+
+	// IndexTypeWildcard is a wildcard index to index all fields or subpaths.
+	IndexTypeWildcard IndexType = "wildcard"
+
+	// IndexTypeClustered is a clustered index that orders the collection on the index key.
+	IndexTypeClustered IndexType = "clustered"
+)

backend/shared/database/repository/repository.go

@@ -0,0 +1,58 @@
+package repository
+
+import (
+	"context"
+
+	"git.sendico.io/tech/sxchnge/shared/database/internal/repository"
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	rd "git.sendico.io/tech/sxchnge/shared/database/repository/decoder"
+	ri "git.sendico.io/tech/sxchnge/shared/database/repository/index"
+	"git.sendico.io/tech/sxchnge/shared/database/transaction"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+type (
+	// FilterQuery selects documents to operate on.
+	FilterQuery = builder.Query
+	// PatchDoc defines field/value modifications for partial updates.
+	PatchDoc = builder.Patch
+)
+
+type Repository interface {
+	Aggregate(ctx context.Context, builder builder.Pipeline, decoder rd.DecodingFunc) error
+	Insert(ctx context.Context, obj storable.Storable, getFilter builder.Query) error
+	InsertMany(ctx context.Context, objects []storable.Storable) error
+	Get(ctx context.Context, id bson.ObjectID, result storable.Storable) error
+	FindOneByFilter(ctx context.Context, builder builder.Query, result storable.Storable) error
+	FindFirstByFilter(ctx context.Context, builder builder.Query, result storable.Storable) error
+	FindManyByFilter(ctx context.Context, builder builder.Query, decoder rd.DecodingFunc) error
+	// FindAllByFilter decodes all matching documents into result, which must be a pointer to a slice.
+	FindAllByFilter(ctx context.Context, builder builder.Query, result any) error
+	CountByFilter(ctx context.Context, builder builder.Query) (int64, error)
+	Update(ctx context.Context, obj storable.Storable) error
+	// ReplaceOneByFilter replaces one matching document with obj and reports whether a document matched the filter.
+	// The repository must persist obj as provided and must not mutate its timestamps or identity before replacement.
+	ReplaceOneByFilter(ctx context.Context, filter builder.Query, obj storable.Storable) (bool, error)
+	// Upsert replaces the document identified by obj ID, inserting it when no document exists.
+	Upsert(ctx context.Context, obj storable.Storable) error
+	// Patch applies partial updates defined by patch to the document identified by id.
+	Patch(ctx context.Context, id bson.ObjectID, patch PatchDoc) error
+	// PatchOneByFilter atomically patches one document matching filter and decodes the updated document into result.
+	PatchOneByFilter(ctx context.Context, filter FilterQuery, patch PatchDoc, result storable.Storable) (bool, error)
+	// PatchMany applies partial updates defined by patch to all documents matching filter and returns the number of updated documents.
+	PatchMany(ctx context.Context, filter FilterQuery, patch PatchDoc) (int, error)
+	Delete(ctx context.Context, id bson.ObjectID) error
+	DeleteMany(ctx context.Context, query builder.Query) error
+	CreateIndex(def *ri.Definition) error
+	DropIndex(ctx context.Context, name string) error
+	ListIndexDefinitions(ctx context.Context) ([]*ri.Definition, error)
+	ListIDs(ctx context.Context, query builder.Query) ([]bson.ObjectID, error)
+	WithTransaction(ctx context.Context, cb transaction.Callback) (any, error)
+	Collection() string
+}
+
+func CreateMongoRepository(db *mongo.Database, collection string) Repository {
+	return repositoryimp.NewMongoRepository(db, collection)
+}

backend/shared/database/template/interface.go

@@ -0,0 +1,21 @@
+package template
+
+import (
+	"context"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type DB[T storable.Storable] interface {
+	Create(ctx context.Context, object T) error
+	InsertMany(ctx context.Context, objects []T) error
+	Get(ctx context.Context, objectRef bson.ObjectID, result T) error
+	Update(ctx context.Context, object T) error
+	Patch(ctx context.Context, objectRef bson.ObjectID, patch builder.Patch) error
+	Delete(ctx context.Context, objectRef bson.ObjectID) error
+	DeleteMany(ctx context.Context, query builder.Query) error
+	DeleteCascade(ctx context.Context, objectRef bson.ObjectID) error
+	FindOne(ctx context.Context, query builder.Query, result T) error
+}

backend/shared/database/template/template.go

@@ -0,0 +1,99 @@
+package template
+
+import (
+	"context"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository"
+	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"git.sendico.io/tech/sxchnge/shared/logging/fields"
+	"git.sendico.io/tech/sxchnge/shared/service"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+type CascadeDeleterT = func(ctx context.Context, objectRef bson.ObjectID) error
+
+type DBImp[T storable.Storable] struct {
+	Logger     mlogger.Logger
+	Repository repository.Repository
+	cdeleter   CascadeDeleterT
+}
+
+func (db *DBImp[T]) Create(ctx context.Context, object T) error {
+	return db.Repository.Insert(ctx, object, nil)
+}
+
+func (db *DBImp[T]) InsertMany(ctx context.Context, objects []T) error {
+	if len(objects) == 0 {
+		return nil
+	}
+
+	storables := make([]storable.Storable, len(objects))
+	for i, obj := range objects {
+		storables[i] = obj
+	}
+
+	return db.Repository.InsertMany(ctx, storables)
+}
+
+func (db *DBImp[T]) Get(ctx context.Context, objectRef bson.ObjectID, result T) error {
+	return db.Repository.Get(ctx, objectRef, result)
+}
+
+func (db *DBImp[T]) Update(ctx context.Context, object T) error {
+	return db.Repository.Update(ctx, object)
+}
+
+func (db *DBImp[T]) Patch(ctx context.Context, objectRef bson.ObjectID, patch builder.Patch) error {
+	return db.Repository.Patch(ctx, objectRef, patch)
+}
+
+func (db *DBImp[T]) PatchMany(ctx context.Context, query builder.Query, patch builder.Patch) (int, error) {
+	return db.Repository.PatchMany(ctx, query, patch)
+}
+
+func (db *DBImp[T]) Delete(ctx context.Context, objectRef bson.ObjectID) error {
+	return db.Repository.Delete(ctx, objectRef)
+}
+
+func (db *DBImp[T]) DeleteMany(ctx context.Context, query builder.Query) error {
+	return db.Repository.DeleteMany(ctx, query)
+}
+
+func (db *DBImp[T]) FindOne(ctx context.Context, query builder.Query, result T) error {
+	return db.Repository.FindOneByFilter(ctx, query, result)
+}
+
+func (db *DBImp[T]) ListIDs(ctx context.Context, query builder.Query) ([]bson.ObjectID, error) {
+	return db.Repository.ListIDs(ctx, query)
+}
+
+func (db *DBImp[T]) SetDeleter(deleter CascadeDeleterT) {
+	db.Logger.Debug("Custom cascade deletion method installed")
+	db.cdeleter = deleter
+}
+
+func (db *DBImp[T]) deleteCascadeStub(_ context.Context, objectRef bson.ObjectID) error {
+	db.Logger.Warn("Unimplemented cascade delete call", mzap.ObjRef("object_ref", objectRef))
+	return merrors.NotImplemented("custom implementation required")
+}
+
+func (db *DBImp[T]) DeleteCascade(ctx context.Context, objectRef bson.ObjectID) error {
+	return db.cdeleter(ctx, objectRef)
+}
+
+func Create[T storable.Storable](
+	logger mlogger.Logger,
+	collection mservice.Type,
+	db *mongo.Database,
+) *DBImp[T] {
+	res := &DBImp[T]{
+		Logger:     logger.Named(collection),
+		Repository: repository.CreateMongoRepository(db, collection),
+	}
+	res.cdeleter = res.deleteCascadeStub
+	return res
+}

backend/shared/database/transaction/context.go

@@ -0,0 +1,12 @@
+package transaction
+
+import (
+	"context"
+
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+func ActiveMongoTransaction(ctx context.Context) bool {
+	session := mongo.SessionFromContext(ctx)
+	return session != nil && session.TransactionRunning()
+}

backend/shared/database/transaction/context_test.go

@@ -0,0 +1,21 @@
+package transaction
+
+import (
+	"context"
+	"testing"
+
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+func TestActiveMongoTransactionRejectsContextWithoutSession(t *testing.T) {
+	if ActiveMongoTransaction(context.Background()) {
+		t.Fatal("context without mongo session must not be active")
+	}
+}
+
+func TestActiveMongoTransactionRejectsSessionWithoutTransaction(t *testing.T) {
+	ctx := mongo.NewSessionContext(context.Background(), &mongo.Session{})
+	if ActiveMongoTransaction(ctx) {
+		t.Fatal("session without transaction must not be active")
+	}
+}

backend/shared/database/transaction/factory.go

@@ -0,0 +1,5 @@
+package transaction
+
+type Factory interface {
+	CreateTransaction() Transaction
+}

backend/shared/database/transaction/transaction.go

@@ -0,0 +1,11 @@
+package transaction
+
+import (
+	"context"
+)
+
+type Callback = func(ctx context.Context) (any, error)
+
+type Transaction interface {
+	Execute(ctx context.Context, cb Callback) (any, error)
+}

backend/shared/duration/duration.go

@@ -0,0 +1,7 @@
+package mduration
+
+import "time"
+
+func Param2Duration(param int, d time.Duration) time.Duration {
+	return time.Duration(param) * d
+}

backend/shared/errors/classified.go

@@ -0,0 +1,48 @@
+package merrors
+
+import "strings"
+
+type classifiedError struct {
+	base          error
+	code          error
+	msg           string
+	reason        string
+	publicMessage bool
+	argumentNames []string
+}
+
+func (e classifiedError) Error() string {
+	if e.publicMessage {
+		msg := strings.TrimSpace(e.msg)
+		if msg != "" {
+			return msg
+		}
+		if e.code != nil {
+			return e.code.Error()
+		}
+		if e.base != nil {
+			return e.base.Error()
+		}
+		return ""
+	}
+	return Wrap(e.base, e.msg).Error()
+}
+
+func (e classifiedError) Unwrap() []error {
+	causes := make([]error, 0, 2)
+	if e.base != nil {
+		causes = append(causes, e.base)
+	}
+	if e.code != nil {
+		causes = append(causes, e.code)
+	}
+	return causes
+}
+
+func (e classifiedError) Reason() string {
+	return strings.TrimSpace(e.reason)
+}
+
+func (e classifiedError) InvalidArgumentFields() []string {
+	return append([]string(nil), e.argumentNames...)
+}

backend/shared/errors/errors.go

@@ -0,0 +1,262 @@
+package merrors
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+)
+
+type definedError string
+
+func (e definedError) Error() string {
+	return string(e)
+}
+
+type wrappedError struct {
+	base error
+	msg  string
+}
+
+// opaqueWrappedError preserves error classification and causal inspection
+// without including the cause text in Error. Use it at boundaries where a
+// storage or provider error can contain secrets or sensitive identifiers.
+type opaqueWrappedError struct {
+	base  error
+	cause error
+	msg   string
+}
+
+func (e wrappedError) Error() string {
+	baseText := ""
+	if e.base != nil {
+		baseText = strings.TrimSpace(e.base.Error())
+	}
+	msg := strings.TrimSpace(e.msg)
+
+	switch {
+	case baseText == "":
+		return msg
+	case msg == "":
+		return baseText
+	default:
+		return baseText + ": " + msg
+	}
+}
+
+func (e wrappedError) Unwrap() error {
+	return e.base
+}
+
+func (e opaqueWrappedError) Error() string {
+	return Wrap(e.base, e.msg).Error()
+}
+
+func (e opaqueWrappedError) Unwrap() []error {
+	causes := make([]error, 0, 2)
+	if e.base != nil {
+		causes = append(causes, e.base)
+	}
+	if e.cause != nil {
+		causes = append(causes, e.cause)
+	}
+	return causes
+}
+
+func Define(msg string) error {
+	return definedError(msg)
+}
+
+func Message(msg string) error {
+	return definedError(msg)
+}
+
+func Messagef(format string, args ...any) error {
+	return Message(fmt.Sprintf(format, args...))
+}
+
+func Wrap(err error, msg string) error {
+	return wrappedError{
+		base: err,
+		msg:  msg,
+	}
+}
+
+func Wrapf(err error, format string, args ...any) error {
+	return Wrap(err, fmt.Sprintf(format, args...))
+}
+
+// OpaqueWrap adds safe context while retaining the cause for errors.Is and
+// errors.As. Unlike Wrap, it deliberately excludes the cause text from Error.
+func OpaqueWrap(base, cause error, msg string) error {
+	return opaqueWrappedError{base: base, cause: cause, msg: msg}
+}
+
+var ErrNotImplemented = Define("notImplemented")
+
+func NotImplemented(msg string) error {
+	return Wrap(ErrNotImplemented, msg)
+}
+
+var ErrNoData = Define("noData")
+
+func NoData(msg string) error {
+	return Wrap(ErrNoData, msg)
+}
+
+func NoDataf(format string, args ...any) error {
+	return NoData(fmt.Sprintf(format, args...))
+}
+
+var ErrInternal = Define("internal")
+
+func Internal(msg string) error {
+	return Wrap(ErrInternal, msg)
+}
+
+func Internalf(format string, args ...any) error {
+	return Internal(fmt.Sprintf(format, args...))
+}
+
+var ErrInvalidArg = Define("invalidArgError")
+
+func InvalidArgument(msg string, argumentNames ...string) error {
+	return Wrap(ErrInvalidArg, invalidArgumentMessage(msg, argumentNames...))
+}
+
+func InvalidArgumentf(format string, args ...any) error {
+	return InvalidArgument(fmt.Sprintf(format, args...))
+}
+
+func InvalidArgumentWithNamesf(argumentNames []string, format string, args ...any) error {
+	return InvalidArgument(fmt.Sprintf(format, args...), argumentNames...)
+}
+
+var ErrDataConflict = Define("dataConflict")
+
+func DataConflict(msg string) error {
+	return Wrap(ErrDataConflict, msg)
+}
+
+func DataConflictf(format string, args ...any) error {
+	return DataConflict(fmt.Sprintf(format, args...))
+}
+
+func DataConflictWrap(err error, msg string) error {
+	return wrapError(ErrDataConflict, msg, err)
+}
+
+func DataConflictWrapf(err error, format string, args ...any) error {
+	return DataConflictWrap(err, fmt.Sprintf(format, args...))
+}
+
+var ErrFailedPrecondition = Define("failedPrecondition")
+
+func FailedPrecondition(msg string) error {
+	return Wrap(ErrFailedPrecondition, msg)
+}
+
+func FailedPreconditionf(format string, args ...any) error {
+	return FailedPrecondition(fmt.Sprintf(format, args...))
+}
+
+func FailedPreconditionWrap(err error, msg string) error {
+	return wrapError(ErrFailedPrecondition, msg, err)
+}
+
+func FailedPreconditionWrapf(err error, format string, args ...any) error {
+	return FailedPreconditionWrap(err, fmt.Sprintf(format, args...))
+}
+
+var ErrServiceUnavailable = Define("serviceUnavailable")
+
+func ServiceUnavailable(msg string) error {
+	return Wrap(ErrServiceUnavailable, msg)
+}
+
+func ServiceUnavailablef(format string, args ...any) error {
+	return ServiceUnavailable(fmt.Sprintf(format, args...))
+}
+
+func ServiceUnavailableWrap(err error, msg string) error {
+	return wrapError(ErrServiceUnavailable, msg, err)
+}
+
+func ServiceUnavailableWrapf(err error, format string, args ...any) error {
+	return ServiceUnavailableWrap(err, fmt.Sprintf(format, args...))
+}
+
+type objectRef interface {
+	IsZero() bool
+	Hex() string
+}
+
+var ErrAccessDenied = Define("accessDenied")
+
+func PermissionDenied(msg string) error {
+	return Wrap(ErrAccessDenied, msg)
+}
+
+func AccessDenied(object, action string, ref objectRef) error {
+	if ref != nil && !ref.IsZero() {
+		return Wrap(ErrAccessDenied, fmt.Sprintf("cannot %s object of type '%s' with ID '%s'", action, object, ref.Hex()))
+	}
+	return Wrap(ErrAccessDenied, fmt.Sprintf("cannot %s object of type '%s'", action, object))
+}
+
+var ErrInvalidDataType = Define("invalidDataType")
+
+func InvalidDataType(msg string) error {
+	return Wrap(ErrInvalidDataType, msg)
+}
+
+func InvalidDataTypef(format string, args ...any) error {
+	return InvalidDataType(fmt.Sprintf(format, args...))
+}
+
+var ErrUnauthorized = Define("unathorized")
+
+func Unauthorized(msg string) error {
+	return Wrap(ErrUnauthorized, msg)
+}
+
+func Unauthorizedf(format string, args ...any) error {
+	return Unauthorized(fmt.Sprintf(format, args...))
+}
+
+func InvalidArgumentWrap(err error, msg string, argumentNames ...string) error {
+	return wrapError(ErrInvalidArg, invalidArgumentMessage(msg, argumentNames...), err)
+}
+
+func InvalidArgumentWrapf(err error, format string, args ...any) error {
+	return InvalidArgumentWrap(err, fmt.Sprintf(format, args...))
+}
+
+func InternalWrap(err error, msg string) error {
+	return wrapError(ErrInternal, msg, err)
+}
+
+func InternalWrapf(err error, format string, args ...any) error {
+	return InternalWrap(err, fmt.Sprintf(format, args...))
+}
+
+func InternalWrapAll(msg string, errs ...error) error {
+	return wrapErrors(ErrInternal, msg, errs...)
+}
+
+func wrapError(base error, msg string, err error) error {
+	return wrapErrors(base, msg, err)
+}
+
+func wrapErrors(base error, msg string, errs ...error) error {
+	baseErr := Wrap(base, msg)
+	causes := make([]error, 0, len(errs))
+	for _, err := range errs {
+		if err != nil {
+			causes = append(causes, err)
+		}
+	}
+	if len(causes) == 0 {
+		return baseErr
+	}
+	return errors.Join(baseErr, errors.Join(causes...))
+}

backend/shared/errors/errors_test.go

@@ -0,0 +1,125 @@
+package merrors
+
+import (
+	"errors"
+	"strings"
+	"testing"
+)
+
+type testReasonedError struct {
+	error
+	reason string
+}
+
+func (e testReasonedError) Reason() string {
+	return e.reason
+}
+
+func TestReasonUsesReasonedError(t *testing.T) {
+	err := testReasonedError{
+		error:  InvalidArgument("value is invalid"),
+		reason: "amount_below_minimum",
+	}
+	reason, ok := Reason(err)
+	if !ok {
+		t.Fatalf("expected reason")
+	}
+	if reason != "amount_below_minimum" {
+		t.Fatalf("reason mismatch: got=%q", reason)
+	}
+}
+
+func TestInvalidArgumentSupportsBrokenArgumentName(t *testing.T) {
+	t.Run("without argument name keeps old behavior", func(t *testing.T) {
+		err := InvalidArgument("value is missing")
+		expected := "invalidArgError: value is missing"
+		if err.Error() != expected {
+			t.Fatalf("unexpected error message: %s", err)
+		}
+		if !errors.Is(err, ErrInvalidArg) {
+			t.Fatalf("error should wrap ErrInvalidArg")
+		}
+	})
+
+	t.Run("single argument name", func(t *testing.T) {
+		err := InvalidArgument("value is missing", "bot_token_env")
+		expected := `invalidArgError: broken argument "bot_token_env": value is missing`
+		if err.Error() != expected {
+			t.Fatalf("unexpected error message: %s", err)
+		}
+	})
+
+	t.Run("multiple argument names", func(t *testing.T) {
+		err := InvalidArgument("value mismatch", "bot_token_env", "chat_id_env", " ")
+		expected := `invalidArgError: broken arguments "bot_token_env", "chat_id_env": value mismatch`
+		if err.Error() != expected {
+			t.Fatalf("unexpected error message: %s", err)
+		}
+	})
+}
+
+func TestInvalidArgumentWithNamesfSupportsBrokenArgumentName(t *testing.T) {
+	err := InvalidArgumentWithNamesf([]string{"gateway.supported_assets.currency"}, "asset[%d] %s", 2, "is invalid")
+	expected := `invalidArgError: broken argument "gateway.supported_assets.currency": asset[2] is invalid`
+	if err.Error() != expected {
+		t.Fatalf("unexpected error message: %s", err)
+	}
+	if !errors.Is(err, ErrInvalidArg) {
+		t.Fatalf("error should wrap ErrInvalidArg")
+	}
+}
+
+func TestInvalidArgumentWrapSupportsBrokenArgumentName(t *testing.T) {
+	base := Define("root cause")
+	err := InvalidArgumentWrap(base, "value is missing", "bot_token_env")
+	if !strings.Contains(err.Error(), `invalidArgError: broken argument "bot_token_env": value is missing`) {
+		t.Fatalf("wrapped error should include broken argument name: %s", err)
+	}
+	if !errors.Is(err, ErrInvalidArg) || !errors.Is(err, base) {
+		t.Fatalf("wrapped error should preserve all error layers")
+	}
+}
+
+func TestInternalWrapAllPreservesAllCauses(t *testing.T) {
+	first := Define("first cause")
+	second := Define("second cause")
+	err := InternalWrapAll("combined failure", first, nil, second)
+	if !strings.Contains(err.Error(), "internal: combined failure") {
+		t.Fatalf("wrapped error should include context: %s", err)
+	}
+	if !errors.Is(err, ErrInternal) || !errors.Is(err, first) || !errors.Is(err, second) {
+		t.Fatalf("wrapped error should preserve all error layers")
+	}
+}
+
+func TestOpaqueWrapPreservesCauseWithoutExposingItsText(t *testing.T) {
+	cause := DataConflict("restricted storage key")
+	err := OpaqueWrap(ErrInternal, cause, "safe persistence failure")
+
+	if got, want := err.Error(), "internal: safe persistence failure"; got != want {
+		t.Fatalf("opaque error mismatch: got=%q want=%q", got, want)
+	}
+	if !errors.Is(err, ErrInternal) || !errors.Is(err, ErrDataConflict) {
+		t.Fatalf("opaque error did not preserve classifications: %v", err)
+	}
+}
+
+func TestOperationalWrapsPreserveClassificationAndCause(t *testing.T) {
+	cause := Define("dependency failure")
+	tests := []struct {
+		name string
+		err  error
+		kind error
+	}{
+		{name: "failed precondition", err: FailedPreconditionWrap(cause, "AA capability unavailable"), kind: ErrFailedPrecondition},
+		{name: "service unavailable", err: ServiceUnavailableWrap(cause, "Arbitrum RPC unavailable"), kind: ErrServiceUnavailable},
+		{name: "data conflict", err: DataConflictWrap(cause, "managed wallet replay differs"), kind: ErrDataConflict},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if !errors.Is(tt.err, tt.kind) || !errors.Is(tt.err, cause) {
+				t.Fatalf("wrapped error should preserve classification and cause: %s", tt.err)
+			}
+		})
+	}
+}

backend/shared/errors/invalid_argument.go

@@ -0,0 +1,44 @@
+package merrors
+
+import (
+	"fmt"
+	"strings"
+)
+
+// InvalidArgumentClassified returns an invalid-argument error with a stable
+// machine reason and structured field names for transport adapters.
+func InvalidArgumentClassified(reason, msg string, argumentNames ...string) error {
+	return classifiedError{
+		base:          ErrInvalidArg,
+		msg:           invalidArgumentMessage(msg, argumentNames...),
+		reason:        strings.TrimSpace(reason),
+		argumentNames: normalizeArgumentNames(argumentNames),
+	}
+}
+
+func invalidArgumentMessage(msg string, argumentNames ...string) string {
+	normalizedNames := normalizeArgumentNames(argumentNames)
+	names := make([]string, 0, len(normalizedNames))
+	for _, name := range normalizedNames {
+		names = append(names, fmt.Sprintf("%q", name))
+	}
+	if len(names) == 0 {
+		return msg
+	}
+
+	prefix := "broken argument"
+	if len(names) > 1 {
+		prefix = "broken arguments"
+	}
+	return fmt.Sprintf("%s %s: %s", prefix, strings.Join(names, ", "), msg)
+}
+
+func normalizeArgumentNames(argumentNames []string) []string {
+	names := make([]string, 0, len(argumentNames))
+	for _, name := range argumentNames {
+		if name = strings.TrimSpace(name); name != "" {
+			names = append(names, name)
+		}
+	}
+	return names
+}

backend/shared/errors/reason.go

@@ -0,0 +1,19 @@
+package merrors
+
+import (
+	"errors"
+	"strings"
+)
+
+func Reason(err error) (string, bool) {
+	var reasoned interface {
+		Reason() string
+	}
+	if errors.As(err, &reasoned) {
+		reason := strings.TrimSpace(reasoned.Reason())
+		if reason != "" {
+			return reason, true
+		}
+	}
+	return "", false
+}

backend/shared/errors/throttle.go

@@ -0,0 +1,50 @@
+package merrors
+
+import (
+	"errors"
+	"strings"
+	"time"
+)
+
+// ThrottleDetails describes a temporary request limit without coupling callers
+// to a transport-specific response format.
+type ThrottleDetails struct {
+	ScopeKind  string
+	RetryAfter time.Duration
+}
+
+type throttleDetailsError struct {
+	base    error
+	msg     string
+	details ThrottleDetails
+}
+
+func (e throttleDetailsError) Error() string {
+	return Wrap(e.base, e.msg).Error()
+}
+
+func (e throttleDetailsError) Unwrap() error {
+	return e.base
+}
+
+// WithThrottle annotates an error with retry information while preserving its
+// classification for errors.Is and errors.As.
+func WithThrottle(base error, scopeKind string, retryAfter time.Duration, msg string) error {
+	return throttleDetailsError{
+		base: base,
+		msg:  msg,
+		details: ThrottleDetails{
+			ScopeKind:  strings.TrimSpace(scopeKind),
+			RetryAfter: retryAfter,
+		},
+	}
+}
+
+// ThrottleDetailsFrom returns retry information attached by WithThrottle.
+func ThrottleDetailsFrom(err error) (ThrottleDetails, bool) {
+	var throttled throttleDetailsError
+	if !errors.As(err, &throttled) {
+		return ThrottleDetails{}, false
+	}
+	return throttled.details, true
+}

backend/shared/errors/throttle_test.go

@@ -0,0 +1,35 @@
+package merrors
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestWithThrottlePreservesClassificationAndDetails(t *testing.T) {
+	base := Define("verificationLimited")
+	err := Wrap(
+		WithThrottle(base, " destination ", 45*time.Second, "request is temporarily limited"),
+		"verification failed",
+	)
+
+	if !errors.Is(err, base) {
+		t.Fatalf("throttle error did not preserve classification: %v", err)
+	}
+	details, ok := ThrottleDetailsFrom(err)
+	if !ok {
+		t.Fatal("throttle details were not available through wrapping")
+	}
+	if details.ScopeKind != "destination" || details.RetryAfter != 45*time.Second {
+		t.Fatalf("unexpected throttle details: %+v", details)
+	}
+	if got, want := err.Error(), "verificationLimited: request is temporarily limited: verification failed"; got != want {
+		t.Fatalf("unexpected throttle error text: got=%q want=%q", got, want)
+	}
+}
+
+func TestThrottleDetailsFromRejectsUnannotatedError(t *testing.T) {
+	if details, ok := ThrottleDetailsFrom(ServiceUnavailable("dependency unavailable")); ok {
+		t.Fatalf("unexpected throttle details: %+v", details)
+	}
+}

backend/shared/go.mod

@@ -0,0 +1,71 @@
+module git.sendico.io/tech/sxchnge/shared
+
+go 1.27.0
+
+require (
+	github.com/go-viper/mapstructure/v2 v2.5.0
+	github.com/mattn/go-colorable v0.1.15
+	github.com/stretchr/testify v1.12.1
+	github.com/testcontainers/testcontainers-go v0.44.0
+	github.com/testcontainers/testcontainers-go/modules/mongodb v0.44.0
+	go.mongodb.org/mongo-driver/v2 v2.9.0
+	go.uber.org/zap v1.28.0
+)
+
+require (
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/containerd/errdefs v1.0.0 // indirect
+	github.com/containerd/errdefs/pkg v0.3.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/containerd/platforms v0.2.1 // indirect
+	github.com/cpuguy83/dockercfg v0.3.2 // indirect
+	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/go-connections v0.7.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/ebitengine/purego v0.10.1 // indirect
+	github.com/felixge/httpsnoop v1.1.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.3.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/klauspost/compress v1.19.2 // indirect
+	github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/go-archive v0.2.0 // indirect
+	github.com/moby/moby/api v1.55.0 // indirect
+	github.com/moby/moby/client v0.5.0 // indirect
+	github.com/moby/patternmatcher v0.6.1 // indirect
+	github.com/moby/sys/sequential v0.7.0 // indirect
+	github.com/moby/sys/user v0.4.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/moby/term v0.5.2 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.1 // indirect
+	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
+	github.com/shirou/gopsutil/v4 v4.26.6 // indirect
+	github.com/sirupsen/logrus v1.9.4 // indirect
+	github.com/tklauser/go-sysconf v0.4.0 // indirect
+	github.com/tklauser/numcpus v0.12.0 // indirect
+	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
+	github.com/xdg-go/scram v1.2.0 // indirect
+	github.com/xdg-go/stringprep v1.0.4 // indirect
+	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 // indirect
+	go.opentelemetry.io/otel v1.44.0 // indirect
+	go.opentelemetry.io/otel/metric v1.44.0 // indirect
+	go.opentelemetry.io/otel/trace v1.44.0 // indirect
+	go.uber.org/multierr v1.10.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.5 // indirect
+	golang.org/x/crypto v0.56.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.41.0 // indirect
+)

backend/shared/go.sum

@@ -0,0 +1,177 @@
+dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
+dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8afgbRMd7mFxO99hRNu+6tazq8nFF9lIwo9JFroBk=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6/go.mod h1:8o94RPi1/7XTJvwPpRSzSUedZrtlirdB3r9Z20bi2f8=
+github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c h1:udKWzYgxTojEKWjV8V+WSxDXJ4NFATAsZjh8iIbsQIg=
+github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
+github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
+github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
+github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk=
+github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
+github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
+github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
+github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
+github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
+github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
+github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
+github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
+github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/go-connections v0.7.0 h1:6SsRfJddP22WMrCkj19x9WKjEDTB+ahsdiGYf0mN39c=
+github.com/docker/go-connections v0.7.0/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q=
+github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
+github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
+github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY=
+github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc=
+github.com/felixge/httpsnoop v1.1.0/go.mod h1:Zqxgdd+1Rkcz8euOqdr7lqgCRJztwr5hp9vDSi5UZCE=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
+github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
+github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
+github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
+github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/klauspost/compress v1.19.2 h1:hMRETovs/pu/dVWN7zIT1PGG8t509MwT6bO7XSi26R8=
+github.com/klauspost/compress v1.19.2/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e h1:Q6MvJtQK/iRcRtzAscm/zF23XxJlbECiGPyRicsX+Ak=
+github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
+github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
+github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
+github.com/mattn/go-colorable v0.1.15 h1:+u9SLTRGnXv73cEsnsmoZBom+dMU88B2M0aDcWy0/jY=
+github.com/mattn/go-colorable v0.1.15/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
+github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
+github.com/moby/go-archive v0.2.0 h1:zg5QDUM2mi0JIM9fdQZWC7U8+2ZfixfTYoHL7rWUcP8=
+github.com/moby/go-archive v0.2.0/go.mod h1:mNeivT14o8xU+5q1YnNrkQVpK+dnNe/K6fHqnTg4qPU=
+github.com/moby/moby/api v1.55.0 h1:2/sexvQyqIWS8pRSCFddBfpW2qE7vR7FCL+vN8pxwMc=
+github.com/moby/moby/api v1.55.0/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs=
+github.com/moby/moby/client v0.5.0 h1:5XhyPk2fuOWf6RlSFa3MkIIgDZkF25xToXW8Q/BH7cc=
+github.com/moby/moby/client v0.5.0/go.mod h1:rcVpF8ncl9vo5gaIBdol6CnbEtSj1uxMvEV/UrykF/s=
+github.com/moby/patternmatcher v0.6.1 h1:qlhtafmr6kgMIJjKJMDmMWq7WLkKIo23hsrpR3x084U=
+github.com/moby/patternmatcher v0.6.1/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
+github.com/moby/sys/sequential v0.7.0 h1:ASQNGNROJSuOO6LL6bPHbKvuZu6NU8P4ldPWk31zj/8=
+github.com/moby/sys/sequential v0.7.0/go.mod h1:NfSTAp6V3fw4tmkD62PEcOKeZKquXT8VKCkf7aVR79o=
+github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs=
+github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
+github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
+github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
+github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ=
+github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
+github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
+github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU=
+github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
+github.com/shirou/gopsutil/v4 v4.26.6 h1:Mzr/npDtQC/xpeEuQKHZt8Zo9CmPvhTj8nkR8w5TLDs=
+github.com/shirou/gopsutil/v4 v4.26.6/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ=
+github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
+github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
+github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4=
+github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0=
+github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
+github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
+github.com/testcontainers/testcontainers-go v0.44.0 h1:/Fwh6HY1mIikhnm9e7HwoxGycx0lzRAE0f5VQpjFxzI=
+github.com/testcontainers/testcontainers-go v0.44.0/go.mod h1:IcnwQrYTO86xHXu5bvMaBH7ATlbS3Qn1M1QWW3c66rE=
+github.com/testcontainers/testcontainers-go/modules/mongodb v0.44.0 h1:VSPDFiumAtt0CkZEVbmAkEmYVRvsJpKJy9oF3exRKYg=
+github.com/testcontainers/testcontainers-go/modules/mongodb v0.44.0/go.mod h1:kHfzrY1cYP/zr9H4TdqAxbP836A1C2fyUojlHidhFGI=
+github.com/tklauser/go-sysconf v0.4.0 h1:7H0uAN+7RkwWRaxhYXDLqa5V3LPrJeV8wmD9dRUgPQU=
+github.com/tklauser/go-sysconf v0.4.0/go.mod h1:8mTNWyog7H+MpKijp4VmKJAd2bbYQ2zuUwkYRbUArPI=
+github.com/tklauser/numcpus v0.12.0 h1:NR85qdvHA9pFse3x3weVZ0r0ST8R6l5RHbZrlRaqob4=
+github.com/tklauser/numcpus v0.12.0/go.mod h1:ABHeXzJnr/qqwguhClkZKT1/8VABcYrsyUiUGobwWJg=
+github.com/xdg-go/pbkdf2 v1.0.0 h1:Su7DPu48wXMwC3bs7MCNG+z4FhcyEuz5dlvchbq0B0c=
+github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI=
+github.com/xdg-go/scram v1.2.0 h1:bYKF2AEwG5rqd1BumT4gAnvwU/M9nBp2pTSxeZw7Wvs=
+github.com/xdg-go/scram v1.2.0/go.mod h1:3dlrS0iBaWKYVt2ZfA4cj48umJZ+cAEbR6/SjLA88I8=
+github.com/xdg-go/stringprep v1.0.4 h1:XLI/Ng3O1Atzq0oBs3TWm+5ZVgkq2aqdlvP9JtoZ6c8=
+github.com/xdg-go/stringprep v1.0.4/go.mod h1:mPGuuIYwz7CmR2bT9j4GbQqutWS1zV24gijq1dTyGkM=
+github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
+github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfSfmXjznFBSZNN13rSJjlIOI1fUNAtF7rmI=
+github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
+github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
+go.mongodb.org/mongo-driver/v2 v2.9.0 h1:e2mQdOmbkiYz+dj3faM7lVDwl7WdnRD+g5VicafMhL0=
+go.mongodb.org/mongo-driver/v2 v2.9.0/go.mod h1:SHKN0IWkKmEVGHLjXnni6s4wPKX4v86FTgOeJJFuXcA=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 h1:8tvICD4vSTOOsNrsI4Ljf6C+6UKvpTEH5XY3JMoyPoo=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0/go.mod h1:z9+yiacE0IHRqM4qFfkbt/JYlmYXgss8GY/jXoNuPJI=
+go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
+go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
+go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
+go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
+go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
+go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
+go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
+go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
+go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
+go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
+go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.28.0 h1:IZzaP1Fv73/T/pBMLk4VutPl36uNC+OSUh3JLG3FIjo=
+go.uber.org/zap v1.28.0/go.mod h1:rDLpOi171uODNm/mxFcuYWxDsqWSAVkFdX4XojSKg/Q=
+go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
+go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/crypto v0.56.0 h1:GUh5Ii4J5jtcseSMiRqr1jXCNHoxjeV9Fmekc2oLy6Y=
+golang.org/x/crypto v0.56.0/go.mod h1:OMW5y6CY9l38uPLmxU6l6pwcXp1obtLo3e6gT7gQR2I=
+golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
+golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.3.8/go.mod h1:E6s5w1FMmriuDzIBO73fBruAKo1PCIq6d2Q6DHfQ8WQ=
+golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
+golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
+gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
+pgregory.net/rapid v1.2.0 h1:keKAYRcjm+e1F0oAuU5F5+YPAWcyxNNRK2wud503Gnk=
+pgregory.net/rapid v1.2.0/go.mod h1:PY5XlDGj0+V1FCq0o192FdRhpKHGTRIWBgqjDBTrq04=

backend/shared/http/methods.go

@@ -0,0 +1,36 @@
+package api
+
+import "fmt"
+
+type HTTPMethod int
+
+const (
+	Get HTTPMethod = iota
+	Post
+	Put
+	Patch
+	Delete
+	Options
+	Head
+)
+
+func HTTPMethod2String(method HTTPMethod) string {
+	switch method {
+	case Get:
+		return "GET"
+	case Post:
+		return "POST"
+	case Put:
+		return "PUT"
+	case Delete:
+		return "DELETE"
+	case Patch:
+		return "PATCH"
+	case Options:
+		return "OPTIONS"
+	case Head:
+		return "HEAD"
+	default:
+		return fmt.Sprintf("unknown: %d", method)
+	}
+}

backend/shared/http/response/response.go

@@ -0,0 +1,225 @@
+package response
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	api "git.sendico.io/tech/sxchnge/shared/http"
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"git.sendico.io/tech/sxchnge/shared/service"
+	"go.uber.org/zap"
+)
+
+// BaseResponse is a general structure for all API responses.
+type BaseResponse struct {
+	Status string `json:"status"` // "success" or "error"
+	Data   any    `json:"data"`   // The actual data payload or the error details
+}
+
+// ErrorResponse provides more details about an error.
+type ErrorResponse struct {
+	Code    int    `json:"code"` // A unique identifier for the error type, useful for client handling
+	Error   string `json:"error"`
+	Source  string `json:"source"`
+	Details any    `json:"details"` // Additional details or hints about the error, if necessary
+}
+
+func errMessage(err error) string {
+	if err != nil {
+		return err.Error()
+	}
+	return ""
+}
+
+func logRequest(logger mlogger.Logger, r *http.Request, message string) {
+	logger.Debug(
+		message,
+		zap.String("host", r.Host),
+		zap.String("address", r.RemoteAddr),
+		zap.String("method", r.Method),
+		zap.String("request_uri", r.RequestURI),
+		zap.String("proto", r.Proto),
+		zap.String("user_agent", r.UserAgent()),
+	)
+}
+
+func writeJSON(logger mlogger.Logger, w http.ResponseWriter, r *http.Request, code int, payload any) {
+	w.Header().Set("Content-Type", "application/json; charset=UTF-8")
+	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("Pragma", "no-cache")
+	w.WriteHeader(code)
+	if err := json.NewEncoder(w).Encode(&payload); err != nil {
+		logger.Warn("Failed to encode JSON response",
+			zap.Error(err),
+			zap.String("host", r.Host),
+			zap.String("address", r.RemoteAddr),
+			zap.String("method", r.Method),
+			zap.String("request_uri", r.RequestURI),
+			zap.String("proto", r.Proto),
+			zap.String("user_agent", r.UserAgent()))
+	}
+}
+
+func errorf(
+	logger mlogger.Logger,
+	w http.ResponseWriter, r *http.Request,
+	source mservice.Type, code int, message string, details any,
+) {
+	logRequest(logger, r, message)
+
+	errorMessage := BaseResponse{
+		Status: api.MSError,
+		Data: ErrorResponse{
+			Code:    code,
+			Details: details,
+			Source:  source,
+			Error:   message,
+		},
+	}
+
+	writeJSON(logger, w, r, code, errorMessage)
+}
+
+func Accepted(logger mlogger.Logger, data any) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		resp := BaseResponse{
+			Status: api.MSSuccess,
+			Data:   data,
+		}
+		writeJSON(logger, w, r, http.StatusAccepted, resp)
+	}
+}
+
+func Ok(logger mlogger.Logger, data any) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		resp := BaseResponse{
+			Status: api.MSSuccess,
+			Data:   data,
+		}
+		writeJSON(logger, w, r, http.StatusOK, resp)
+	}
+}
+
+func Created(logger mlogger.Logger, data any) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		resp := BaseResponse{
+			Status: api.MSSuccess,
+			Data:   data,
+		}
+		writeJSON(logger, w, r, http.StatusCreated, resp)
+	}
+}
+
+func Auto(logger mlogger.Logger, source mservice.Type, err error) http.HandlerFunc {
+	if err == nil {
+		return Success(logger)
+	}
+	if errors.Is(err, merrors.ErrAccessDenied) {
+		return AccessDenied(logger, source, errMessage(err))
+	}
+	if errors.Is(err, merrors.ErrDataConflict) {
+		return DataConflict(logger, source, errMessage(err))
+	}
+	if errors.Is(err, merrors.ErrInvalidArg) {
+		return BadRequest(logger, source, "invalid_argument", errMessage(err))
+	}
+	if errors.Is(err, merrors.ErrNoData) {
+		return NotFound(logger, source, errMessage(err))
+	}
+	if errors.Is(err, merrors.ErrUnauthorized) {
+		return Unauthorized(logger, source, errMessage(err))
+	}
+	if errors.Is(err, merrors.ErrServiceUnavailable) {
+		return Error(logger, source, http.StatusServiceUnavailable, "service_unavailable", errMessage(err))
+	}
+	return Internal(logger, source, err)
+}
+
+func Internal(logger mlogger.Logger, source mservice.Type, err error) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, http.StatusInternalServerError, "internal_error", errMessage(err))
+	}
+}
+
+func NotImplemented(logger mlogger.Logger, source mservice.Type, hint string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, http.StatusNotImplemented, "not_implemented", hint)
+	}
+}
+
+func BadRequest(logger mlogger.Logger, source mservice.Type, err, hint string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, http.StatusBadRequest, err, hint)
+	}
+}
+
+func Gone(logger mlogger.Logger, source mservice.Type, err, hint string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, http.StatusGone, err, hint)
+	}
+}
+
+func BadQueryParam(logger mlogger.Logger, source mservice.Type, param string, err error) http.HandlerFunc {
+	return BadRequest(logger, source, "invalid_query_parameter", fmt.Sprintf("Failed to parse '%s': %v", param, err))
+}
+
+func BadReference(logger mlogger.Logger, source mservice.Type, refName, refVal string, err error) http.HandlerFunc {
+	return BadRequest(logger, source, "broken_reference",
+		fmt.Sprintf("broken object reference: %s = %s, error: %v", refName, refVal, err))
+}
+
+func BadPayload(logger mlogger.Logger, source mservice.Type, err error) http.HandlerFunc {
+	return BadRequest(logger, source, "broken_payload",
+		fmt.Sprintf("broken '%s' object payload, error: %v", source, err))
+}
+
+func DataConflict(logger mlogger.Logger, source mservice.Type, hint string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, http.StatusConflict, "data_conflict", hint)
+	}
+}
+
+func Error(logger mlogger.Logger, source mservice.Type, code int, errType, hint string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, code, errType, hint)
+	}
+}
+
+func ErrorWithDetails(logger mlogger.Logger, source mservice.Type, code int, errType string, details any) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, code, errType, details)
+	}
+}
+
+func AccessDenied(logger mlogger.Logger, source mservice.Type, hint string) http.HandlerFunc {
+	return Error(logger, source, http.StatusForbidden, "access_denied", hint)
+}
+
+func Forbidden(logger mlogger.Logger, source mservice.Type, errType, hint string) http.HandlerFunc {
+	return Error(logger, source, http.StatusForbidden, errType, hint)
+}
+
+func TooManyRequests(logger mlogger.Logger, source mservice.Type, hint string) http.HandlerFunc {
+	return Error(logger, source, http.StatusTooManyRequests, "too_many_requests", hint)
+}
+
+func LicenseRequired(logger mlogger.Logger, source mservice.Type, hint string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, http.StatusPaymentRequired, "license_required", hint)
+	}
+}
+
+func Unauthorized(logger mlogger.Logger, source mservice.Type, hint string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, http.StatusUnauthorized, "unauthorized", hint)
+	}
+}
+
+func NotFound(logger mlogger.Logger, source mservice.Type, hint string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf(logger, w, r, source, http.StatusNotFound, "not_found", hint)
+	}
+}

backend/shared/http/response/response_test.go

@@ -0,0 +1,42 @@
+package response
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"git.sendico.io/tech/sxchnge/shared/service"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+)
+
+func TestAutoMapsServiceUnavailable(t *testing.T) {
+	req := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/health", nil)
+	recorder := httptest.NewRecorder()
+
+	Auto(zap.NewNop(), mservice.Type("test"), merrors.ServiceUnavailable("dependency down")).ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusServiceUnavailable, recorder.Code)
+	require.True(t, strings.Contains(recorder.Body.String(), "service_unavailable"))
+}
+
+func TestErrorWithDetailsPreservesStructuredPayload(t *testing.T) {
+	req := httptest.NewRequestWithContext(context.Background(), http.MethodPost, "/actions", nil)
+	recorder := httptest.NewRecorder()
+
+	ErrorWithDetails(zap.NewNop(), mservice.Type("test"), http.StatusConflict, "conflict", map[string]string{
+		"operation_ref": "operation-1",
+	}).ServeHTTP(recorder, req)
+
+	var payload struct {
+		Data struct {
+			Details map[string]string `json:"details"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(recorder.Body.Bytes(), &payload))
+	require.Equal(t, "operation-1", payload.Data.Details["operation_ref"])
+}

backend/shared/http/response/result.go

@@ -0,0 +1,19 @@
+package response
+
+import (
+	"net/http"
+
+	"git.sendico.io/tech/sxchnge/shared/logging"
+)
+
+type Result struct {
+	Result bool `json:"result"`
+}
+
+func Success(logger mlogger.Logger) http.HandlerFunc {
+	return Ok(logger, Result{Result: true})
+}
+
+func Failed(logger mlogger.Logger) http.HandlerFunc {
+	return Accepted(logger, Result{Result: false})
+}

backend/shared/http/status.go

@@ -0,0 +1,8 @@
+package api
+
+const (
+	MSSuccess   string = "success"
+	MSProcessed string = "processed"
+	MSError     string = "error"
+	MSRequest   string = "request"
+)

backend/shared/logging/factory/mlogger.go

@@ -0,0 +1,10 @@
+package mlogger
+
+import (
+	lt "git.sendico.io/tech/sxchnge/shared/logging"
+	li "git.sendico.io/tech/sxchnge/shared/logging/internal"
+)
+
+func NewLogger(debug bool) lt.Logger {
+	return li.NewLoggerImp(debug)
+}

backend/shared/logging/fields/account.go

@@ -0,0 +1,23 @@
+package mzap
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/logging/mask"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.uber.org/zap"
+)
+
+func AccRef(accountRef bson.ObjectID) zap.Field {
+	return ObjRef("account_ref", accountRef)
+}
+
+func Email(email string) zap.Field {
+	return MaskEmail("email", email)
+}
+
+func MaskEmail(field, email string) zap.Field {
+	return zap.String(field, mask.Email(email))
+}
+
+func MaskEmails(field string, emails []string) zap.Field {
+	return zap.Strings(field, mask.Emails(emails))
+}

backend/shared/logging/fields/error.go

@@ -0,0 +1,14 @@
+package mzap
+
+import (
+	"reflect"
+
+	"go.uber.org/zap"
+)
+
+func ErrorType(err error) zap.Field {
+	if err == nil {
+		return zap.String("error_type", "")
+	}
+	return zap.String("error_type", reflect.TypeOf(err).String())
+}

backend/shared/logging/fields/object.go

@@ -0,0 +1,15 @@
+package mzap
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.uber.org/zap"
+)
+
+func ObjRef(name string, objRef bson.ObjectID) zap.Field {
+	return zap.String(name, objRef.Hex())
+}
+
+func StorableRef(obj storable.Storable) zap.Field {
+	return ObjRef(obj.Collection()+"_ref", *obj.GetID())
+}

backend/shared/logging/internal/mlogger.go

@@ -0,0 +1,23 @@
+package mlogger
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"github.com/mattn/go-colorable"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+)
+
+func NewLoggerImp(debug bool) mlogger.Logger {
+	if debug {
+		dc := zap.NewDevelopmentEncoderConfig()
+		dc.EncodeLevel = zapcore.CapitalColorLevelEncoder
+		logger := zap.New(zapcore.NewCore(
+			zapcore.NewConsoleEncoder(dc),
+			zapcore.AddSync(colorable.NewColorableStdout()),
+			zapcore.DebugLevel,
+		))
+		return logger
+	}
+
+	return zap.Must(zap.NewProduction())
+}

backend/shared/logging/logger.go

@@ -0,0 +1,119 @@
+package mlogger
+
+import (
+	"fmt"
+	"strings"
+
+	"go.uber.org/zap"
+)
+
+type Logger = *zap.Logger
+
+// Named appends logger name components while avoiding adjacent or already-present
+// name stutter such as "notification.notification" or "vault.vault.kv".
+func Named(logger Logger, names ...any) Logger {
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+
+	current := splitName(logger.Name())
+	for _, name := range names {
+		if name == nil {
+			continue
+		}
+		parts := splitName(fmt.Sprint(name))
+		if len(parts) == 0 {
+			continue
+		}
+		if containsParts(current, parts) {
+			continue
+		}
+
+		parts = trimOverlappingPrefix(current, parts)
+		parts = trimStutteringPrefix(current, parts)
+		if len(parts) == 0 {
+			continue
+		}
+
+		child := strings.Join(parts, ".")
+		logger = logger.Named(child)
+		current = append(current, parts...)
+	}
+
+	return logger
+}
+
+func splitName(name string) []string {
+	raw := strings.Split(name, ".")
+	parts := make([]string, 0, len(raw))
+	for _, part := range raw {
+		part = strings.TrimSpace(part)
+		if part == "" {
+			continue
+		}
+		parts = append(parts, part)
+	}
+	return parts
+}
+
+func containsParts(parent, child []string) bool {
+	if len(parent) == 0 || len(child) == 0 || len(child) > len(parent) {
+		return false
+	}
+	for i := 0; i <= len(parent)-len(child); i++ {
+		matches := true
+		for j := range child {
+			if parent[i+j] != child[j] {
+				matches = false
+				break
+			}
+		}
+		if matches {
+			return true
+		}
+	}
+	return false
+}
+
+func trimOverlappingPrefix(parent, child []string) []string {
+	max := len(parent)
+	if len(child) < max {
+		max = len(child)
+	}
+	for n := max; n > 0; n-- {
+		matches := true
+		for i := 0; i < n; i++ {
+			if parent[len(parent)-n+i] != child[i] {
+				matches = false
+				break
+			}
+		}
+		if matches {
+			return child[n:]
+		}
+	}
+	return child
+}
+
+func trimStutteringPrefix(parent, child []string) []string {
+	if len(parent) == 0 || len(child) == 0 {
+		return child
+	}
+
+	last := parent[len(parent)-1]
+	first := child[0]
+	for _, separator := range []string{"_", "-"} {
+		prefix := last + separator
+		if !strings.HasPrefix(first, prefix) {
+			continue
+		}
+		trimmed := strings.TrimSpace(strings.TrimPrefix(first, prefix))
+		if trimmed == "" {
+			return child[1:]
+		}
+		out := append([]string{trimmed}, child[1:]...)
+		return out
+	}
+
+	return child
+}

backend/shared/logging/logger_test.go

@@ -0,0 +1,71 @@
+package mlogger
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zaptest/observer"
+)
+
+func TestNamedAvoidsLoggerNameStutter(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		base string
+		add  []any
+		want string
+	}{
+		{
+			name: "skips duplicate service name",
+			base: "notification",
+			add:  []any{"notification"},
+			want: "notification",
+		},
+		{
+			name: "overlaps dotted component",
+			base: "vault",
+			add:  []any{"vault.kv"},
+			want: "vault.kv",
+		},
+		{
+			name: "drops child prefix stutter",
+			base: "server.client",
+			add:  []any{"client_v2"},
+			want: "server.client.v2",
+		},
+		{
+			name: "keeps already present module name",
+			base: "payments.quotation.server",
+			add:  []any{"payments.quotation"},
+			want: "payments.quotation.server",
+		},
+		{
+			name: "extends partial overlap",
+			base: "payments",
+			add:  []any{"payments.quotation"},
+			want: "payments.quotation",
+		},
+		{
+			name: "keeps unrelated names",
+			base: "gateway.server",
+			add:  []any{"chain", "storage.mongo"},
+			want: "gateway.server.chain.storage.mongo",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			observed, logs := observer.New(zap.InfoLevel)
+			logger := Named(zap.New(observed).Named(tt.base), tt.add...)
+			logger.Info("test")
+
+			entries := logs.All()
+			require.Len(t, entries, 1)
+			require.Equal(t, tt.want, entries[0].LoggerName)
+		})
+	}
+}

backend/shared/logging/mask/mask.go

@@ -0,0 +1,29 @@
+package mask
+
+import "strings"
+
+func Email(email string) string {
+	parts := strings.Split(email, "@")
+	if len(parts) != 2 {
+		return email
+	}
+	local := parts[0]
+	if len(local) > 2 {
+		local = local[:1] + "***" + local[len(local)-1:]
+	} else {
+		local = local[:1] + "***"
+	}
+	return local + "@" + parts[1]
+}
+
+func Emails(emails []string) []string {
+	if emails == nil {
+		return nil
+	}
+
+	masked := make([]string, len(emails))
+	for i, email := range emails {
+		masked[i] = Email(email)
+	}
+	return masked
+}

backend/shared/logging/mask/mask_test.go

@@ -0,0 +1,21 @@
+package mask
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestEmailsMasksEachEmail(t *testing.T) {
+	got := Emails([]string{"alice@example.com", "bo@example.org", "invalid"})
+	want := []string{"a***e@example.com", "b***@example.org", "invalid"}
+
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("Emails() = %#v, want %#v", got, want)
+	}
+}
+
+func TestEmailsPreservesNil(t *testing.T) {
+	if got := Emails(nil); got != nil {
+		t.Fatalf("Emails(nil) = %#v, want nil", got)
+	}
+}

backend/shared/model/archivable.go

@@ -0,0 +1,18 @@
+package model
+
+type Archivable interface {
+	IsArchived() bool
+	SetArchived(archived bool)
+}
+
+type ArchivableBase struct {
+	Archived bool `bson:"isArchived" json:"isArchived"`
+}
+
+func (a *ArchivableBase) IsArchived() bool {
+	return a.Archived
+}
+
+func (a *ArchivableBase) SetArchived(archived bool) {
+	a.Archived = archived
+}

backend/shared/model/describable.go

@@ -0,0 +1,11 @@
+package model
+
+type Describable struct {
+	Name        string  `bson:"name" json:"name"`                                   // Name
+	Description *string `bson:"description,omitempty" json:"description,omitempty"` // Optional description
+}
+
+const (
+	NameField        = "name"
+	DescriptionField = "description"
+)

backend/shared/model/fconfig.go

@@ -0,0 +1,8 @@
+package model
+
+type SettingsT = map[string]any
+
+type DriverConfig[T any] struct {
+	Driver   T         `yaml:"driver"`
+	Settings SettingsT `yaml:"settings"`
+}

backend/shared/model/viewcursor.go

@@ -0,0 +1,8 @@
+package model
+
+// ViewCursor aggregates pagination and archival filters for list queries
+type ViewCursor struct {
+	Limit      *int64
+	Offset     *int64
+	IsArchived *bool
+}

backend/shared/ratelimit/config.go

@@ -0,0 +1,38 @@
+package ratelimit
+
+import (
+	"strings"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/errors"
+)
+
+const (
+	MinWindow = time.Second
+	MaxWindow = 24 * time.Hour
+	MaxLimit  = 10000
+)
+
+type WindowConfig struct {
+	Limit  int    `yaml:"limit"`
+	Window string `yaml:"window"`
+}
+
+type Window struct {
+	Limit  int
+	Window time.Duration
+}
+
+func ResolveWindow(raw WindowConfig, field string) (Window, error) {
+	if raw.Limit < 1 || raw.Limit > MaxLimit {
+		return Window{}, merrors.InvalidArgument("rate limit must be between 1 and 10000", field+".limit")
+	}
+	window, err := time.ParseDuration(strings.TrimSpace(raw.Window))
+	if err != nil {
+		return Window{}, merrors.InvalidArgument("rate limit window must be a valid duration", field+".window")
+	}
+	if window < MinWindow || window > MaxWindow {
+		return Window{}, merrors.InvalidArgument("rate limit window must be between 1s and 24h", field+".window")
+	}
+	return Window{Limit: raw.Limit, Window: window}, nil
+}

backend/shared/ratelimit/store/db.go

@@ -0,0 +1,184 @@
+package ratelimits
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"strings"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/shared/database/record"
+	"git.sendico.io/tech/sxchnge/shared/database/repository"
+	ri "git.sendico.io/tech/sxchnge/shared/database/repository/index"
+	"git.sendico.io/tech/sxchnge/shared/errors"
+	"git.sendico.io/tech/sxchnge/shared/logging"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.uber.org/zap"
+)
+
+const (
+	defaultCollection = "rate_limits"
+
+	fieldScopeKind   = "scopeKind"
+	fieldScopeHash   = "scopeHash"
+	fieldWindowStart = "windowStart"
+	fieldCount       = "count"
+	fieldExpiresAt   = "expiresAt"
+)
+
+// Store provides atomic, fixed-window abuse accounting shared by every BFF
+// instance connected to the same database.
+type Store interface {
+	Current(context.Context, string, string, time.Time) (int, error)
+	Increment(context.Context, string, string, time.Time, time.Time) (int, error)
+}
+
+func HashScope(kind, value string) string {
+	sum := sha256.Sum256([]byte(strings.TrimSpace(kind) + "\x00" + strings.TrimSpace(value)))
+	return hex.EncodeToString(sum[:])
+}
+
+type record struct {
+	storable.Base `bson:",inline"`
+	ScopeKind     string    `bson:"scopeKind"`
+	ScopeHash     string    `bson:"scopeHash"`
+	WindowStart   time.Time `bson:"windowStart"`
+	Count         int       `bson:"count"`
+	ExpiresAt     time.Time `bson:"expiresAt"`
+}
+
+func (r *record) Collection() string { return defaultCollection }
+
+type DB struct {
+	repo   repository.Repository
+	logger mlogger.Logger
+}
+
+func Create(logger mlogger.Logger, database *mongo.Database, collection string) (*DB, error) {
+	if database == nil {
+		return nil, merrors.InvalidArgument("database is required", "database")
+	}
+	collection = strings.TrimSpace(collection)
+	if collection == "" {
+		collection = defaultCollection
+	}
+	db := &DB{
+		repo:   repository.CreateMongoRepository(database, collection),
+		logger: logger.Named("rate_limits"),
+	}
+	if err := db.ensureIndexes(); err != nil {
+		db.logger.Error("Failed to create rate-limit indexes", zap.Error(err), zap.String("collection", collection))
+		return nil, err
+	}
+	return db, nil
+}
+
+func (db *DB) Current(
+	ctx context.Context,
+	scopeKind, scopeHash string,
+	windowStart time.Time,
+) (int, error) {
+	filter, err := scopeFilter(scopeKind, scopeHash, windowStart)
+	if err != nil {
+		return 0, err
+	}
+	current := &record{}
+	if err := db.repo.FindOneByFilter(ctx, filter, current); err != nil {
+		if errors.Is(err, merrors.ErrNoData) {
+			return 0, nil
+		}
+		return 0, err
+	}
+	return current.Count, nil
+}
+
+func (db *DB) Increment(
+	ctx context.Context,
+	scopeKind, scopeHash string,
+	windowStart, expiresAt time.Time,
+) (int, error) {
+	filter, err := scopeFilter(scopeKind, scopeHash, windowStart)
+	if err != nil {
+		return 0, err
+	}
+	if expiresAt.IsZero() || !expiresAt.After(windowStart) {
+		return 0, merrors.InvalidArgument("expiry must be after window start", "expiresAt")
+	}
+
+	current := &record{}
+	if err := db.repo.FindOneByFilter(ctx, filter, current); err == nil {
+		updated := &record{}
+		matched, patchErr := db.repo.PatchOneByFilter(ctx, filter, repository.Patch().
+			Inc(repository.Field(fieldCount), 1).
+			Set(repository.Field(fieldExpiresAt), expiresAt.UTC()), updated)
+		if patchErr != nil {
+			return 0, patchErr
+		}
+		if !matched {
+			return db.Increment(ctx, scopeKind, scopeHash, windowStart, expiresAt)
+		}
+		return updated.Count, nil
+	} else if !errors.Is(err, merrors.ErrNoData) {
+		return 0, err
+	}
+
+	created := &record{
+		ScopeKind:   strings.TrimSpace(scopeKind),
+		ScopeHash:   strings.TrimSpace(scopeHash),
+		WindowStart: windowStart.UTC(),
+		Count:       1,
+		ExpiresAt:   expiresAt.UTC(),
+	}
+	if err := db.repo.Insert(ctx, created, nil); err != nil {
+		if errors.Is(err, merrors.ErrDataConflict) {
+			return db.Increment(ctx, scopeKind, scopeHash, windowStart, expiresAt)
+		}
+		return 0, err
+	}
+	return created.Count, nil
+}
+
+func (db *DB) ensureIndexes() error {
+	ttl := int32(0)
+	indexes := []*ri.Definition{
+		{
+			Keys: []ri.Key{
+				{Field: fieldScopeKind, Sort: ri.Asc},
+				{Field: fieldScopeHash, Sort: ri.Asc},
+				{Field: fieldWindowStart, Sort: ri.Asc},
+			},
+			Unique: true,
+			Name:   "unique_rate_limit_window",
+		},
+		{
+			Keys: []ri.Key{{Field: fieldExpiresAt, Sort: ri.Asc}},
+			TTL:  &ttl,
+			Name: "ttl_rate_limit_expiry",
+		},
+	}
+	for _, index := range indexes {
+		if err := db.repo.CreateIndex(index); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func scopeFilter(scopeKind, scopeHash string, windowStart time.Time) (repository.FilterQuery, error) {
+	scopeKind = strings.TrimSpace(scopeKind)
+	if scopeKind == "" {
+		return nil, merrors.InvalidArgument("scope kind is required", "scopeKind")
+	}
+	scopeHash = strings.TrimSpace(scopeHash)
+	if scopeHash == "" {
+		return nil, merrors.InvalidArgument("scope hash is required", "scopeHash")
+	}
+	if windowStart.IsZero() {
+		return nil, merrors.InvalidArgument("window start is required", "windowStart")
+	}
+	return repository.Query().
+		Filter(repository.Field(fieldScopeKind), scopeKind).
+		Filter(repository.Field(fieldScopeHash), scopeHash).
+		Filter(repository.Field(fieldWindowStart), windowStart.UTC()), nil
+}

backend/shared/service/mservice.go

@@ -0,0 +1,10 @@
+package mservice
+
+import (
+	"context"
+)
+
+type MicroService interface {
+	Name() Type
+	Finish(ctx context.Context) error
+}

backend/shared/service/services.go

@@ -0,0 +1,11 @@
+package mservice
+
+type Type = string
+
+const (
+	Accounts           Type = "accounts"            // Represents user accounts in the system
+	Site               Type = "site"                // Represents public site endpoints
+	Clients            Type = "clients"             // Represents client information
+	RefreshTokens      Type = "refresh_tokens"      // Represents refresh tokens for authentication
+	VerificationTokens Type = "verification_tokens" //Represents verification tokens managed in the system
+)

backend/shared/version/factory/factory.go

@@ -0,0 +1,10 @@
+package version
+
+import (
+	"git.sendico.io/tech/sxchnge/shared/version"
+	versionimp "git.sendico.io/tech/sxchnge/shared/version/internal"
+)
+
+func Create(info *version.Info) version.Printer {
+	return versionimp.Create(info)
+}

backend/shared/version/info.go

@@ -0,0 +1,9 @@
+package version
+
+type Printer interface {
+	Print() string
+	Short() string
+	Info() string
+	Context() string
+	Program() string
+}