// pkg/account/types.go
package account

import (
    "time"
    "github.com/yourusername/finlib/pkg/common"
)

// AccountType represents the classification of an account
type AccountType string

const (
    Asset     AccountType = "ASSET"
    Liability AccountType = "LIABILITY"
    Equity    AccountType = "EQUITY"
    Revenue   AccountType = "REVENUE"
    Expense   AccountType = "EXPENSE"
)

// Account represents a financial account in the system
type Account struct {
    ID            string
    Code          string
    Name          string
    Type          AccountType
    ParentID      *string
    Created       time.Time
    LastModified  time.Time
    MetaData      map[string]interface{}
    
    // Plugin developers can extend the account structure
    Extensions    map[string]interface{}
}

// AccountManager defines the interface for account operations
type AccountManager interface {
    // CreateAccount creates a new account
    CreateAccount(ctx context.Context, account *Account) error
    
    // GetAccount retrieves an account by ID
    GetAccount(ctx context.Context, id string) (*Account, error)
    
    // UpdateAccount updates an existing account
    UpdateAccount(ctx context.Context, account *Account) error
    
    // DeleteAccount marks an account as deleted
    DeleteAccount(ctx context.Context, id string) error
    
    // ListAccounts retrieves accounts based on filters
    ListAccounts(ctx context.Context, filters AccountFilters) ([]*Account, error)
}

// pkg/validation/types.go
package validation

import (
    "context"
    "github.com/yourusername/finlib/pkg/common"
)

// ValidationSeverity indicates the severity of a validation result
type ValidationSeverity string

const (
    Error   ValidationSeverity = "ERROR"
    Warning ValidationSeverity = "WARNING"
    Info    ValidationSeverity = "INFO"
)

// ValidationResult represents the outcome of a validation check
type ValidationResult struct {
    Code      string
    Message   string
    Severity  ValidationSeverity
    Field     string
    Metadata  map[string]interface{}
}

// Validator defines the interface for implementing validation rules
type Validator interface {
    // Validate performs the validation and returns any violations
    Validate(ctx context.Context, obj interface{}) ([]ValidationResult, error)
    
    // GetRules returns the rules this validator checks
    GetRules() []ValidationRule
    
    // Priority determines the order of validator execution
    Priority() int
}

// ValidationRule describes a specific validation rule
type ValidationRule struct {
    ID          string
    Description string
    Severity    ValidationSeverity
    Category    string
}

// ValidationEngine coordinates validation across the system
type ValidationEngine interface {
    // RegisterValidator adds a new validator to the engine
    RegisterValidator(validator Validator) error
    
    // Validate runs all applicable validators against an object
    Validate(ctx context.Context, obj interface{}) ([]ValidationResult, error)
    
    // GetValidators returns all registered validators
    GetValidators() []Validator
}

// pkg/events/types.go
package events

import (
    "context"
    "time"
    "github.com/yourusername/finlib/pkg/common"
)

// Event represents a system event
type Event struct {
    ID          string
    Type        string
    Source      string
    Time        time.Time
    Data        interface{}
    Metadata    map[string]interface{}
}

// EventHandler processes events of specific types
type EventHandler interface {
    // HandleEvent processes a single event
    HandleEvent(ctx context.Context, event *Event) error
    
    // GetHandledEventTypes returns the event types this handler processes
    GetHandledEventTypes() []string
}

// EventBus manages event distribution
type EventBus interface {
    // PublishEvent sends an event to all registered handlers
    PublishEvent(ctx context.Context, event *Event) error
    
    // Subscribe registers a handler for specific event types
    Subscribe(handler EventHandler) error
    
    // Unsubscribe removes a handler registration
    Unsubscribe(handler EventHandler) error
}

// pkg/plugin/system.go
package plugin

import (
    "context"
    "github.com/yourusername/finlib/pkg/common"
)

// PluginCapability represents a specific capability a plugin can provide
type PluginCapability struct {
    ID          string
    Version     string
    Interface   string
    Config      map[string]interface{}
}

// PluginMetadata contains information about a plugin
type PluginMetadata struct {
    ID              string
    Name            string
    Version         string
    Description     string
    Author          string
    Website         string
    License         string
    Dependencies    []string
    Capabilities    []PluginCapability
}

