2.2 CountryPlugin Interface

The— CountryPluginFull interfaceContract is writtenWritten to `apps/api/src/main/kotlin/no/alai/bilko/country/CountryPlugin.kt:

**Interface invariant:** Zero `if jurisdiction ==` branches in core services
(`services/`, `routes/`). All market differences are absorbed here.

```kotlin
package no.alai.bilko.country

import no.alai.bilko.einvoice.CanonicalInvoice
import no.alai.bilko.einvoice.EInvoiceAdapter
import java.util.Currency

/**
 * Per-jurisdiction plugin — the single extension point for all market-specific behaviour.
 *
 * INVARIANT: ZeroNo `if jurisdiction == X` or `when(jurisdiction)` branches in
 core* services.apps/api/src/main/kotlin/no/alai/bilko/{services,routes}/.
 * All market
 * differences are absorbed here. (ADR-bilko-002 Variant C / ADR-bilko-003 3-layer model)C)
 *
 * ImplementationsImplementations:
 *   PluginHR      → country/hr/PluginHR.kt          (Phase 1H — priority):
 *   - PluginHR  → apps/api/src/main/kotlin/no/alai/bilko/country/hr/PluginHR.kt
 *   -   PluginRS      → stubcountry/rs/PluginRS.kt           (stub, Phase 1S)
 *   - PluginBAFED   → stubcountry/ba/PluginBAFED.kt        (stub, Phase 1B)
 *   - PluginBARS    → stubcountry/ba/PluginBARS.kt         (stub, Phase 1B)
 *
 * DIDI: wiring: Ktor `plugins/DI.kt`kt registers all implementations4 andin selectsa Map<TaxJurisdiction, CountryPlugin>.
 * basedResolution: onorgId `org.country`from JWT claim→ DB lookup organizations.country → TaxJurisdiction.valueOf()
 * → PluginRegistry.resolve() (see ADR-023015 §3.3)2.4 for full pipeline).
 */
interface CountryPlugin {

    /**
     * Returns the tax jurisdiction this plugin handles.
     * Used by PluginRegistry to route. Must be consistent with the plugin's
     * registration key in the DI registry to route to the correct plugin.map.
     */
    fun jurisdiction(): TaxJurisdiction

    /**
     * Calculates VAT breakdown for the given canonical invoice.
     *
     * Returns a [VatResult] containing itemised tax lines per rate band.
     * Core invoice service calls this; NEVER inspects jurisdiction directly.
     *
     * HR example:HR: 25% (S — standard), 13% (AA — reduced-1), 5% (E — reduced-2), 0% (Z — zero/export)
     * RS example:RS: 20% (standard), 10% (reduced), 0% (export)
     * BA-FED/FED / BA-RS: 17% (standard), 0% (export)
     *
     * @throws UnsupportedOperationException for stub implementations (RS, BA)
     */
    fun calculateVat(invoice: CanonicalInvoice): VatResult

    /**
     * Generates jurisdiction-specific e-invoice XML/bytes from the canonical model.
     *
     * Delegates to the platform-specific [EInvoiceAdapter]EInvoiceAdapter.serialize()] for this jurisdiction.
     * Returns the wire-format payload (UBL 2.1 XML wrappedStorecove inenvelope platformfor envelope)HR; SEF XML for RS).
     * Contract: OFFLINE — no network, no credentials required.
     *
     * HR:@throws delegatesUnsupportedOperationException to StorecoveHrFiskEInvoiceAdapter.serialize() (WORKS offline)
     * RS: SEF XML serializer (Phase 1S)
     * BA: CPF/UINOfor stub (Phase 1B)implementations
     */
    fun generateEInvoiceXml(invoice: CanonicalInvoice): ByteArray

    /**
     * Submits a previously serialized e-invoice to the fiscal platform.
     *
     * [receipt] containsbundles the serialized bytes from [generateEInvoiceXml] plus
     *with the originating
     * [CanonicalInvoice] for idempotency key generation.
     * * Returns a [FiscalSubmissionHandle] with platform-assignedthe platform submission ID.
     * Throws [no.alai.bilko.adapter.AdapterException] on all failure modes — NEVER platform-native exceptions.modes.
     *
     * HR lifecycle: STUB until MC #8675 (Storecove account activation).
     */
    fun submitToFiscalPlatform(receipt: FiscalReceipt): FiscalSubmissionHandle

