Skip to main content

ADR-019: Market Priority HR-First

ADR-019 — Market Priority: HR-First Ratification

Status: Accepted — CEO override 2026-05-09 ratified as architectural decision Date: 2026-05-13 Author: Petter Graff (CodeCraft, Architecture Lead) Decision-maker: CEO Alem Bašić — override issued 2026-05-09 ("B i onda dokumentuj Opcija C — ali prvo ide Hrvatska ne srbija") MC Task: #100586 (Phase 0' ADR-017 RLS strategy + ADR-019 market priority) Cross-references:

  • ADR-023 §6 CEO override 2026-05-09 ("market priority is HR → BA → SR")
  • ADR-015-FOUR-JURISDICTION-PLUGIN.md (TaxJurisdiction enum: HR, RS, BA_FED, BA_RS)
  • ADR-016-EINVOICE-ADAPTER.md (HR Storecove Peppol path = Path B, signed 2026-04-24)
  • ADR-019-INTEGRATION-ADAPTER-REGISTRY.md (adapter lifecycle + HR EINVOICE = first to SANDBOX_VERIFIED)
  • Plan v3 §3 diff table (v2 was RS-first; v3 is HR-first — CEO override rationale)
  • Plan v3 §4d (HR critical path: Storecove MC #8675 as external dependency)
  • MC #8675 (Storecove account activation — CEO/John action, unblocks Phase 1H.6)
  • MEMORY: project_bilko_hr_competitor_intel_2026-05-10.md (competitive drivers)

Note on numbering: ADR-019-INTEGRATION-ADAPTER-REGISTRY.md (Phase 0', 2026-05-11) covers adapter governance. This document is a separate ADR-019 variant covering market priority strategy. Both are accepted. The naming convention adr-019-market-priority-hr-first.md distinguishes this document from the adapter registry document by suffix, consistent with the file system evidence requirements of MC #100586.

1. Context

1.1 The v2 Plan Was RS-First

The original v2 multi-market architecture plan (~/system/specs/bilko-multi-market-architecture-plan.md, 2026-04-21, now superseded) prioritized Serbia as the launch market for two reasons:

  1. The Serbian SEF (Sistem e-Faktura) e-invoice mandate was already in force
  2. StorecoveHrFiskEInvoiceAdapter.serialize() had not yet been written

The v2 plan tasked CodeCraft with SEF outbound adapter work (Tasks 1.4 and 1.5) as the Phase 1 priority.

1.2 CEO Override — 2026-05-09

During the ADR-023 routing decision session (2026-05-09), CEO Alem Bašić issued an explicit market priority override:

"B i onda dokumentuj Opcija C — ali prvo ide Hrvatska ne srbija" (Translated: "B and then document Option C — but Croatia goes first, not Serbia")

ADR-023 §6 records this as: "CEO override 2026-05-09: market priority is HR → BA → SR"

The Plan v3 (2026-05-11, approved by CEO) reflects this in its §1 executive summary: "Market priority flipped HR-first (CEO override 2026-05-09, ADR-023 §6)."

1.3 Why This ADR

The CEO override was captured in ADR-023 and Plan v3, but neither document contains a structured decision record with alternatives analysis, consequences, and binding implementation rules. The override must be ratified as a first-class architectural decision so that:

  1. New team members understand WHY HR is first (competitive, regulatory, and technical drivers)
  2. RS deprioritization is explicit and does not require repeated CEO re-confirmation
  3. The Storecove MC #8675 activation is recognized as a critical-path CEO action
  4. The BA sequencing rationale (after HR, before RS in terms of complexity) is documented

2. Decision

Market launch priority: HR (Croatia) → BA (Bosnia-Herzegovina) → SR (Serbia)

This sequence is CEO-mandated and applies to:

  • Phase scheduling (Phase 1H before Phase 1S before Phase 1B)
  • Adapter development priority (StorecoveHrFiskEInvoiceAdapter SANDBOX_VERIFIED before SEF)
  • Flyway migration priority (HR Kontni Plan seeded before RS Pravilnik)
  • Frontend MarketContext priority (HR locale, EUR currency, OIB validation before RS/BA)
  • Marketing and GTM (bilko.cloud HR brand before bilko.rs / bilko.company)
  • Securion audit priority (HR-scoped RLS audit before RS/BA)
  • Storecove account activation (MC #8675) is a CEO/John-owned critical-path action

2.1 SR Deprioritization — Explicit Scope

The following RS-focused work items are explicitly DEPRIORITIZED to Phase 1S (post-HR GA):

  • SEF outbound adapter (SefRsEInvoiceAdapter) — Phase 1S.3
  • SEF inbound adapter (supplier invoice webhook) — Phase 1S.4
  • SEF sandbox certification (5 invoice types, real SEF sandbox) — Phase 1S.5
  • PluginRS full implementation (PDV 20/10%, PIB validator, APR CoA, RSD formatters) — Phase 1S.1
  • TaxEngine service with JurisdictionRuleSet interface — Phase 1S.2
  • RS company registry adapter (APR), exchange rate adapter (NBS), ePorezi filing adapter — Phase 1S.6
  • packages/domain-rs TypeScript plugin work — deprioritized (stub only)
  • bilko.rs domain registration — open (MC #100124), not required for HR GA

What stays active for RS: ePorezi RS registration (MC decision signed 2026-04-24, started 2026-04-25). Registration process runs independently of code priority — it takes 6+ months and has no code dependency.

2.2 BA Sequencing — After HR, Before Full SR

BiH (Bosnia-Herzegovina) follows HR in sequence for a specific reason: the BA market has two sub-jurisdictions (BA_FED — Federation, under UIO-FBiH tax authority; BA_RS — Republika Srpska entity, under Poreska Uprava RS entity) that require parallel adapters. This is architecturally more complex than RS (single SEF platform) but the BA market is strategically closer to the HR market in terms of regulatory readiness:

  • BA e-invoice mandate is forthcoming (not yet in force as of 2026-05-13)
  • BA SMBs currently use paper or simple e-invoicing; Bilko can enter with less competitive friction
  • BA demographics and business language overlap with BiH diaspora in Norway (Alem's network)
  • The TaxJurisdiction enum already defines BA_FED and BA_RS (V16 applied)

BA sequencing rule: Phase 1B (BiH generalization) begins after Phase 1S kickoff, not after Phase 1S GA. This allows BA and RS to run in parallel in the later phases.

3. Drivers: Why HR Is First

3.1 Competitive Driver — Minimax HR Is the Threat

The HR competitive map (project_bilko_hr_competitor_intel_2026-05-10.md) identifies Minimax HR (under SEYFOR group) as the primary SMB competitor in Croatia. Key facts:

  • SEYFOR (formerly Saop) owns Minimax, Vasco, Opal across the Adriatic — 50K+ users
  • Minimax has modern cloud UX + FISK 2.0 + EU-mandate compliance
  • MojaFirma.hr (previously thought as a threat) was confirmed as HR/timesheet only, NOT accounting (live probe 2026-05-10: paušal module = NN 55/2024 evidencija, NO B2B e-faktura, NO HR-FISK 2.0)
  • Bilko's differentiation: "Fiken simplicity" vs. Minimax breadth + eRačun/FISK 2.0 gap
  • First-mover window: FISK 2.0 mandate is creating a compliance urgency that Bilko can exploit before the market consolidates around Minimax

RS market has Moj-eRačun / SEF as an established ecosystem. Bilko entering RS after HR GA means 2–3 weeks of RS delay against a market that is already mature — acceptable given the HR first-mover opportunity.

3.2 Regulatory Driver — eRačun 2026 Deadline

Croatia mandated eRačun (electronic invoicing) via HR-FISK 2.0 for B2B transactions. The effective deadline creates an urgency window: businesses that do not have an e-invoice solution are actively searching for one. Bilko entering the HR market during this window maximizes TAM capture without requiring marketing spend — regulatory urgency does the demand generation.

Serbia's SEF mandate is already in force since 2022 — the urgency window has closed. Businesses that needed a SEF-compliant solution have already adopted one. The Croatia window is open now.

3.3 Technical Driver — Storecove Serialize Already Works

StorecoveHrFiskEInvoiceAdapter.serialize() is implemented and tested offline. The Peppol path (Option B, CEO-signed 2026-04-24) is confirmed. The only blocked item is submit() and pollStatus(), which require Storecove account activation (MC #8675 — CEO/John action).

In contrast, the RS SEF path requires:

  • A dedicated SEF API key (available but requires sandbox registration)
  • A separate certificate for AS4/Peppol via a Serbian IS posrednik (intermediary)
  • More complex XML format (SEF-specific UBL variant) with no existing serializer

The HR path is 60–70% built. The RS path is 20% built. Given equal team velocity, HR GA is achievable in 4–5 weeks from Phase 1H kickoff; RS GA would take 8–10 additional weeks.

3.4 Banking Partnership Driver — PBZ Alignment

MC #8608 (PBZ Zagreb, Tomislav Premuz) is an active banking partnership discussion framed as fee income + deposit retention for the Intesa group (per PBZ banking dossier 2026-05-10). An HR product demo enables the PBZ partnership conversation with a concrete reference implementation. A RS-first launch does not enable this conversation.

The 12-week banking sequencing (W4 PBZ go/no-go, W5–6 parallel Erste+Zaba) is timed to HR GA (target 2026-06-08). RS partnership discussions are a Phase 1S+B parallel track.

4. Consequences

4.1 Required Actions (Binding)

The following actions are required by this decision and cannot be deferred to post-HR GA:

  • MC #8675 — Storecove account activation (CEO/John action): Must be completed by 2026-05-25 to maintain HR GA target of 2026-06-08. This is the only external dependency with variable lead time. Storecove account provides STORECOVE_API_KEY and STORECOVE_LEGAL_ENTITY_ID enabling submit() and pollStatus() in StorecoveHrFiskEInvoiceAdapter.

  • packages/domain-rs TypeScript deprioritization: The packages/domain-rs package exists on disk as a TypeScript stub. It is NOT wired to the Kotlin runtime. No further work on this package until Phase 1S kickoff. CodeCraft must not route sprint capacity to domain-rs while Phase 1H is in progress.

  • SEF tasks parked: Plan v3 Tasks 1.4 (SEF outbound) and 1.5 (SEF sandbox cert) are PARKED. They are not in the sprint backlog. Any SEF-related MC task opened while Phase 1H is active must be tagged Phase 1S and deferred.

  • BA-FED / BA-RS Kotlin split timing: TaxJurisdiction already has BA_FED and BA_RS (V16 applied). PluginBAFED and PluginBARS are stub implementations in Phase 1H.3. Full BA implementation waits for Phase 1B kickoff (post-HR GA + Phase 1S kickoff).

4.2 Critical Path: Storecove MC #8675

MC #8675 is the single external dependency that can delay HR GA. The activation sequence:

  1. CEO/John activates Storecove account → receives STORECOVE_API_KEY + STORECOVE_LEGAL_ENTITY_ID
  2. Storecove provisions Peppol participant ID for Bilko's legal entity (typically 1–3 business days)
  3. CodeCraft wires submit() + pollStatus() in StorecoveHrFiskEInvoiceAdapter (skeleton already written — activation is uncomment + wire, not a new implementation)
  4. Proveo runs 5 sandbox invoice types: B2B outbound, B2G outbound, credit note, cancelled invoice, inbound received — all with real Storecove submission IDs
  5. lifecycleState advances from STUB to SANDBOX_VERIFIED
  6. AdapterConfig row: (HR, EINVOICE, enabled=true) set in stage DB

If MC #8675 is not activated by 2026-05-25, Phase 1H.6 slips. The rest of Phase 1H (DI wiring, CountryPlugin interface, PluginHR, Flyway V16) can complete without MC #8675. A demo with submit() in STUB state is possible — it shows HR VAT rates, EUR currency, OIB validation, and e-invoice serialization. GA (first paying HR customer) requires Storecove activation.

Hard deadline: CEO activates MC #8675 no later than 2026-05-25.

4.3 Impact on domain-rs TypeScript Package

The packages/domain-rs TypeScript package exists on disk and compiles to dist/. It is NOT loaded by the Kotlin runtime — it is a TypeScript-only scaffold.

This decision means packages/domain-rs receives no active development during Phase 1H. The package may accumulate technical debt if Kotlin PluginRS in Phase 1S diverges from the TypeScript stub patterns. This is accepted:

  • The TypeScript packages are frontend/tooling artifacts, not the source of RS business logic
  • RS business logic lives in Kotlin PluginRS (Phase 1S.1)
  • packages/domain-rs will be updated in Phase 1S to align with PluginRS implementation

4.4 IS Posrednik Decision (MC #100273) — HR First

The IS posrednik selection (build vs. Mer/Visma AS4 vs. FINA fallback) is a HR-specific decision for the FISK 2.0 AS4 submission path. This decision (MC #100273) is on the HR critical path and must be resolved before Phase 1H.6 (Storecove submit() wiring).

The Storecove Peppol path (Option B, CEO-signed 2026-04-24) uses Storecove as the IS posrednik — it is not a direct FINA connection. This means:

  • MC #100273 (IS posrednik decision) is answered by MC #8675 (Storecove = IS posrednik) for the HR FISK 2.0 path
  • MC #100273 remains open if FINA fallback is considered for non-Storecove scenarios
  • For Phase 1H: Storecove IS the IS posrednik. MC #100273 can be closed as "Resolved by CEO decision 2026-04-24 (Storecove Peppol Option B)"

4.5 Banking Partnership Parallel Track

PBZ (MC #8608), Erste, and Zaba banking discussions proceed in parallel with Phase 1H engineering. The banking partnership is not a code dependency — it is a commercial track that requires an HR product demo (deliverable of Phase 1H) to advance to pilot stage.

The 12-week banking sequencing timeline:

  • W4 (2026-06-01): PBZ go/no-go decision
  • W5–6 (2026-06-08): parallel Erste + Zaba outreach (mandatory per competitive intel memo)
  • W8 (2026-06-22): pilot agreement
  • W12 (2026-07-20): LOI or pivot

This timeline is compatible with HR GA target of 2026-06-08. The PBZ go/no-go aligns with HR GA week.

5. Alternatives Considered

Option A: SR-First (v2 Plan)

Rationale at time of v2: SEF mandate already in force; SEF sandbox certification was the nearest technical milestone; RS market was assumed to be most revenue-ready.

Why rejected: CEO override 2026-05-09. On reflection, the SR-first rationale was based on regulatory urgency (SEF in force) but missed the competitive urgency in HR (FISK 2.0 compliance window + Minimax as the primary threat). Additionally, the Storecove serialize() completion made HR technically closer to done than originally assessed. The SEF adapter has no existing serializer — it is further from done than HR, not closer.

Option B: Simultaneous HR + SR Launch

Develop PluginHR and PluginRS in parallel, targeting simultaneous GA.

Why rejected: Team capacity and risk. Running two market adapters in parallel while stabilizing the RLS migration (Phase 2A) and the CountryPlugin DI wiring (Phase 1H) creates four concurrent workstreams for a small team. The probability of schedule slip on all four increases nonlinearly. HR-first serializes the risk: prove the CountryPlugin architecture works for HR, then apply it to RS with confidence.

Option C: BA-First

BiH has strategic importance (CEO personal network, diaspora market in Norway). Target BA before HR.

Why rejected: BiH e-invoice mandate is not yet in force. The BA market has no regulatory urgency comparable to HR-FISK 2.0. Additionally, BA requires two sub-jurisdiction implementations (BA_FED and BA_RS) — more architectural complexity than HR's single jurisdiction. Starting with the more complex market before the architecture is proven increases risk. BA follows HR when the CountryPlugin DI pattern is validated.

6. Implementation Notes

6.1 Sprint Backlog Rules (Enforced)

While Phase 1H is active (Weeks 1–3 from 2026-05-11), the following rules apply to the CodeCraft sprint backlog:

  1. No MC tasks with label market:RS or market:BA may enter the active sprint
  2. Any domain-rs TypeScript work is automatically deferred to Phase 1S
  3. SEF-related tasks are parked (not closed — they will be activated at Phase 1S kickoff)
  4. PluginRS and PluginBAFED/PluginBARS stubs (Phase 1H.3) are the ONLY RS/BA items in Phase 1H — they are stubs, not implementations

6.2 Phase 1S Kickoff Gate

Phase 1S (Serbia generalization) kicks off when the following are true:

  • Phase 1H complete: PluginHR live in production, Storecove SANDBOX_VERIFIED
  • Phase 5H.1 passed: Proveo HR smoke test with real stage DB
  • HR GA target date (2026-06-08) reached or within 1 week
  • CEO explicit kick-off confirmation (not assumed from Phase 1H completion)

The Phase 1S kickoff is a separate CEO decision — completing Phase 1H does not auto-trigger Phase 1S. Market conditions may change between 2026-05-11 and 2026-06-08 (e.g., a BA regulatory announcement could reprioritize 1B before 1S).

6.3 Phase 1B Kickoff Gate

Phase 1B (Bosnia generalization) kicks off in parallel with Phase 1S (not after):

  • Phase 1S.1 (PluginRS full implementation) merged to main
  • Phase 1H stable (no regressions in HR market for 2 weeks post-GA)
  • CEO decision on BA PSD2 / Tok scope (Open CEO Decision #3, Plan v3 §10)
  • BA e-invoice regulatory update assessed (if mandate announced, accelerate)

Running Phase 1B and Phase 1S in parallel is feasible because PluginBAFED and PluginBARS do not share code with PluginRS. Two teams (or two sprint lanes within CodeCraft) can develop them concurrently after the CountryPlugin DI pattern is proven via HR.

7. Approval

Status: Accepted (ratification of CEO override 2026-05-09) Architecture review: Required from Petter Graff before Phase 1H kickoff

Role Sign Date
Architecture Lead (Petter Graff) Pending —
CEO (Alem Bašić) — OVERRIDE ALREADY ISSUED Override recorded 2026-05-09 (ADR-023 §6) 2026-05-09
CEO (Alem Bašić) — MC #8675 critical-path acknowledgement Required: CEO must acknowledge Storecove deadline 2026-05-25 —

8. Document History

Date Author Change
2026-05-13 Petter Graff (CodeCraft) Initial — MC #100586 Phase 0' HR-first market priority ratification
Back to top