// PluginLoader handles the loading and initialization of plugins
type PluginLoader interface {
    // LoadPlugin loads a plugin from a given source
    LoadPlugin(ctx context.Context, source string) (*Plugin, error)
    
    // UnloadPlugin safely unloads a plugin
    UnloadPlugin(ctx context.Context, pluginID string) error
    
    // ValidatePlugin checks if a plugin is compatible
    ValidatePlugin(ctx context.Context, metadata *PluginMetadata) error
}

// PluginRegistry manages plugin registration and discovery
type PluginRegistry interface {
    // RegisterPlugin adds a plugin to the registry
    RegisterPlugin(ctx context.Context, plugin *Plugin) error
    
    // GetPlugin retrieves a plugin by ID
    GetPlugin(ctx context.Context, id string) (*Plugin, error)
    
    // FindPluginsByCapability finds plugins that provide specific capabilities
    FindPluginsByCapability(ctx context.Context, capability string) ([]*Plugin, error)
    
    // ListPlugins returns all registered plugins
    ListPlugins(ctx context.Context) ([]*Plugin, error)
}

// PluginLifecycle manages plugin state transitions
type PluginLifecycle interface {
    // Initialize prepares the plugin for use
    Initialize(ctx context.Context) error
    
    // Start begins plugin operation
    Start(ctx context.Context) error
    
    // Stop halts plugin operation
    Stop(ctx context.Context) error
    
    // Cleanup performs any necessary cleanup
    Cleanup(ctx context.Context) error
}

// pkg/transaction/processor.go
package transaction

import (
    "context"
    "time"
    "github.com/shopspring/decimal"
    "github.com/yourusername/finlib/pkg/common"
    "github.com/yourusername/finlib/pkg/validation"
)

// TransactionStatus represents the current state of a transaction
type TransactionStatus string

const (
    Pending     TransactionStatus = "PENDING"
    Posted      TransactionStatus = "POSTED"
    Voided      TransactionStatus = "VOIDED"
    Failed      TransactionStatus = "FAILED"
)

// TransactionType categorizes the transaction
type TransactionType string

const (
    Journal     TransactionType = "JOURNAL"
    Adjustment  TransactionType = "ADJUSTMENT"
    Transfer    TransactionType = "TRANSFER"
    Reversal    TransactionType = "REVERSAL"
)

// BatchProcessingMode defines how transactions are processed
type BatchProcessingMode string

const (
    Atomic     BatchProcessingMode = "ATOMIC"      // All succeed or all fail
    BestEffort BatchProcessingMode = "BEST_EFFORT" // Process as many as possible
)

// TransactionProcessor handles the core transaction processing logic
type TransactionProcessor interface {
    // ProcessTransaction handles a single transaction
    ProcessTransaction(ctx context.Context, tx *Transaction) error
    
    // ProcessTransactionBatch handles multiple transactions
    ProcessTransactionBatch(ctx context.Context, txs []*Transaction, mode BatchProcessingMode) error
    
    // ValidateTransaction performs comprehensive validation
    ValidateTransaction(ctx context.Context, tx *Transaction) ([]validation.ValidationResult, error)
    
    // ReverseTransaction creates and processes a reversal transaction
    ReverseTransaction(ctx context.Context, txID string, reason string) error
}

// TransactionHooks allows plugins to interact with transaction processing
type TransactionHooks interface {
    // BeforeValidation is called before transaction validation
    BeforeValidation(ctx context.Context, tx *Transaction) error
    
    // BeforeProcess is called before transaction processing
    BeforeProcess(ctx context.Context, tx *Transaction) error
    
    // AfterProcess is called after successful processing
    AfterProcess(ctx context.Context, tx *Transaction) error
    
    // OnError is called when an error occurs
    OnError(ctx context.Context, tx *Transaction, err error) error
}

// TransactionReconciliation handles transaction matching and reconciliation
type TransactionReconciliation interface {
    // ReconcileTransactions matches and reconciles transactions
    ReconcileTransactions(ctx context.Context, criteria ReconciliationCriteria) (*ReconciliationResult, error)
    
    // GetUnreconciledTransactions returns transactions pending reconciliation
    GetUnreconciledTransactions(ctx context.Context, accountID string) ([]*Transaction, error)
}

// TransactionIndexer manages transaction indexing for efficient querying
type TransactionIndexer interface {
    // IndexTransaction adds a transaction to the index
    IndexTransaction(ctx context.Context, tx *Transaction) error
    
    // SearchTransactions performs a search based on criteria
    SearchTransactions(ctx context.Context, criteria SearchCriteria) ([]*Transaction, error)
    
    // UpdateIndex updates the index for a modified transaction
    UpdateIndex(ctx context.Context, tx *Transaction) error
}