    /**
     * Returns the default Chart of Accounts entries for this jurisdiction.
     *
     * Called once on org creation (onboarding wizard) to seed the tenant's * account list with the
     * mandatory Pravilnik accounts. Company may thenadd *or add/rename accounts — these are minimums.
     *
     * HR: FINA Kontni Plan (11-year retention required)retention)
     * RS: Serbian Pravilnik (10-year retention)
     * BA: FBiH/FBiH / RS entity Pravilnik (10-year retention)
     */
    fun getChartOfAccountsDefaults(): List<ChartOfAccountEntry>

    /**
     * Returns filing deadline schedule for this jurisdiction.
     *
     * Returns a sorted list of [FilingDeadline] for the next 12 months from the call date.
     * Used by ComplianceCalendarService to populate per-org reminder schedules.
     *
     * HR: quarterly PDV return (last working day of month after quarter end) *     + annual CIT (30 April), via ePorezna
     * RS: monthly PDV return (within 15 days of month end), via ePorezi
     * BA: FBiH/FBiH / RS entity PDV return schedules
     *
     * Returns a sorted list of [FilingDeadline] for the next 12 months from
     * the call date. Consumers display these as compliance calendar reminders.
     */
    fun getFilingDeadlines(): List<FilingDeadline>

    /**
     * Returns data retention policy for this jurisdiction.
     *
     * HR: 11 years (— Zakon o računovodstvu NN 78/2015, čl. 10)10
     * RS: 10 years (— Zakon o računovodstvu RS)RS
     * BA:BA-FED / BA-RS: 10 years
     (FBiH) / 10 years (RS entity)
     *
     * The [RetentionPolicy] is usedUsed by the document archiving service (ADR-022)
     * to set per-org retention periods and by
     * the RLS audit partition (ADR-017 Phase 2B).
     */
    fun getRetentionRules(): RetentionPolicy

    /**
     * Returns the functional currency for this jurisdiction.
     *
     * HR: Currency.getInstance("EUR")  — Croatia adopted EUR 2023-01-01
     * RS: Currency.getInstance("RSD")
     * BA-FED / BA-RS: Currency.getInstance("BAM")
     *
     * Core invoice service usesvalidates CanonicalInvoice.currencyCode against this to validate `CanonicalInvoice.currencyCode`
     * against the org's jurisdiction on invoice creation.
     */
    fun getCurrency(): Currency

    /**
     * Returns locale-specific formatters for this jurisdiction.
     *
     * HR: decimal='.', thousands=',', date='dd.MM.yyyy', time zone=tz='Europe/Zagreb'
     * RS: decimal=',', thousands='.', date='dd.MM.yyyy', time zone=tz='Europe/Belgrade'
     * BA: decimal=',', thousands='.', date='dd.MM.yyyy', time zone=tz='Europe/Sarajevo'
     *
     * Used by report generation, PDF invoices, and UI date/number display.
     */
    fun getFormatters(): JurisdictionFormatters

