Navka.Contracts 1.1.6

Navka.Contracts

Version: 1.0.0 Stability: Stable - Never Breaking

📋 Overview

Navka.Contracts is the foundational contract layer for the Navka Platform plugin ecosystem. This package contains only interfaces and DTOs with zero implementations, providing a stable, dependency-free API surface for module development.

Purpose

• ✅ Stable plugin contracts - Modules depend on this, not on heavy implementations
• ✅ Zero rebuild coupling - Change implementations without rebuilding modules
• ✅ Backward compatibility - v1.0.0 contracts never break (new versions can add, never remove)
• ✅ Third-party plugin support - External developers can build modules against stable APIs

🎯 What's Inside

Core Interfaces

• ITenantContext - Multi-tenancy context (read-only access to tenant/user info)
• INavkaModule - Plugin/module contract (lifecycle, metadata, health checks)

Service Abstractions

• IAIService - AI and LLM operations
• IBillingService - Payment and subscription processing
• IMessagingService - Multi-channel messaging (email, SMS, push)
• IMakerService - 3D printing and makerspace operations
• ISocialService - Social media integration
• ILoyaltyService - Loyalty program management
• IInventoryService - Inventory and stock management

DTOs

• UserDto - User information transfer object
• TenantDto - Tenant information transfer object
• ResponseDto<T> - Standard API response wrapper

🚀 Usage

In Your Module

using Navka.Contracts;
using Navka.Contracts.Services;

public class MyCustomModule : INavkaModule
{
    public string ModuleName => "my-custom-module";
    public string Version => "1.0.0";
    public IEnumerable<string> SupportedApiVersions => new[] { "1.0" };

    public Task OnLoadAsync(IServiceProvider services)
    {
        // Register your services
        // Access IAIService, IBillingService, etc. from DI
        return Task.CompletedTask;
    }

    public Task<ModuleHealthStatus> CheckHealthAsync()
    {
        // Health check logic
        return Task.FromResult(ModuleHealthStatus.Healthy);
    }
}

In Your Controller/Service

public class MyController : ControllerBase
{
    private readonly ITenantContext _tenantContext;
    private readonly IAIService _aiService;

    public MyController(ITenantContext tenantContext, IAIService aiService)
    {
        _tenantContext = tenantContext;
        _aiService = aiService;
    }

    [HttpGet]
    public async Task<IActionResult> GetData()
    {
        // Multi-tenancy is automatic
        var tenantId = _tenantContext.TenantId;
        var userId = _tenantContext.UserId;

        // Use AI service (implementation injected by host)
        var response = await _aiService.CompleteChatAsync(new ChatRequest
        {
            Messages = new[] { new ChatMessage { Role = "user", Content = "Hello" } }
        });

        return Ok(response);
    }
}

📦 Installation

dotnet add package Navka.Contracts --version 1.0.0

Or in your .csproj:

<PackageReference Include="Navka.Contracts" Version="1.0.0" />

🔒 Stability Promise

What's Guaranteed

✅ Interface stability - Existing members never removed or changed ✅ Backward compatibility - v1.x modules work with future v1.y runtime ✅ Semantic versioning - Breaking changes = major version bump ✅ Long-term support - v1.0.0 supported indefinitely

Version Policy

• v1.0.x - Bug fixes only (no breaking changes)
• v1.x.0 - New interfaces/methods (additive, backward compatible)
• v2.0.0 - Breaking changes (rare, with migration guide)

What Can Change

✅ Adding new interfaces (backward compatible) ✅ Adding new optional members with defaults (backward compatible) ✅ Adding new DTOs (backward compatible) ❌ Removing interfaces (NEVER) ❌ Removing members (NEVER) ❌ Changing signatures (NEVER)

🏗️ Architecture

┌─────────────────────────────────────┐
│     Navka.Contracts (v1.0.0)        │  ← Thin, stable, rarely changes
│  Interfaces Only, Zero Dependencies │
└──────────┬──────────────────────────┘
           │
    ┌──────┴───────────────┐
    │                      │
┌───▼───────────┐   ┌─────▼──────────┐
│   Modules     │   │  Navka.Runtime │  ← Can change frequently
│  (Products)   │   │ (Implementations)
└───────────────┘   └────────────────┘

Benefits:

• Modules depend on contracts (stable)
• Runtime provides implementations (can evolve)
• Zero rebuild coupling (change runtime, modules unaffected)

📚 Documentation

• Full API Reference: /docs/reference/INAVKAMODULE_INTERFACE.md
• Plugin Development Guide: /docs/setup/MODULE_DEVELOPMENT_GUIDE.md
• Backward Compatibility Policy: /docs/reference/BACKWARD_COMPATIBILITY.md

🛠️ Development

Building

dotnet build Navka.Contracts.csproj

Packaging

dotnet pack Navka.Contracts.csproj -c Release -o ./nupkg

Publishing

dotnet nuget push ./nupkg/Navka.Contracts.1.0.0.nupkg \
  --source "https://pkgs.dev.azure.com/navka/_packaging/navka-platform/nuget/v3/index.json" \
  --api-key $AZURE_ARTIFACTS_PAT

⚠️ Important Notes

1. This package has ZERO dependencies - Keep it that way!
2. Never add implementation code - Interfaces and DTOs only
3. Document breaking changes - Use [Obsolete] attribute before removing
4. Version carefully - Breaking changes require major version bump

📝 License

Proprietary - See LICENSE file for details

🤝 Contributing

This is a critical stability package. Changes require:

1. Architecture review
2. Backward compatibility analysis
3. Multi-service impact assessment
4. Approval from platform team

Pull Requests: Create PR against main with detailed description of changes and compatibility impact.

Questions? Contact the platform team or see /docs/planning/PLUGIN_ECOSYSTEM_IMPLEMENTATION_ROADMAP.md