// Balance represents an account balance at a specific point in time
type Balance struct {
    AccountID       string
    Amount          decimal.Decimal
    Currency        string
    Timestamp       time.Time
    TransactionID   string  // Last transaction that affected this balance
}

// BalanceCalculator handles balance calculations
type BalanceCalculator interface {
    // GetBalance returns the current balance for an account
    GetBalance(ctx context.Context, accountID string) (*Balance, error)
    
    // GetBalanceAsOf returns the balance at a specific point in time
    GetBalanceAsOf(ctx context.Context, accountID string, asOf time.Time) (*Balance, error)
    
    // GetTrialBalance returns a trial balance for all accounts
    GetTrialBalance(ctx context.Context) ([]*Balance, error)
}

// pkg/transaction/types.go
package transaction

import (
    "time"
    "github.com/yourusername/finlib/pkg/common"
    "github.com/shopspring/decimal"
)

// Entry represents a single line item in a transaction
type Entry struct {
    AccountID string
    Amount    decimal.Decimal
    Currency  string
    Notes     string
}

// Transaction represents a financial transaction
type Transaction struct {
    ID            string
    Date          time.Time
    Description   string
    Entries       []Entry
    Status        TransactionStatus
    CreatedBy     string
    Created       time.Time
    LastModified  time.Time
    MetaData      map[string]interface{}
    
    // Plugin developers can extend the transaction structure
    Extensions    map[string]interface{}
}

// TransactionManager defines the interface for transaction operations
type TransactionManager interface {
    // CreateTransaction creates a new transaction
    CreateTransaction(ctx context.Context, tx *Transaction) error
    
    // GetTransaction retrieves a transaction by ID
    GetTransaction(ctx context.Context, id string) (*Transaction, error)
    
    // UpdateTransaction updates a pending transaction
    UpdateTransaction(ctx context.Context, tx *Transaction) error
    
    // PostTransaction finalizes a transaction making it immutable
    PostTransaction(ctx context.Context, id string) error
    
    // VoidTransaction marks a transaction as void
    VoidTransaction(ctx context.Context, id string, reason string) error
}

// pkg/reporting/types.go
package reporting

import (
    "time"
    "github.com/yourusername/finlib/pkg/common"
)

// ReportType defines the type of financial report
type ReportType string

const (
    BalanceSheet    ReportType = "BALANCE_SHEET"
    IncomeStatement ReportType = "INCOME_STATEMENT"
    CashFlow        ReportType = "CASH_FLOW"
    Custom          ReportType = "CUSTOM"
)

// ReportDefinition defines the structure and calculations for a report
type ReportDefinition struct {
    ID          string
    Type        ReportType
    Name        string
    Description string
    Format      string    // e.g., "pdf", "xlsx", "json"
    Template    string    // Template definition (format-specific)
    Parameters  map[string]interface{}
    
    // Plugin developers can extend the report definition
    Extensions  map[string]interface{}
}

// ReportGenerator defines the interface for generating reports
type ReportGenerator interface {
    // GenerateReport creates a report based on the definition and parameters
    GenerateReport(ctx context.Context, def *ReportDefinition, params map[string]interface{}) ([]byte, error)
    
    // ValidateDefinition checks if a report definition is valid
    ValidateDefinition(ctx context.Context, def *ReportDefinition) error
    
    // ListAvailableReports returns all registered report definitions
    ListAvailableReports(ctx context.Context) ([]*ReportDefinition, error)
}

// pkg/plugin/types.go
package plugin

import (
    "github.com/yourusername/finlib/pkg/common"
)

// Plugin represents a registered plugin
type Plugin struct {
    ID          string
    Name        string
    Version     string
    Description string
    Interfaces  []string    // List of implemented interfaces
}

// PluginManager defines the interface for plugin operations
type PluginManager interface {
    // RegisterPlugin registers a new plugin
    RegisterPlugin(ctx context.Context, plugin *Plugin) error
    
    // UnregisterPlugin removes a plugin registration
    UnregisterPlugin(ctx context.Context, id string) error
    
    // GetPlugin retrieves plugin information
    GetPlugin(ctx context.Context, id string) (*Plugin, error)
    
    // ListPlugins returns all registered plugins
    ListPlugins(ctx context.Context) ([]*Plugin, error)
}