    /**
     * Extension hook for jurisdiction-specific validation beyond the standard 8 methods.
     *
     * Called by InvoiceService before invoice creation. Default implementation is a no-op;
     * override to add market-specific business rules (e.g., HR OIB cross-validation
     * against FINA company registry once APRCompanyRegistryAdapter is live).
     *
     * This hook is the designated extension point to avoid adding new required interface
     * methods for market-specific edge cases. See §3.2 for evolution contract.
     *
     * @param invoice draft canonical invoice before persistence
     * @throws no.alai.bilko.adapter.AdapterException with VALIDATION_BUSINESS_RULE if invalid
     */
    fun validateInvoiceForJurisdiction(invoice: CanonicalInvoice) {
        // Default: no-op. Override in PluginHR, PluginRS etc. as needed.
    }

``` ### 2.3 Supporting Value Types

These types are defined alongside CountryPluginDefined in the `no.alai.bilko.countrycountry` package (or in a sub-package `no.alai.bilko.country.modelmodel`):

```kotlin
// VAT calculation result
data class VatResult(
    val lines: List<VatLine>,
    val totalVatAmount: java.math.BigDecimal,
    val totalTaxableAmount: java.math.BigDecimal,
)

data class VatLine(
    val rate: java.math.BigDecimal,          // e.g. BigDecimal("25.00000000")
    val category: no.alai.bilko.einvoice.TaxCategory,
    val taxableAmount: java.math.BigDecimal,
    val taxAmount: java.math.BigDecimal,
    val description: String,                 // Human-readablereadable, fore.g. audit"HR trailstandard PDV 25%"
)

// Fiscal submission input — bundles serialize() output with canonical invoice
data class FiscalReceipt(
    val serializedInvoice: ByteArray,
    val canonicalInvoice: no.alai.bilko.einvoice.CanonicalInvoice,
)

data class FiscalSubmissionHandle(
    val platformInvoiceId: String,           // Storecove GUID, SEF ID, etc.
    val initialStatus: no.alai.bilko.einvoice.EInvoiceStatus,
    val submittedAt: java.time.Instant,
)

// Chart of Accounts entry
data class ChartOfAccountEntry(
    val code: String,                        // e.g. "1300" (HR) or "204" (RS)
    val name: String,
    val type: AccountType,                   // ASSET, LIABILITY, EQUITY, INCOME, EXPENSE
    val vatTreatment: String?,
)

// Filing deadlinesdeadline
data class FilingDeadline(
    val name: String,                        // e.g. "Quarterly PDV return Q1 2026"
    val dueDate: java.time.LocalDate,
    val authority: String,                   // e.g. "Porezna uprava HR (ePorezna)"
    val periodStart: java.time.LocalDate,
    val periodEnd: java.time.LocalDate,
)

// Data retention
data class RetentionPolicy(
    val years: Int,                          // 10 or 11 depending on jurisdiction
    val legalBasis: String,                  // Statutory reference
    val jurisdiction: TaxJurisdiction,
)

// Formatters
data class JurisdictionFormatters(
    val decimalSeparator: Char,
    val thousandsSeparator: Char,
    val datePattern: String,                 // ISO strftime-compatiblecompatible, e.g. "dd.MM.yyyy"
    val timeZoneId: String,                  // IANA tztz, e.g. "Europe/Zagreb"
    val currencySymbol: String,
    val currencyPosition: CurrencyPosition,  // PREFIX or SUFFIX
)

enum class CurrencyPosition { PREFIX, SUFFIX }

### 2.4 DI RegistrationWiring Pattern

**JWT reality:** The KtorJWT DIaccess moduletoken contains `orgId` only (apps/api/src/main/kotlin/no/alai/bilko/plugins/DI.kt)verified registersin plugins`JwtService.kt` keyedlines 35–45). The `org.country` value is NOT embedded in the JWT. It is fetched from the `organizations` DB table at request time by TaxJurisdictionmiddleware before the route handler runs. **Resolution pipeline:** ``` HTTP request → JWT validation (JwtService.verifyAccessToken) → extract orgId from JWT claim "orgId" → DB: SELECT country FROM organizations WHERE id = orgId (OrgScopePlugin / middleware) → TaxJurisdiction.valueOf(country) → PluginRegistry.resolve(jurisdiction) → CountryPlugin dispatch ``` **DI registration in `plugins/DI.kt`:

