Sprint 1-3 + Arch Roadmap

Sprint 1-3 + Arch Roadmap 
 Sprint program context: Post-CEO Bilko triage 2026-05-02 
 Phase: Bug-fix sprint following UAT Phase 1 findings (MC #10487) 
 
 Sprint 1 (MC #10495) — P0 Legal + Email + Dead UI 
 Status: OPEN (H priority) 
 Owner: TBD (awaiting dispatch) 
 Scope 
 Three high-severity bugs blocking go-live: 
 1. SEF Stub → Real e-Invoicing Integration 
 Current state: SefService.kt issues stub sefId ( SEF-STUB-<id> ) and marks invoices as "submitted" without ever contacting efaktura.gov.rs. 
 Legal risk: Serbian e-invoicing law (2023) mandates submission of all B2B invoices to SEF. Stub invoices = non-compliant. If Kotlin backend promoted to prod without completing this, every "sent" invoice will have fake sefId. 
 Code location: apps/api/src/main/kotlin/no/alai/bilko/services/SefService.kt:180-200 
 Round 2 comment in code: 
 // Round 2 replaces stub with real Ktor CIO HTTP call to efaktura.gov.rs
// Retry queue already persisted — just wire up actual SEF submission
 
 Decision pending CEO: 
 
 Option A: Real efaktura.gov.rs integration (requires SEF credentials, test environment access, XML signature setup) 
 Option B: Honest "not yet active" banner in UI + block invoice "send" action until SEF configured (safer short-term path) 
 
 Blocker: Without CEO decision, cannot proceed. Integration effort = 3-5 days (XML schema, auth flow, retry handling). 
 
 2. Invoice Email Delivery 
 Current state: Invoice wizard Step 6 shows email compose UI (To, Subject, Message, "Send me a copy"). InvoiceService.sendInvoice() changes invoice status to "sent" but does NOT dispatch email. 
 Impact: Customer never receives invoice. User believes invoice was sent. Creates chargeback disputes when client says "nisam dobio nista." 
 Code gap: No email service injection in DI container ( DI.kt ). No SMTP/Resend/SendGrid integration exists in Kotlin backend. 
 Evidence: apps/api/src/main/kotlin/no/alai/bilko/services/InvoiceService.kt — sendInvoice() function has no email dispatch logic. 
 Acceptance criteria: 
 
 Wire email service (Resend recommended — already used in other ALAI products) 
 Pass emailTo , subject , message from wizard Step 6 to API 
 Attach invoice PDF to email 
 Return email delivery confirmation (message ID) 
 Show interim banner until wired: "Faktura je snimljena — email slanje još nije aktivno. Preuzmite PDF i pošaljite ručno." 
 
 
 3. Dead UI Buttons — Receipt Scan + Attach 
 What: Two buttons on expense form ( /expenses/new ) have zero functionality: 
 
 "Skeniraj racun" (Scan Receipt) — no onClick handler, no camera access, no OCR 
 "Prikaci racun" (Attach Receipt, Paperclip icon) — no onClick , no file input 
 
 Impact: Mobile expense entry — a marketed selling point — is non-functional. RS/BA tax law requires receipt documentation for deductible expenses; without attachment, Bilko cannot support compliance. 
 UX deception: "Skeniraj racun" button is 120px tall, full-width, purple, most dominant UI element on form. Tapping it does nothing. On iPhone Safari with VoiceOver, announces "Skeniraj racun, button" but zero feedback on activation. 
 Acceptance criteria: 
 
 Minimum viable (Phase 1): Wire Paperclip button to <input type="file" accept="image/*,application/pdf"> . Connect to expense API upload endpoint. Store receipt URL in expenses.receipt_url column. 
 Future (Phase 2): Wire "Skeniraj racun" to navigator.mediaDevices.getUserMedia for camera access. Add OCR pipeline (Textract or similar). 
 Interim: Change "Skeniraj racun" button label to "Skeniraj racun (uskoro)" with disabled state. Never show interactive UI for non-functional features. 
 
 
 Sprint 2 (MC #10496) — P1 Core Workflow 
 Status: OPEN (M priority) 
 Owner: TBD 
 Scope 
 Four P1 gaps affecting core accounting workflows: 
 1. Chart of Accounts Seeding on Org Creation 
 Gap: CountryService.seedChartOfAccounts() exists ( CountryService.kt:220 ) but is NOT called from AuthService.register() . 
 Impact: New organizations have empty chart of accounts. US-030 AC1 requires "all 10 account classes present on new Serbian org" — currently fails. 
 Fix: Add countryService.seedChartOfAccounts(organizationId, country) call after org creation in AuthService.register() . 
 
 2. Multi-Org Switcher 
 Gap: Each user has single organizationId . No UI switcher, no API endpoint to switch active org. 
 Impact: Accountants managing multiple companies (common in SMB Balkans) must log out/in with different emails. US-004 unmet. 
 Acceptance criteria: 
 
 Add user_organizations junction table (user can belong to multiple orgs) 
 Add GET /users/me/organizations endpoint 
 Add POST /users/me/switch-organization endpoint (updates session active org) 
 Add org switcher dropdown in top-bar (web) 
 
 
 3. EUR Exchange Rate Fetch from Central Bank 
 Gap: InvoiceService.getExchangeRate() exists ( InvoiceService.kt:972-990 ) but has TODO comment: "fetch from NBS API for RS, CBBiH for BA." 
 Current behavior: Returns hardcoded 1.0 or throws error if currency not BAM/RSD. 
 Impact: Foreign currency invoices (EUR, USD) cannot be created. US-070 partially unmet. 
 Acceptance criteria: 
 
 Wire to RS central bank XML API: https://www.nbs.rs/kursnaListaModul/zaXML.faces 
 Wire to BA central bank: https://www.cbbh.ba/CurrencyExchange/GetJson 
 Cache rates daily (store in exchange_rates table) 
 Fallback: prompt for manual entry if API unavailable (US-070 AC3) 
 
 
 4. Bank CSV Parser — Balkan Format Presets 
 Gap: CSV import expects generic date,description,amount,reference format. Real banks: Raiffeisen BA (semicolon, DD.MM.YYYY ), UniCredit RS (local thousand separators), Intesa RS (multi-line headers). 
 Impact: User exports from real bank, uploads CSV, gets 0 imported rows. Feature reads as broken. 
 Acceptance criteria: 
 
 Add named bank format presets: Raiffeisen BA, UniCredit RS, Intesa RS, ProCredit BA, OTP BA 
 Each preset: delimiter, date format, column positions, header skip count 
 OR: CSV mapping UI where user defines which column = date/amount/description 
 Store selected bank format in bank_accounts.import_format column 
 
 
 Sprint 3 (MC #10497) — P2 Polish 
 Status: OPEN (L priority) 
 Owner: TBD 
 Scope 
 Three P2 UX polish items: 
 1. sr-Latn Translation Pass (Dialect Consistency) 
 Gap: apps/web/messages/sr-Latn.json mixes Bosnian and Serbian forms: "dospijeva" (BS) alongside "dospeva" (RS/SR), "mjesec" vs "mesec", "Postavke" vs "Podešavanja." 
 Decision: sr-Latn targets RS market (pure Serbian ekavica). Bosnian forms belong in bs.json . 
 Acceptance criteria: 
 
 Audit sr-Latn.json — replace Bosnian ijekavica with Serbian ekavica 
 "mjesec" → "mesec", "sedmično" → "nedeljno", "dospijeva" → "dospeva" 
 QA review by Serbian native speaker 
 
 
 2. Mobile UX Micro-Fixes 
 Gaps (from maria-santos report): 
 
 Invoice wizard step labels hidden on mobile ( hidden sm:inline ) 
 Line item inputs ~70px wide on 390px iPhone (grid-cols-2 sm:grid-cols-4) 
 Sidebar overlay no slide animation (raw div, no CSS transition) 
 Date picker label misalignment on iOS Safari small screens 
 Language switcher tap target 36px (WCAG 2.1 AA requires 44px) 
 Amount inputs missing inputmode="decimal" (iOS numeric keyboard has no decimal separator) 
 
 Acceptance criteria: Address top 3 (step labels, line item width, sidebar animation). 
 
 3. Dashboard Empty States + Error Message Clarity 
 Gap: Dashboard shows Recharts widgets with no data → renders blank/broken-looking on first login. No empty state illustrations/guidance. 
 Acceptance criteria: 
 
 Add empty state for "No invoices yet" (illustration + CTA "Create first invoice") 
 Add empty state for "No expenses yet" 
 Improve API error messages (currently generic "Registration failed. Please try again." with no timing/retry info) 
 
 
 Arch Roadmap (MC #10498) — Infrastructure + CI 
 Status: OPEN (M priority) 
 Owner: TBD 
 Scope 
 Four architectural/infra improvements: 
 1. Kotlin CI Pipeline 
 Gap: cloudbuild.yaml deploys web only. Kotlin API has no CI (manual deploy only). 
 Risk: Regression in apps/api/ invisible to CI. If developer pushes breaking change to main, web gets deployed, API does not. Two can silently diverge. 
 Acceptance criteria: 
 
 Add Cloud Build trigger for apps/api/** path changes 
 Build steps: ./gradlew test , ./gradlew build , docker build -f Dockerfile.api-kotlin 
 Push image to GCR 
 Deploy to stage Cloud Run bilko-api-stage (auto) 
 Deploy to prod requires manual approval (Cloud Build approval gate) 
 
 
 2. RUNBOOK.md Fix (Still References Vercel) 
 Gap: docs/operations/OPERATIONAL-RUNBOOK.md:23,59,66,120 references Vercel ( vercel --prod , vercel rollback , vercel env add ) as deployment platform. 
 Reality: Deployment is GCP Cloud Run + Cloud Build. Vercel not used. 
 Acceptance criteria: 
 
 Replace Vercel commands with Cloud Run equivalents ( gcloud run deploy , gcloud run revisions list , gcloud run services update-traffic ) 
 Add rollback procedure for Kotlin API (currently only web rollback documented) 
 Update SLA report template with actual Cloud Run metrics endpoints 
 
 
 3. .gcloudignore Optimization (MC #10504) 
 Gap: Cloud Build web deploy uploads 492MB (includes apps/api/build/ , .gradle/ , node_modules/ from all workspaces). 
 Impact: Upload timeout on slow connections (3+ minutes on Build step 1/24). 
 Acceptance criteria: 
 
 Add to .gcloudignore :
 apps/api/build/
apps/api/.gradle/
**/node_modules/
**/.next/
**/dist/
 
 
 Verify upload size reduction (target <100MB) 
 
 
 4. Cloud Build Trigger Registration (Auto-Deploy on Push) 
 Gap: Cloud Build triggers are manual ( gcloud builds submit ) per deploy. No auto-trigger on git push origin main . 
 Acceptance criteria: 
 
 Register Cloud Build GitHub App trigger for main branch (web) 
 Register trigger for main branch (api, once Kotlin CI pipeline wired) 
 Add approval gate for prod deploys (manual Cloud Build approval step) 
 
 
 Dependency Diagram 
 graph TB
 UAT[UAT Phase 1 #10487] --> Express[Express Deletion #10493]
 Express --> Sprint0[Sprint 0 #10494]
 Sprint0 --> WebDockerfix[Web Dockerfile #10505]
 WebDockerfix --> Sprint1[Sprint 1 #10495]
 Sprint1 --> Sprint2[Sprint 2 #10496]
 Sprint1 --> Sprint3[Sprint 3 #10497]
 Sprint0 --> Arch[Arch #10498]
 Sprint1 --> AngieRerun[Angie Re-run #10500]
 Sprint0 --> ProdCutover[PROD CUTOVER #10502]
 Arch --> gcloudignore[.gcloudignore #10504]
 
 style UAT fill:#e1f5ff
 style Express fill:#c8e6c9
 style Sprint0 fill:#c8e6c9
 style WebDockerfix fill:#c8e6c9
 style Sprint1 fill:#fff9c4
 style Sprint2 fill:#fff9c4
 style Sprint3 fill:#fff9c4
 style Arch fill:#fff9c4
 style ProdCutover fill:#ffccbc
 style AngieRerun fill:#f3e5f5
 style gcloudignore fill:#f3e5f5
 
 Legend: 
 
 Blue: Discovery (UAT) 
 Green: DONE 
 Yellow: OPEN 
 Orange: BLOCKER 
 Purple: Followup 
 
 
 References 
 MCs: 
 
 MC #10487 — UAT Phase 1 
 MC #10493 — Express deletion (DONE) 
 MC #10494 — Sprint 0 (DONE) 
 MC #10495 — Sprint 1 (OPEN, H) 
 MC #10496 — Sprint 2 (OPEN, M) 
 MC #10497 — Sprint 3 (OPEN, L) 
 MC #10498 — Arch roadmap (OPEN, M) 
 MC #10500 — angie-jones re-run (OPEN, M) 
 MC #10502 — PROD CUTOVER (OPEN, H, BLOCKER) 
 MC #10504 — .gcloudignore (OPEN, M, child of #10498) 
 MC #10505 — Web Dockerfile regression (DONE) 
 
 Evidence: 
 
 /tmp/bilko-uat-ux-10487.md — UX findings (maria-santos) 
 /tmp/bilko-uat-gap-10487.md — Architecture gaps (petter-graff) 
 USER-STORIES.md — Acceptance criteria source