// pkg/money/types.go
package money

import (
    "context"
    "time"
    "github.com/shopspring/decimal"
    "github.com/yourusername/finlib/pkg/common"
)

// Money represents a monetary value in a specific currency
type Money struct {
    Amount      decimal.Decimal
    Currency    string
    // Scale represents the number of decimal places for this currency
    Scale       uint8
}

// Currency represents a currency definition in the system
type Currency struct {
    // ISO 4217 code (e.g., "USD", "EUR")
    Code           string
    // Official currency name
    Name           string
    // Number of decimal places typically used
    DefaultScale   uint8
    // Symbol used for display (e.g., "$", "€")
    Symbol         string
    // Whether the symbol appears before the amount
    SymbolPrefix   bool
    // Grouping and decimal separators
    Format         CurrencyFormat
    // Whether this currency is still active
    Active         bool
}

// ExchangeRate represents the rate between two currencies
type ExchangeRate struct {
    BaseCurrency    string
    QuoteCurrency   string
    Rate            decimal.Decimal
    // When this rate becomes effective
    EffectiveFrom   time.Time
    // Optional expiration time
    EffectiveTo     *time.Time
    // Source of this rate (e.g., "ECB", "INTERNAL")
    Source          string
    // Additional rate metadata
    Metadata        map[string]interface{}
}

// MoneyCalculator performs arithmetic operations on monetary values
type MoneyCalculator interface {
    // Add performs addition of monetary values
    Add(a, b Money) (Money, error)
    
    // Subtract performs subtraction of monetary values
    Subtract(a, b Money) (Money, error)
    
    // Multiply multiplies a monetary value by a factor
    Multiply(m Money, factor decimal.Decimal) (Money, error)
    
    // Divide divides a monetary value by a factor
    Divide(m Money, factor decimal.Decimal) (Money, error)
    
    // Round rounds a monetary value according to currency rules
    Round(m Money) (Money, error)
}

// CurrencyConverter handles currency conversion operations
type CurrencyConverter interface {
    // Convert converts an amount between currencies
    Convert(ctx context.Context, amount Money, targetCurrency string) (Money, error)
    
    // ConvertAtDate converts using historical rates
    ConvertAtDate(ctx context.Context, amount Money, targetCurrency string, date time.Time) (Money, error)
    
    // GetExchangeRate retrieves the current exchange rate
    GetExchangeRate(ctx context.Context, baseCurrency, quoteCurrency string) (*ExchangeRate, error)
    
    // GetHistoricalRate retrieves a historical exchange rate
    GetHistoricalRate(ctx context.Context, baseCurrency, quoteCurrency string, date time.Time) (*ExchangeRate, error)
}

// RateProvider supplies exchange rates to the system
type RateProvider interface {
    // GetCurrentRate gets the latest rate for a currency pair
    GetCurrentRate(ctx context.Context, baseCurrency, quoteCurrency string) (*ExchangeRate, error)
    
    // GetHistoricalRates gets historical rates for a period
    GetHistoricalRates(ctx context.Context, baseCurrency, quoteCurrency string, from, to time.Time) ([]*ExchangeRate, error)
    
    // SupportsHistoricalRates indicates whether historical rates are available
    SupportsHistoricalRates() bool
}

// pkg/money/examples.go
package money

// AllocationStrategy determines how to handle remainders
type AllocationStrategy string

const (
    // Allocate remainder to first portion
    FirstRemainderAllocation AllocationStrategy = "FIRST"
    // Allocate remainder to last portion
    LastRemainderAllocation  AllocationStrategy = "LAST"
    // Distribute remainder evenly
    EvenRemainderAllocation  AllocationStrategy = "EVEN"
)

// Allocator handles splitting monetary amounts
type Allocator interface {
    // Split divides a monetary amount into n parts
    Split(amount Money, n int, strategy AllocationStrategy) ([]Money, error)
    
    // Allocate divides a monetary amount by ratios
    Allocate(amount Money, ratios []decimal.Decimal, strategy AllocationStrategy) ([]Money, error)
}

// pkg/security/types.go
package security

import (
    "context"
    "time"
    "github.com/yourusername/finlib/pkg/common"
)

// Principal represents an authenticated entity in the system
type Principal struct {
    ID          string
    Type        PrincipalType
    Attributes  map[string]interface{}
    // When this principal's authentication expires
    ExpiresAt   time.Time
}