```kotlin
// DI.kt — CountryPlugin registry (Phase 1H Task 1H.4)4
val plugins:pluginRegistry: Map<TaxJurisdiction, CountryPlugin> = mapOf(
    TaxJurisdiction.HR     to PluginHR(StorecoveHrFiskEInvoiceAdapter()),
    TaxJurisdiction.RS     to PluginRS(),      // stub — Phase 1S
    TaxJurisdiction.BA_FED to PluginBAFED(),   // stub — Phase 1B
    TaxJurisdiction.BA_RS  to PluginBARS(),    // stub — Phase 1B
)

// In Koin module:
single<Map<TaxJurisdiction, CountryPlugin>> { pluginRegistry }

// Resolution —helper called(usable from any serviceKoin-injected handler with org context:service):
fun resolvePlugin(
    jurisdiction: TaxJurisdiction)TaxJurisdiction,
    registry: Map<TaxJurisdiction, CountryPlugin>
): CountryPlugin = plugins[registry[jurisdiction]
    ?: throw IllegalStateException(
        "No CountryPlugin registered for $jurisdiction — check DI.kt"kt registration"
    )

**Services that need a `CountryPlugin` receive it via constructor injection:** ```kotlin class InvoiceService( private val pluginRegistry: Map<TaxJurisdiction, CountryPlugin> // ... other deps ) { private fun plugin(org: Organization): CountryPlugin = resolvePlugin(TaxJurisdiction.valueOf(org.country), pluginRegistry) } ``` ### 2.5 OrgScopePlugin Sequencing Decision **Decision: CountryPlugin resolution runs AFTER OrgScopePlugin (org isolation middleware).** Rationale: 1. **Security gate must run first.** OrgScopePlugin validates that the authenticated user belongs to the org being operated on and sets the `app.current_org_id` Postgres session variable for RLS PERMISSIVE enforcement (Phase 2A). This is a security boundary; no business logic should execute before it. 2. **CountryPlugin requires an authenticated, org-scoped context.** Resolving a `CountryPlugin` requires reading `organizations.country` from DB, which in turn requires a verified `orgId`. OrgScopePlugin is what establishes and validates that `orgId`. 3. **Failure mode is clean.** If OrgScopePlugin fails (user not in org, org not found), the request is rejected with 403 before CountryPlugin resolution is attempted. No country-specific logic runs on unauthenticated requests. **Execution order in the Ktor pipeline:** ``` 1. Authentication plugin (JWT validation) 2. OrgScopePlugin: a. Validate user.org_id matches the resource being accessed b. SET app.current_org_id = :orgId (for RLS) c. Fetch org record → populate OrgContext (includes org.country) 3. CountryPlugin resolution: a. TaxJurisdiction.valueOf(orgContext.country) b. resolvePlugin(jurisdiction) → inject into route handler 4. Route handler executes with both OrgContext and CountryPlugin available ``` **Parisa Tabriz (Securion) note:** OrgScopePlugin must complete step 2b before any CountryPlugin method is called. This ensures the RLS session variable is set before any DB query inside the plugin executes. Violating this order creates a window where a CountryPlugin DB query runs without the RLS filter active. ### 2.6 TypeScript Packages — Separate Concern The JWTfive principalTypeScript carries org.countrypackages ('HR'`packages/domain-rs`, |`packages/domain-hr`, 'RS'`packages/domain-ba`, |`packages/domain-ba-fed`, 'BA_FED'`packages/domain-ba-rs`) |contain 'BA_RS')frontend domain types compiled to `dist/`. They are **not loaded by the Kotlin runtime** and are **not in scope for this ADR**. The routing`TaxJurisdiction` pipeline:

HTTPvalues requestmust →remain JWTconsistent validationbetween →the extractKotlin org.countryenum →and TaxJurisdiction.valueOf(org.country)any
→TypeScript resolvePlugin() → CountryPlugin dispatch

This replaces all when(organization.country) branchesenums in servicethese code.

string values: `"HR"`, `"RS"`, `"BA_FED"`, `"BA_RS"`). That alignment is enforced at the API boundary (JWT claim and REST API JSON) — not via a shared runtime dependency. Backwards compatibility rule: if `TaxJurisdiction` gains a new value (e.g., `SI` for Slovenia), the corresponding TypeScript packages must be updated in the same PR. This is a documentation constraint, not a compile-time enforcement. --- ## 3. Enforcement

### 3.1 Linting Rule

A custom ktlint or Detekt rule must reject any file in `apps/api/src/main/kotlin/no/alai/bilko/core/ (or services/, routes/){services,routes}/` that contains thepatterns: string- `if.*jurisdictionjurisdiction` or- `when.*jurisdictionjurisdiction` or- `if.*country ==` patterns.- `when.*country` This enforces the invariant from ADR-bilko-002 §conclusion.

The linting rule is a Phase 1H gateCI —gate. itIt runs in CI before any Phase 1H code merges.

to main. The rule is not applied to `country/` package itself (plugin implementations may internally branch on jurisdiction during their own construction if absolutely necessary). ### 3.2 Interface Evolution Contract

When a new method must be added to CountryPlugin`CountryPlugin`:

1.
1. Add**Prefer the extension hook** (`validateInvoiceForJurisdiction`) for market-specific validation that does not generalise across all markets. 2. If a new method is genuinely cross-market: add it with a default implementationbody that throws `UnsupportedOperationException("Not implemented for $jurisdiction — opensee MC"MC #XXXX")`.
2. 3. Override in PluginHR`PluginHR` (priority market) first.
first;
3. Otherother implementationsplugins follow in their marketphase. phase.
4.
4. Default throws are acceptable until the market phase begins — they surface as clear runtime errors, not silent wrong behaviour.

This## pattern is specified in ADR-bilko-002 §consequences (line 145–146).

4. Implementation Path

5. Consequences

### 5.1 Positive

-
• **Fifth market = one new plugin.file.** Adding Slovenia (SI) requires creating`PluginSI.kt`, one fileDI (PluginSI.kt), registering it in DI,registration, and adding`SI` SIadded to TaxJurisdiction`TaxJurisdiction`. Zero changes to core services.
service
• changes. - **Bounded audit surface.** Croatian tax authority reviewing PDV complianceauditors readsread `country/hr/PluginHR.ktkt` only. No- RS or BA logic mixed in.
• **Team parallelism.** HR sprint and RS sprint can work concurrently on their plugin implementations without merge conflicts (separate files,files. separate- packages).
• Historical correctness via versioned**Versioned CoA.** `getChartOfAccountsDefaults()` seeds Pravilnik data; rate changes are handled via the versioned chart_of_accounts`chart_of_accounts` table (ADR-017 §2.44). /### ADR-bilko-003 §Layer 3).