Bilko Mobile PRD

Bilko Mobile Companion PRD

Product: Bilko Mobile Companion
Markets: Croatia (HR), Serbia (RS), Bosnia & Herzegovina (BA)
Status: Direction approved — native iPhone + Samsung/Android companion; product scope remains draft
Date: 2026-05-25
Updated: 2026-06-04
Owner: ALAI / Bilko Product

1. Source Context

This PRD is derived from the current Bilko product and regulatory documentation:

• docs/business-requirements/BRD.md
• docs/business-requirements/FUNCTIONAL-REQUIREMENTS.md
• docs/business-requirements/USER-STORIES.md
• docs/regulatory/MULTI-REGION-OVERVIEW.md
• docs/regulatory/HR/README.md
• docs/regulatory/RS/README.md
• docs/regulatory/BA/README.md
• docs/frontend/PAGES.md
• docs/PRICING-STRATEGY.md

2. Product Positioning

Bilko Mobile should be a daily owner/operator companion, not a full replacement for the Bilko web accounting workspace.

The mobile app should help Balkan SMB owners and accountants do the urgent work that naturally happens away from a desk:

• capture receipts, supplier invoices, and other documents;
• check cash position and overdue invoices;
• approve expenses and invoice actions;
• create or send simple invoices;
• receive country-specific compliance and e-invoice status alerts;
• collaborate with an accountant on missing documents.

The web app remains the primary workspace for full bookkeeping, double-entry journals, complex reporting, configuration, reconciliation, and administration.

3. Target Users

3.1 SMB Owner / Director

Needs quick answers and fast actions:

• “How much cash and unpaid revenue do I have?”
• “Who is overdue?”
• “Can I send this invoice now?”
• “Did SEF/eRačun accept my invoice?”
• “What documents does my accountant need?”

3.2 Field Operator / Freelancer

Needs mobile capture and simple invoicing:

• scan receipt immediately;
• create a simple invoice after job completion;
• share invoice PDF via email/WhatsApp;
• work when connection is weak and sync later.

3.3 Accountant / Bookkeeper

Needs lightweight collaboration:

• request missing documents;
• comment on expense/invoice records;
• approve or reject submitted documents;
• reduce back-and-forth over email and messaging apps.

4. Goals

1. Increase daily engagement with Bilko through mobile-first workflows.
2. Reduce missing receipts and late expense capture.
3. Give owners instant cash, unpaid invoice, and VAT/PDV visibility.
4. Support time-sensitive regulatory workflows through alerts and status views.
5. Keep accounting integrity by making the backend the source of truth.
6. Make the app useful in HR, RS, and BA through country plugins and localized terminology.

5. Non-Goals

The first internal mobile build / Phase 1 must not attempt to implement:

• full double-entry journal editing;
• full bank reconciliation workflow;
• complex financial report builder;
• payroll;
• manual regulatory XML editing;
• full admin/settings console;
• durable offline queue;
• OCR extraction;
• push notifications;
• /mobile/* BFF rebuild unless explicitly scoped;
• BiH e-invoice submission before official specs/platform requirements are stable.

6. Country Requirements

6.1 Croatia (HR)

Mobile must support:

• EUR currency display;
• Croatian VAT/PDV labels and rates surfaced from backend/domain logic;
• eRačun/HR-FISK readiness/status views as backend support matures;
• certificate/connection readiness warnings where applicable;
• submission success/failure notifications.

Priority: prepare for 2026 eRačun/HR-FISK operational use without moving regulated generation/signing logic into the mobile client.

6.2 Serbia (RS)

Mobile must support:

• RSD currency display;
• Serbian PDV terminology;
• SEF status visibility for B2B invoices;
• notifications for accepted/rejected/failed/overdue e-invoice states;
• handoff to web for complex correction workflows.

Priority: SEF visibility and owner alerts, because Serbian B2B e-invoicing is already mandatory.

6.3 Bosnia & Herzegovina (BA)

Mobile must support:

• BAM currency display;
• 17% VAT/PDV basics surfaced from backend/domain logic;
• entity/company profile display where relevant;
• document capture, cash dashboard, VAT reminders, and accountant collaboration.

Priority: do not implement speculative e-invoice submission until official BA specs and platform requirements are stable.

7. Product MVP Scope

This section describes the broader product MVP ambition. It is not the first engineering slice. The first internal iPhone/Android build is narrowed in section 12 to login, dashboard/list visibility, camera capture/upload, and basic HR travel-order quick-add after backend blockers are closed.

7.1 Today Dashboard

Required:

• cash/bank balance summary when available;
• unpaid invoices total;
• overdue invoices count and amount;
• expenses pending approval;
• upcoming VAT/PDV obligation/deadline card;
• country-specific currency and labels.

Should:

• deep link to invoice/expense lists;
• show “needs attention” items first;
• work from cached data when offline in Phase 2+.

7.2 Document Inbox and Capture

Required:

• capture receipt or bill using camera;
• import PDF/image from mobile share sheet;
• create expense or supplier invoice draft;
• attach document image/PDF;
• show upload status and retry errors in Phase 1;
• queue upload if offline in Phase 2+.

Should:

• OCR-assisted extraction for supplier, amount, date, VAT/PDV, and category in Phase 3+ after legal/cost review;
• manual correction before submit;
• dead-letter state when sync repeatedly fails.

7.3 Invoice Quick Actions

Required:

• list invoices by status;
• view invoice details;
• share/download PDF when backend PDF exists;
• send payment reminder;
• mark invoice paid, subject to permissions and audit trail.

Should:

• create simple invoice from existing customer and item/service list;
• save draft offline and sync later;
• start regulated e-invoice submission only through backend-supported workflows.

7.4 Approvals

Required:

• approve/reject expense draft;
• approve/reject invoice before sending/submission;
• comment on rejection;
• push notification for approval requests.

Should:

• show audit history for approvals;
• support role-based permissions aligned with the web app.

7.5 Compliance and Status Alerts

Required:

• VAT/PDV deadline reminders;
• overdue invoice reminders;
• e-invoice status notifications for supported markets;
• failed submission alerts;
• deep links from notification to relevant record.

Should:

• certificate/token expiry warning for HR/regulated integrations where applicable;
• user-configurable notification preferences.

7.6 Accountant Collaboration

Required:

• comments on invoice/expense/document;
• missing-document task list;
• mark requested document as provided;
• push notification when accountant requests action.

Should:

• simple in-app thread per record;
• unread indicator.

8. Functional Requirements

ID	Requirement	Priority
MOB-FR-001	User can log in with Microsoft Entra External ID / Bilko account.	P0
MOB-FR-002	User can select/switch company if account has multiple companies.	P2
MOB-FR-003	App displays country-specific currency and tax labels.	P0
MOB-FR-004	User can view dashboard summary.	P0
MOB-FR-005	User can view invoice list and detail.	P0
MOB-FR-006	User can capture receipt/bill with camera.	P0
MOB-FR-007	User can submit expense draft with attachment.	P0
MOB-FR-008	App queues supported draft actions offline.	P2
MOB-FR-009	User receives approval and compliance push notifications.	P3
MOB-FR-010	User can approve/reject expense or invoice action.	P1
MOB-FR-011	User can create a simple invoice draft.	P1
MOB-FR-012	User can share invoice PDF generated by backend.	P1
MOB-FR-013	User can see SEF/eRačun/HR-FISK status where backend supports it.	P1
MOB-FR-014	User can comment on documents/invoices/expenses.	P2
MOB-FR-015	User can manage notification preferences.	P2

9. UX Structure

Recommended bottom tabs:

1. Today — dashboard and attention queue.
2. Inbox — captured documents and missing-document tasks.
3. Invoices — invoices, reminders, simple create/share.
4. Expenses — expense drafts and approvals.
5. More — company switcher, settings, security, help.

Key design rule: mobile screens should optimize for one-handed action and short sessions, not dense accounting tables.

10. Data and Backend Dependencies

The Phase 1 mobile app needs backend/API support for:

• Microsoft Entra External ID bridge: token validation, Bilko user/org mapping, role mapping, and mobile-safe session/API token issuance;
• existing /api/v1 dashboard/report data or a minimal dashboard projection;
• invoice list/detail read-only endpoints;
• expense draft create/update/submit;
• attachment upload with clear size limit and retry behavior;
• country/org metadata via GET /auth/me or equivalent.

Later phases need backend/API support for:

• /mobile/* BFF endpoints where projection efficiency justifies them;
• approval actions with audit log;
• notification token registration;
• e-invoice status endpoint per supported provider/market;
• sync endpoints or mutation queue-compatible APIs.

Backend remains authoritative for:

• tax/VAT/PDV calculation;
• double-entry posting;
• invoice numbering;
• regulated XML generation/submission;
• audit trail;
• permissions.

11. Success Metrics

Phase 1 success should be measured by:

• successful Entra/Bilko login rate;
• internal testers who can open Today, Invoices, Expenses, and More on iPhone + Android;
• receipt capture/upload success rate;
• mobile crash-free sessions;
• API/auth failures per session.

Later product MVP success should additionally measure:

• weekly active mobile users / active Bilko companies;
• receipt capture count per company per month;
• reduction in missing-document tasks older than 7 days;
• approval turnaround time;
• invoice status alert open rate;
• simple invoice creation or PDF share usage;
• sync failure/dead-letter rate.

12. Release Plan

Phase 0 — Backend/Auth Prerequisites

• Microsoft Entra External ID app registration and OIDC/PKCE configuration;
• Bilko backend auth bridge for Entra token validation;
• Bilko user/org/role mapping;
• mobile-safe session/API token issuance without browser httpOnly cookie dependency;
• align document upload size limit in backend and docs.

Phase 1 — Internal iPhone/Android Companion Build

• Entra/Bilko login/session;
• Today dashboard;
• invoice and expense read-only lists;
• camera capture;
• expense draft submission with attachment upload;
• basic HR travel-order quick-add if backend payload is confirmed;
• no durable offline queue, no OCR, no push notifications.

Phase 2 — Cache, Company Switch, and Import

• company switcher;
• cached dashboard/list state;
• file/share import;
• sync status UI;
• optional durable offline upload queue after security review.

Phase 3 — Notifications and Approvals

• push token registration;
• approval request notifications;
• expense/invoice approve/reject;
• VAT/PDV reminders.

Phase 4 — Simple Invoicing

• simple invoice draft;
• backend PDF generation/share;
• payment reminder;
• mark paid where permitted.

Phase 5 — Country Regulatory Status

• RS SEF status first;
• HR eRačun/HR-FISK status/readiness next;
• BA status only after stable official specs/platforms exist.

13. Acceptance Criteria for MVP

Phase 1 internal build can be accepted when:

• authenticated user can log in via Entra/Bilko and use Today, Invoices, Expenses, More;
• receipt capture/upload works on iOS and Android;
• country/currency labels are correct for HR/RS/BA companies;
• sensitive tokens/session material are stored only in secure storage;
• user can recover from failed upload without losing the current capture state;
• no code path stores tokens in AsyncStorage or Zustand.

Product MVP can be considered ready later when offline queue, approvals/audit, and push deep links are implemented and verified.

14. Open Questions

1. Which market should be the commercial pilot: RS because SEF is mandatory, or HR because 2026 eRačun/HR-FISK creates urgency?
2. Should Phase 2 add /mobile/* BFF endpoints, or keep adapting existing /api/v1/* endpoints?
3. Which OCR provider should be used, and what data residency/privacy constraints apply?
4. Which push provider should be selected: Expo Notifications, FCM/APNs directly, or a unified service?
5. Should simple invoice creation be in MVP or Phase 4 only?