// Permission represents a specific operation that can be performed
type Permission struct {
    Resource    string
    Action      string
    Constraints map[string]interface{}
}

// SecurityContext contains security-related information for operations
type SecurityContext struct {
    Principal     *Principal
    Permissions   []Permission
    SecurityLevel SecurityLevel
    // Additional security metadata
    Metadata      map[string]interface{}
}

// AuthenticationProvider handles user authentication
type AuthenticationProvider interface {
    // Authenticate verifies credentials and returns a Principal
    Authenticate(ctx context.Context, credentials interface{}) (*Principal, error)
    
    // ValidatePrincipal checks if a Principal is still valid
    ValidatePrincipal(ctx context.Context, principal *Principal) error
    
    // RefreshAuthentication extends authentication validity
    RefreshAuthentication(ctx context.Context, principal *Principal) error
}

// AuthorizationProvider handles access control
type AuthorizationProvider interface {
    // CheckPermission verifies if an operation is allowed
    CheckPermission(ctx context.Context, principal *Principal, permission Permission) error
    
    // GetPermissions retrieves all permissions for a Principal
    GetPermissions(ctx context.Context, principal *Principal) ([]Permission, error)
    
    // CheckSecurityLevel verifies required security level
    CheckSecurityLevel(ctx context.Context, principal *Principal, requiredLevel SecurityLevel) error
}

// AuditLogger records security-relevant events
type AuditLogger interface {
    // LogSecurityEvent records a security-related event
    LogSecurityEvent(ctx context.Context, event *SecurityEvent) error
    
    // QueryAuditLog retrieves security events
    QueryAuditLog(ctx context.Context, query AuditQuery) ([]*SecurityEvent, error)
    
    // GetAuditTrail gets the complete audit trail for an entity
    GetAuditTrail(ctx context.Context, entityID string) ([]*SecurityEvent, error)
}

// EncryptionService handles data encryption operations
type EncryptionService interface {
    // Encrypt encrypts sensitive data
    Encrypt(ctx context.Context, data []byte, options EncryptionOptions) ([]byte, error)
    
    // Decrypt decrypts encrypted data
    Decrypt(ctx context.Context, encryptedData []byte) ([]byte, error)
    
    // RotateKey performs key rotation
    RotateKey(ctx context.Context, keyID string) error
}

// pkg/security/examples.go
package security

// SecurityLevel indicates the required security level for operations
type SecurityLevel string

const (
    Standard SecurityLevel = "STANDARD"
    High     SecurityLevel = "HIGH"
    Critical SecurityLevel = "CRITICAL"
)

// SecurityEvent represents a security-relevant occurrence
type SecurityEvent struct {
    ID           string
    Time         time.Time
    EventType    string
    PrincipalID  string
    Resource     string
    Action       string
    Result       string
    Details      map[string]interface{}
}

// Example implementing enhanced security for high-value transactions
type TransactionSecurityEnhancer struct {
    authProvider AuthenticationProvider
    auditLogger  AuditLogger
}

func (e *TransactionSecurityEnhancer) EnhanceTransaction(
    ctx context.Context, 
    tx *Transaction,
) error {
    // Get security context
    secCtx := GetSecurityContext(ctx)
    
    // Check transaction amount thresholds
    if tx.Amount.GreaterThan(highValueThreshold) {
        // Require additional authentication
        if err := e.requireAdditionalAuth(ctx, secCtx); err != nil {
            return err
        }
        
        // Log enhanced security event
        e.auditLogger.LogSecurityEvent(ctx, &SecurityEvent{
            EventType: "ENHANCED_SECURITY_APPLIED",
            Details: map[string]interface{}{
                "transactionId": tx.ID,
                "amount": tx.Amount,
                "enhancedMeasures": []string{
                    "additional_authentication",
                    "extended_validation",
                },
            },
        })
    }
    
    return nil
}

// pkg/errors/types.go
package errors

import (
    "context"
    "fmt"
    "time"
    "github.com/yourusername/finlib/pkg/common"
)

// ErrorCategory classifies the type of error
type ErrorCategory string

const (
    // ValidationError indicates invalid input or state
    ValidationError ErrorCategory = "VALIDATION"
    // BusinessError indicates a violation of business rules
    BusinessError ErrorCategory = "BUSINESS"
    // TechnicalError indicates system or infrastructure issues
    TechnicalError ErrorCategory = "TECHNICAL"
    // SecurityError indicates security-related issues
    SecurityError ErrorCategory = "SECURITY"
    // ConcurrencyError indicates timing or locking issues
    ConcurrencyError ErrorCategory = "CONCURRENCY"
)

// ErrorSeverity indicates the impact level of an error
type ErrorSeverity string

const (
    // Info represents informational issues
    Info ErrorSeverity = "INFO"
    // Warning represents potential problems
    Warning ErrorSeverity = "WARNING"
    // Error represents significant issues
    Error ErrorSeverity = "ERROR"
    // Critical represents severe issues requiring immediate attention
    Critical ErrorSeverity = "CRITICAL"
    // Fatal represents unrecoverable errors
    Fatal ErrorSeverity = "FATAL"
)

// FinancialError represents a domain-specific error
type FinancialError struct {
    // Unique error identifier
    ID            string
    // Error code for categorization
    Code          string
    // Human-readable message
    Message       string
    // Detailed error description
    Details       string
    // Error category
    Category      ErrorCategory
    // Error severity
    Severity      ErrorSeverity
    // Time the error occurred
    Timestamp     time.Time
    // Component where the error originated
    Source        string
    // Related entity IDs
    RelatedIDs    []string
    // Whether the operation can be retried
    Retryable     bool
    // Suggested resolution steps
    Resolution    string
    // Additional error context
    Context       map[string]interface{}
    // Original error if wrapped
    Cause         error
}

// Implement error interface
func (e *FinancialError) Error() string {
    return fmt.Sprintf("[%s-%s] %s: %s", e.Category, e.Code, e.Message, e.Details)
}

// ErrorHandler manages error processing and resolution
type ErrorHandler interface {
    // HandleError processes an error and determines appropriate action
    HandleError(ctx context.Context, err error) error
    
    // RecordError logs error details for analysis
    RecordError(ctx context.Context, err error) error
    
    // GetErrorResolution provides resolution steps for an error
    GetErrorResolution(ctx context.Context, err error) (*ErrorResolution, error)
}

// RetryManager handles retry operations for failed operations
type RetryManager interface {
    // ShouldRetry determines if an operation should be retried
    ShouldRetry(ctx context.Context, err error) bool
    
    // GetRetryDelay determines the delay before next retry
    GetRetryDelay(ctx context.Context, attempt int) time.Duration
    
    // GetMaxRetries returns the maximum number of retry attempts
    GetMaxRetries(ctx context.Context, err error) int
}

// CircuitBreaker prevents cascading failures
type CircuitBreaker interface {
    // AllowOperation checks if an operation should proceed
    AllowOperation(ctx context.Context, operationType string) error
    
    // RecordSuccess records a successful operation
    RecordSuccess(ctx context.Context, operationType string)
    
    // RecordFailure records a failed operation
    RecordFailure(ctx context.Context, operationType string, err error)
    
    // GetCircuitStatus returns the current circuit breaker status
    GetCircuitStatus(ctx context.Context, operationType string) (*CircuitStatus, error)
}

// pkg/dal/types.go
package dal

import (
    "context"
    "time"
    "github.com/yourusername/finlib/pkg/common"
)

// Entity represents a base type for all persistent objects
type Entity struct {
    ID            string
    Version       uint64
    Created       time.Time
    LastModified  time.Time
    CreatedBy     string
    ModifiedBy    string
    // Optimistic locking token
    Etag          string
    // Soft deletion support
    Deleted       bool
    DeletedAt     *time.Time
    // Audit and tracking
    ChangeHistory []EntityChange
}

// Repository provides generic data access operations
type Repository[T any] interface {
    // Create inserts a new entity
    Create(ctx context.Context, entity *T) error
    
    // Get retrieves an entity by ID
    Get(ctx context.Context, id string) (*T, error)
    
    // Update modifies an existing entity
    Update(ctx context.Context, entity *T) error
    
    // Delete marks an entity as deleted
    Delete(ctx context.Context, id string) error
    
    // List retrieves entities based on criteria
    List(ctx context.Context, criteria QueryCriteria) ([]*T, error)
    
    // GetVersion retrieves a specific version of an entity
    GetVersion(ctx context.Context, id string, version uint64) (*T, error)
}

// UnitOfWork manages transactional boundaries
type UnitOfWork interface {
    // Begin starts a new transaction
    Begin(ctx context.Context) (Transaction, error)
    
    // GetRepository returns a repository for the given entity type
    GetRepository(entityType string) (interface{}, error)
}

// Transaction represents a database transaction
type Transaction interface {
    // Commit persists all changes
    Commit(ctx context.Context) error
    
    // Rollback discards all changes
    Rollback(ctx context.Context) error
    
    // IsActive checks if the transaction is still active
    IsActive() bool
}

// QueryBuilder constructs type-safe queries
type QueryBuilder[T any] interface {
    // Where adds filtering conditions
    Where(condition string, args ...interface{}) QueryBuilder[T]
    
    // OrderBy adds sorting criteria
    OrderBy(field string, ascending bool) QueryBuilder[T]
    
    // Limit sets the maximum number of results
    Limit(limit int64) QueryBuilder[T]
    
    // Offset sets the starting position
    Offset(offset int64) QueryBuilder[T]
    
    // Execute runs the query and returns results
    Execute(ctx context.Context) ([]*T, error)
    
    // Count returns the total number of matching records
    Count(ctx context.Context) (int64, error)
}

// pkg/config/types.go
package config

import (
    "context"
    "time"
    "github.com/yourusername/finlib/pkg/common"
)

// ConfigurationValue represents a single configuration setting
type ConfigurationValue struct {
    // Unique identifier for this configuration
    Key         string
    // The configuration value
    Value       interface{}
    // Data type of the value
    ValueType   string
    // Whether this config can be changed at runtime
    Dynamic     bool
    // Validation rules for this config
    Validation  string
    // Environment this config applies to
    Environment string
    // When this value becomes effective
    EffectiveAt time.Time
    // Optional expiration time
    ExpiresAt   *time.Time
    // Audit information
    CreatedBy   string
    CreatedAt   time.Time
    UpdatedBy   string
    UpdatedAt   time.Time
}

// ConfigurationManager handles configuration operations
type ConfigurationManager interface {
    // GetValue retrieves a configuration value
    GetValue(ctx context.Context, key string) (*ConfigurationValue, error)
    
    // SetValue updates a configuration value
    SetValue(ctx context.Context, value *ConfigurationValue) error
    
    // DeleteValue removes a configuration value
    DeleteValue(ctx context.Context, key string) error
    
    // GetEnvironmentConfig gets all config for an environment
    GetEnvironmentConfig(ctx context.Context, env string) (map[string]*ConfigurationValue, error)
    
    // ValidateConfiguration checks configuration validity
    ValidateConfiguration(ctx context.Context) ([]ValidationResult, error)
}

// ConfigurationProvider supplies configuration values
type ConfigurationProvider interface {
    // GetConfiguration loads configuration values
    GetConfiguration(ctx context.Context) (map[string]*ConfigurationValue, error)
    
    // RefreshConfiguration reloads configuration values
    RefreshConfiguration(ctx context.Context) error
    
    // SupportsHotReload indicates if provider supports runtime updates
    SupportsHotReload() bool
}

// ConfigurationSubscriber receives configuration updates
type ConfigurationSubscriber interface {
    // OnConfigurationChanged is called when config changes
    OnConfigurationChanged(ctx context.Context, changes map[string]*ConfigurationValue) error
    
    // GetSubscribedKeys returns keys this subscriber cares about
    GetSubscribedKeys() []string
}

// pkg/config/features.go
package config

// FeatureFlag represents a toggleable system feature
type FeatureFlag struct {
    // Feature identifier
    Key         string
    // Whether the feature is enabled
    Enabled     bool
    // Feature configuration
    Config      map[string]interface{}
    // Targeting rules for feature activation
    Rules       []FeatureRule
    // Rollout configuration
    Rollout     RolloutConfig
}

// FeatureManager handles feature flag operations
type FeatureManager interface {
    // IsFeatureEnabled checks if a feature is enabled
    IsFeatureEnabled(ctx context.Context, key string) bool
    
    // GetFeatureConfig gets feature configuration
    GetFeatureConfig(ctx context.Context, key string) (map[string]interface{}, error)
    
    // UpdateFeature modifies feature settings
    UpdateFeature(ctx context.Context, feature *FeatureFlag) error
    
    // GetFeatureList returns all feature flags
    GetFeatureList(ctx context.Context) ([]*FeatureFlag, error)
}

// RolloutConfig controls feature deployment
type RolloutConfig struct {
    // Percentage of users to enable for
    Percentage  float64
    // Start time of rollout
    StartTime   time.Time
    // End time of rollout
    EndTime     time.Time
    // Rollout strategy
    Strategy    string
}

// pkg/config/environment.go
package config

// Environment represents a deployment environment
type Environment struct {
    // Environment identifier
    Name        string
    // Environment type (e.g., Production, Staging)
    Type        string
    // Environment-specific settings
    Settings    map[string]*ConfigurationValue
    // Security level required
    SecurityLevel string
    // Active feature flags
    Features    []string
}

// EnvironmentManager handles environment operations
type EnvironmentManager interface {
    // GetEnvironment retrieves environment configuration
    GetEnvironment(ctx context.Context, name string) (*Environment, error)
    
    // UpdateEnvironment modifies environment settings
    UpdateEnvironment(ctx context.Context, env *Environment) error
    
    // ValidateEnvironment checks environment configuration
    ValidateEnvironment(ctx context.Context, name string) ([]ValidationResult, error)
}

// pkg/config/plugins.go
package config

// PluginConfig represents plugin configuration
type PluginConfig struct {
    // Plugin identifier
    PluginID    string
    // Plugin version
    Version     string
    // Plugin settings
    Settings    map[string]*ConfigurationValue
    // Dependencies
    Dependencies []PluginDependency
    // Resource limits
    Resources   ResourceLimits
}

// PluginConfigManager handles plugin configuration
type PluginConfigManager interface {
    // GetPluginConfig retrieves plugin configuration
    GetPluginConfig(ctx context.Context, pluginID string) (*PluginConfig, error)
    
    // UpdatePluginConfig modifies plugin settings
    UpdatePluginConfig(ctx context.Context, config *PluginConfig) error
    
    // ValidatePluginConfig checks plugin configuration
    ValidatePluginConfig(ctx context.Context, config *PluginConfig) error
}

// pkg/config/changes.go
package config

// ConfigurationChange represents a configuration modification
type ConfigurationChange struct {
    // Change identifier
    ID          string
    // Configuration key
    Key         string
    // Previous value
    OldValue    interface{}
    // New value
    NewValue    interface{}
    // Change requester
    RequestedBy string
    // Change approver
    ApprovedBy  string
    // Change timestamp
    Timestamp   time.Time
    // Change reason
    Reason      string
}

// ChangeManager handles configuration changes
type ChangeManager interface {
    // RequestChange initiates a configuration change
    RequestChange(ctx context.Context, change *ConfigurationChange) error
    
    // ApproveChange approves a configuration change
    ApproveChange(ctx context.Context, changeID string, approver string) error
    
    // RevertChange reverts a configuration change
    RevertChange(ctx context.Context, changeID string) error
}

// pkg/versioning/types.go
package versioning

// VersionInfo contains system version information
type VersionInfo struct {
    // Semantic version of the system
    Version     string
    // Minimum supported plugin API version
    MinAPIVersion string
    // Maximum supported plugin API version
    MaxAPIVersion string
    // Required database schema version
    SchemaVersion string
    // Build information
    BuildInfo    BuildInfo
}

// CompatibilityChecker validates system compatibility
type CompatibilityChecker interface {
    // CheckPluginCompatibility verifies plugin compatibility
    CheckPluginCompatibility(ctx context.Context, pluginInfo PluginInfo) error
    
    // CheckSchemaCompatibility verifies database schema compatibility
    CheckSchemaCompatibility(ctx context.Context) error
    
    // GetCompatibilityMatrix returns compatibility information
    GetCompatibilityMatrix(ctx context.Context) (*CompatibilityMatrix, error)
}

// pkg/transaction/processor_test.go
package transaction_test

import (
    "testing"
    "context"
    "github.com/stretchr/testify/assert"
    "github.com/yourusername/finlib/pkg/transaction"
)

func TestTransactionProcessor(t *testing.T) {
    // Example test structure for transaction processing
    tests := []struct {
        name          string
        transaction   *transaction.Transaction
        expectedErr   error
        setupFunc     func(context.Context) error
        cleanupFunc   func(context.Context) error
    }{
        // Test cases here
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Test implementation
        })
    }
}

// pkg/transaction/benchmark_test.go
package transaction_test

import (
    "testing"
    "context"
    "github.com/yourusername/finlib/pkg/transaction"
)

func BenchmarkTransactionProcessing(b *testing.B) {
    // Benchmark setup
    ctx := context.Background()
    processor := setupTestProcessor()
    
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        tx := generateTestTransaction()
        err := processor.ProcessTransaction(ctx, tx)
        if err != nil {
            b.Fatal(err)
        }
    }
}