# Bilko — Balkan Accounting SaaS Cloud accounting for Balkan SMBs (Serbia, BiH, Croatia). Fiken-inspired. # Frontend Next.js 15 frontend — pages, components, design system # Pages & Routing # Bilko Frontend Pages **Framework:** Next.js 15 (App Router) **Current State:** Fully implemented with mock data **Future State:** Will require API integration to replace mock data --- ## Route Architecture Overview ```mermaid graph TD ROOT["app/layout.tsx\n(Root HTML, Inter font, metadata)"] ROOT --> LANDING["/ — Landing Page\napp/page.tsx"] ROOT --> AUTH["(auth) group\nNo shared layout"] ROOT --> DASH["(dashboard) group\napp/(dashboard)/layout.tsx\nSidebar + TopBar"] AUTH --> LOGIN["/login\nLoginPage"] AUTH --> REGISTER["/register\nRegisterPage"] DASH --> DASHBOARD["/dashboard\nDashboard Home"] DASH --> INVOICES["/invoices\nInvoice List"] DASH --> INV_NEW["/invoices/new\nInvoice Wizard"] DASH --> EXPENSES["/expenses\nExpense List"] DASH --> EXPENSES_NEW["/expenses/new\nAdd Expense"] DASH --> PURCHASES["/purchases\nPurchases (alias → expenses)"] DASH --> BANKING["/banking\nBanking Hub"] DASH --> REPORTS["/reports\nReports Hub"] DASH --> REPORTS_PL["/reports/profit-loss\nP&L Report"] DASH --> REPORTS_VAT["/reports/vat\nVAT Report"] DASH --> SETTINGS["/settings\nSettings"] LANDING --> LOGIN LOGIN --> DASHBOARD REGISTER --> DASHBOARD classDef layout fill:#1e1e2e,color:#cdd6f4,stroke:#89b4fa classDef auth fill:#313244,color:#cba6f7,stroke:#cba6f7 classDef dashboard fill:#1e1e2e,color:#a6e3a1,stroke:#a6e3a1 classDef reports fill:#313244,color:#89dceb,stroke:#89dceb class ROOT,DASH layout class AUTH,LOGIN,REGISTER auth class DASHBOARD,INVOICES,INV_NEW,EXPENSES,EXPENSES_NEW,PURCHASES,BANKING,SETTINGS dashboard class REPORTS,REPORTS_PL,REPORTS_VAT reports ``` --- ## Layouts ### Root Layout - **Route:** `/` - **File:** `app/layout.tsx` - **Purpose:** Root HTML wrapper, applies Inter font, sets metadata - **Metadata:** - Title: "Bilko - Accounting Made Simple" - Description: "Modern accounting software for Balkan businesses" - **Dependencies:** Inter font from Google Fonts - **Current State:** Fully implemented ### Dashboard Layout - **Route:** `/(dashboard)/*` - **File:** `app/(dashboard)/layout.tsx` - **Purpose:** Layout wrapper for all authenticated pages - **Key Components:** - Sidebar (desktop persistent, mobile overlay) - TopBar (header with search, notifications, user menu) - **State Management:** Local state for mobile sidebar toggle - **Mobile Responsiveness:** Responsive sidebar with overlay - **Current State:** Fully implemented ```mermaid graph LR DL["DashboardLayout\napp/(dashboard)/layout.tsx"] DL --> SB["Sidebar\ncomponents/sidebar.tsx\n• Logo\n• Main nav (5 items)\n• Bottom nav (Settings)\n• Active state via usePathname"] DL --> TB["TopBar\ncomponents/top-bar.tsx\n• Mobile menu button\n• Search (Cmd+K)\n• Notifications bell\n• User dropdown menu"] DL --> SLOT["Page Slot\n{children}"] SB -->|"dark sidebar #111113"| SCREEN["Rendered Screen"] TB -->|"white top bar"| SCREEN SLOT -->|"light content #FAFAFA"| SCREEN ``` --- ## Pages ### Dashboard (Home) - **Route:** `/dashboard` - **File:** `app/(dashboard)/dashboard/page.tsx` - **Purpose:** Financial overview and quick actions - **Key Components:** - Metric cards (Cash Balance, Revenue MTD, Unpaid Invoices) - P&L Bar Chart (6-month trend) - Receivables Aging (stacked bar chart) - Expenses by Category (donut chart) - Recent Transactions table - Quick Actions card - **Data Requirements (Future API):** - `GET /api/metrics` — cashBalance, revenueMTD, unpaidInvoices, expensesMTD, profitMTD, cashFlowChange - `GET /api/pl/monthly` — monthly P&L data (revenue, expenses, profit) - `GET /api/receivables/aging` — receivables breakdown (current, 30d, 60d, 90d+) - `GET /api/expenses/by-category` — expenses grouped by category - `GET /api/transactions/recent?limit=5` — recent transactions - **Charts:** Recharts (BarChart, PieChart) with responsive containers - **Current State:** Mock data from `lib/mock-data.ts` - **Mobile Responsive:** Grid adapts 1/2/3 columns based on breakpoint ```mermaid graph TD DP["Dashboard Page\n/dashboard"] DP --> ROW1["Row 1 — Metric Cards\ngrid-cols-1 md:grid-cols-3"] DP --> ROW2["Row 2 — Charts\ngrid-cols-1 md:grid-cols-3"] DP --> ROW3["Row 3 — Tables + Actions\ngrid-cols-1 lg:grid-cols-3"] ROW1 --> MC1["Cash Balance\nwith trend arrow"] ROW1 --> MC2["Revenue MTD\ncurrent month total"] ROW1 --> MC3["Unpaid Invoices\nwith warning badge"] ROW2 --> CH1["P&L Bar Chart\nRecharts BarChart\n6-month revenue/expenses/profit"] ROW2 --> CH2["Receivables Aging\nRecharts StackedBarChart\ncurrent/30d/60d/90d+"] ROW2 --> CH3["Expenses by Category\nRecharts PieChart (donut)\nper-category breakdown"] ROW3 --> TBL["Recent Transactions\nRecharts Table\nlast 5 transactions"] ROW3 --> QA["Quick Actions\nNew Invoice\nNew Expense\nImport Bank Statement"] ``` ### Invoices List - **Route:** `/invoices` - **File:** `app/(dashboard)/invoices/page.tsx` - **Purpose:** Invoice management with search, filter, sort - **Key Features:** - Status filter (all/draft/sent/paid/overdue) - Search by customer name or invoice number - Date range filter (this month, last month, quarter, all) - Sortable columns (number, customer, date, due date, amount) - Row actions (view, edit, send, download PDF, delete) - Summary row with totals by status - **Data Requirements (Future API):** - `GET /api/invoices?status=X&search=Y&dateRange=Z&sort=field&dir=asc` — filtered/sorted invoice list - `PATCH /api/invoices/:id` — update invoice - `DELETE /api/invoices/:id` — delete invoice - `POST /api/invoices/:id/send` — send invoice via email - `GET /api/invoices/:id/pdf` — generate PDF - **Current State:** Mock data, client-side filtering/sorting - **Mobile Responsive:** Table scrolls horizontally, filters stack vertically ### Invoice Creation Wizard - **Route:** `/invoices/new` - **File:** `app/(dashboard)/invoices/new/page.tsx` - **Purpose:** 6-step wizard to create and send invoices - **Steps:** 1. **Customer Selection** — Select existing customer or add new (dialog) 2. **Invoice Details** — Invoice number, issue/due dates, net terms, currency 3. **Line Items** — Add/remove items (description, qty, unit price, VAT rate), auto-calculate totals 4. **Customization** — Optional notes and payment terms 5. **Preview** — Visual preview of generated invoice 6. **Send** — Email form (to, subject, message, copy to self) + save/download options - **Data Requirements (Future API):** - `GET /api/customers` — customer list for dropdown - `POST /api/customers` — create new customer - `POST /api/invoices` — create invoice (draft) - `POST /api/invoices/:id/send` — send invoice via email - `GET /api/invoices/:id/pdf` — download PDF - **Form Validation:** - Step 1: Customer required - Step 3: At least one line item with description required - Step 6: Email address required - **Current State:** Mock data, local state, no persistence - **Mobile Responsive:** Wizard steps adapt, form fields stack on mobile ### Expenses List - **Route:** `/expenses` - **File:** `app/(dashboard)/expenses/page.tsx` - **Purpose:** Expense tracking with categorization and approval workflow - **Key Features:** - Period filter (this month, last month, quarter, year) - Category filter (Office, Travel, Meals, Utilities, Marketing, Infrastructure, Software, Professional Services) - Search by description or vendor - Status badges (pending, approved, paid) - Receipt attachment indicator - Add Expense dialog (with upload placeholder) - Summary stats (total, pending, approved, paid counts) - **Data Requirements (Future API):** - `GET /api/expenses?period=X&category=Y&search=Z` — filtered expense list - `POST /api/expenses` — create expense - `PATCH /api/expenses/:id` — update expense status - `POST /api/expenses/:id/receipt` — upload receipt (multipart) - `GET /api/expenses/:id/receipt` — download receipt - **Form Fields:** - Amount + currency (EUR, RSD, BAM) - Category (dropdown) - Date - Vendor (searchable input) - Payment method (Cash, Card, Bank Transfer) - Receipt upload (placeholder UI) - Description (optional) - **Current State:** Mock data, form submits to console - **Mobile Responsive:** Filters stack, table scrolls ### Purchases (Alias) - **Route:** `/purchases` - **File:** `app/(dashboard)/purchases/page.tsx` - **Purpose:** Alias to expenses page - **Current State:** Same component as `/expenses` ### Banking - **Route:** `/banking` - **File:** `app/(dashboard)/banking/page.tsx` - **Purpose:** Bank account management and reconciliation - **Key Features:** - 3 tabs: Accounts, Reconcile, Transactions - **Accounts Tab:** List of bank accounts with balances (multiple currencies) - **Reconcile Tab:** Unreconciled transactions with match confidence, period selector - **Transactions Tab:** All bank transactions (chronological) - Import Transactions button (placeholder) - Match actions (approve, link, create new) - **Data Requirements (Future API):** - `GET /api/bank-accounts` — list accounts - `POST /api/bank-accounts` — add account - `GET /api/bank-accounts/:id/transactions?reconciled=false` — unreconciled transactions - `POST /api/bank-accounts/:id/import` — CSV import - `POST /api/bank-accounts/:id/transactions/:txId/reconcile` — mark reconciled - `POST /api/bank-accounts/:id/transactions/:txId/link?invoiceId=X` — link to invoice/expense - **Match Confidence Logic:** Visual indicators for 0%, <50%, 50-89%, 90%+ - **Current State:** Mock data, no reconciliation logic - **Mobile Responsive:** Tabs stack, tables scroll ### Reports Hub - **Route:** `/reports` - **File:** `app/(dashboard)/reports/page.tsx` - **Purpose:** Financial report selection and P&L preview - **Report Cards:** - Profit & Loss (implemented at `/reports/profit-loss`) - Balance Sheet (coming soon) - Cash Flow Statement (coming soon) - VAT/PDV Report (live at `/reports/vat`) - Trial Balance (coming soon) - General Ledger (coming soon) - **P&L Preview:** - Expandable Revenue/Expenses sections - Current month detailed breakdown - Export buttons (PDF, Excel) — placeholders - **Data Requirements (Future API):** - `GET /api/reports/pl?month=YYYY-MM` — P&L report data - `GET /api/reports/balance-sheet?date=YYYY-MM-DD` — balance sheet - `GET /api/reports/cash-flow?period=X` — cash flow statement - **Current State:** Only P&L and VAT reports implemented, others show "Coming Soon" badge - **Mobile Responsive:** Report cards grid adapts ```mermaid graph TD RH["Reports Hub\n/reports"] RH --> PL["Profit & Loss\n/reports/profit-loss\nLIVE — expandable revenue/expenses\nfetches from API with mock fallback"] RH --> BS["Balance Sheet\nCOMING SOON"] RH --> CF["Cash Flow Statement\nCOMING SOON"] RH --> VAT["VAT/PDV Report\n/reports/vat\nLIVE — 3-step wizard"] RH --> TB["Trial Balance\nCOMING SOON"] RH --> GL["General Ledger\nCOMING SOON"] PL --> PL_R["Revenue Section\n(expandable, breakdown by category)"] PL --> PL_E["Expenses Section\n(expandable, breakdown by category)"] PL --> PL_NP["Net Profit + Margin"] PL --> PL_EX["Export PDF / Export Excel"] VAT --> VAT_S1["Step 1: Reconciliation Check\n(warn if unreconciled transactions)"] VAT --> VAT_S2["Step 2: VAT Audit\n(all VAT transactions table)"] VAT --> VAT_S3["Step 3: Return Summary\nBox 1 / Box 2 / Box 3"] classDef live fill:#1e3a2f,color:#a6e3a1,stroke:#a6e3a1 classDef soon fill:#2a1e2e,color:#888,stroke:#555 class PL,VAT live class BS,CF,TB,GL soon ``` ### VAT Report - **Route:** `/reports/vat` - **File:** `app/(dashboard)/reports/vat/page.tsx` - **Purpose:** 3-step VAT return preparation - **Steps:** 1. **Reconciliation Check** — Warns if unreconciled bank transactions exist 2. **VAT Audit** — Table of all VAT transactions (invoices + expenses) with net/VAT amounts 3. **Return Summary** — VAT return boxes (Box 1: collected, Box 2: paid, Box 3: net due) - **Data Requirements (Future API):** - `GET /api/bank-accounts/unreconciled-count` — reconciliation status - `GET /api/vat/transactions?period=YYYY-MM` — all VAT transactions - `GET /api/vat/return?period=YYYY-MM` — calculated VAT return data - `POST /api/vat/submit` — e-filing (Phase 2) - `GET /api/vat/export/pdf` — PDF export - `GET /api/vat/export/xml` — XML for e-filing - **Calculations:** Assumes 20% standard VAT rate, converts all currencies to EUR equivalent - **Current State:** Mock data, no submission, export placeholders - **Mobile Responsive:** Tabs adapt, tables scroll, boxes stack ### Settings - **Route:** `/settings` - **File:** `app/(dashboard)/settings/page.tsx` - **Purpose:** Multi-section settings page - **Sections:** 1. **Company** — Company profile (name, legal form, address, tax ID, currency, fiscal year) 2. **Users** — User management table (name, email, role, status), invite button 3. **Tax & Compliance** — Country, VAT registration, VAT number/rate, compliance reminders 4. **Integrations** — Connected integrations (Intesa Bank CSV, Email SMTP), available integrations (Stripe, Fiken, Google Sheets, Slack, DocuSeal) 5. **Notifications** — Email and in-app notification preferences 6. **Security** — 2FA, session timeout, password policy, audit log, data export, delete company - **Data Requirements (Future API):** - `GET /api/settings/company` — company data - `PATCH /api/settings/company` — update company - `GET /api/users` — user list - `POST /api/users/invite` — invite user - `GET /api/settings/tax` — tax settings - `PATCH /api/settings/tax` — update tax settings - `GET /api/integrations` — integration list - `POST /api/integrations/:id/connect` — connect integration - `GET /api/settings/notifications` — notification preferences - `PATCH /api/settings/notifications` — update preferences - `GET /api/security/audit-log` — audit log - `POST /api/security/data-export` — request data export - `DELETE /api/company` — delete company - **Current State:** Mock data, form submits to console - **Mobile Responsive:** Sidebar nav stacks, forms adapt --- ## Authentication Flow ```mermaid sequenceDiagram participant U as User participant AP as AuthProvider participant AS as useAuthStore participant R as Router participant API as Backend API U->>AP: Navigate to /dashboard AP->>AS: checkAuth() AS->>API: GET /api/auth/me (Bearer token) alt API not configured (demo mode) AP-->>U: Render page directly (demoFallback=true) else Token valid API-->>AS: 200 OK — user data AS-->>AP: isAuthenticated=true AP-->>U: Render protected page else Token invalid / no token API-->>AS: 401 Unauthorized AS-->>AP: isAuthenticated=false AP->>R: router.replace('/login') R-->>U: Redirect to /login U->>U: Enter email + password U->>AS: login(email, password) AS->>API: POST /api/auth/login API-->>AS: 200 OK — JWT token AS->>R: router.push('/dashboard') R-->>U: Redirect to /dashboard end ``` --- ## Screenshot Descriptions ### Dashboard User sees: - 3 metric cards at top (cash balance with green arrow, revenue MTD, unpaid invoices with warning badge) - 3 charts in row below (P&L bar chart, receivables aging stacked bar, expenses donut) - Bottom row: recent transactions table on left, quick action buttons on right ### Invoices List User sees: - Header with "Invoices" title and "New Invoice" button - Filter row (status dropdown, search input, date range dropdown) - Table with all invoices (sortable columns, status badges, action menu per row) - Summary bar at bottom showing totals by status ### Invoice Wizard User sees: - Progress bar with 6 steps at top - Current step content in card below - Back/Next buttons at bottom (Send on final step) - Step 3 shows line items with add/remove, running total calculation - Step 5 shows formatted invoice preview ### Expenses User sees: - "Expenses" header with "Add Expense" button - Filters (period, category, search) - Table with date, description, category, amount, vendor, status badge, receipt icon - Summary bar with totals (total €, pending count, approved count, paid count) - Add dialog: form with amount+currency, category, date, vendor, payment method, receipt upload, description ### Banking User sees: - 3 tabs: Accounts, Reconcile, Transactions - Accounts tab: table of bank accounts with type, currency, balance - Reconcile tab: account selector, period, unreconciled transaction table with match confidence indicators, action buttons (✓ approve, link, create) - Transactions tab: full transaction history with reconciled status ### VAT Report User sees: - 3-step tabs at top - Step 1: Warning card if unreconciled transactions exist, "Reconcile Now" and "Continue" buttons - Step 2: VAT transaction table (type badge, net amount, VAT rate, VAT amount), summary boxes (collected, paid, net due) - Step 3: VAT return boxes (Box 1, Box 2, Box 3 highlighted), export buttons (PDF, XML), submit button (disabled, "Coming in Phase 2") ### Settings User sees: - Sidebar nav on left (6 sections) - Content area on right showing active section - Company section: form fields for company data - Users section: table with invite button - Integrations section: connected integrations cards, available integrations grid - Security section: danger zone at bottom (delete company, red border) --- ## Notes - **All pages use mock data** from `lib/mock-data.ts` - **Authentication** implemented via `AuthProvider` + `useAuthStore` — demo mode active when `NEXT_PUBLIC_API_URL` not set - **No persistence** — refreshing page loses all changes - **Mobile-first design** — all pages tested at mobile/tablet/desktop breakpoints - **Dark sidebar + light content area** — consistent layout across all pages # State Management # Bilko State Management **Current State:** Primarily React hooks (useState, useEffect) **Installed but Minimal Use:** Zustand 4.5.0 **Future State:** Migrate to Zustand for global state --- ## Architecture Overview ```mermaid flowchart LR subgraph CURRENT["Current Architecture (Phase 1)"] MD["lib/mock-data.ts\n(static imports)"] -->|imported directly| PG["Page Component\n(useState + useMemo)"] PG -->|renders| UI["UI Components"] PG -->|local state only| PG end subgraph FUTURE["Future Architecture (Phase 2)"] API["Backend API\n(Express + PostgreSQL)"] -->|fetch| ST["Zustand Stores\nauth / org / invoices\nexpenses / banking / ui"] ST -->|subscribe| PG2["Page Component\nuseInvoicesStore()"] PG2 -->|renders| UI2["UI Components"] PG2 -->|optimistic update| ST end style CURRENT fill:#1a1a2e,stroke:#4a4a6e,color:#aaa style FUTURE fill:#1a2e1a,stroke:#4a6e4a,color:#aaa ``` --- ## Current State Patterns ### Local Component State (React useState) **Usage:** Most components use local state for UI interactions and form data. #### Examples: **Dashboard Page:** ```typescript // No local state — purely presentational, uses mock data imports ``` **Invoice List Page:** ```typescript const [statusFilter, setStatusFilter] = useState("all") const [searchQuery, setSearchQuery] = useState("") const [dateRange, setDateRange] = useState("this-month") const [sortColumn, setSortColumn] = useState("date") const [sortDirection, setSortDirection] = useState<"asc" | "desc">("desc") ``` **Invoice Wizard:** ```typescript const [step, setStep] = useState(1) const [customer, setCustomer] = useState(null) const [showAddCustomer, setShowAddCustomer] = useState(false) const [invoiceDetails, setInvoiceDetails] = useState({...}) const [lineItems, setLineItems] = useState([...]) const [notes, setNotes] = useState("Thank you for your business!") const [terms, setTerms] = useState("Payment due within 30 days.") const [emailData, setEmailData] = useState({...}) ``` **Expenses Page:** ```typescript const [isDialogOpen, setIsDialogOpen] = useState(false) const [periodFilter, setPeriodFilter] = useState("This Month") const [categoryFilter, setCategoryFilter] = useState("All Categories") const [searchQuery, setSearchQuery] = useState("") const [formData, setFormData] = useState({...}) ``` **Banking Page:** ```typescript const [selectedAccount, setSelectedAccount] = useState(mockBankAccounts[0].id) ``` **Reports Page:** ```typescript const [plExpanded, setPlExpanded] = useState({ revenue: true, expenses: true }) ``` **VAT Report:** ```typescript const [currentStep, setCurrentStep] = useState<'reconciliation' | 'audit' | 'summary'>('reconciliation') ``` **Settings Page:** ```typescript const [activeSection, setActiveSection] = useState('company') const [companyData, setCompanyData] = useState({...}) const [vatSettings, setVatSettings] = useState({...}) ``` **Dashboard Layout:** ```typescript const [sidebarOpen, setSidebarOpen] = useState(false) ``` **Sidebar:** ```typescript const [expandedSections, setExpandedSections] = useState([ "Sales", "Purchases", "Reports" ]) ``` --- ### Local State Distribution by Page ```mermaid flowchart TD subgraph IL["Invoice List /invoices"] IL1["statusFilter\nsearchQuery\ndateRange\nsortColumn\nsortDirection"] end subgraph IW["Invoice Wizard /invoices/new"] IW1["step (1-6)\ncustomer\nshowAddCustomer\ninvoiceDetails\nlineItems\nnotes / terms\nemailData"] end subgraph EP["Expenses /expenses"] EP1["isDialogOpen\nperiodFilter\ncategoryFilter\nsearchQuery\nformData"] end subgraph BP["Banking /banking"] BP1["selectedAccount"] end subgraph RP["Reports /reports"] RP1["plExpanded\n{revenue, expenses}"] end subgraph VP["VAT /reports/vat"] VP1["currentStep\n'reconciliation' | 'audit' | 'summary'"] end subgraph SP["Settings /settings"] SP1["activeSection\ncompanyData\nvatSettings"] end subgraph LY["Dashboard Layout"] LY1["sidebarOpen (mobile)"] end subgraph SB["Sidebar component"] SB1["expandedSections: string[]"] end ``` --- ### Computed State (React useMemo) **Purpose:** Derived values from props/state to avoid expensive recalculations. **Invoice List:** ```typescript // Filtered/sorted invoice list const filteredInvoices = useMemo(() => { let filtered = [...mockInvoices] // Apply filters if (statusFilter !== "all") { filtered = filtered.filter((inv) => inv.status === statusFilter) } if (searchQuery) { const query = searchQuery.toLowerCase() filtered = filtered.filter( (inv) => inv.customerName.toLowerCase().includes(query) || inv.number.toLowerCase().includes(query) ) } // Date range filter logic... // Sort logic... return filtered }, [statusFilter, searchQuery, dateRange, sortColumn, sortDirection]) // Summary calculations const summary = useMemo(() => { const total = filteredInvoices.length const byStatus = filteredInvoices.reduce((acc, inv) => { // Aggregate by status... return acc }, {}) return { total, byStatus } }, [filteredInvoices]) ``` **Invoice Wizard:** ```typescript // Customer list const customers = useMemo( () => mockContacts.filter((c) => c.type === "customer"), [] ) // Calculate totals const totals = useMemo(() => { const subtotal = lineItems.reduce( (sum, item) => sum + item.quantity * item.unitPrice, 0 ) const vatTotal = lineItems.reduce( (sum, item) => sum + item.quantity * item.unitPrice * (item.vatRate / 100), 0 ) const total = subtotal + vatTotal return { subtotal, vatTotal, total } }, [lineItems]) ``` **Expenses Page:** ```typescript // Filtered expenses const filteredExpenses = useMemo(() => { return mockExpenses.filter(expense => { const matchesCategory = categoryFilter === "All Categories" || expense.category === categoryFilter const matchesSearch = searchQuery === "" || expense.description.toLowerCase().includes(searchQuery.toLowerCase()) || expense.vendor.toLowerCase().includes(searchQuery.toLowerCase()) return matchesCategory && matchesSearch }) }, [categoryFilter, searchQuery]) // Stats const stats = useMemo(() => { const total = filteredExpenses.reduce((sum, exp) => { // Convert to EUR and sum... }, 0) const pending = filteredExpenses.filter(e => e.status === 'pending').length const approved = filteredExpenses.filter(e => e.status === 'approved').length const paid = filteredExpenses.filter(e => e.status === 'paid').length return { total, pending, approved, paid } }, [filteredExpenses]) ``` **Banking Page:** ```typescript // Total balance in EUR const totalBalanceEUR = useMemo(() => { return mockBankAccounts.reduce((sum, acc) => { const eurAmount = acc.currency === 'EUR' ? acc.balance : acc.currency === 'RSD' ? acc.balance / 117 : acc.balance / 2 // BAM to EUR return sum + eurAmount }, 0) }, []) // Unreconciled transactions const unreconciledTransactions = useMemo(() => { return mockBankTransactions.filter(tx => !tx.reconciled && tx.bankAccountId === selectedAccount) }, [selectedAccount]) ``` --- ### Navigation State (Next.js usePathname) **Sidebar:** ```typescript const pathname = usePathname() const isActive = (href: string | undefined) => { if (!href) return false return pathname === href } ``` **Usage:** Highlights active navigation item based on current route. --- ### Router State (Next.js useRouter) **Invoice Wizard:** ```typescript const router = useRouter() const handleNext = () => { if (step === 6) { alert("Invoice sent!") router.push("/invoices") } else { setStep(step + 1) } } const handleCancel = () => { if (confirm("Are you sure you want to cancel? All changes will be lost.")) { router.push("/invoices") } } ``` **Usage:** Programmatic navigation after form submission or cancel. --- ## Data Flow (Current) ```mermaid flowchart LR MD["lib/mock-data.ts\nmockInvoices\nmockExpenses\nmockBankAccounts\nmockContacts\nmockBankTransactions"] MD -->|"import { mockInvoices }"| IL["Invoice List\nfilter → sort → display"] MD -->|"import { mockExpenses }"| EP["Expenses Page\nfilter → stats → display"] MD -->|"import { mockBankAccounts }"| BP["Banking Page\ncurrency conversion → display"] MD -->|"import { mockContacts }"| IW["Invoice Wizard\nfilter customers → wizard"] MD -->|"import metrics"| DP["Dashboard\nmetrics → charts"] IL -->|"useMemo(filteredInvoices)"| IT["Invoice Table"] IL -->|"useMemo(summary)"| IS["Summary Bar"] EP -->|"useMemo(filteredExpenses)"| ET["Expense Table"] EP -->|"useMemo(stats)"| ES["Summary Stats"] BP -->|"useMemo(totalBalanceEUR)"| BA["Balance Display"] BP -->|"useMemo(unreconciledTx)"| REC["Reconcile Tab"] ``` ### Mock Data Import Pattern All pages import mock data directly: ```typescript import { mockInvoices, mockExpenses, mockBankAccounts } from "@/lib/mock-data" ``` **Issues:** - No centralized state - Data changes lost on page refresh - No persistence - Each page re-imports same data ### Data Transformation Components transform mock data for display: ```typescript // Dashboard: Calculate metrics from raw data const dashboardMetrics = { cashBalance: 2478170, revenueMTD: 485700, unpaidInvoices: 218200, // ... } // Invoice list: Filter/sort/search const filteredInvoices = mockInvoices.filter(...) // Banking: Currency conversion const totalBalanceEUR = mockBankAccounts.reduce((sum, acc) => { const eurAmount = convertToEUR(acc.balance, acc.currency) return sum + eurAmount }, 0) ``` --- ## Zustand (Installed but Not Used) **Package:** `zustand: ^4.5.0` (installed in package.json) **Current Usage:** None **Planned Usage:** Global state stores for: - User authentication state - Organization/company data - Cached invoices/expenses/contacts - UI preferences (theme, sidebar expanded) --- ## Future State Architecture (Phase 2) ### Planned Zustand Store Structure ```mermaid classDiagram class AuthStore { +user: User | null +isAuthenticated: boolean +isLoading: boolean +token: string | null +error: string | null +login(email, password) Promise~void~ +logout() void +refreshToken() Promise~void~ +checkAuth() Promise~boolean~ } class OrgStore { +organization: Organization | null +settings: OrgSettings +updateSettings(settings) Promise~void~ } class InvoicesStore { +invoices: Invoice[] +isLoading: boolean +error: string | null +fetchInvoices(filters) Promise~void~ +createInvoice(data) Promise~Invoice~ +updateInvoice(id, data) Promise~void~ +deleteInvoice(id) Promise~void~ +sendInvoice(id, emailData) Promise~void~ } class ExpensesStore { +expenses: Expense[] +isLoading: boolean +fetchExpenses(filters) Promise~void~ +createExpense(data) Promise~Expense~ +updateExpense(id, data) Promise~void~ +deleteExpense(id) Promise~void~ } class BankingStore { +accounts: BankAccount[] +transactions: BankTransaction[] +isLoading: boolean +fetchAccounts() Promise~void~ +fetchTransactions(accountId) Promise~void~ +importTransactions(accountId, file) Promise~void~ +reconcileTransaction(txId) Promise~void~ +linkTransaction(txId, type, id) Promise~void~ } class UIStore { +sidebarOpen: boolean +sidebarExpandedSections: string[] +theme: string +toggleSidebar() void +toggleSection(section) void +setTheme(theme) void } AuthStore --> OrgStore : loads org on login AuthStore --> InvoicesStore : scoped by orgId AuthStore --> ExpensesStore : scoped by orgId AuthStore --> BankingStore : scoped by orgId ``` ### Planned Zustand Stores #### Auth Store ```typescript // Planned: stores/auth.ts interface AuthState { user: User | null isAuthenticated: boolean token: string | null login: (email: string, password: string) => Promise logout: () => void refreshToken: () => Promise } ``` #### Organization Store ```typescript // Planned: stores/organization.ts interface OrgState { organization: Organization | null settings: OrgSettings updateSettings: (settings: Partial) => Promise } ``` #### Invoices Store ```typescript // Planned: stores/invoices.ts interface InvoicesState { invoices: Invoice[] isLoading: boolean error: string | null fetchInvoices: (filters: InvoiceFilters) => Promise createInvoice: (data: InvoiceCreateData) => Promise updateInvoice: (id: string, data: Partial) => Promise deleteInvoice: (id: string) => Promise sendInvoice: (id: string, emailData: EmailData) => Promise } ``` #### Expenses Store ```typescript // Planned: stores/expenses.ts interface ExpensesState { expenses: Expense[] isLoading: boolean fetchExpenses: (filters: ExpenseFilters) => Promise createExpense: (data: ExpenseCreateData) => Promise updateExpense: (id: string, data: Partial) => Promise deleteExpense: (id: string) => Promise } ``` #### Banking Store ```typescript // Planned: stores/banking.ts interface BankingState { accounts: BankAccount[] transactions: BankTransaction[] isLoading: boolean fetchAccounts: () => Promise fetchTransactions: (accountId: string) => Promise importTransactions: (accountId: string, file: File) => Promise reconcileTransaction: (txId: string) => Promise linkTransaction: (txId: string, linkType: string, linkId: string) => Promise } ``` #### UI Store ```typescript // Planned: stores/ui.ts interface UIState { sidebarOpen: boolean sidebarExpandedSections: string[] theme: 'light' | 'dark' toggleSidebar: () => void toggleSection: (section: string) => void setTheme: (theme: 'light' | 'dark') => void } ``` ### Migration Strategy 1. **Phase 2a:** Create stores with API integration 2. **Phase 2b:** Replace useState with store hooks in components 3. **Phase 2c:** Add optimistic updates and caching 4. **Phase 2d:** Implement persistence (localStorage for UI prefs) **Example Migration:** **Before (current):** ```typescript // Invoice list page const [invoices, setInvoices] = useState(mockInvoices) ``` **After (Phase 2):** ```typescript // Invoice list page import { useInvoicesStore } from '@/stores/invoices' const { invoices, fetchInvoices, isLoading } = useInvoicesStore() useEffect(() => { fetchInvoices({ status: statusFilter, dateRange }) }, [statusFilter, dateRange]) ``` --- ## API Integration Pattern (Future) ### API Client (lib/api.ts) ```typescript // Planned: lib/api.ts const API_BASE = process.env.NEXT_PUBLIC_API_URL export const api = { get: async (endpoint: string) => { const res = await fetch(`${API_BASE}${endpoint}`, { headers: { Authorization: `Bearer ${getToken()}` } }) if (!res.ok) throw new Error(await res.text()) return res.json() }, post: async (endpoint: string, data: any) => { const res = await fetch(`${API_BASE}${endpoint}`, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${getToken()}` }, body: JSON.stringify(data) }) if (!res.ok) throw new Error(await res.text()) return res.json() }, // PATCH, DELETE... } ``` ### Store Integration ```typescript // Planned: stores/invoices.ts export const useInvoicesStore = create((set, get) => ({ invoices: [], isLoading: false, error: null, fetchInvoices: async (filters) => { set({ isLoading: true, error: null }) try { const data = await api.get(`/invoices?${buildQueryString(filters)}`) set({ invoices: data, isLoading: false }) } catch (error) { set({ error: error.message, isLoading: false }) } }, createInvoice: async (data) => { const invoice = await api.post('/invoices', data) set({ invoices: [...get().invoices, invoice] }) return invoice }, // Other CRUD methods... })) ``` --- ## Future Data Flow ```mermaid flowchart LR subgraph BROWSER["Browser"] subgraph STORES["Zustand Stores"] AS["AuthStore\ntoken, user"] IS["InvoicesStore\ninvoices, isLoading"] ES["ExpensesStore\nexpenses, isLoading"] BS["BankingStore\naccounts, transactions"] US["UIStore\nsidebarOpen, theme"] end subgraph PAGES["Pages"] IP["Invoice List"] IWP["Invoice Wizard"] EP["Expenses"] BP["Banking"] end subgraph PERSIST["Persistence"] LS["localStorage\nUI prefs (UIStore)"] CK["httpOnly Cookie\nJWT token"] end end BE["Backend API\n(Express + PostgreSQL)"] AS -->|"Authorization: Bearer"| BE BE -->|"invoices[]"| IS BE -->|"expenses[]"| ES BE -->|"accounts[], txs[]"| BS IS --> IP IS --> IWP ES --> EP BS --> BP US <-->|persist| LS AS <-->|token| CK ``` --- ## Loading States (Future) **Current:** No loading states (instant mock data) **Future:** Loading skeletons and states ```typescript // Component usage (future) const { invoices, isLoading } = useInvoicesStore() if (isLoading) { return } ``` --- ## Error Handling (Future) **Current:** No error handling (mock data never fails) **Future:** Error boundaries and toast notifications ```typescript // Store error state (future) const { error } = useInvoicesStore() if (error) { toast.error(`Failed to load invoices: ${error}`) } ``` --- ## Optimistic Updates (Future) **Concept:** Update UI immediately, rollback on API failure ```typescript // Example: Delete invoice (future) deleteInvoice: async (id) => { // Optimistic update const prevInvoices = get().invoices set({ invoices: prevInvoices.filter(inv => inv.id !== id) }) try { await api.delete(`/invoices/${id}`) } catch (error) { // Rollback on failure set({ invoices: prevInvoices, error: error.message }) toast.error('Failed to delete invoice') } } ``` --- ## State Persistence (Future) **UI Preferences:** localStorage **Auth Token:** httpOnly cookie (secure) **Data Cache:** sessionStorage (optional, for performance) ```typescript // Example: Persist sidebar state (future) export const useUIStore = create( persist( (set) => ({ sidebarOpen: false, toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })) }), { name: 'bilko-ui-preferences' } ) ) ``` --- ## Summary **Current State:** - React hooks (useState, useMemo, useEffect) - Mock data imports - Local component state - No persistence - No global state - Zustand installed but unused **Future State (Phase 2):** - Zustand stores for global state - API integration layer - Loading/error states - Optimistic updates - State persistence (UI prefs) - JWT token management # Frontend — Status & Architecture # Bilko Web — Next.js Frontend ## BookStack — Provjeri PRVO Prije traženja bilo čega — provjeri BookStack (http://localhost:6875). Centralna baza znanja za tools, skills, hooks, agents, rules, projekte, klijente, dokumentaciju. Ako odgovor postoji tamo — NE TRAŽI dalje. ## Tech Stack - **Framework:** Next.js 15 (App Router) - **React:** 19.0.0 - **TypeScript:** 5.3.0 - **Styling:** Tailwind CSS 4 + shadcn/ui - **State:** Zustand 4.5.0 (installed but mostly React hooks) - **Charts:** Recharts 2.15.0 - **Icons:** Lucide React ## Pages (App Router) All pages under `app/(dashboard)/`: - `dashboard/page.tsx` — Revenue, expenses, charts - `invoices/page.tsx` — Invoice list - `invoices/new/page.tsx` — 6-step invoice wizard - `expenses/page.tsx` — Expense list - `purchases/page.tsx` — Alias to expenses - `banking/page.tsx` — Placeholder - `reports/page.tsx` — Reports hub - `reports/vat/page.tsx` — VAT report - `settings/page.tsx` — User settings ## Components **UI (shadcn/ui):** 17 components in `components/ui/` - avatar, button, card, dialog, dropdown-menu, input, label, select, separator, sheet, skeleton, table, tabs **Layout:** - `components/sidebar.tsx` — Dark navigation sidebar - `components/top-bar.tsx` — Header with user menu ## Design System **Embedded in `tailwind.config.ts`:** 73 tokens - **Colors:** primary (#00E5A0), sidebar dark (#111113), chart colors - **Typography:** Inter font, 8 sizes (xs to 4xl) - **Spacing:** 8px grid (xs, sm, md, lg, xl, 2xl, 3xl) - **Radius:** 4 values (sm: 6px, md: 8px, lg: 12px, full: 9999px) - **Shadows:** card, modal, dropdown - **Breakpoints:** sm (640px), md (768px), lg (1024px), xl (1280px) ## Mock Data **CRITICAL:** All data from `lib/mock-data.ts` - Revenue, expenses, invoices, bank accounts, contacts - **MUST be replaced** with real API calls when backend ready - Flag all mock data usage with comments: `// TODO: Replace with API call` ## State Management - **Zustand installed** but not yet used - Currently: React hooks (useState, useEffect) - **Future:** Migrate to Zustand stores for global state (user, org, auth) ## Development Rules 1. **No production mock data** — Always flag mock data usage 2. **Design system tokens** — Use tokens from tailwind.config.ts, NEVER hardcode colors 3. **Responsive** — Mobile-first, test at all breakpoints 4. **Accessibility** — Use shadcn/ui primitives (Radix UI), semantic HTML 5. **TypeScript strict** — No `any` types without explicit justification ## API Integration (Future) When backend ready: - Create `lib/api.ts` with fetch wrappers - Replace mock-data imports with API calls - Add loading states, error handling - Implement auth token management (JWT) # Component Inventory # Bilko Component Inventory **Last Updated:** 2026-02-20 **Source of Truth:** Filesystem scan of `apps/web/components/` --- ## Component Hierarchy Overview ```mermaid graph TD APP["app/layout.tsx\nRoot Layout"] APP --> LAND["Landing Page\napp/page.tsx"] APP --> AUTH_GRP["Auth Group\napp/(auth)"] APP --> DASH_GRP["Dashboard Group\napp/(dashboard)/layout.tsx"] LAND --> LN["Landing Components\ncomponents/landing/"] LN --> NAVBAR["Navbar"] LN --> HERO["Hero"] LN --> FEATURES["Features"] LN --> PRICING["Pricing"] LN --> TESTIMONIALS["Testimonials"] LN --> FOOTER["Footer"] AUTH_GRP --> LOGIN_PG["LoginPage\ncomponents/ui/input\ncomponents/ui/button"] AUTH_GRP --> REG_PG["RegisterPage\ncomponents/ui/input\ncomponents/ui/button"] DASH_GRP --> SIDEBAR["Sidebar\ncomponents/sidebar.tsx"] DASH_GRP --> TOPBAR["TopBar\ncomponents/top-bar.tsx"] DASH_GRP --> PAGES["Dashboard Pages"] PAGES --> DP["Dashboard\n/dashboard"] PAGES --> IP["Invoices\n/invoices"] PAGES --> IWP["Invoice Wizard\n/invoices/new"] PAGES --> EP["Expenses\n/expenses"] PAGES --> BP["Banking\n/banking"] PAGES --> RP["Reports\n/reports"] PAGES --> PLP["Profit & Loss\n/reports/profit-loss"] PAGES --> VP["VAT Report\n/reports/vat"] PAGES --> SP["Settings\n/settings"] classDef layout fill:#1e2235,color:#89b4fa,stroke:#89b4fa classDef landing fill:#2a1e35,color:#cba6f7,stroke:#cba6f7 classDef auth fill:#2a1e1e,color:#f38ba8,stroke:#f38ba8 classDef page fill:#1e2e1e,color:#a6e3a1,stroke:#a6e3a1 class APP,DASH_GRP layout class LAND,LN,NAVBAR,HERO,FEATURES,PRICING,TESTIMONIALS,FOOTER landing class AUTH_GRP,LOGIN_PG,REG_PG auth class SIDEBAR,TOPBAR,PAGES,DP,IP,IWP,EP,BP,RP,PLP,VP,SP page ``` --- ## Layout Components ### Sidebar - **File:** `components/sidebar.tsx` - **Purpose:** Dark left navigation sidebar with hierarchical menu - **Props:** None (uses pathname from Next.js navigation) - **Features:** - Active link highlighting (primary green border + background) - Dark theme (#111113 background) - Logo at top ("bilko" with SVG icon) - Arrow indicators on Sales and Purchases (hasSubmenu) - **Navigation Items:** - Dashboard (direct link, LayoutDashboard icon) - Sales → `/invoices` (DollarSign icon, hasSubmenu) - Purchases → `/purchases` (CreditCard icon, hasSubmenu) - Banking (Landmark icon) - Reports (BarChart3 icon) - Settings (bottom nav, Settings icon) - **State:** None — uses `usePathname()` for active detection - **Dependencies:** Lucide icons (LayoutDashboard, DollarSign, CreditCard, Landmark, BarChart3, Settings, ChevronRight) ### TopBar - **File:** `components/top-bar.tsx` - **Purpose:** Header bar with search, notifications, user menu - **Props:** - `onMenuClick?: () => void` — callback for mobile menu toggle - **Features:** - Mobile menu button (hidden on desktop) - Mobile logo (hidden on desktop) - Search input (placeholder: "Search... (Cmd+K)") - Notification bell icon (no badge count yet) - User dropdown menu (Profile, Settings, Logout) - **Dependencies:** Lucide icons (Search, Bell, Menu, User), shadcn/ui dropdown-menu - **Mobile Responsive:** Shows menu button + logo on mobile, hides on desktop ```mermaid graph LR SB["Sidebar\ncomponents/sidebar.tsx"] SB --> LOGO["Logo Section\nImage svg + 'bilko' text"] SB --> MAINNAV["Main Navigation\nnav > ul > li"] SB --> BOTTOMNAV["Bottom Navigation\n(Settings)"] MAINNAV --> DASH_LI["Dashboard\nLayoutDashboard icon"] MAINNAV --> SALES_LI["Sales (→ /invoices)\nDollarSign icon + ChevronRight"] MAINNAV --> PURCH_LI["Purchases (→ /purchases)\nCreditCard icon + ChevronRight"] MAINNAV --> BANK_LI["Banking\nLandmark icon"] MAINNAV --> REP_LI["Reports\nBarChart3 icon"] BOTTOMNAV --> SET_LI["Settings\nSettings icon"] SB -->|"isActive(href)"| ACTIVE["Active State\nbg-primary/10 + text-primary"] SB -->|"inactive"| INACTIVE["Hover State\nhover:bg-sidebar-hover"] ``` --- ## UI Components (shadcn/ui) All components in `components/ui/` are from shadcn/ui library (Radix UI primitives + Tailwind). ```mermaid graph TD SHADCN["shadcn/ui Components\ncomponents/ui/"] SHADCN --> FORM_GRP["Form Components"] SHADCN --> DISPLAY_GRP["Display Components"] SHADCN --> OVERLAY_GRP["Overlay Components"] SHADCN --> FEEDBACK_GRP["Feedback Components"] FORM_GRP --> INPUT["Input\ntext, email, number, date, search"] FORM_GRP --> SELECT["Select\nRadix Select primitive\nSelectTrigger + SelectContent + SelectItem"] FORM_GRP --> TEXTAREA["Textarea\nmulti-line input, 3-6 rows"] FORM_GRP --> LABEL["Label\nRadix Label, accessible"] DISPLAY_GRP --> CARD["Card\nCard + CardHeader + CardTitle\n+ CardDescription + CardContent + CardFooter"] DISPLAY_GRP --> TABLE["Table\nTable + TableHeader + TableBody\n+ TableRow + TableHead + TableCell"] DISPLAY_GRP --> BADGE["Badge\ndefault / secondary / success\n/ warning / destructive"] DISPLAY_GRP --> AVATAR["Avatar\nRadix Avatar (not yet used)"] DISPLAY_GRP --> SEPARATOR["Separator\nhorizontal/vertical"] DISPLAY_GRP --> SKELETON["Skeleton\npulse animation (not yet used)"] OVERLAY_GRP --> DIALOG["Dialog\nRadix Dialog\nDialogContent + DialogHeader\n+ DialogFooter"] OVERLAY_GRP --> DROPDOWN["DropdownMenu\nRadix DropdownMenu\nTrigger + Content + Item"] OVERLAY_GRP --> TABS["Tabs\nRadix Tabs\nTabsList + TabsTrigger + TabsContent"] OVERLAY_GRP --> SHEET["Sheet\nRadix Dialog styled\n(not yet used)"] FEEDBACK_GRP --> BUTTON["Button\ndefault / destructive / outline\n/ secondary / ghost / link\nsm / default / lg / icon sizes"] ``` ### Avatar - **File:** `components/ui/avatar.tsx` - **Purpose:** User avatar with fallback - **Radix Primitive:** `@radix-ui/react-avatar` - **Usage:** Not yet used in current pages (ready for user profile) ### Badge - **File:** `components/ui/badge.tsx` - **Purpose:** Status indicators (draft, sent, paid, overdue, success, warning, etc.) - **Variants:** default, secondary, success, warning, destructive - **Usage:** - Invoice status badges - Expense status badges - "Coming Soon" tags on report cards - User status in settings - **Props:** `variant?: "default" | "secondary" | "destructive" | "outline" | "success" | "warning"` ### Button - **File:** `components/ui/button.tsx` - **Purpose:** Primary UI button - **Variants:** default, destructive, outline, secondary, ghost, link - **Sizes:** default, sm, lg, icon - **Usage:** All action buttons throughout the app - **Radix Primitive:** `@radix-ui/react-slot` (asChild support) ### Card - **File:** `components/ui/card.tsx` - **Purpose:** Content container with header/content sections - **Sub-components:** - `Card` — outer wrapper - `CardHeader` — header section - `CardTitle` — title text - `CardDescription` — subtitle/description text - `CardContent` — body content - `CardFooter` — footer section (not used yet) - **Usage:** - Dashboard metric cards - Report cards - Settings content wrapper - Banking account/transaction tables - **Shadow:** `shadow-card` (0 2px 8px rgba(0, 0, 0, 0.08)) ### Dialog - **File:** `components/ui/dialog.tsx` - **Purpose:** Modal dialogs - **Radix Primitive:** `@radix-ui/react-dialog` - **Sub-components:** - `Dialog` — wrapper - `DialogTrigger` — trigger button - `DialogContent` — modal content - `DialogHeader` — header section - `DialogTitle` — modal title - `DialogDescription` — modal description - `DialogFooter` — action buttons - **Usage:** - Add Customer dialog (invoice wizard) - Add Expense dialog - **Overlay:** Black 50% opacity, click-to-close ### Dropdown Menu - **File:** `components/ui/dropdown-menu.tsx` - **Purpose:** Context menus and dropdowns - **Radix Primitive:** `@radix-ui/react-dropdown-menu` - **Sub-components:** - `DropdownMenu` — wrapper - `DropdownMenuTrigger` — trigger button - `DropdownMenuContent` — menu content - `DropdownMenuItem` — menu item - `DropdownMenuLabel` — label text - `DropdownMenuSeparator` — divider - **Usage:** - Invoice row actions (view, edit, send, download, delete) - User menu in top bar - **Shadow:** `shadow-dropdown` (0 4px 16px rgba(0, 0, 0, 0.10)) ### Input - **File:** `components/ui/input.tsx` - **Purpose:** Text input field - **Types Supported:** text, email, number, date, search - **Usage:** - All form inputs (invoice wizard, expense form, settings) - Search inputs (invoice list, expense list) - Filter inputs - **Styling:** Border, padding, focus ring (primary color) ### Label - **File:** `components/ui/label.tsx` - **Purpose:** Form field labels - **Radix Primitive:** `@radix-ui/react-label` - **Usage:** All form field labels - **Accessibility:** Proper label-input association ### Select - **File:** `components/ui/select.tsx` - **Purpose:** Dropdown select input - **Radix Primitive:** `@radix-ui/react-select` - **Sub-components:** - `Select` — wrapper - `SelectTrigger` — trigger button - `SelectValue` — selected value display - `SelectContent` — dropdown content - `SelectItem` — option item - **Usage:** - Status filters (invoices, expenses) - Date range filters - Currency selectors - Category selectors - Settings dropdowns - **Styling:** Chevron icon, border, focus ring ### Separator - **File:** `components/ui/separator.tsx` - **Purpose:** Visual divider line - **Radix Primitive:** `@radix-ui/react-separator` - **Orientations:** horizontal, vertical - **Usage:** Not heavily used yet (potential in settings/forms) ### Sheet - **File:** `components/ui/sheet.tsx` - **Purpose:** Slide-out panel (mobile sidebar alternative) - **Radix Primitive:** `@radix-ui/react-dialog` (styled as sheet) - **Usage:** Not yet used (potential for mobile sidebar instead of overlay) - **Direction:** Can slide from left/right/top/bottom ### Skeleton - **File:** `components/ui/skeleton.tsx` - **Purpose:** Loading placeholder - **Usage:** Used in `AuthProvider` loading state and `reports/profit-loss` page - **Animation:** Pulse animation - **Future Use:** Data fetching loading states ### Table - **File:** `components/ui/table.tsx` - **Purpose:** Data table - **Sub-components:** - `Table` — wrapper - `TableHeader` — header section - `TableBody` — body section - `TableRow` — row - `TableHead` — header cell - `TableCell` — data cell - `TableCaption` — caption text (not used) - `TableFooter` — footer section (not used) - **Usage:** - Invoice list - Expense list - Bank transactions - VAT transactions - Recent transactions (dashboard) - Settings (users, integrations) - **Styling:** Border, alternating row hover ### Tabs - **File:** `components/ui/tabs.tsx` - **Purpose:** Tab navigation - **Radix Primitive:** `@radix-ui/react-tabs` - **Sub-components:** - `Tabs` — wrapper - `TabsList` — tab button container - `TabsTrigger` — tab button - `TabsContent` — tab panel - **Usage:** - Banking page (Accounts, Reconcile, Transactions) - VAT Report (Reconciliation, Audit, Summary) - **Styling:** Primary underline for active tab ### Textarea - **File:** `components/ui/textarea.tsx` - **Purpose:** Multi-line text input - **Usage:** - Invoice notes (customization step) - Invoice terms (customization step) - Email message (send step) - Expense description (optional) - **Rows:** Configurable (default: 3-6 rows) --- ## Landing Components ```mermaid graph TD LP["Landing Page\napp/page.tsx"] LP --> LNAV["Navbar\ncomponents/landing/navbar.tsx\nlogo + nav links + CTA button"] LP --> LHERO["Hero\ncomponents/landing/hero.tsx\nheadline + subtext + CTAs"] LP --> LFEAT["Features\ncomponents/landing/features.tsx\nfeature grid cards"] LP --> LPRICE["Pricing\ncomponents/landing/pricing.tsx\npricing tiers"] LP --> LTESTI["Testimonials\ncomponents/landing/testimonials.tsx\ncustomer quotes"] LP --> LFOOT["Footer\ncomponents/landing/footer.tsx\nlinks + copyright"] ``` --- ## Chatbot Components ```mermaid graph TD CW["ChatWidget\ncomponents/chatbot/ChatWidget.tsx\nfloating chat button + panel"] CW --> CM["ChatMessage\ncomponents/chatbot/ChatMessage.tsx\nindividual message bubble"] CW --> CI["ChatInput\ncomponents/chatbot/ChatInput.tsx\ntext input + send button"] ``` --- ## Chart Components Charts are built with **Recharts 2.15.0** (not custom components). Key chart types used: - **BarChart** — P&L trend, receivables aging - **PieChart** — Expenses by category (donut) - **ResponsiveContainer** — Wrapper for all charts (100% width, fixed height) - **XAxis, YAxis, CartesianGrid, Tooltip, Legend** — Chart primitives **Chart Colors (from tailwind.config.ts):** - Revenue: `#22C55E` (chart-revenue) - Expense: `#EF4444` (chart-expense) - Profit: `#3B82F6` (chart-profit) - Neutral: `#6B7280` (chart-neutral) --- ## Utility Components ### cn (lib/utils.ts) - **Purpose:** Utility function for conditional class names - **Usage:** `cn("base-class", condition && "conditional-class")` - **Dependencies:** `clsx` + `tailwind-merge` ### AuthProvider (lib/auth-provider.tsx) - **Purpose:** Route guard — redirects unauthenticated users to `/login` - **Demo Mode:** Activates automatically when `NEXT_PUBLIC_API_URL` is not set, bypassing auth check - **Public Paths:** `/login`, `/register`, `/forgot-password`, `/` - **Loading State:** Uses `Skeleton` component while checking auth --- ## Page-Specific Components **Currently none standalone.** All components are reusable shadcn/ui components + layout components. No page-specific extracted components yet. Potential future page-specific components: - `InvoicePreview` (extracted from wizard step 5) - `MetricCard` (extracted from dashboard) - `TransactionRow` (extracted from dashboard/banking) - `ExpenseFormDialog` (extracted from expenses page) --- ## Component Usage Map | Component | Used In | Count | |-----------|---------|-------| | Button | All pages | 50+ | | Card | Dashboard, Reports, Banking, Settings, Expenses | 20+ | | Table | Invoices, Expenses, Banking, Reports, Dashboard, Settings | 10+ | | Input | Invoice wizard, Expenses, Settings, TopBar | 30+ | | Select | Invoices, Expenses, Banking, Settings, Invoice wizard | 20+ | | Badge | Invoices, Expenses, Banking, Reports, Settings | 15+ | | Dialog | Invoice wizard, Expenses | 2 | | Dropdown Menu | Invoices, TopBar | 2 | | Tabs | Banking, VAT Report | 2 | | Textarea | Invoice wizard | 3 | | Sidebar | All pages | 1 | | TopBar | All pages | 1 | | Label | All forms | 40+ | | Skeleton | AuthProvider, P&L Report | 2+ | | Separator | Minimal | 1-2 | | Avatar | None yet | 0 | | Sheet | None yet | 0 | --- ## Component Relationships by Page ```mermaid graph LR subgraph INVOICE_LIST["Invoice List /invoices"] IL_CARD["Card\n(filter container)"] IL_SEL["Select\n(status filter)"] IL_INP["Input\n(search)"] IL_TBL["Table\n(invoice rows)"] IL_BADGE["Badge\n(status)"] IL_DD["DropdownMenu\n(row actions)"] IL_BTN["Button\n(New Invoice)"] end subgraph INVOICE_WIZ["Invoice Wizard /invoices/new"] IW_DLG["Dialog\n(Add Customer)"] IW_SEL["Select\n(customer, currency, VAT)"] IW_INP["Input\n(fields per step)"] IW_TA["Textarea\n(notes, terms, email)"] IW_BTN["Button\n(Back, Next, Send)"] end subgraph BANKING["Banking /banking"] BK_TABS["Tabs\n(Accounts, Reconcile, Txs)"] BK_TBL["Table\n(transactions)"] BK_BADGE["Badge\n(match confidence)"] BK_BTN["Button\n(approve, link, create)"] end subgraph REPORTS["Reports /reports/vat"] R_TABS["Tabs\n(3-step VAT wizard)"] R_TBL["Table\n(VAT transactions)"] R_CARD["Card\n(return boxes)"] R_BADGE["Badge\n(invoice/expense type)"] end ``` --- ## Notes - **All UI components** are from shadcn/ui (no custom variants yet) - **No phantom components** — this list is exhaustive based on filesystem scan - **Radix UI primitives** provide accessibility out of the box - **Tailwind CSS 4** for styling (all tokens in tailwind.config.ts) - **Lucide React** for all icons (consistent icon library) - **Landing components** exist in `components/landing/` — not covered in original docs - **Chatbot components** exist in `components/chatbot/` — ChatWidget, ChatMessage, ChatInput # Design System # Bilko Design System **Source:** Extracted from `apps/web/tailwind.config.ts` + brand identity spec **Design Language:** Modern Balkan accounting SaaS — clean, professional, accessible --- ## Token Architecture Overview ```mermaid graph TD TC["tailwind.config.ts\n(73 design tokens)"] TC --> COLORS["Color Tokens"] TC --> TYPE["Typography Tokens"] TC --> SPACE["Spacing Tokens"] TC --> RADIUS["Border Radius Tokens"] TC --> SHADOW["Shadow Tokens"] TC --> BP["Breakpoint Tokens"] COLORS --> PRIMARY["Primary Brand\n#00E5A0 / #00B380 / #33EBB3"] COLORS --> STATUS["Status Colors\nsuccess / warning / error / info"] COLORS --> TEXT["Text Scale\nprimary / secondary / muted"] COLORS --> BG["Backgrounds\nlight #FAFAFA / surface #FFF"] COLORS --> SIDEBAR["Sidebar (Dark Theme)\nbg / text / text-muted / active / hover"] COLORS --> CHART["Chart Colors\nrevenue / expense / profit / neutral"] TYPE --> FONT["Inter (Google Fonts)\nxs 12px → 4xl 40px"] TYPE --> WEIGHT["Weights\n400 / 500 / 600 / 700"] SPACE --> GRID["8px Grid\nxs 4px → 3xl 64px"] RADIUS --> SIZES["6px / 8px / 12px / full"] SHADOW --> ELEV["card / modal / dropdown"] BP --> SCREEN["640px / 768px / 1024px / 1280px"] ``` --- ## Color Palette ### Primary Brand Colors ``` Primary: #00E5A0 (Vibrant teal-green — primary CTA, links, active states) Primary Dark: #00B380 (Darker variant for hover states) Primary Light: #33EBB3 (Lighter variant for backgrounds) ``` ### Status Colors ``` Success: #22C55E (Green — success states, paid invoices, positive metrics) Warning: #F59E0B (Amber — warnings, pending items, aging invoices) Error: #EF4444 (Red — errors, overdue invoices, negative actions) Info: #3B82F6 (Blue — informational messages, neutral data) ``` ### Text Colors ``` Text Primary: #111113 (Near-black — body text, headings) Text Secondary: #6B7280 (Gray-600 — secondary text, labels) Text Muted: #888888 (Gray-500 — muted text, placeholders) ``` ### Background Colors ``` Background Light: #FAFAFA (Off-white — main content area background) Background Surface: #FFFFFF (White — card backgrounds, modals) ``` ### Border Color ``` Border: #E5E7EB (Gray-200 — borders, dividers) ``` ### Chart Colors ``` Chart Revenue: #22C55E (Green — revenue bars/lines) Chart Expense: #EF4444 (Red — expense bars/lines) Chart Profit: #3B82F6 (Blue — profit bars/lines) Chart Neutral: #6B7280 (Gray — neutral data points) ``` ### Sidebar Colors (Dark Theme) ``` Sidebar BG: #111113 (Near-black — sidebar background) Sidebar Text: #FAFAFA (Off-white — sidebar text) Sidebar Text Muted: #888888 (Gray — inactive menu items) Sidebar Active: #00E5A0 (Primary green — active menu item) Sidebar Hover: #1F1F23 (Slightly lighter black — hover state) ``` **Usage:** - Sidebar = dark (#111113) with light text - Content area = light (#FAFAFA) with dark text - Cards = white (#FFFFFF) surface on light background --- ## Color Relationship Map ```mermaid graph LR subgraph BRAND["Brand Identity"] P["Primary\n#00E5A0"] PD["Primary Dark\n#00B380\n(hover)"] PL["Primary Light\n#33EBB3\n(bg tint)"] P --> PD P --> PL end subgraph LAYOUT["Layout Zones"] SBG["Sidebar BG\n#111113"] SBG --> STEXT["Sidebar Text\n#FAFAFA"] SBG --> SMUTED["Sidebar Muted\n#888888"] SBG --> SACTIVE["Active Item\n#00E5A0"] CBG["Content BG\n#FAFAFA"] CBG --> SURF["Card Surface\n#FFFFFF"] CBG --> BORDER["Border\n#E5E7EB"] end subgraph SEMANTIC["Semantic Status"] SUCCESS["Success\n#22C55E\n(paid, positive)"] WARN["Warning\n#F59E0B\n(pending, aging)"] ERR["Error\n#EF4444\n(overdue, delete)"] INFO["Info\n#3B82F6\n(neutral data)"] end subgraph TEXT_SCALE["Text Scale"] TP["Text Primary\n#111113"] TS["Text Secondary\n#6B7280"] TM["Text Muted\n#888888"] end P -->|"active states"| SACTIVE SUCCESS -->|"chart-revenue"| CR["Chart Revenue"] ERR -->|"chart-expense"| CE["Chart Expense"] INFO -->|"chart-profit"| CP["Chart Profit"] ``` --- ## Typography ### Font Family ``` Sans Serif: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif ``` **Source:** Google Fonts Inter (variable font) **Fallback:** System UI fonts for performance ### Font Sizes ``` xs: 12px (Small badges, captions) sm: 14px (Table cells, secondary text, form labels) base: 16px (Body text, default) lg: 18px (Subheadings, emphasized text) xl: 20px (Section titles) 2xl: 24px (Card titles, small headings) 3xl: 32px (Page headings) 4xl: 40px (Hero text, large numbers) ``` ### Font Weights ``` normal: 400 (Body text) medium: 500 (Emphasis, table headers) semibold: 600 (Subheadings, button text) bold: 700 (Headings, metric numbers) ``` ### Type Scale Usage - **Headings:** - Page title: `text-3xl font-bold` (32px, 700) - Section title: `text-2xl font-bold` (24px, 700) - Card title: `text-base font-semibold` (16px, 600) - **Body:** - Default: `text-base font-normal` (16px, 400) - Table cells: `text-sm font-medium` (14px, 500) - Muted text: `text-sm text-text-muted` (14px, #888888) - **Numbers:** - Metrics: `text-3xl font-bold` (32px, 700) - Totals: `text-2xl font-bold` (24px, 700) - Amounts: `text-base font-medium` (16px, 500) --- ## Spacing System (8px Grid) ``` xs: 4px (Tight spacing, icon gaps) sm: 8px (Input padding, small gaps) md: 16px (Default spacing, card padding) lg: 24px (Section spacing) xl: 32px (Large section spacing) 2xl: 48px (Major section breaks) 3xl: 64px (Hero spacing) ``` **Usage:** - Card padding: `p-6` (24px) - Form field gap: `space-y-4` (16px) - Section spacing: `space-y-6` (24px) - Grid gap: `gap-6` (24px) **Consistency:** All spacing uses 8px increments (4px, 8px, 16px, 24px, 32px, 48px, 64px) --- ## Border Radius ``` sm: 6px (Small elements, badges) md: 8px (Buttons, inputs, cards) lg: 12px (Modals, large cards) full: 9999px (Circular elements, pills) ``` **Usage:** - Cards: `rounded-md` (8px) - Buttons: `rounded-md` (8px) - Inputs: `rounded-md` (8px) - Badges: `rounded-sm` (6px) - User avatar: `rounded-full` (circular) --- ## Shadows ``` Card Shadow: 0 2px 8px rgba(0, 0, 0, 0.08) (Subtle card elevation) Modal Shadow: 0 8px 24px rgba(0, 0, 0, 0.12) (Dialog/modal elevation) Dropdown Shadow: 0 4px 16px rgba(0, 0, 0, 0.10) (Dropdown menu elevation) ``` **Usage:** - Cards: `shadow-card` - Modals/dialogs: `shadow-modal` - Dropdown menus: `shadow-dropdown` **Philosophy:** Subtle shadows for depth, avoid heavy shadows (material design style) --- ## Design Token Relationships ```mermaid classDiagram class ButtonTokens { +height_default: 40px +height_sm: 32px +height_lg: 48px +padding_x: 16px +border_radius: 8px (md) +font_size: 14px medium +variant_default: primary-bg white-text +variant_outline: border-only transparent +variant_ghost: no-border no-bg +variant_destructive: error-red white-text } class InputTokens { +height: 40px +padding_x: 12px +border: 1px solid #E5E7EB +border_radius: 8px (md) +font_size: 14px normal +focus_ring: 2px primary-color } class CardTokens { +background: #FFFFFF +border: 1px solid #E5E7EB +border_radius: 8px (md) +shadow: 0 2px 8px rgba-8pct +padding: 24px } class BadgeTokens { +padding: 4px 8px +border_radius: 6px (sm) +font_size: 12px medium +variant_success: green-bg +variant_warning: amber-bg +variant_destructive: red-bg +variant_secondary: light-gray-bg } class TableTokens { +row_height: 48px +cell_padding_x: 12px +cell_padding_y: 16px +border: 1px solid #E5E7EB +hover: light-gray #FAFAFA +header_weight: medium +header_color: text-secondary } class ColorTokens { +primary: #00E5A0 +primary_dark: #00B380 +success: #22C55E +warning: #F59E0B +error: #EF4444 +info: #3B82F6 +text_primary: #111113 +text_secondary: #6B7280 +border: #E5E7EB +surface: #FFFFFF +bg_light: #FAFAFA } ButtonTokens --> ColorTokens : uses primary, error InputTokens --> ColorTokens : uses border, primary (focus) CardTokens --> ColorTokens : uses surface, border BadgeTokens --> ColorTokens : uses success, warning, error TableTokens --> ColorTokens : uses border, bg-light (hover) ``` --- ## Breakpoints ``` sm: 640px (Small tablets, large phones) md: 768px (Tablets) lg: 1024px (Small desktops, large tablets) xl: 1280px (Desktops) ``` **Mobile-First Strategy:** - Base styles = mobile (< 640px) - `sm:` = small tablet (640px+) - `md:` = tablet/desktop toggle (768px+) - `lg:` = desktop layout (1024px+) - `xl:` = wide desktop (1280px+) **Responsive Patterns:** - Grid: `grid-cols-1 md:grid-cols-2 lg:grid-cols-3` - Sidebar: `hidden md:block` (hide on mobile) - Filters: `flex-col sm:flex-row` (stack on mobile, row on tablet+) --- ## Responsive Layout Behavior ```mermaid graph TD subgraph MOBILE["Mobile (< 640px)"] M1["Sidebar: hidden\n(overlay when toggled)"] M2["TopBar: shows hamburger + logo"] M3["Grid: single column"] M4["Filters: stacked vertically"] M5["Tables: horizontal scroll"] end subgraph TABLET["Tablet (768px+)"] T1["Sidebar: visible, persistent"] T2["TopBar: shows search + user menu"] T3["Grid: 2 columns"] T4["Filters: row layout"] T5["Tables: full width"] end subgraph DESKTOP["Desktop (1024px+)"] D1["Sidebar: 256px fixed width"] D2["TopBar: full bar"] D3["Grid: 3 columns"] D4["Settings: sidebar + content split"] D5["Banking: full tab content"] end ``` --- ## Component Tokens ### Button - **Height:** 40px (default), 32px (sm), 48px (lg), 40px (icon) - **Padding:** 16px horizontal (default), 12px (sm), 20px (lg) - **Border Radius:** 8px (md) - **Font:** 14px medium (default), 12px (sm), 16px (lg) - **Variants:** - Default: Primary green background, white text - Outline: Border only, transparent background - Ghost: No border, no background, hover shows background - Destructive: Error red background, white text ### Input - **Height:** 40px - **Padding:** 12px horizontal - **Border:** 1px solid #E5E7EB (border color) - **Border Radius:** 8px (md) - **Font:** 14px normal - **Focus:** Primary color ring (2px) ### Card - **Background:** #FFFFFF (surface) - **Border:** 1px solid #E5E7EB - **Border Radius:** 8px (md) - **Shadow:** 0 2px 8px rgba(0, 0, 0, 0.08) - **Padding:** 24px (default content padding) ### Badge - **Padding:** 4px 8px - **Border Radius:** 6px (sm) - **Font:** 12px medium - **Variants:** - Default: Gray background - Success: Green background - Warning: Amber background - Destructive: Red background - Secondary: Light gray ### Table - **Row Height:** 48px (default) - **Cell Padding:** 12px horizontal, 16px vertical - **Border:** 1px solid #E5E7EB (between rows) - **Hover:** Light gray background (#FAFAFA) - **Header:** Medium font weight, secondary text color --- ## Icon System **Library:** Lucide React (v0.469.0) **Size:** Consistent 16px (`w-4 h-4`) or 20px (`w-5 h-5`) **Usage:** - Buttons: 16px icon + 8px gap from text - Menu items: 20px icon + 12px gap from text - Standalone: 24px or larger **Common Icons:** - Plus (add actions) - Search (search inputs) - Menu (mobile sidebar toggle) - User (user menu) - Bell (notifications) - ChevronDown/Right (expandable sections) - Check (success, reconciliation) - X (close, delete) - Download (export actions) - Send (send email) --- ## Chart Design Tokens ### Chart Colors (Recharts) ``` Revenue: #22C55E (Green bars) Expense: #EF4444 (Red bars) Profit: #3B82F6 (Blue bars) Neutral: #6B7280 (Gray — when no semantic meaning) ``` ### Chart Typography - **Axis Labels:** 12px normal - **Tooltip:** 14px medium - **Legend:** 12px normal ### Chart Layout - **Responsive Container:** 100% width, fixed height (250px default) - **Cartesian Grid:** Dashed, #E5E7EB stroke - **Tooltip Background:** White with border - **Border Radius:** 8px (md) --- ## Accessibility ### Color Contrast - All text colors meet WCAG AA standards - Primary text (#111113) on white = 16.17:1 (AAA) - Secondary text (#6B7280) on white = 4.69:1 (AA) - Primary green (#00E5A0) on white = 2.92:1 (fails — used for accents only, not body text) ### Focus Indicators - All interactive elements have visible focus ring - Focus ring color: Primary green (#00E5A0) - Focus ring width: 2px ### Semantic HTML - Proper heading hierarchy (h1 → h2 → h3) - Form labels properly associated with inputs - ARIA labels on icon-only buttons - Table headers properly scoped --- ## Design Principles 1. **Clarity over Decoration** — Data-first, minimal ornamentation 2. **Consistent Spacing** — 8px grid, predictable rhythm 3. **Accessible by Default** — WCAG AA minimum, Radix UI primitives 4. **Mobile-First** — Responsive from 375px+ (iPhone SE) 5. **Dark Sidebar + Light Content** — Clear visual separation 6. **Primary Color as Accent** — Green (#00E5A0) for actions, not backgrounds 7. **Subtle Shadows** — Elevation without heaviness 8. **Data-Dense UI** — Tables, charts, metrics — optimized for information density --- ## Brand Identity Alignment From `~/system/specs/bilko-brand-identity.md`: - **Primary Color:** #00E5A0 (implemented) - **Typography:** Inter (implemented) - **Tone:** Modern, professional, Balkan-focused (implemented) - **Dark Sidebar:** #111113 (implemented) - **Logo Placement:** Top left sidebar (implemented) --- ## Future Tokens (Phase 2) When implementing API integration: - **Loading States:** Skeleton component colors - **Error States:** Error message backgrounds (#FEF2F2, light red) - **Success States:** Success message backgrounds (#F0FDF4, light green) - **Toast Notifications:** Background, text, border colors - **Dark Mode:** Full dark theme variant (optional) # Forms & Validation # Bilko Forms Documentation **Current State:** Native HTML forms with React state **Validation:** Client-side JavaScript validation (no schema validation yet) **Future State:** Zod schemas for validation, react-hook-form for form management --- ## Forms Overview ```mermaid graph TD FORMS["Bilko Forms"] FORMS --> IW["Invoice Wizard\n6-step multi-page form\n/invoices/new"] FORMS --> EF["Expense Form\nDialog (modal)\n/expenses"] FORMS --> SF["Settings Forms\n6 sections\n/settings"] FORMS --> AUTH["Auth Forms\nLogin + Register\n/login /register"] IW --> IW1["Step 1: Customer"] IW --> IW2["Step 2: Details"] IW --> IW3["Step 3: Line Items"] IW --> IW4["Step 4: Customization"] IW --> IW5["Step 5: Preview"] IW --> IW6["Step 6: Send"] EF --> EF1["Amount + Currency"] EF --> EF2["Category + Date"] EF --> EF3["Vendor + Payment Method"] EF --> EF4["Receipt Upload (placeholder)"] EF --> EF5["Description (optional)"] SF --> SF1["Company Profile"] SF --> SF2["Tax & Compliance"] SF --> SF3["Notification Preferences"] SF --> SF4["Security Settings"] AUTH --> AUTH1["Login\nemail + password"] AUTH --> AUTH2["Register\nname, company, email, password, country"] ``` --- ## Invoice Creation Wizard (6-Step Multi-Page Form) **Route:** `/invoices/new` **File:** `app/(dashboard)/invoices/new/page.tsx` ### Wizard State Machine ```mermaid stateDiagram-v2 [*] --> Step1_Customer : navigate to /invoices/new Step1_Customer : Step 1 — Customer Selection Step1_Customer : Select existing customer (dropdown) Step1_Customer : OR open Add Customer dialog Step1_Customer : Validation: customer required Step2_Details : Step 2 — Invoice Details Step2_Details : invoiceNumber (auto-generated) Step2_Details : issueDate, dueDate Step2_Details : netTerms (Net 15/30/60 → auto-updates dueDate) Step2_Details : currency (EUR/RSD/BAM) Step3_LineItems : Step 3 — Line Items Step3_LineItems : description (required), qty, unitPrice Step3_LineItems : vatRate (0/10/17/20/25%) Step3_LineItems : total auto-calculated (read-only) Step3_LineItems : Validation: min 1 item with description Step4_Customize : Step 4 — Customization Step4_Customize : notes (optional textarea) Step4_Customize : terms (optional textarea) Step4_Customize : No validation required Step5_Preview : Step 5 — Preview Step5_Preview : Read-only invoice render Step5_Preview : All data from previous steps Step5_Preview : No validation Step6_Send : Step 6 — Send / Save Step6_Send : to (email, pre-filled from customer) Step6_Send : subject, message (pre-filled template) Step6_Send : sendCopy (checkbox) Step6_Send : Save as Draft / Download PDF / Send Invoice Step1_Customer --> Step2_Details : Next (customer selected) Step1_Customer --> Step1_Customer : Next (no customer) — alert shown Step2_Details --> Step3_LineItems : Next Step2_Details --> Step1_Customer : Back Step3_LineItems --> Step4_Customize : Next (has valid item) Step3_LineItems --> Step3_LineItems : Next (no items) — alert shown Step3_LineItems --> Step2_Details : Back Step4_Customize --> Step5_Preview : Next Step4_Customize --> Step3_LineItems : Back Step5_Preview --> Step6_Send : Next Step5_Preview --> Step4_Customize : Back Step6_Send --> [*] : Send Invoice → alert + redirect /invoices Step6_Send --> Step5_Preview : Back Step6_Send --> [*] : Cancel → confirm dialog → /invoices ``` ### Form Structure #### Step 1: Customer Selection **Fields:** - **Customer** (required) - Type: Select (dropdown) - Options: All customers from contacts (type='customer') - Can add new customer via dialog - Validation: Required before proceeding to step 2 **Add Customer Dialog:** - **Name** (required) - Type: Text - Validation: Required - **Email** (required) - Type: Email - Validation: Required, valid email format - **Phone** (optional) - Type: Tel - Validation: None - **Tax ID** (optional) - Type: Text - Validation: None **Validation:** - Alert shown if user tries to proceed without selecting customer - Form submission triggers inline alert (no schema validation) --- #### Step 2: Invoice Details **Fields:** - **Invoice Number** - Type: Text - Default: Auto-generated (e.g., "INV-2026-009") - Validation: None (can be edited) - **Issue Date** - Type: Date - Default: Today's date - Validation: None - **Due Date** - Type: Date - Default: 30 days from issue date - Validation: None - **Net Terms** (shortcut selector) - Type: Select - Options: Net 15, Net 30, Net 60 - Behavior: Auto-calculates due date when selected - Validation: None - **Currency** - Type: Select - Options: EUR, RSD, BAM - Default: EUR - Validation: None **Behavior:** - Net terms selector auto-updates due date field - All fields can be manually overridden --- #### Step 3: Line Items **Repeating Fields (Line Items):** Each line item contains: - **Description** (required) - Type: Text - Placeholder: "Service or product description" - Validation: At least one item must have description - **Quantity** - Type: Number - Default: 1 - Min: 1 - Validation: Positive number - **Unit Price** - Type: Number - Default: 0 - Min: 0 - Step: 0.01 - Validation: Non-negative - **VAT Rate** - Type: Select - Options: 0%, 10%, 17%, 20%, 25% - Default: 20% - Validation: None - **Total** (calculated, read-only) - Type: Text (disabled input) - Calculation: `quantity * unitPrice * (1 + vatRate/100)` - Display: Formatted currency **Actions:** - **Add Item** button: Appends new empty line item - **Remove Item** button (X): Removes line item (disabled if only 1 item) **Totals Display (read-only):** - Subtotal (before VAT) - VAT Total - Grand Total (with VAT) **Validation:** - Alert shown if user tries to proceed with all empty descriptions - Form submission requires at least one item with description --- #### Step 4: Customization **Fields:** - **Notes** (optional) - Type: Textarea - Default: "Thank you for your business!" - Placeholder: "Add a note for your customer..." - Validation: None - **Terms** (optional) - Type: Textarea - Default: "Payment due within 30 days." - Placeholder: "Payment terms and conditions..." - Validation: None **Behavior:** - Both fields are optional - Default values pre-populated but can be cleared --- #### Step 5: Preview (Read-Only) **No form fields.** Displays formatted invoice preview with all data from previous steps. **Preview Elements:** - Invoice title ("INVOICE") - From/To addresses - Invoice number, date, due date - Line items table - Subtotal, VAT, Total - Notes (if provided) - Terms (if provided) **No validation.** Step is purely visual review. --- #### Step 6: Send/Save **Email Form:** - **To** (required) - Type: Email - Default: Pre-filled with customer email - Validation: Valid email format (no schema yet) - **Subject** (required) - Type: Text - Default: "Invoice {invoiceNumber}" - Validation: Required - **Message** (required) - Type: Textarea - Default: Pre-filled template - Rows: 6 - Validation: Required - **Send Me a Copy** (optional) - Type: Checkbox - Default: Unchecked - Validation: None **Action Buttons:** - **Save as Draft** — Alert placeholder (no API) - **Download PDF** — Alert placeholder (no API) - **Send Invoice** — Alert + redirect to `/invoices` (no API) **Validation:** - No schema validation - Form submission triggers alert "Invoice sent!" --- ### Line Item Data Flow ```mermaid flowchart LR DESC["description\n(text input)"] QTY["quantity\n(number input)"] PRICE["unitPrice\n(number input)"] VAT["vatRate\n(Select: 0/10/17/20/25%)"] QTY --> CALC["useMemo(totals)\nsubtotal = qty * price\nvatTotal = subtotal * rate\ntotal = subtotal + vatTotal"] PRICE --> CALC VAT --> CALC CALC --> ROW_TOTAL["Row Total\n(read-only display)"] CALC --> SUBTOTAL["Subtotal\n(sum of all rows)"] CALC --> VAT_TOTAL["VAT Total\n(sum of all VAT)"] CALC --> GRAND_TOTAL["Grand Total\n(subtotal + vatTotal)"] DESC -->|"required"| VALID["Validation\nAt least 1 item\nwith description"] ``` --- ### Form State Management **Local State:** ```typescript const [step, setStep] = useState(1) const [customer, setCustomer] = useState(null) const [showAddCustomer, setShowAddCustomer] = useState(false) const [invoiceDetails, setInvoiceDetails] = useState({ number: "INV-2026-009", issueDate: "2026-02-20", dueDate: "2026-03-22", currency: "EUR" }) const [lineItems, setLineItems] = useState([ { description: "", quantity: 1, unitPrice: 0, vatRate: 20, total: 0 } ]) const [notes, setNotes] = useState("Thank you for your business!") const [terms, setTerms] = useState("Payment due within 30 days.") const [emailData, setEmailData] = useState({ to: "", subject: "", message: "", sendCopy: false }) ``` **No persistence:** All state lost on page refresh or navigation away. **No Zod schemas:** Validation is inline JavaScript (alert boxes). --- ## Expense Form (Dialog) **Route:** `/expenses` **Component:** Dialog triggered by "Add Expense" button ### Expense Form Flow ```mermaid flowchart TD BTN["'Add Expense' Button\nExpenses Page"] BTN --> DLG["Dialog Opens\nisDialogOpen=true"] DLG --> AMOUNT["Amount (number, required)"] DLG --> CURRENCY["Currency (Select: EUR/RSD/BAM)"] DLG --> CATEGORY["Category (Select, required)\nOffice/Travel/Meals/Utilities\nMarketing/Infrastructure\nSoftware/Professional Services"] DLG --> DATE["Date (date input, required)"] DLG --> VENDOR["Vendor (text, optional)"] DLG --> PAYMENT["Payment Method (Select, optional)\nCash/Card/Bank Transfer"] DLG --> RECEIPT["Receipt Upload\n(placeholder UI — no real upload)"] DLG --> DESC["Description (text, optional)"] AMOUNT --> SUBMIT["Save Expense button"] CATEGORY --> SUBMIT SUBMIT -->|"current"| CONSOLE["console.log(formData)\nDialog closes\nForm resets"] SUBMIT -->|"future"| API["POST /api/expenses\nRefetch expense list"] DLG --> CANCEL["Cancel button\nDialog closes\nForm resets"] ``` ### Form Fields - **Amount** (required) - Type: Number - Placeholder: "0.00" - Validation: Required (no schema) - **Currency** (required) - Type: Select - Options: EUR, RSD, BAM - Default: EUR - Width: 24px (narrow select next to amount) - Validation: None - **Category** (required) - Type: Select - Options: Office, Travel, Meals, Utilities, Marketing, Infrastructure, Software, Professional Services - Placeholder: "Select category" - Validation: Required - **Date** (required) - Type: Date - Default: Today's date - Validation: None - **Vendor** (optional) - Type: Text - Placeholder: "Search vendor..." - Validation: None - Note: Not a searchable autocomplete yet — plain text input - **Payment Method** (optional) - Type: Select - Options: Cash, Card, Bank Transfer - Placeholder: "Select method" - Validation: None - **Receipt** (optional) - Type: File upload (placeholder UI only) - Display: Dashed border div with "Upload or Drag" text - Behavior: No actual upload implemented - Validation: None - **Description** (optional) - Type: Text - Placeholder: "Additional notes..." - Validation: None ### Form Actions - **Cancel** — Closes dialog, resets form - **Save Expense** — Logs form data to console, closes dialog, resets form **No API submission.** Form data not persisted. **No Zod schemas.** Validation is JavaScript logic in form submit handler. --- ## Settings Forms **Route:** `/settings` **File:** `app/(dashboard)/settings/page.tsx` ### Settings Navigation Flow ```mermaid stateDiagram-v2 [*] --> Company : default section Company : Company Profile Company : name, legalForm, address, city\npostalCode, country, taxId\nbaseCurrency, fiscalYearStart Users : Users & Roles Users : User management table\n(name, email, role, status)\nInvite User button Tax : Tax & Compliance Tax : country (Serbia/BiH/Croatia)\nvatRegistered (checkbox)\nvatNumber (conditional)\nvatRate (conditional)\ncompliance reminder checkboxes Integrations : Integrations Integrations : Connected: Intesa Bank CSV, Email SMTP\nAvailable: Stripe, Fiken\nGoogle Sheets, Slack, DocuSeal Notifications : Notification Preferences Notifications : Email: paid, overdue, approved, synced\nIn-App: invoice updates, expense updates\nreconciliation matches Security : Security Settings Security : Enable 2FA button\nSession Timeout Select\nPassword Policy checkboxes\nAudit Log / Data Export / Delete Company Company --> Users : sidebar nav click Company --> Tax : sidebar nav click Company --> Integrations : sidebar nav click Company --> Notifications : sidebar nav click Company --> Security : sidebar nav click Users --> Company : sidebar nav click Tax --> Company : sidebar nav click Integrations --> Company : sidebar nav click Notifications --> Company : sidebar nav click Security --> Company : sidebar nav click ``` ### Company Profile Form **Fields:** - **Company Name** (required) - Type: Text - Default: "SnowIT d.o.o." - **Legal Form** - Type: Select - Options: d.o.o., a.d., Preduzetnik - Default: "d.o.o." - **Address** - Type: Text - Default: "Zmaja od Bosne" - **City** - Type: Text - Default: "Sarajevo" - **Postal Code** - Type: Text - Default: "71000" - **Country** - Type: Text - Default: "BiH" - **Tax ID / PIB / JIB** - Type: Text - Default: "4200000000" - **Base Currency** - Type: Select - Options: EUR, RSD, BAM - Default: "EUR" - **Fiscal Year Start** - Type: Select - Options: Jan 1, Apr 1, Jul 1, Oct 1 - Default: "Jan 1" **Action:** - **Save Changes** — Alert placeholder (no API) **Validation:** None (no required fields enforced) --- ### Tax & Compliance Form **Fields:** - **Country** - Type: Select - Options: Serbia, BiH, Croatia - Default: "Serbia" - **VAT Registered** - Type: Checkbox - Default: Checked - **VAT Number** (conditional, shown only if VAT registered) - Type: Text - Default: "RS123456789" - Placeholder: "Enter VAT number" - **VAT Rate** (conditional, shown only if VAT registered) - Type: Select - Options: 17% (BiH), 20% (Serbia), 25% (Croatia) - Default: "20" **Compliance Reminders:** - **VAT filing deadlines** — Checkbox (default: checked) - **Annual tax returns** — Checkbox (default: checked) - **Payroll tax deadlines** — Checkbox (default: unchecked) **Action:** - **Save Settings** — Alert placeholder (no API) **Validation:** None --- ### Notification Preferences **Email Notifications:** - Invoice paid — Checkbox (default: checked) - Invoice overdue — Checkbox (default: checked) - Expense approved — Checkbox (default: unchecked) - Bank account synced — Checkbox (default: checked) **In-App Notifications:** - Invoice updates — Checkbox (default: checked) - Expense updates — Checkbox (default: checked) - Reconciliation matches — Checkbox (default: unchecked) **Action:** - **Save Preferences** — Alert placeholder (no API) **Validation:** None --- ### Security Settings **Two-Factor Authentication:** - **Enable 2FA** button — No functionality yet **Session Timeout:** - Type: Select - Options: 15 minutes, 30 minutes, 1 hour, 4 hours - Default: 30 minutes **Password Policy:** - Minimum 12 characters — Checkbox (default: checked) - Require special characters — Checkbox (default: checked) - Expire passwords after 90 days — Checkbox (default: unchecked) **Actions:** - **View Audit Log** — No functionality yet - **Request Data Export** — No functionality yet - **Delete Company** (Danger Zone) — No functionality yet **Validation:** None --- ## Auth Forms ### Login Form (`/login`) ```mermaid flowchart TD LP["LoginPage\n/login"] LP --> EMAIL["Email input\ntype=email, required"] LP --> PASS["Password input\ntype=password, show/hide toggle"] LP --> SUBMIT["Submit Button\n'Prijavite se'"] SUBMIT --> STORE["useAuthStore.login(email, password)"] STORE -->|"success"| DASH["router.push('/dashboard')"] STORE -->|"error"| ERR["Error banner\n(red bg, border, message from store)"] LP --> FORGOT["Forgot password link\n(no functionality yet)"] LP --> REG["Link to /register"] ``` ### Register Form (`/register`) **Fields:** - **First Name** (required) - **Last Name** (required) - **Company** (required) - **Email** (required) - **Password** (required, show/hide toggle) - **Country** (required, Select) **Submit:** Calls `api.auth.register()` → auto-login via `useAuthStore.login()` → redirect to `/dashboard` --- ## Validation Architecture ```mermaid flowchart LR subgraph CURRENT["Current (Phase 1)"] INLINE["Inline JS Validation\nalert() on submit\nno schema, no real-time feedback"] INLINE --> INVOICE_V["Invoice Wizard\n• Step 1: if(!customer) alert()\n• Step 3: if(!descriptions) alert()"] INLINE --> EXPENSE_V["Expense Form\n• if(!amount || !category) return"] INLINE --> AUTH_V["Auth Forms\n• HTML required attribute\n• type=email browser validation"] end subgraph FUTURE["Future (Phase 2)"] ZOD["Zod Schemas\ncentralized, type-safe, reusable"] RHF["react-hook-form\nuseForm + zodResolver"] ZOD --> RHF RHF --> RT["Real-time Validation\nfield-level, on-change or on-blur"] RHF --> EM["Error Messages\ninline under each field"] RHF --> ES["Error State Styling\nred border + error text"] end ``` --- ## Future Form Enhancements (Phase 2) ### Zod Schema Validation **Planned:** Replace inline validation with Zod schemas **Example (Invoice Wizard Step 1):** ```typescript import { z } from 'zod' const customerSchema = z.object({ id: z.string(), name: z.string().min(1, "Customer name required"), email: z.string().email("Valid email required"), phone: z.string().optional(), taxId: z.string().optional() }) ``` **Benefits:** - Type-safe validation - Reusable schemas for API/DB - Better error messages - Centralized validation logic --- ### react-hook-form Integration **Planned:** Replace useState with react-hook-form **Example (Expense Form):** ```typescript import { useForm } from 'react-hook-form' import { zodResolver } from '@hookform/resolvers/zod' const expenseSchema = z.object({ amount: z.number().positive("Amount must be positive"), currency: z.enum(['EUR', 'RSD', 'BAM']), category: z.string().min(1, "Category required"), date: z.string(), vendor: z.string().optional(), paymentMethod: z.string().optional(), description: z.string().optional() }) const { register, handleSubmit, formState: { errors } } = useForm({ resolver: zodResolver(expenseSchema) }) ``` **Benefits:** - Automatic error handling - Less boilerplate - Better performance (no re-renders on every keystroke) - Built-in dirty/touched state --- ### Field-Level Validation **Planned:** Real-time validation as user types **Example (Email Field):** ```typescript {errors.email && ( {errors.email.message} )} ``` **Current State:** No real-time validation, only on form submit. --- ### Form Persistence **Planned:** Save draft forms to localStorage **Use Cases:** - Invoice wizard state saved between page refreshes - Expense form data saved if user closes dialog accidentally **Implementation:** ```typescript // Save to localStorage on every state change useEffect(() => { localStorage.setItem('invoice-draft', JSON.stringify(invoiceState)) }, [invoiceState]) // Load from localStorage on mount useEffect(() => { const draft = localStorage.getItem('invoice-draft') if (draft) setInvoiceState(JSON.parse(draft)) }, []) ``` --- ### File Upload (Receipt Attachment) **Current State:** Placeholder UI only (dashed border div) **Future Implementation:** - Drag-and-drop file upload - File size validation (max 5MB) - File type validation (PDF, JPG, PNG) - Preview uploaded file - Remove uploaded file - Upload to backend API **API Endpoint (planned):** ``` POST /api/expenses/:id/receipt Content-Type: multipart/form-data ``` --- ### Autocomplete/Search Fields **Current State:** Plain text inputs **Future Enhancement (Vendor Field):** - Searchable dropdown - Autocomplete from existing vendors - Create new vendor inline - Match by partial name **Library:** Radix UI Combobox or react-select --- ### Multi-Currency Conversion **Current State:** User manually selects currency **Future Enhancement:** - Fetch live exchange rates - Auto-convert amounts for display - Store both original currency and base currency - Show converted amounts in tooltips --- ## Summary **Current Forms:** 1. Invoice Wizard (6-step) — Customer, Details, Line Items, Customization, Preview, Send 2. Expense Form (dialog) — Amount, Category, Date, Vendor, Receipt, etc. 3. Company Profile — All company settings 4. Tax & Compliance — VAT settings 5. Notification Preferences — Email/in-app notification toggles 6. Security Settings — 2FA, session timeout, password policy 7. Login Form — Email + password, auth via Zustand store 8. Register Form — Name, company, email, password, country **Validation:** - Inline JavaScript (alert boxes) for wizard and expense form - HTML `required` attribute + browser validation for auth forms - No schema validation - No real-time validation - No error state styling **State Management:** - React useState for all forms - No persistence (lost on refresh) - No form libraries (native HTML forms) - Auth forms use `useAuthStore` from Zustand (login/register) **Future (Phase 2):** - Zod schemas for validation - react-hook-form for form management - Field-level validation - Form persistence (localStorage) - File upload functionality - Autocomplete/search fields - API integration for submission # CEO App-Audit UX Wave — 2026-07-13 $(cat /tmp/page-3209-updated.html | jq -Rs .) # Bilko — Contact Form + Pricing Restructure (2026-07-14) *Documents two shipped-and-live-verified changes deployed to demo (app.bilko.cloud) on 2026-07-14. Written for the ZAKON DOC gate covering MC #105588 and MC #105589.* ## MC #105588 — In-app contact form (RESOLVED, live) ### Problem The "Kontaktiraj nas" CTA (shown on contact-only tiers) executed `window.location.href='mailto:info@bilko.io'`. This was broken in practice: it requires a configured mail client on the visitor's machine, and it pointed at a `.io` domain that looks suspicious to a Balkan SMB user rather than the product's own domain. ### Fix - New backend endpoint: `POST /api/v1/leads` — public, rate-limited to 5 requests/min/IP via trusted-IP keying, closed tier enum (no arbitrary string injection), no PII echoed back in the response. - Lead emails are sent via **Resend** (note: the repo uses Resend, not SendGrid) to `LEADS_NOTIFICATION_EMAIL`, which defaults to `alem@alai.no`. - New shared frontend component, `LeadContactForm`, used as a modal from both `ChangePlanDrawer` and the public `/pricing` page — so both contact-only tiers (Računovođa, Enterprise) route through the same in-app form instead of a mailto link. ### Security review Parisa Tabriz (Securion) reviewed the public lead endpoint: **PASS WITH FOLLOW-UPS**. Hardening follow-ups tracked as MC #105592: HTML-escape the email body, escape the C0 control-character range in JSON output, add a `RequestBodyLimit`, and add a global request cap. ### Commits / PR - Backend: `f15dee26` - Frontend: `07ee9a9b` - PR144 → merged as `2ce713e2` ### Verification (Angie Jones / Proveo, live UAT) **PASS** — clicking "Kontaktiraj nas" opens an in-app modal titled "Kontaktirajte nas" with Ime / Email / Poruka fields. No `mailto:` navigation occurs. Evidence captured at `~/system/evidence/deploy-497-uat/`, notably `06-after-kontakt-click.png` (plus `05-before-kontakt-click.png`, `07-modal-closeup.png`, `06-modal-text.txt`, and the run's `uat-report.json`). --- ## MC #105589 — Pricing restructure: base + add-ons spine (RESOLVED, live) ### Decision CEO decision (2026-07-14), adversarially reviewed by Markos Zachariadis (Finverge) — **ENDORSE WITH CHANGES**. Bilko had two overlapping pricing models running in parallel: a tier-bundle model and an add-on module model. This created two competing paths to full bookkeeping — the Računovođa tier at €39, versus Biznis (€19) + FULL add-on (€18) = €37 — which cannibalized each other. The decision collapses this into **one base + add-ons spine**. ### Changes shipped - **Removed** the Računovođa tier everywhere in the UI (pricing-matrix.json / TIER\_UI / ChangePlanDrawer). - Full bookkeeping is now available **only** via the `ACCOUNTING_FULL_ADDON` at €18. - Multi-org cockpit is now bundled **free** with the FULL add-on (`multiOrg` is derived from `accountingFull`) — consistent with the 2026-06-25 multi-org pricing decision and the Fiken-inspired model. Verified live via the Testcontainers `MeCapabilitiesRoutesTest` (`multiOrg=true` on ENTERPRISE). - FULL grants an accountant-sized e-invoice quota (~300). - Added a "vs Pantheon €150+" competitive anchor line on the FULL add-on card. - HR pricing: PDV running total including 25% shown on `/pretplata`, plus "cijena bez PDV-a (25%)" labels on `/pricing`. - Kept the BIZNIS bundle tier as-is. - Enterprise remains the sole contact-only tier. - Added graceful fallback handling for unknown/legacy `planTier` values. ### Explicitly out of scope **No Stripe price mutations.** Tier prices in Stripe remain placeholders pending explicit CEO confirmation of final numbers before any `Stripe price create` call. ### Blast-radius check Live enumeration before removal: 0 organizations on ENTERPRISE or RACUNOVODJA tiers (PRO=5, BASIC=2, PREMIUM=1). Removing the Računovođa tier breaks no live customer. ### Commits / PR - `eb3b81ef` + `fd439b0e` (cleanup) - PR145 → merged as `21ad3534` ### Verification (Angie Jones / Proveo, live UAT) **PASS** — live tiers are Paušalac €9 / Biznis €19 / Enterprise (contact); no Računovođa tier present; FULL add-on shown at €18 with the Pantheon comparison line; PDV labels present as specified. Evidence at `~/system/evidence/deploy-497-uat/` (`02-public-pricing-page.png`/`.txt`, `03-pretplata-page.png`/`.txt`, `08-pretplata-addons-scrolled.png`, `09-addon-add-button.png`). ### Follow-up MC #105614 — two stale "Računovođa" copy strings remain (Modul B CTA + `/pricing` sidebar) and need a copy cleanup pass. --- ## Deploy note Both changes were deployed to demo via the **canonical azdo pipeline** `Promote_Demo` stage — self-hosted agent, pipeline service connection, **not** a manual personal `az` deploy (per ZAKON PI2). Build 497 (manual trigger, commit `21ad3534`), approved via PAT, `Promote_Demo` succeeded, and `app.bilko.cloud` returned HTTP 200 post-deploy. ## Evidence index
ItemLocation
Live UAT screenshots + reports (both MCs)`~/system/evidence/deploy-497-uat/`
Contact-click before/after`05-before-kontakt-click.png`, `06-after-kontakt-click.png`, `06-modal-text.txt`, `07-modal-closeup.png`
Public pricing page`02-public-pricing-page.png`/`.txt`
Subscription (/pretplata) page`03-pretplata-page.png`/`.txt`, `08-pretplata-addons-scrolled.png`, `09-addon-add-button.png`
Change-plan drawer`04-change-plan-drawer.png`/`.txt`
UAT structured report`uat-report.json`
## Related MC tasks - \#105588 — In-app contact form (this doc) - \#105589 — Pricing restructure base+add-ons (this doc) - \#105592 — Lead endpoint hardening follow-up (Parisa) - \#105614 — Stale "Računovođa" copy cleanup follow-up # Design & Brand Figma designs, logo, tokens, validation # Figma Validation Report (2026-02-21) ## Figma vs Build Validation — 2026-02-21 ### Critical Fix: Sidebar Dark → White
ElementBefore (BUG)After (FIXED)Figma
Sidebar background\#111113 (black)\#FFFFFF (white)\#FFFFFF
Sidebar text\#FAFAFA (white)\#111113 (dark)\#111113
Sidebar hover\#1F1F23 (dark)\#F5F5F5 (light)light
Active nav stateSolid #00E5A0 + white textLight mint #E6FFF8 + green textLight mint + green
Hamburger menuHidden on desktopVisible alwaysVisible
Notification bellPresentRemovedNot in design
LogoCSS box with 'B' textSharp B SVG from FigmaSharp B geometric
### Root Cause `globals.css` `@theme` block had inverted sidebar colors (dark mode values). Tailwind CSS v4 prioritizes `@theme` over `tailwind.config.ts`, so the correct tokens in config were overridden by wrong values in CSS. ### Files Changed - `apps/web/app/globals.css` — sidebar color tokens fixed - `apps/web/components/sidebar.tsx` — active state + logo SVG - `apps/web/components/top-bar.tsx` — hamburger visible, bell removed - `apps/web/public/logo-icon.svg` — Sharp B logo extracted from Figma ### Pages Validated
PageRouteSidebarContent Match
Dashboard/dashboard✓ White✓ Structure matches
Sales/Invoices/invoices✓ White✓ Build AHEAD (filters, actions)
VAT Return/reports/vat✓ White✓ Matches (minor: decimals)
Reports Hub/reports✓ White✓ Build AHEAD (P&L detail)
Add Expense/expenses/new✓ White✓ Matches
Purchases/purchases✓ White✓ Build AHEAD (full table)
Banking/banking✓ White✓ Build AHEAD (accounts)
Settings/settings✓ White✓ Build AHEAD (full form)
### Remaining Minor Differences - ⌘K badge style (Figma: separate badges, Build: inline text) - Nav icons differ slightly (Figma uses different icon set than Lucide) - Settings bottom has N avatar in build, gear icon in Figma - Invoice # format, status badge style, date format — content differences ### Build Status ✓ 0 errors, 12/12 pages compiled, Next.js 15.5.12 # Documentation Index # Bilko Documentation Index > **Last updated:** 2026-02-20 > **Project ID:** bbd77cc0 > **Status:** Backend SPECIFICATION (not implemented) > **Pipeline Status:** 7/8 gates PASS — [See Validation Report](/books/bilko-balkan-accounting-saas/page/validation-report) --- ## Key Documents - **[VALIDATION REPORT](/books/bilko-balkan-accounting-saas/page/validation-report)** — Gate validation results (2026-02-20) - **PIPELINE *(not in BookStack)*** — 8-gate progress tracker --- ## Purpose This documentation defines the implementation contract for Bilko's backend. The database schema exists and the frontend is built with mock data. These docs specify what the backend MUST implement to complete the system. --- ## Backend Documentation | Document | Description | Status | |----------|-------------|--------| | [API Reference](/books/bilko-balkan-accounting-saas/page/api-reference) | All API endpoints — method, path, request/response, auth | SPECIFICATION | | [Database Schema](/books/bilko-balkan-accounting-saas/page/database-schema) | All 15 models — columns, types, constraints, indexes | IMPLEMENTED (Prisma) | | [Authentication](/books/bilko-balkan-accounting-saas/page/authentication-authorization) | JWT auth flow, password hashing, 2FA, RBAC | SPECIFICATION | | [Business Logic](/books/bilko-balkan-accounting-saas/page/business-logic) | Double-entry bookkeeping, VAT calculation, multi-currency, reconciliation | SPECIFICATION | | [Middleware](/books/bilko-balkan-accounting-saas/page/middleware-stack) | Express middleware stack — security, auth, validation, error handling | SPECIFICATION | | [Services](/books/bilko-balkan-accounting-saas/page/external-services-integration) | External service integrations — SendGrid, Cloudflare R2, exchange rates, PDF generation | SPECIFICATION | --- ## Frontend Documentation | Document | Description | Status | |----------|-------------|--------| | [Pages](/books/bilko-balkan-accounting-saas/page/pages-routing) | All 10 implemented pages — routes, data requirements, mobile responsive | IMPLEMENTED | | [Component Inventory](/books/bilko-balkan-accounting-saas/page/component-inventory) | All 17 shadcn/ui components — usage, props, examples | IMPLEMENTED | | [Design System](/books/bilko-balkan-accounting-saas/page/design-system) | Colors, typography, spacing, shadows — 73 design tokens | IMPLEMENTED | | [State Management](/books/bilko-balkan-accounting-saas/page/state-management) | Zustand setup, stores, patterns | SPECIFICATION | | [Forms](/books/bilko-balkan-accounting-saas/page/forms-validation) | Form validation, error handling, submission patterns | SPECIFICATION | | Web App CLAUDE.md *(local file only)* | Next.js 15 frontend overview | REFERENCE | --- ## Infrastructure Documentation | Document | Description | Status | |----------|-------------|--------| | [Deployment](/books/bilko-balkan-accounting-saas/page/deployment-guide) | Deployment strategy — Vercel (frontend), Railway (backend+DB), environments | SPECIFICATION | | [CI/CD](/books/bilko-balkan-accounting-saas/page/cicd-pipeline) | GitHub Actions pipeline — lint, test, build, deploy | SPECIFICATION | | [Environment](/books/bilko-balkan-accounting-saas/page/environment-configuration) | Environment variables, secrets management, config | SPECIFICATION | --- ## Security Documentation | Document | Description | Status | |----------|-------------|--------| | [Security Architecture](/books/bilko-balkan-accounting-saas/page/security-architecture) | JWT auth, RBAC, encryption, rate limiting, OWASP Top 10 | SPECIFICATION | | [Compliance](/books/bilko-balkan-accounting-saas/page/gdpr-compliance) | GDPR compliance, data retention, user rights, privacy policy | SPECIFICATION | --- ## Testing Documentation | Document | Description | Status | |----------|-------------|--------| | [Testing Guide](/books/bilko-balkan-accounting-saas/page/testing-guide) | Testing philosophy, pyramid, tech stack (Vitest, Supertest, Playwright) | SPECIFICATION | | [Test Inventory](/books/bilko-balkan-accounting-saas/page/test-inventory) | Critical test scenarios, coverage requirements, quality gates | SPECIFICATION | --- ## Regulatory Documentation | Document | Description | Status | |----------|-------------|--------| | [Serbia SEF](/books/bilko-balkan-accounting-saas/page/serbia-sef-e-invoicing) | SEF e-invoicing (UBL 2.1), 20% PDV, Kontni Okvir Chart of Accounts, e-Transport | RESEARCH COMPLETE | | [BiH PDV](/books/bilko-balkan-accounting-saas/page/bosnia-pdv-system) | 17% PDV, UNO/ITA filing, e-invoicing draft law, FBiH (IFRS) + RS Chart of Accounts | RESEARCH COMPLETE | | [Croatia eRačun](/books/bilko-balkan-accounting-saas/page/croatia-eracun-hr-fisk) | eRačun B2G (2019) + B2B (2026), 25% VAT, RRiF Chart of Accounts, Fiscalization 2.0 | RESEARCH COMPLETE | | [Chart of Accounts](/books/bilko-balkan-accounting-saas/page/chart-of-accounts-all-countries) | Serbia (Class 0-9), BiH (IFRS/RS), Croatia (RRiF) — account structures | RESEARCH COMPLETE | --- ## How to Use This Documentation ### For Backend Developers 1. Start with [API Reference](/books/bilko-balkan-accounting-saas/page/api-reference) — this is your implementation contract 2. Read [Database Schema](/books/bilko-balkan-accounting-saas/page/database-schema) — understand the data model 3. Review [Business Logic](/books/bilko-balkan-accounting-saas/page/business-logic) — learn accounting domain rules 4. Implement endpoints following [Middleware](/books/bilko-balkan-accounting-saas/page/middleware-stack) and [Authentication](/books/bilko-balkan-accounting-saas/page/authentication-authorization) ### For Frontend Developers - All endpoints in API Reference include TypeScript interfaces - Replace mock data imports with API calls - Use the request/response types from API Reference ### For QA Engineers - API Reference includes example requests/responses for all endpoints - Use these as test cases - Verify business logic rules from Business Logic document --- ## Key Architectural Decisions ### 1. Double-Entry Bookkeeping Every financial event creates a `Transaction` with debitAccount + creditAccount. Debits = Credits always. ### 2. Multi-Currency with Rate Locking Exchange rate is locked at transaction date. Historical transactions NEVER recalculated with current rates. ### 3. Immutable Audit Trail `LoggedAction` table is APPEND-ONLY. All INSERT/UPDATE/DELETE operations captured. ### 4. Organization-Scoped Multi-Tenancy Every API request filtered by organizationId. No cross-org data access. ### 5. NUMERIC(19,4) for ALL Money NEVER use float or JavaScript number for currency. Precision is critical. --- ## Related Documents - Product Requirements *(local spec)* — Feature requirements, success metrics - Tech Stack *(local spec)* — Technology decisions - Wireframes *(local spec)* — UI specifications - Brand Identity *(local spec)* — Branding guidelines --- ## Contributing When adding new documentation: 1. Add entry to this INDEX.md 2. Follow existing document structure (Purpose → Spec → Examples) 3. Mark implementation status (SPECIFICATION, IN PROGRESS, IMPLEMENTED) 4. Update "Last updated" date in this file # Architecture # High-Level Design (HLD) # Bilko — High-Level Design (HLD) **Version:** 1.0 **Date:** 2026-02-23 **Project ID:** bbd77cc0 **Status:** Current — reflects actual codebase as of 2026-02-23 --- ## Table of Contents 1. [System Overview](#1-system-overview) 2. [Monorepo Structure](#2-monorepo-structure) 3. [Component Architecture](#3-component-architecture) 4. [Data Flow](#4-data-flow) 5. [Tech Stack Rationale](#5-tech-stack-rationale) 6. [Multi-Tenancy Model](#6-multi-tenancy-model) 7. [Authentication Architecture](#7-authentication-architecture) 8. [Multi-Currency Architecture](#8-multi-currency-architecture) 9. [Country Plugin System](#9-country-plugin-system) 10. [Infrastructure Overview](#10-infrastructure-overview) 11. [Security Model](#11-security-model) --- ## 1. System Overview Bilko is a cloud-based accounting SaaS for Balkan SMBs operating in Serbia, Bosnia & Herzegovina, and Croatia. It is modeled after Fiken (Norway) — simple, compliant, and affordable. **Key design goals:** - Double-entry bookkeeping engine with immutable audit trail - Multi-country regulatory compliance (RS, BA, HR) via pluggable country modules - Multi-currency support with exchange rate locking at transaction date - Organization-scoped multi-tenancy - All monetary values stored as `NUMERIC(19,4)` — never float **Target users:** 50K–500K SMBs across the Balkan region **Domains:** bilko.io (primary), bilko.rs (Serbia redirect) --- ## 2. Monorepo Structure The project uses **Turborepo** for monorepo management. ``` Bilko/ ├── apps/ │ ├── web/ # Next.js 15 frontend (App Router) │ └── api/ # Express + TypeScript backend ├── packages/ │ ├── database/ # Prisma schema + Prisma Client (@bilko/database) │ ├── core/ # Accounting engine (@bilko/core) │ ├── country-rs/ # Serbia plugin (@bilko/country-rs) │ ├── country-ba/ # Bosnia & Herzegovina plugin (@bilko/country-ba) │ ├── country-hr/ # Croatia plugin (@bilko/country-hr) │ └── ui/ # Shared UI scaffold (empty, placeholder) ├── infrastructure/ │ ├── terraform/ # AWS infrastructure as code │ ├── docker/ # Dockerfiles and docker-compose │ ├── nginx/ # Nginx reverse proxy config │ ├── pm2/ # PM2 process manager config │ └── scripts/ # Deployment shell scripts ├── docs/ # All documentation │ ├── backend/ # API, auth, services, DB schema docs │ ├── frontend/ # Pages, components, design system docs │ ├── infrastructure/ # Deployment, CI/CD, environment docs │ ├── regulatory/ # Country-specific accounting law summaries │ ├── security/ # Security architecture, compliance │ └── testing/ # Testing guides and inventory ├── CLAUDE.md # Project AI assistant instructions └── PIPELINE.md # 8-gate checklist ``` --- ## 3. Component Architecture ```mermaid graph TB subgraph Client["Client Layer"] Browser["Browser / Mobile"] end subgraph Frontend["apps/web — Next.js 15"] AppRouter["App Router"] Pages["Pages (Dashboard, Invoices, Expenses, Reports, Banking, Settings)"] Components["shadcn/ui Components"] MockData["lib/mock-data.ts (TEMP — replace with API calls)"] Zustand["Zustand Store (future)"] end subgraph Backend["apps/api — Express + TypeScript"] Middleware["Middleware Stack (helmet → cors → json → rate-limit → auth → validate → handler → error)"] Routes["Route Modules (auth, invoices, expenses, contacts, accounts, transactions, reports, banking, settings)"] Services["Service Layer (Invoice, Expense, Contact, Account, Banking, Report, Settings)"] CoreEngine["@bilko/core (accounting, tax, multi-currency, bank-import)"] end subgraph Plugins["Country Plugins"] RS["@bilko/country-rs (Serbia: PDV 20%, SEF, CIT 15%)"] BA["@bilko/country-ba (BiH: PDV 17%, IFRS, UIO)"] HR["@bilko/country-hr (Croatia: PDV 25%, eRačun, FINA)"] end subgraph Data["Data Layer"] Prisma["@bilko/database — Prisma Client"] PG["PostgreSQL 15 (RDS)"] end subgraph Storage["Storage"] R2["Cloudflare R2 (PDF storage, receipts)"] end Browser --> AppRouter AppRouter --> Pages Pages --> Components Pages --> MockData Pages --> Zustand Pages -->|"REST API calls (future)"| Routes Middleware --> Routes Routes --> Services Services --> CoreEngine Services --> Plugins Services --> Prisma Prisma --> PG Services --> R2 ``` --- ## 4. Data Flow ### 4.1 Standard Request Flow ```mermaid sequenceDiagram participant U as User (Browser) participant FE as Next.js Frontend participant MW as Middleware Stack participant RT as Route Handler participant SV as Service Layer participant CE as @bilko/core participant PR as Prisma Client participant DB as PostgreSQL U->>FE: User Action (e.g., Create Invoice) FE->>MW: POST /api/v1/invoices + Bearer token MW->>MW: helmet (security headers) MW->>MW: cors (origin check) MW->>MW: rate-limit (100 req/15min per IP) MW->>MW: authGuard (verify JWT access token) MW->>MW: organizationScope (attach orgId to request) MW->>MW: validate (Zod schema check) MW->>RT: req.user + req.body validated RT->>SV: invoiceService.createInvoice(orgId, userId, data) SV->>CE: calculateVAT(), lockExchangeRate() SV->>PR: prisma.$transaction([create invoice, create items]) PR->>DB: INSERT invoices, invoice_items DB-->>PR: Created records PR-->>SV: Invoice with items SV-->>RT: Formatted response RT-->>FE: 201 JSON response FE-->>U: Updated UI ``` ### 4.2 Invoice Lifecycle with Double-Entry ```mermaid stateDiagram-v2 [*] --> draft: POST /api/v1/invoices draft --> sent: PATCH /status {action: "send"}\n→ Creates TX: DR Receivable / CR Revenue sent --> viewed: (future: email tracking webhook) viewed --> paid: PATCH /status {action: "mark-paid"}\n→ Creates TX: DR Bank / CR Receivable sent --> paid: PATCH /status {action: "mark-paid"} draft --> cancelled: PATCH /status {action: "cancel"} sent --> cancelled: PATCH /status {action: "cancel"} viewed --> overdue: (cron job: past due date) overdue --> paid: PATCH /status {action: "mark-paid"} ``` ### 4.3 Expense Lifecycle with Double-Entry ```mermaid stateDiagram-v2 [*] --> pending: POST /api/v1/expenses pending --> approved: PATCH /expenses/:id/approve\n→ Creates TX: DR Expense / CR Payable approved --> paid: PATCH /expenses/:id/pay\n→ Creates TX: DR Payable / CR Bank pending --> rejected: (future endpoint) ``` --- ## 5. Tech Stack Rationale | Layer | Technology | Rationale | |-------|-----------|-----------| | **Frontend Framework** | Next.js 15 (App Router) | SSR for fast initial load, SEO, file-system routing, React Server Components | | **Frontend Language** | TypeScript 5.3 | Type safety, IDE support, catch errors at compile time | | **Styling** | Tailwind CSS 4 + shadcn/ui | Utility-first styling with accessible, unstyled Radix UI primitives | | **State Management** | Zustand 4.5 (planned) | Lightweight global state; React hooks used currently during mock phase | | **Charts** | Recharts 2.15 | React-native chart library, composable, good TypeScript support | | **Icons** | Lucide React | Consistent icon set, tree-shakeable, maintained fork of Feather | | **Backend Framework** | Express + TypeScript | Minimal, battle-tested, massive ecosystem; team familiarity | | **ORM** | Prisma | Type-safe database access, migration management, schema-as-code | | **Database** | PostgreSQL 15 | NUMERIC(19,4) for money, mature ACID compliance, full-text search | | **Auth** | JWT (access + refresh) | Stateless, scalable; no session store needed | | **Validation** | Zod | Runtime schema validation with full TypeScript inference | | **Monorepo** | Turborepo | Fast incremental builds, shared packages, workspace management | | **Decimal Arithmetic** | Decimal.js | Arbitrary-precision arithmetic — required for financial calculations | | **Infrastructure** | AWS (EC2, RDS, S3, CloudFront) | Reliable, eu-central-1 region close to Balkan users | | **IaC** | Terraform | Declarative infrastructure, reproducible environments | --- ## 6. Multi-Tenancy Model Bilko uses **organization-scoped multi-tenancy** — all business data is isolated by `organizationId`. ```mermaid erDiagram Organization { uuid id PK string name string baseCurrency "EUR by default" string country "RS, BA, HR" string language "sr, bs, hr" } User { uuid id PK uuid organizationId FK enum role "owner, admin, accountant, viewer" } Invoice { uuid id PK uuid organizationId FK } Expense { uuid id PK uuid organizationId FK } Transaction { uuid id PK uuid organizationId FK } Organization ||--o{ User : has Organization ||--o{ Invoice : owns Organization ||--o{ Expense : owns Organization ||--o{ Transaction : owns ``` **Enforcement mechanism:** The `organizationScope` middleware (`apps/api/src/middleware/org-scope.ts`) attaches `req.user.organizationId` to every authenticated request. All service methods receive `organizationId` as first parameter and filter all Prisma queries with `where: { organizationId }`. Cross-organization data access is structurally impossible via the API layer. **RBAC roles:** | Role | Permissions | |------|-------------| | `owner` | Full access, manage users, change roles, delete org | | `admin` | Full access except role management | | `accountant` | CRUD on invoices, expenses, transactions, reports | | `viewer` | Read-only access to all data | --- ## 7. Authentication Architecture ```mermaid sequenceDiagram participant C as Client participant A as API /auth participant DB as PostgreSQL C->>A: POST /api/v1/auth/login {email, password} A->>DB: findUser(email) → user + passwordHash A->>A: bcrypt.verify(password, passwordHash) A->>A: signAccessToken({sub, email, role, orgId}) [15min, JWT_SECRET] A->>A: signRefreshToken({sub, jti}) [7d, JWT_REFRESH_SECRET] A-->>C: 200 {accessToken, user, org} + Set-Cookie: refreshToken (httpOnly) Note over C,A: Subsequent requests C->>A: GET /api/v1/invoices + Authorization: Bearer A->>A: authGuard: verifyAccessToken() → payload A->>A: organizationScope: attach orgId to req A-->>C: 200 {data} Note over C,A: Token refresh C->>A: POST /api/v1/auth/refresh (cookie: refreshToken) A->>A: verifyRefreshToken() → {sub, jti} A->>DB: findUser(sub) → user A->>A: signAccessToken(newPayload) A-->>C: 200 {accessToken} ``` **Token storage:** - Access token: returned in response body, client stores in memory - Refresh token: `httpOnly` cookie, path `/api/v1/auth`, `SameSite: strict` **Security:** - Passwords: bcrypt with 12 salt rounds (`apps/api/src/utils/password.ts`) - JWT: RS256 signing, issuer/audience validation (`apps/api/src/utils/jwt.ts`) - Optional 2FA: TOTP via `User.twoFactorSecret` (field exists, not yet wired) --- ## 8. Multi-Currency Architecture All monetary amounts stored as `DECIMAL(19,4)` in PostgreSQL. The system maintains both the transaction currency amount and the base-currency equivalent. **Key fields on monetary entities:** | Field | Type | Purpose | |-------|------|---------| | `currencyCode` | CHAR(3) | ISO 4217 currency of the transaction | | `exchangeRate` | DECIMAL(12,6) | Rate locked at transaction date | | `amount` | DECIMAL(19,4) | Amount in transaction currency | | `baseAmount` | DECIMAL(19,4) | Amount converted to org's baseCurrency | **Rate locking:** When an invoice or expense is created, the exchange rate is fetched from the `ExchangeRate` table for the most recent date on or before the transaction date and locked permanently. Historical rates are never recalculated (`packages/core/src/multi-currency/index.ts`: `lockExchangeRate()`). **Supported currencies:** EUR, RSD, BAM, HRK, USD, GBP, CHF **Fallback:** If no exchange rate is found for a currency pair on a given date, the system logs a warning and uses 1.0. This is a known gap — exchange rate population is a prerequisite for multi-currency accuracy. --- ## 9. Country Plugin System Each country is a separate npm package with the same module structure: ``` packages/country-{code}/src/ ├── tax/index.ts # VAT/PDV calculation, CIT, WHT ├── chart/index.ts # Country-specific chart of accounts ├── fiscal/index.ts # Fiscal year rules ├── filing/index.ts # Tax filing periods and deadlines ├── locale/index.ts # Language/formatting (date, currency) └── index.ts # Re-exports all modules ``` **Country-specific data:** | Country | Plugin | VAT Standard | VAT Reduced | CIT | E-Invoice | |---------|--------|-------------|-------------|-----|-----------| | Serbia (RS) | `@bilko/country-rs` | 20% | 10% | 15% flat | SEF (UBL 2.1) mandatory since 2023 | | Bosnia & Herzegovina (BA) | `@bilko/country-ba` | 17% | none | 10% (FBiH/RS both) | CPF (pending, ~2026) | | Croatia (HR) | `@bilko/country-hr` | 25% | 13%, 5% | 10%/18% progressive | eRačun (UBL 2.1) mandatory since 2026 | The core engine (`@bilko/core`) provides country-agnostic accounting primitives. Country plugins extend these with jurisdiction-specific rules without modifying core logic. --- ## 10. Infrastructure Overview ```mermaid graph LR subgraph DNS["Route 53"] D1["bilko.io"] D2["api.bilko.io"] end subgraph CDN["CloudFront"] CF["CloudFront Distribution\n(bilko.io → S3/Next.js)"] end subgraph Compute["EC2 (eu-central-1)"] NG["Nginx (reverse proxy)"] PM2["PM2 (process manager)"] API["Express API\n(Node.js)"] WEB["Next.js Frontend\n(standalone build)"] end subgraph Data["Data Layer"] RDS["RDS PostgreSQL 15\n(Multi-AZ)"] S3["S3 (backups, assets)"] R2["Cloudflare R2\n(PDFs, receipts)"] end subgraph Monitor["Monitoring"] CW["CloudWatch\n(logs, alarms)"] end D1 --> CF --> NG D2 --> NG NG --> PM2 PM2 --> API PM2 --> WEB API --> RDS API --> R2 API --> CW ``` **Key infrastructure decisions:** - Region: `eu-central-1` (Frankfurt) — closest to Balkan users with strong data residency - RDS Multi-AZ for database high availability - CloudFront for global CDN caching of static frontend assets - PM2 for Node.js process management and zero-downtime restarts - Terraform backend: S3 state bucket + DynamoDB lock table in `eu-central-1` --- ## 11. Security Model | Layer | Control | |-------|---------| | Transport | HTTPS enforced (HSTS, `maxAge: 31536000`, `includeSubDomains`) | | Security headers | helmet (CSP, X-Frame-Options: deny, X-Content-Type-Options: noSniff) | | CORS | Whitelist: `bilko.io`, `www.bilko.io`, `localhost:3000` | | Rate limiting | 100 req/15min per IP (general); stricter limit on `/auth/login` and `/auth/register` | | Authentication | JWT access token (15min) + refresh token (7d, httpOnly cookie) | | Authorization | RBAC checked per endpoint; `organizationScope` middleware enforces tenancy | | Password storage | bcrypt, 12 salt rounds | | Audit trail | `LoggedAction` table — append-only, captures all INSERT/UPDATE/DELETE with user, timestamp, old/new values | | Money precision | NUMERIC(19,4) everywhere; Decimal.js in business logic | | Transaction immutability | `Transaction.locked = true` makes records unmodifiable | | SQL injection | Prisma parameterized queries — no raw SQL in business logic | | Secret management | Environment variables; never committed to repository | # Low-Level Design (LLD) # Bilko — Low-Level Design (LLD) **Version:** 1.0 **Date:** 2026-02-23 **Project ID:** bbd77cc0 **Status:** Current — reflects actual codebase as of 2026-02-23 --- ## Table of Contents 1. [API Endpoint Specifications](#1-api-endpoint-specifications) 2. [Database Schema Documentation](#2-database-schema-documentation) 3. [Service Layer Design](#3-service-layer-design) 4. [Middleware Stack](#4-middleware-stack) 5. [Double-Entry Bookkeeping Implementation](#5-double-entry-bookkeeping-implementation) 6. [Tax Calculation Logic Per Country](#6-tax-calculation-logic-per-country) 7. [Invoice Lifecycle](#7-invoice-lifecycle) 8. [Bank Import Flow](#8-bank-import-flow) 9. [Core Engine Modules](#9-core-engine-modules) --- ## 1. API Endpoint Specifications **Base URL:** `/api/v1` **Auth:** All endpoints except `/auth/*` and `/health` require `Authorization: Bearer ` **Content-Type:** `application/json` **Error format:** ```json { "error": "Human-readable message", "code": "ERROR_CODE", "details": {} } ``` --- ### 1.1 Health #### `GET /api/v1/health` No auth required. **Response 200:** ```json { "status": "ok", "timestamp": "2026-02-23T10:00:00.000Z" } ``` --- ### 1.2 Authentication (`/auth`) **Source:** `apps/api/src/routes/auth.ts` #### `POST /api/v1/auth/register` Rate-limited (stricter). Creates organization + owner user in a single Prisma transaction. **Request body:** ```json { "organizationName": "Acme DOO", "country": "RS", "baseCurrency": "RSD", "language": "sr", "registrationNumber": "12345678", "vatNumber": "123456789", "email": "user@acme.rs", "password": "securepassword", "fullName": "Marko Marković" } ``` **Response 201:** ```json { "user": { "id": "uuid", "email": "...", "fullName": "...", "role": "owner" }, "organization": { "id": "uuid", "name": "...", "country": "RS", "baseCurrency": "RSD" }, "tokens": { "accessToken": "jwt...", "refreshToken": "jwt..." } } ``` **Errors:** `409 DUPLICATE` (email exists), `400 VALIDATION_ERROR` --- #### `POST /api/v1/auth/login` Rate-limited (stricter). `rememberMe: true` extends refresh token to 30 days. **Request body:** ```json { "email": "user@acme.rs", "password": "securepassword", "rememberMe": false } ``` **Response 200:** Same shape as register response. Sets `refreshToken` httpOnly cookie (path: `/api/v1/auth`). **Errors:** `401 UNAUTHORIZED` (invalid credentials) --- #### `POST /api/v1/auth/refresh` Uses `refreshToken` cookie. Issues new access token. **Response 200:** ```json { "accessToken": "jwt..." } ``` **Errors:** `401 NO_TOKEN`, `401 TOKEN_EXPIRED`, `401 INVALID_TOKEN` --- #### `POST /api/v1/auth/logout` Clears `refreshToken` cookie. **Response 204:** No content. --- #### `GET /api/v1/auth/me` Requires `Authorization: Bearer `. **Response 200:** ```json { "id": "uuid", "email": "...", "fullName": "...", "role": "owner", "twoFactorEnabled": false, "lastLoginAt": "2026-02-23T10:00:00.000Z", "organization": { "id": "uuid", "name": "...", "country": "RS", "baseCurrency": "RSD", "language": "sr" } } ``` --- ### 1.3 Invoices (`/invoices`) **Source:** `apps/api/src/routes/invoices.ts`, `apps/api/src/services/invoice.service.ts` #### `GET /api/v1/invoices` List invoices with pagination and filtering. **Query params:** | Param | Type | Description | |-------|------|-------------| | `status` | enum | `draft`, `sent`, `viewed`, `paid`, `overdue`, `cancelled` | | `customerId` | uuid | Filter by customer | | `fromDate` | YYYY-MM-DD | Invoice date from | | `toDate` | YYYY-MM-DD | Invoice date to | | `page` | int | Default 1 | | `perPage` | int | Default 20, max 100 | | `sort` | string | `invoiceDate`, `totalAmount`, `createdAt` | | `order` | string | `asc`, `desc` | **Response 200:** ```json { "data": [{ "id": "uuid", "invoiceNumber": "INV-2026-001", "customerId": "uuid", "customerName": "Acme Client", "invoiceDate": "2026-02-01", "dueDate": "2026-03-01", "currencyCode": "RSD", "totalAmount": "120000.0000", "status": "draft", "createdAt": "2026-02-01T10:00:00.000Z" }], "meta": { "total": 42, "page": 1, "perPage": 20, "totalPages": 3 } } ``` --- #### `GET /api/v1/invoices/:id` Get single invoice with all line items. **Response 200:** ```json { "id": "uuid", "invoiceNumber": "INV-2026-001", "customerId": "uuid", "customerName": "...", "invoiceDate": "2026-02-01", "dueDate": "2026-03-01", "currencyCode": "RSD", "exchangeRate": "1.000000", "subtotal": "100000.0000", "taxAmount": "20000.0000", "discountAmount": "0.0000", "totalAmount": "120000.0000", "baseAmount": "120000.0000", "status": "draft", "sentAt": null, "paidAt": null, "items": [{ "id": "uuid", "lineNumber": 1, "description": "Consulting services", "quantity": "10.00", "unitPrice": "10000.0000", "taxRate": "20.00", "lineTotal": "100000.0000", "accountId": "uuid" }], "notes": null, "terms": null, "pdfUrl": null, "createdBy": "uuid", "createdAt": "...", "updatedAt": "..." } ``` **Errors:** `404 NOT_FOUND` --- #### `POST /api/v1/invoices` Create invoice in `draft` status. Auto-generates invoice number (`INV-YYYY-NNN`). Locks exchange rate at `invoiceDate`. **Request body:** ```json { "customerId": "uuid", "invoiceDate": "2026-02-01", "dueDate": "2026-03-01", "currencyCode": "RSD", "items": [ { "description": "Consulting", "quantity": 10, "unitPrice": 10000, "taxRate": 20, "accountId": "uuid" } ], "notes": "Optional notes", "terms": "Net 30" } ``` **Response 201:** Full invoice object (same as GET /:id) **Errors:** `404 NOT_FOUND` (customer), `400 VALIDATION_ERROR` --- #### `PUT /api/v1/invoices/:id` Update invoice. Only allowed when `status = draft`. **Request body (partial):** ```json { "invoiceDate": "2026-02-15", "dueDate": "2026-03-15", "items": [ ... ], "notes": "Updated notes" } ``` **Errors:** `404 NOT_FOUND`, `400 BAD_REQUEST` (not draft) --- #### `PATCH /api/v1/invoices/:id/status` Change invoice status. Each action triggers double-entry transaction creation. **Request body:** ```json { "action": "send" } { "action": "mark-paid", "paidAt": "2026-02-20" } { "action": "cancel" } ``` **Actions and effects:** | Action | From Status | To Status | Journal Entry | |--------|------------|-----------|--------------| | `send` | `draft` | `sent` | DR Accounts Receivable / CR Revenue | | `mark-paid` | `sent`, `viewed` | `paid` | DR Bank / CR Accounts Receivable | | `cancel` | `draft`, `sent`, `viewed` | `cancelled` | None | **Errors:** `404 NOT_FOUND`, `400 BAD_REQUEST` (invalid transition), `400 BAD_REQUEST` (accounts not found) --- #### `GET /api/v1/invoices/:id/pdf` Redirects to PDF URL in Cloudflare R2. Returns `404` if PDF not generated yet. --- #### `POST /api/v1/invoices/:id/send` Send invoice email to customer. **Request body:** ```json { "to": "customer@example.com", "subject": "Invoice ...", "message": "..." } ``` **Response 200:** ```json { "sentAt": "...", "sentTo": "customer@example.com", "emailId": "..." } ``` *Note: Email sending is a placeholder — not yet implemented.* --- #### `DELETE /api/v1/invoices/:id` Delete invoice. Only allowed when `status = draft`. **Response 204:** No content. **Errors:** `404 NOT_FOUND`, `400 BAD_REQUEST` (not draft) --- ### 1.4 Expenses (`/expenses`) **Source:** `apps/api/src/routes/expenses.ts`, `apps/api/src/services/expense.service.ts` #### `GET /api/v1/expenses` List with pagination. **Query params:** `status`, `category`, `vendorId`, `fromDate`, `toDate`, `page`, `perPage`, `sort`, `order` --- #### `GET /api/v1/expenses/:id` **Response 200:** ```json { "id": "uuid", "expenseNumber": "EXP-2026-001", "vendorId": "uuid", "vendorName": "Office Supplies Ltd", "expenseDate": "2026-02-01", "category": "office", "currencyCode": "RSD", "exchangeRate": "1.000000", "amount": "5000.0000", "baseAmount": "5000.0000", "taxAmount": "850.0000", "paymentMethod": "bank_transfer", "accountId": "uuid", "description": "Office supplies purchase", "receiptUrl": null, "status": "pending", "approvedAt": null, "paidAt": null, "createdBy": "uuid", "createdAt": "...", "updatedAt": "..." } ``` --- #### `POST /api/v1/expenses` Create expense in `pending` status. Auto-generates number (`EXP-YYYY-NNN`). **Request body:** ```json { "vendorId": "uuid", "expenseDate": "2026-02-01", "category": "office", "amount": 5000, "currencyCode": "RSD", "taxAmount": 850, "paymentMethod": "bank_transfer", "accountId": "uuid", "description": "Office supplies" } ``` --- #### `PUT /api/v1/expenses/:id` Update expense. Only `pending` status. --- #### `PATCH /api/v1/expenses/:id/approve` Approve expense. Creates double-entry: **DR Expense Account / CR Accounts Payable** **Response 200:** Updated expense with `status: approved` --- #### `PATCH /api/v1/expenses/:id/pay` Mark expense paid. Creates double-entry: **DR Accounts Payable / CR Bank** **Response 200:** Updated expense with `status: paid` --- #### `DELETE /api/v1/expenses/:id` Delete expense. Only `pending` status. --- ### 1.5 Contacts (`/contacts`) **Source:** `apps/api/src/routes/contacts.ts`, `apps/api/src/services/contact.service.ts` #### `GET /api/v1/contacts` **Query params:** `type` (`customer`, `vendor`, `both`), `search`, `page`, `perPage` #### `GET /api/v1/contacts/:id` #### `POST /api/v1/contacts` **Request body:** ```json { "type": "customer", "name": "Acme Client DOO", "email": "billing@acme.rs", "phone": "+381 11 123 4567", "registrationNumber": "12345678", "vatNumber": "123456789", "addressLine1": "Bulevar Kralja Aleksandra 1", "city": "Beograd", "postalCode": "11000", "country": "RS", "currencyCode": "RSD", "paymentTerms": 30, "notes": "VIP client" } ``` #### `PUT /api/v1/contacts/:id` #### `DELETE /api/v1/contacts/:id` Soft-delete: sets `isActive = false`. Contact remains in database for historical records. --- ### 1.6 Accounts (Chart of Accounts) (`/accounts`) **Source:** `apps/api/src/routes/accounts.ts`, `apps/api/src/services/account.service.ts` #### `GET /api/v1/accounts` **Query params:** `typeId`, `isActive`, `includeBalances` (boolean) **Response 200:** ```json { "data": [{ "id": "uuid", "code": "120", "name": "Potraživanja od kupaca", "accountTypeId": 1, "accountType": "Asset", "currencyCode": "RSD", "parentAccountId": null, "isActive": true }] } ``` #### `POST /api/v1/accounts` **Request body:** `{ "code": "1201", "name": "...", "accountTypeId": 1, "currencyCode": "RSD", "parentAccountId": "uuid" }` #### `PUT /api/v1/accounts/:id` --- ### 1.7 Transactions (General Ledger) (`/transactions`) **Source:** `apps/api/src/routes/transactions.ts` #### `GET /api/v1/transactions` **Query params:** `fromDate`, `toDate`, `accountId`, `referenceType` (`invoice`, `expense`, `payment`, `manual`), `referenceId`, `page`, `perPage`, `sort`, `order` **Response 200:** ```json { "data": [{ "id": "uuid", "transactionDate": "2026-02-01", "description": "Invoice INV-2026-001", "debitAccountId": "uuid", "debitAccountCode": "120", "debitAccountName": "Receivables", "creditAccountId": "uuid", "creditAccountCode": "600", "creditAccountName": "Revenue", "amount": "120000.0000", "currencyCode": "RSD", "exchangeRate": "1.000000", "baseAmount": "120000.0000", "referenceType": "invoice", "referenceId": "uuid", "locked": false, "reconciled": false, "createdBy": "uuid", "createdAt": "..." }], "meta": { "total": 100, "page": 1, "perPage": 20, "totalPages": 5 } } ``` #### `GET /api/v1/transactions/:id` Full transaction detail including account type information. #### `POST /api/v1/transactions` Manual journal entry. Requires `owner`, `admin`, or `accountant` role. Debit and credit accounts must be different. **Request body:** ```json { "transactionDate": "2026-02-01", "description": "Manual adjustment", "debitAccountId": "uuid", "creditAccountId": "uuid", "amount": 5000, "currencyCode": "RSD", "notes": "Correction entry" } ``` **Errors:** `403 FORBIDDEN` (viewer role), `422 VALIDATION_ERROR` (same debit/credit account), `404 NOT_FOUND` (accounts) --- ### 1.8 Reports (`/reports`) **Source:** `apps/api/src/routes/reports.ts`, `apps/api/src/services/report.service.ts` #### `GET /api/v1/reports/dashboard` MTD metrics: cash balance, revenue, unpaid invoices, expenses, profit, monthly P&L (6 months), receivables aging, expenses by category. #### `GET /api/v1/reports/profit-loss` **Query params:** `from` (YYYY-MM-DD), `to` (YYYY-MM-DD) **Response 200:** ```json { "period": { "from": "2026-01-01", "to": "2026-01-31" }, "baseCurrency": "RSD", "revenue": { "total": "500000.0000", "accounts": [{ "accountCode": "600", "accountName": "Revenue", "amount": "500000.0000" }] }, "expenses": { "total": "200000.0000", "accounts": [...] }, "netProfit": "300000.0000" } ``` #### `GET /api/v1/reports/balance-sheet` **Query params:** `date` (YYYY-MM-DD, default: today) Returns assets (current + fixed), liabilities (current + long-term), equity with account detail. #### `GET /api/v1/reports/cash-flow` **Query params:** `from`, `to` Categorizes bank account transactions into operating, investing, and financing cash flows with opening/closing balance. #### `GET /api/v1/reports/vat` **Query params:** `from`, `to` Returns output VAT (from invoices), input VAT (from expenses), net VAT, and reconciliation status. #### `GET /api/v1/reports/trial-balance` **Query params:** `date` (YYYY-MM-DD, default: today) Returns all accounts with debit total, credit total, balance, and whether total debits equal total credits. #### `GET /api/v1/reports/general-ledger` **Query params:** `accountId` (optional), `from`, `to` Returns accounts with individual transaction entries sorted by date, showing running debit/credit/counter-account. --- ### 1.9 Banking (`/bank-accounts`) **Source:** `apps/api/src/routes/banking.ts`, `apps/api/src/services/banking.service.ts` #### `GET /api/v1/bank-accounts` List all bank accounts with balances. #### `GET /api/v1/bank-accounts/:id` Single bank account with recent transactions. #### `POST /api/v1/bank-accounts` **Request body:** ```json { "bankName": "UniCredit Banka", "accountNumber": "170-123456789-01", "iban": "RS35170006310000014243", "currencyCode": "RSD", "accountId": "uuid" } ``` #### `GET /api/v1/bank-accounts/:id/transactions` **Query params:** `fromDate`, `toDate`, `reconciled` (boolean), `page`, `perPage` #### `POST /api/v1/bank-accounts/:id/import` Import CSV bank statement. Request body: `{ "csvContent": "Date,Amount,..." }` **Response:** ```json { "imported": 45, "duplicates": 3, "errors": 0 } ``` #### `POST /api/v1/bank-accounts/:id/reconcile` **Request body:** ```json { "bankTransactionId": "uuid", "transactionId": "uuid" } ``` --- ### 1.10 Settings **Source:** `apps/api/src/routes/settings.ts`, `apps/api/src/services/settings.service.ts` #### `GET /api/v1/organization` #### `PUT /api/v1/organization` Requires `owner` or `admin` role. **Request body:** ```json { "name": "Updated Name DOO", "registrationNumber": "12345678", "vatNumber": "123456789", "language": "sr" } ``` #### `GET /api/v1/users` Requires `owner` or `admin` role. Returns all users in the organization. #### `POST /api/v1/users/invite` **Request body:** ```json { "email": "newuser@acme.rs", "fullName": "Jana Jović", "role": "accountant" } ``` #### `PUT /api/v1/users/:id/role` Requires `owner` role only. **Request body:** ```json { "role": "admin" } ``` #### `DELETE /api/v1/users/:id` Requires `owner` role. Cannot delete self. #### `GET /api/v1/currencies` List all active currencies with code, name, symbol, decimal places. #### `GET /api/v1/exchange-rates` **Query params:** `baseCurrency`, `targetCurrency`, `date` #### `GET /api/v1/settings/tax-rates` Get org-level tax rate overrides. #### `PUT /api/v1/settings/tax-rates` Requires `owner` or `admin`. --- ## 2. Database Schema Documentation **Source:** `packages/database/prisma/schema.prisma` **Database:** PostgreSQL 15 **ORM:** Prisma ### 2.1 Entity Relationship Diagram ```mermaid erDiagram Organization { UUID id PK VARCHAR(255) name VARCHAR(50) registrationNumber VARCHAR(50) vatNumber CHAR(3) baseCurrency "default: EUR" CHAR(2) country CHAR(2) language "default: sr" DATE fiscalYearStart TIMESTAMP createdAt TIMESTAMP updatedAt } User { UUID id PK UUID organizationId FK VARCHAR(255) email UK VARCHAR(255) passwordHash VARCHAR(255) fullName ENUM role "owner|admin|accountant|viewer" BOOLEAN twoFactorEnabled VARCHAR(255) twoFactorSecret TIMESTAMP lastLoginAt TIMESTAMP createdAt TIMESTAMP updatedAt } AccountType { INT id PK "autoincrement" VARCHAR(50) name UK ENUM normalBalance "debit|credit" TIMESTAMP createdAt } Account { UUID id PK UUID organizationId FK VARCHAR(10) code VARCHAR(255) name INT accountTypeId FK CHAR(3) currencyCode UUID parentAccountId FK "nullable, self-reference" BOOLEAN isActive TIMESTAMP createdAt TIMESTAMP updatedAt } Contact { UUID id PK UUID organizationId FK ENUM type "customer|vendor|both" VARCHAR(255) name VARCHAR(255) email VARCHAR(50) phone VARCHAR(50) registrationNumber VARCHAR(50) vatNumber VARCHAR(255) addressLine1 VARCHAR(255) addressLine2 VARCHAR(100) city VARCHAR(20) postalCode CHAR(2) country CHAR(3) currencyCode INT paymentTerms "default: 30 days" TEXT notes BOOLEAN isActive TIMESTAMP createdAt TIMESTAMP updatedAt } Invoice { UUID id PK UUID organizationId FK UUID customerId FK VARCHAR(50) invoiceNumber UK DATE invoiceDate DATE dueDate CHAR(3) currencyCode DECIMAL(12_6) exchangeRate DECIMAL(19_4) subtotal DECIMAL(19_4) taxAmount DECIMAL(19_4) discountAmount DECIMAL(19_4) totalAmount DECIMAL(19_4) baseAmount ENUM status "draft|sent|viewed|paid|overdue|cancelled" TIMESTAMP sentAt TIMESTAMP viewedAt TIMESTAMP paidAt TEXT notes TEXT terms VARCHAR(500) pdfUrl UUID createdBy FK TIMESTAMP createdAt TIMESTAMP updatedAt } InvoiceItem { UUID id PK UUID invoiceId FK INT lineNumber VARCHAR(500) description DECIMAL(10_2) quantity DECIMAL(19_4) unitPrice DECIMAL(5_2) taxRate DECIMAL(19_4) lineTotal UUID accountId FK "nullable" TIMESTAMP createdAt } Expense { UUID id PK UUID organizationId FK UUID vendorId FK "nullable" VARCHAR(50) expenseNumber UK DATE expenseDate CHAR(3) currencyCode DECIMAL(12_6) exchangeRate DECIMAL(19_4) amount DECIMAL(19_4) baseAmount DECIMAL(19_4) taxAmount VARCHAR(100) category VARCHAR(50) paymentMethod UUID accountId FK "nullable" TEXT description VARCHAR(500) receiptUrl ENUM status "pending|approved|paid|rejected" UUID approvedBy FK "nullable" TIMESTAMP approvedAt TIMESTAMP paidAt UUID createdBy FK TIMESTAMP createdAt TIMESTAMP updatedAt } Transaction { UUID id PK UUID organizationId FK DATE transactionDate VARCHAR(255) description UUID debitAccountId FK UUID creditAccountId FK DECIMAL(19_4) amount CHAR(3) currencyCode DECIMAL(12_6) exchangeRate DECIMAL(19_4) baseAmount VARCHAR(50) referenceType "invoice|expense|payment|manual" UUID referenceId "nullable" BOOLEAN locked "default: false" TIMESTAMP lockedAt BOOLEAN reconciled "default: false" TIMESTAMP reconciledAt TEXT notes UUID createdBy FK "nullable" TIMESTAMP createdAt } BankAccount { UUID id PK UUID organizationId FK UUID accountId FK VARCHAR(255) bankName VARCHAR(50) accountNumber VARCHAR(50) iban CHAR(3) currencyCode DECIMAL(19_4) currentBalance BOOLEAN isActive TIMESTAMP createdAt TIMESTAMP updatedAt } BankTransaction { UUID id PK UUID bankAccountId FK DATE transactionDate DECIMAL(19_4) amount VARCHAR(500) description VARCHAR(255) reference BOOLEAN reconciled UUID matchedTransactionId "nullable" TIMESTAMP createdAt } Currency { CHAR(3) code PK VARCHAR(100) name VARCHAR(10) symbol SMALLINT decimalPlaces "default: 2" BOOLEAN isActive TIMESTAMP createdAt } ExchangeRate { UUID id PK CHAR(3) baseCurrency FK CHAR(3) targetCurrency FK DECIMAL(12_6) rate DATE effectiveDate VARCHAR(50) source TIMESTAMP lastUpdated } LoggedAction { BIGINT eventId PK "autoincrement" TEXT schemaName TEXT tableName UUID userId FK "nullable" TIMESTAMP actionTimestamp ENUM action "INSERT|UPDATE|DELETE" JSONB rowData "full row snapshot" JSONB changedFields "diff for UPDATE" TEXT queryText INET clientIp TEXT applicationName "default: fiken-clone-api" } SchemaVersion { VARCHAR(20) version PK TIMESTAMP appliedAt TEXT description } Organization ||--o{ User : has Organization ||--o{ Account : owns Organization ||--o{ Contact : owns Organization ||--o{ Invoice : owns Organization ||--o{ Expense : owns Organization ||--o{ Transaction : owns Organization ||--o{ BankAccount : owns AccountType ||--o{ Account : classifies Account ||--o{ Account : "parent-child" Contact ||--o{ Invoice : "billed to" Contact ||--o{ Expense : "billed from" Invoice ||--o{ InvoiceItem : contains Account ||--o{ InvoiceItem : "revenue account" Account ||--o{ Expense : "expense account" Account ||--o{ BankAccount : links Account ||--o{ Transaction : "debit side" Account ||--o{ Transaction : "credit side" BankAccount ||--o{ BankTransaction : holds Currency ||--o{ ExchangeRate : "base" Currency ||--o{ ExchangeRate : "target" User ||--o{ LoggedAction : audits ``` ### 2.2 Key Indexes | Table | Index | Columns | Purpose | |-------|-------|---------|---------| | `users` | `idx_users_organization` | `organizationId` | User lookup by org | | `users` | `idx_users_email` | `email` | Login lookup | | `accounts` | `idx_accounts_organization` | `organizationId` | List accounts by org | | `accounts` | Unique | `organizationId, code` | Prevent duplicate account codes | | `invoices` | `idx_invoices_organization` | `organizationId` | List invoices by org | | `invoices` | `idx_invoices_status` | `status` | Filter by status | | `invoices` | `idx_invoices_due_date` | `dueDate` | Overdue detection | | `invoices` | `idx_invoices_org_status_date` | `organizationId, status, invoiceDate` | Complex report queries | | `transactions` | `idx_transactions_org_date` | `organizationId, transactionDate` | Date range queries | | `transactions` | `idx_transactions_reference` | `referenceType, referenceId` | Find transactions for an invoice/expense | | `exchange_rates` | `idx_exchange_rates_pair` | `baseCurrency, targetCurrency` | Currency pair lookup | | `exchange_rates` | Unique | `baseCurrency, targetCurrency, effectiveDate` | One rate per pair per day | | `logged_actions` | `idx_logged_actions_timestamp` | `actionTimestamp` | Audit log queries by time | --- ## 3. Service Layer Design All services follow the same pattern: - Constructor receives `PrismaClient` (or use singleton `prisma` from `lib/prisma.ts`) - All methods receive `organizationId` as first parameter - Return plain objects (not Prisma model instances) for clean API layer separation - Use Prisma transactions (`prisma.$transaction()`) for multi-step operations - Throw errors from `utils/errors.ts` for consistent HTTP responses ### 3.1 `InvoiceService` **File:** `apps/api/src/services/invoice.service.ts` | Method | Description | |--------|-------------| | `listInvoices(orgId, params)` | Paginated list with filters | | `getInvoice(orgId, id)` | Single invoice with items | | `createInvoice(orgId, userId, data)` | Create draft, calculate amounts, lock exchange rate | | `updateInvoice(orgId, id, data)` | Update draft only, recalculate if items changed | | `changeInvoiceStatus(orgId, id, data)` | Dispatches to `sendInvoice()`, `markInvoicePaid()`, `cancelInvoice()` | | `deleteInvoice(orgId, id)` | Delete draft only | | `generateInvoiceNumber(orgId)` | `INV-YYYY-NNN` sequential | | `getExchangeRate(from, to, date)` | DB lookup, falls back to 1.0 with warning | | `sendInvoice(invoice)` | Prisma tx: create DR Receivable/CR Revenue + update status | | `markInvoicePaid(invoice, paidAt)` | Prisma tx: create DR Bank/CR Receivable + update status | ### 3.2 `ExpenseService` **File:** `apps/api/src/services/expense.service.ts` | Method | Description | |--------|-------------| | `listExpenses(orgId, params)` | Paginated list with filters | | `getExpense(orgId, id)` | Single expense | | `createExpense(orgId, userId, data)` | Create pending, lock exchange rate | | `updateExpense(orgId, id, data)` | Update pending only | | `approveExpense(orgId, id, userId)` | Prisma tx: create DR Expense/CR Payable + update status | | `payExpense(orgId, id)` | Prisma tx: create DR Payable/CR Bank + update status | | `deleteExpense(orgId, id)` | Delete pending only | ### 3.3 `ContactService` **File:** `apps/api/src/services/contact.service.ts` | Method | Description | |--------|-------------| | `listContacts(orgId, params)` | Paginated list with type filter | | `getContact(orgId, id)` | Single contact | | `createContact(orgId, data)` | Create contact | | `updateContact(orgId, id, data)` | Update contact | | `deleteContact(orgId, id)` | Soft delete (`isActive = false`) | ### 3.4 `AccountService` **File:** `apps/api/src/services/account.service.ts` | Method | Description | |--------|-------------| | `listAccounts(orgId, params)` | List with optional balance calculation | | `createAccount(orgId, data)` | Create account (checks code uniqueness) | | `updateAccount(orgId, id, data)` | Update account metadata | ### 3.5 `ReportService` **File:** `apps/api/src/services/report.service.ts` | Method | Description | |--------|-------------| | `getDashboard(orgId)` | Aggregate MTD metrics | | `getProfitLoss(orgId, query)` | Revenue vs expense by account, net profit | | `getBalanceSheet(orgId, query)` | Assets, liabilities, equity as of date | | `getCashFlow(orgId, query)` | Operating/investing/financing cash flows | | `getVATReport(orgId, query)` | Output VAT (invoices) vs input VAT (expenses), net | | `getTrialBalance(orgId, query)` | All accounts with debit/credit totals, balanced check | | `getGeneralLedger(orgId, query)` | Per-account transaction history | ### 3.6 `BankingService` **File:** `apps/api/src/services/banking.service.ts` | Method | Description | |--------|-------------| | `listBankAccounts(orgId)` | List all active bank accounts | | `getBankAccount(orgId, id)` | Single account with recent transactions | | `createBankAccount(orgId, data)` | Create bank account linked to GL account | | `listBankTransactions(orgId, bankAccountId, params)` | Paginated bank transactions | | `importBankStatement(orgId, bankAccountId, csvContent)` | Parse CSV, detect duplicates, insert | | `reconcileTransaction(orgId, bankAccountId, body)` | Match bank transaction to GL transaction | ### 3.7 `SettingsService` **File:** `apps/api/src/services/settings.service.ts` | Method | Description | |--------|-------------| | `getOrganization(orgId)` | Organization details | | `updateOrganization(orgId, data)` | Update organization metadata | | `listUsers(orgId, params)` | List users in org | | `inviteUser(orgId, data)` | Create user with temporary password | | `changeUserRole(orgId, userId, requesterId, data)` | Change role (cannot demote self) | | `deleteUser(orgId, userId, requesterId)` | Remove user (cannot delete self) | | `listCurrencies()` | All active currencies | | `getExchangeRate(params)` | Get rate for currency pair on date | | `getTaxRates(orgId)` | Get org tax rate config | | `updateTaxRates(orgId, data)` | Update tax rate config | --- ## 4. Middleware Stack **File:** `apps/api/src/app.ts` Order is critical. Each middleware passes control to `next()` or sends error response. ``` Request │ ▼ 1. helmet() — Sets security headers (CSP, HSTS, X-Frame-Options: deny, noSniff) │ ▼ 2. cors() — Validates Origin header against whitelist [bilko.io, localhost:3000] │ credentials: true (allows cookies) ▼ 3. express.json() — Parses request body as JSON (limit: 10mb) │ ▼ 4. express.urlencoded() — Parses URL-encoded bodies (limit: 10mb) │ ▼ 5. cookieParser() — Parses cookie header, makes cookies accessible via req.cookies │ ▼ 6. apiLimiter — Rate limit: 100 req per 15 min per IP (applied to /api/v1/*) │ authLimiter — Stricter rate limit on /auth/login and /auth/register ▼ 7. routes — Mounts all route modules at /api/v1 │ ├── authGuard() — Verifies JWT Bearer token, attaches req.user │ Source: apps/api/src/middleware/auth.ts │ ├── organizationScope() — Validates req.user.organizationId (currently no-op, used as anchor) │ Source: apps/api/src/middleware/org-scope.ts │ ├── validate(schema) — Validates req.body or req.query against Zod schema │ Source: apps/api/src/middleware/validate.ts │ └── routeHandler — Business logic (calls service layer) │ ▼ 8. errorHandler() — Centralized error handler (MUST be last) Source: apps/api/src/middleware/error-handler.ts Translates AppError → HTTP status + JSON ``` **Error response format:** ```json { "error": "Invoice not found", "code": "NOT_FOUND", "details": {} } ``` **HTTP status codes used:** - `400` — Validation error, bad request - `401` — Missing token, expired token, invalid credentials - `403` — Insufficient permissions (role check) - `404` — Resource not found - `409` — Duplicate (unique constraint) - `422` — Unprocessable entity (e.g., same debit/credit account) - `429` — Rate limit exceeded - `500` — Unhandled server error --- ## 5. Double-Entry Bookkeeping Implementation **Core library:** `packages/core/src/accounting/index.ts` **Prisma model:** `Transaction` in `packages/database/prisma/schema.prisma` ### 5.1 Fundamental Rule Every financial event creates exactly one `Transaction` record with: - `debitAccountId` — account to debit - `creditAccountId` — account to credit - `amount` — must be equal for both sides (enforced by model design, not DB constraint) - `currencyCode` + `exchangeRate` + `baseAmount` — for multi-currency ### 5.2 `validateDoubleEntry()` (core engine) ```typescript // packages/core/src/accounting/index.ts export function validateDoubleEntry(lines: JournalEntryLine[]): boolean { // Returns false if: < 2 lines, negative amounts, unbalanced let totalDebits = new Decimal(0); let totalCredits = new Decimal(0); for (const line of lines) { const amount = new Decimal(line.amount); if (amount.lte(0)) return false; if (line.side === 'debit') totalDebits = totalDebits.plus(amount); else totalCredits = totalCredits.plus(amount); } return totalDebits.eq(totalCredits); } ``` ### 5.3 Transaction Creation Patterns **Invoice sent (DR Receivable / CR Revenue):** ``` DR Accounts Receivable (code: 12x) +120,000 RSD CR Revenue (code: 6xx) +120,000 RSD ``` **Payment received (DR Bank / CR Receivable):** ``` DR Bank Account (code: 10x) +120,000 RSD CR Accounts Receivable (code: 12x) +120,000 RSD ``` **Expense approved (DR Expense / CR Payable):** ``` DR Expense Account (code: 5xx) +5,000 RSD CR Accounts Payable (code: 22x) +5,000 RSD ``` **Expense paid (DR Payable / CR Bank):** ``` DR Accounts Payable (code: 22x) +5,000 RSD CR Bank Account (code: 10x) +5,000 RSD ``` ### 5.4 Account Lookup Strategy Services find accounts by account type ID + code prefix: - `accountTypeId: 1` = Asset - `accountTypeId: 2` = Liability - `accountTypeId: 3` = Equity - `accountTypeId: 4` = Revenue - `accountTypeId: 5` = Expense Code prefixes (Balkan chart of accounts): - `10x` = Bank/Cash accounts - `12x` = Accounts Receivable - `22x` = Accounts Payable - `5xx` = Expense accounts - `6xx` = Revenue accounts ### 5.5 Trial Balance ```typescript // packages/core/src/accounting/index.ts export function calculateTrialBalance(transactions: JournalEntry[]): TrialBalance { // Groups by accountNumber, sums debits and credits // Returns: { rows[], totalDebits, totalCredits, isBalanced } // isBalanced = totalDebits.eq(totalCredits) } ``` --- ## 6. Tax Calculation Logic Per Country **Core module:** `packages/core/src/tax/index.ts` **Country modules:** `packages/country-{rs|ba|hr}/src/tax/index.ts` ### 6.1 Serbia (RS) **File:** `packages/country-rs/src/tax/index.ts` | Rate | Value | Applies To | |------|-------|-----------| | Standard | 20% | Most taxable supplies | | Reduced | 10% | Basic food, medicine, newspapers, public transport, utilities | | Zero/Exempt | 0% | Exports, international transport, financial services | ```typescript export const serbianVATRates = { standard: '20', reduced: '10', zero: '0', exempt: '0' } // VAT registration: mandatory above 8M RSD annual revenue export const SERBIAN_VAT_THRESHOLD = '8000000'; // Pausal (simplified) regime: below 6M RSD export const SERBIAN_PAUSAL_THRESHOLD = '6000000'; // Corporate income tax export const SERBIAN_CIT_RATE = '15'; // flat 15% ``` **Key function:** ```typescript export function calculateSerbianPDV(amount: MonetaryAmount, rate = 'standard'): string { // Returns: net.times(rateDecimal).dividedBy(100).toFixed(2) } ``` ### 6.2 Bosnia & Herzegovina (BA) **File:** `packages/country-ba/src/tax/index.ts` | Rate | Value | Applies To | |------|-------|-----------| | Standard | 17% | All taxable supplies (single rate, no reduced) | | Zero | 0% | Exports | ```typescript export const bosnianVATRates = { standard: '17', zero: '0' } // Registration threshold: 100,000 BAM export const BIH_VAT_THRESHOLD = '100000'; // CIT: 10% for both FBiH and RS entities export const BIH_CIT_RATES = { fbih: '10', rs: '10' } // WHT: FBiH dividends 5%, RS dividends 10% export const BIH_WHT_RATES = { fbih: { dividends: '5', interest: '10' }, rs: { dividends: '10', ... } } ``` ### 6.3 Croatia (HR) **File:** `packages/country-hr/src/tax/index.ts` | Rate | Value | Applies To | |------|-------|-----------| | Standard | 25% | Most taxable supplies | | Reduced | 13% | Food products, accommodation, utilities | | Super-reduced | 5% | Books, medicines, newspapers | | Zero | 0% | Intra-EU transport, international transport | ```typescript export const croatianVATRates = { standard: '25', reduced: '13', superReduced: '5', zero: '0' } // Registration threshold: 60,000 EUR (aligned with EU 2025) export const CROATIAN_VAT_THRESHOLD = '60000'; // CIT: progressive — 10% if revenue < 1M EUR, 18% if >= 1M EUR export const CROATIAN_CIT_RATES = { small: '10', standard: '18', threshold: '1000000' } ``` ### 6.4 Generic VAT Calculation (Core Engine) ```typescript // packages/core/src/tax/index.ts export function calculateVAT(amount: MonetaryAmount, rate: MonetaryAmount): VATResult { const base = new Decimal(amount); // net amount const vatRate = new Decimal(rate); const tax = base.times(vatRate).dividedBy(100); const total = base.plus(tax); return { base: new Decimal(base.toFixed(4)), tax: new Decimal(tax.toFixed(4)), total: new Decimal(total.toFixed(4)), }; } export function calculateNetFromGross(grossAmount: MonetaryAmount, vatRate: MonetaryAmount): VATResult { // Reverse VAT: gross / (1 + rate/100) const divisor = new Decimal(100).plus(new Decimal(vatRate)).dividedBy(100); const base = new Decimal(grossAmount).dividedBy(divisor); ... } ``` --- ## 7. Invoice Lifecycle ### 7.1 Status Machine ``` draft ──[send]──► sent ──[mark-paid]──► paid │ │ │ [cancel] │ │ └────[cancel]──► cancelled sent ──[overdue cron]──► overdue ──[mark-paid]──► paid viewed ──[mark-paid]──► paid ``` ### 7.2 Numbering Invoice numbers are generated sequentially per organization per year: `INV-YYYY-NNN` (e.g., `INV-2026-001`). The service queries the last invoice number with the current year prefix and increments. ```typescript private async generateInvoiceNumber(organizationId: string): Promise { const year = new Date().getFullYear(); const prefix = `INV-${year}-`; const lastInvoice = await prisma.invoice.findFirst({ where: { organizationId, invoiceNumber: { startsWith: prefix } }, orderBy: { invoiceNumber: 'desc' }, }); const nextNumber = lastInvoice ? parseInt(lastInvoice.invoiceNumber.split('-')[2]) + 1 : 1; return `${prefix}${String(nextNumber).padStart(3, '0')}`; } ``` ### 7.3 Amount Calculation On create/update: 1. For each line item: `lineTotal = quantity × unitPrice` 2. `taxAmount` per line: `lineTotal × taxRate / 100` 3. `subtotal = Σ lineTotals` 4. `taxAmount = Σ lineTax amounts` 5. `totalAmount = subtotal + taxAmount` 6. `baseAmount = totalAmount × exchangeRate` All using `Decimal.js` — never JavaScript `number`. --- ## 8. Bank Import Flow **Source:** `packages/core/src/bank-import/index.ts` ### 8.1 CSV Format ``` Date,Amount,Currency,Direction,Counterparty,Reference,Description 2026-02-01,5000.00,RSD,inbound,Acme Client,INV-2026-001,Invoice payment ``` Supported date formats: `YYYY-MM-DD`, `DD.MM.YYYY`, `DD/MM/YYYY` ### 8.2 Import Process ``` POST /api/v1/bank-accounts/:id/import │ ├── parseCSV(csvContent) → BankTransaction[] │ - Split by newline, skip header │ - Parse each field: date, amount, currency, direction, reference │ - Generate deterministic ID for dedup: hash(date|amount|currency|reference|lineIndex) │ ├── detectDuplicates(existingTxs, importedTxs) │ - Fingerprint: YYYY-MM-DD|amount|currency|reference │ - Returns list of duplicate transactions │ ├── Filter out duplicates │ └── Insert new BankTransactions into database Returns: { imported: N, duplicates: M, errors: K } ``` ### 8.3 Reconciliation Manual reconciliation links a `BankTransaction` to a `Transaction` (GL entry): ``` POST /api/v1/bank-accounts/:id/reconcile body: { bankTransactionId, transactionId } │ ├── Verify both belong to organization ├── Set BankTransaction.reconciled = true ├── Set BankTransaction.matchedTransactionId = transactionId └── Set Transaction.reconciled = true ``` --- ## 9. Core Engine Modules **Package:** `@bilko/core` (`packages/core/src/`) | Module | File | Purpose | |--------|------|---------| | `accounting` | `src/accounting/index.ts` | `validateDoubleEntry`, `createJournalEntry`, `calculateTrialBalance` | | `tax` | `src/tax/index.ts` | `calculateVAT`, `calculateNetFromGross`, `getVATRates`, `calculateCIT` | | `multi-currency` | `src/multi-currency/index.ts` | `convertCurrency`, `lockExchangeRate`, `calculateForexGainLoss` | | `bank-import` | `src/bank-import/index.ts` | `parseCSV`, `detectDuplicates` | | `invoicing` | `src/invoicing/index.ts` | Invoice computation helpers | | `chart-of-accounts` | `src/chart-of-accounts/index.ts` | Chart structure definitions | | `reporting` | `src/reporting/index.ts` | Report calculation utilities | **Key constraint:** `MonetaryAmount = string | Decimal` — JavaScript `number` is never used for monetary values anywhere in the core engine. # Validation Report # Bilko Validation Report **Date:** 2026-02-20 **Validator:** John (AI Director) — Gate Validation Phase **Project ID:** bbd77cc0 ## Executive Summary **7 out of 8 gates PASS.** Bilko is architecturally sound with comprehensive documentation, validated schema, and working frontend prototype. Gate 8 (CEO Approval) remains PENDING as required. No blocking issues found. Ready for executive review. **Key Findings:** - All 23 documentation files exist and are detailed (12,127 lines total) - Database schema matches PRD requirements with proper accounting architecture - Frontend implemented (10 pages) with design system consistency - Regulatory research complete for all 3 target countries - No phantom features, no hallucinated data, no cross-document contradictions --- ## Gate Results ### Gate 1: Market Research — **PASS** **Evidence:** ~/system/specs/bilko-prd.md (lines 11-22) **Findings:** - ✅ TAM documented: €50-150M addressable market - ✅ Target market defined: 348K businesses across Serbia, BiH, Croatia - ✅ Customer pain points identified: Lack of local tax compliance, multi-currency support, regional language support - ✅ Forcing function documented: Croatia 2026 e-invoicing mandate - ✅ Real market data (not phantom): Numbers cite regulatory requirements and business counts **Issues:** None --- ### Gate 2: Competitive Analysis — **PASS** **Evidence:** ~/system/specs/bilko-prd.md (implicit in positioning), ~/system/specs/bilko-tech-stack.md (lines 45-49, alternatives sections) **Findings:** - ✅ Real competitors analyzed: Fiken (Norway), QuickBooks, Wave - ✅ Differentiation strategy clear: Balkan localization (PDV/SEF/eRačun compliance), multi-currency native, local Chart of Accounts - ✅ Competitive positioning documented in brand identity spec - ✅ No phantom competitors (all mentioned companies are real) **Issues:** None --- ### Gate 3: Tech Stack Decision — **PASS** **Evidence:** ~/system/specs/bilko-tech-stack.md (full doc), /Users/makinja/ALAI/products/Bilko/apps/web/package.json **Findings:** - ✅ Stack fully documented with rationale for each choice - ✅ Installed packages match specification: - Frontend: Next.js 15.0.0, React 19.0.0, Tailwind CSS 4.0.0, TypeScript 5.3.0, Recharts 2.15.0, Zustand 4.5.0, shadcn/ui (Radix UI primitives) - Backend: PostgreSQL + Prisma specified (not implemented yet, by design) - ✅ Monorepo structure exists (apps/web, apps/api, packages/database) - ✅ Cost breakdown realistic: €21/mo MVP hosting - ✅ Technical debt intentionally documented (no Redis, no multi-region, monolith first) **Issues:** None --- ### Gate 4: Product Requirements (PRD) — **PASS** **Evidence:** ~/system/specs/bilko-prd.md (137 lines) **Findings:** - ✅ All MUST-HAVE features defined (9 core + 3 Balkan-specific) - ✅ Acceptance criteria present: 80% activation, <15% churn, NPS >50, 99.5% uptime - ✅ Success metrics documented for product, business, quality - ✅ NICE-TO-HAVE features prioritized (v2): Payroll (HIGH), AI automation (HIGH), Time tracking (MEDIUM) - ✅ Out-of-scope clearly documented - ✅ Open questions identified for research (MC task #1492) - ✅ All 3 target countries covered (Serbia, BiH, Croatia) **Cross-validation with schema:** - ✅ Invoicing → Invoice + InvoiceItem models - ✅ Expenses → Expense model - ✅ Banking → BankAccount + BankTransaction models - ✅ VAT/Tax → Transaction model with tax tracking - ✅ Double-entry → Transaction model with debit/credit accounts - ✅ Multi-currency → Currency + ExchangeRate models - ✅ User collaboration → User model with RBAC (owner/admin/accountant/viewer) - ✅ Security → LoggedAction audit trail **Issues:** None --- ### Gate 5: Database Schema — **PASS** **Evidence:** /Users/makinja/ALAI/products/Bilko/packages/database/prisma/schema.prisma (485 lines), docs/backend/DATABASE-SCHEMA.md (600+ lines) **Findings:** **Schema Coverage (15 models):** - ✅ Organization — Multi-tenant root with baseCurrency, country, language - ✅ User — RBAC with 4 roles (owner, admin, accountant, viewer) - ✅ AccountType + Account — Chart of Accounts with parent-child hierarchy - ✅ Contact — Customers/vendors with multi-currency support - ✅ Invoice + InvoiceItem — Multi-currency invoicing with tax - ✅ Expense — Purchase tracking with approval workflow - ✅ Transaction — Double-entry ledger (debitAccountId + creditAccountId) - ✅ BankAccount + BankTransaction — Bank reconciliation - ✅ Currency + ExchangeRate — Multi-currency with rate locking - ✅ LoggedAction — Immutable audit trail (APPEND-ONLY) - ✅ SchemaVersion — Migration tracking **PRD Feature Validation:** 1. ✅ Invoicing & Estimates — Invoice model with line items, VAT calculation, multi-currency, status tracking 2. ✅ Expense Tracking — Expense model with categories, receipt URL, payment method 3. ✅ Bank Integration — BankAccount + BankTransaction models with reconciliation flags 4. ✅ Financial Reporting — Transaction + Account models support P&L, Balance Sheet, Cash Flow 5. ✅ VAT/Tax Management — InvoiceItem.taxRate, Expense.taxAmount 6. ✅ Double-Entry Bookkeeping — Transaction model with debitAccount + creditAccount, NormalBalance enum 7. ✅ Multi-Device Access — API-first architecture (supports web + mobile PWA) 8. ✅ User Collaboration — User model with role enum, LoggedAction audit trail 9. ✅ Security — LoggedAction immutable audit, password hashing, 2FA fields (twoFactorEnabled, twoFactorSecret) **Critical Validations:** - ✅ **Money fields use NUMERIC(19,4)** — All amount columns use `@db.Decimal(19, 4)` (Invoice.totalAmount, Expense.amount, Transaction.amount) - ✅ **Double-entry enforced** — Transaction has both debitAccountId and creditAccountId (both NOT NULL) - ✅ **Multi-currency with rate locking** — Invoice.exchangeRate, Expense.exchangeRate, Transaction.exchangeRate all present - ✅ **Audit trail immutable** — LoggedAction has no UPDATE/DELETE relations, event_id is autoincrement (append-only) - ✅ **UUID primary keys** — All models use `uuid_generate_v4()` except AccountType (int) and LoggedAction (BigInt autoincrement) - ✅ **Organization-scoped multi-tenancy** — All business entities have organizationId FK with CASCADE delete **No Phantom Features:** - ✅ All models map to PRD features - ✅ No unexplained models (e.g., no "Inventory" or "Projects" which are out-of-scope for MVP) **Issues:** None --- ### Gate 6: UI/UX Design — **PASS** **Evidence:** ~/system/specs/bilko-wireframes.md (634 lines), apps/web/ implementation (10 pages), docs/frontend/ (5 files) **Findings:** **Wireframe Coverage:** - ✅ Screen 1: Dashboard — Implemented at /dashboard (metrics, charts, recent transactions, quick actions) - ✅ Screen 2: Invoice Creation — Implemented at /invoices/new (6-step wizard matches spec) - ✅ Screen 3: Expense Tracking — Implemented at /expenses (list view with filters) - ✅ Screen 4: VAT Reporting — Implemented at /reports/vat (audit table, summary) - ✅ Screen 5: Reports Dashboard — Implemented at /reports (hub with P&L, Balance Sheet, VAT, etc.) **Implemented Pages (10):** 1. /dashboard — Dashboard with metrics + charts 2. /invoices — Invoice list with search/filter 3. /invoices/new — 6-step invoice wizard 4. /expenses — Expense list 5. /purchases — Alias to expenses 6. /banking — Placeholder (wireframe pending) 7. /reports — Reports hub 8. /reports/vat — VAT report 9. /settings — User settings 10. / (root) — Redirects to dashboard **Design System Consistency:** - ✅ **Colors:** Primary #00E5A0 matches brand spec (bilko-brand-identity.md line 38) - ✅ **Typography:** Inter font used throughout (matches brand spec line 71) - ✅ **Spacing:** 8px grid system implemented in tailwind.config.ts (matches brand spec line 90) - ✅ **Components:** 17 shadcn/ui components installed (Radix UI primitives for accessibility) - ✅ **Chart library:** Recharts used (matches tech stack spec line 193) **Cross-validation (tailwind.config.ts vs DESIGN-SYSTEM.md):** - ✅ Primary color: #00E5A0 in both - ✅ Success/Warning/Error colors match - ✅ Text colors (primary/secondary/muted) match - ✅ Sidebar dark theme (#111113) matches - ✅ Font sizes (xs through 4xl) match - ✅ Spacing tokens (xs through 3xl) match **Responsive Design:** - ✅ Mobile-first Tailwind approach - ✅ Sidebar collapses to overlay on mobile - ✅ Charts responsive (ResponsiveContainer in Recharts) **Issues:** None --- ### Gate 7: Regulatory Compliance — **PASS** **Evidence:** docs/regulatory/ (4 files: SERBIA-SEF.md, BIH-PDV.md, CROATIA-ERACUN.md, CHART-OF-ACCOUNTS.md) **Findings:** **Serbia (SERBIA-SEF.md — 351 lines):** - ✅ **VAT Rate:** 20% standard, 10% reduced — **[HIGH confidence]** - ✅ **E-Invoicing:** SEF mandatory since Jan 1, 2023 (B2B) — **[HIGH confidence]** - ✅ **Format:** UBL 2.1 XML — **[HIGH confidence]** - ✅ **Platform:** efaktura.mfin.gov.rs — **[HIGH confidence]** - ✅ **Chart of Accounts:** Kontni Okvir (Class 0-9 structure) — **[HIGH confidence]** - ⚠️ **Digital Certificate:** Qualified cert for signing — **[MEDIUM confidence]** (needs advisor verification) - ✅ **E-Transport:** Mandatory 2026-01-01 (public sector), 2027-10-01 (full) — **[HIGH confidence]** - ✅ **No LOW-confidence MVP blockers** **Bosnia & Herzegovina (BIH-PDV.md — 310 lines):** - ✅ **VAT Rate:** 17% standard (single rate) — **[HIGH confidence]** - ✅ **Filing:** Monthly (UNO/ITA) — **[HIGH confidence]** - ⚠️ **E-Invoicing:** Draft law proposed for 2026-01-01 — **[MEDIUM confidence]** (implementation pending) - ⚠️ **Format:** EN 16931 compliance planned — **[MEDIUM confidence]** (final regulations awaited) - ✅ **Chart of Accounts:** Two-entity system (FBiH uses IFRS, RS uses own standard) — **[HIGH confidence]** - ⚠️ **Platform:** Central Platform for Fiscalisation (CPF) planned — **[MEDIUM confidence]** - ✅ **No LOW-confidence MVP blockers** (can launch with PDF invoices, add e-invoicing when regulations finalize) **Croatia (CROATIA-ERACUN.md — 404 lines):** - ✅ **VAT Rates:** 25% standard, 13% reduced, 5% super-reduced — **[HIGH confidence]** - ✅ **E-Invoicing B2G:** Mandatory since 2019-07-01 — **[HIGH confidence]** - ✅ **E-Invoicing B2B:** Mandatory since 2026-01-01 (Fiscalization 2.0) — **[HIGH confidence]** - ✅ **Format:** UBL 2.1 or CII (EN 16931 compliance) — **[HIGH confidence]** - ✅ **Platform:** Servis eRačun za državu + FINA — **[HIGH confidence]** - ✅ **Fiscalization 1.0:** B2C cash register real-time fiscalization — **[HIGH confidence]** - ✅ **Chart of Accounts:** RRiF standards — **[HIGH confidence]** - ✅ **No LOW-confidence claims** **Chart of Accounts (CHART-OF-ACCOUNTS.md — 523 lines):** - ✅ Serbia: 10-class structure documented (Class 0-9) - ✅ BiH: FBiH (IFRS) + RS (national) dual system explained - ✅ Croatia: RRiF class-based structure documented - ✅ Database schema Account model supports all 3 systems (code field, hierarchical parent-child) **Tax Rates Cross-Check:** - ✅ Serbia: 20% PDV ← Correct (PRD line 29, regulatory doc line 13) - ✅ BiH: 17% PDV ← Correct (PRD line 29, regulatory doc line 15) - ✅ Croatia: 25% VAT ← Correct (PRD line 29, regulatory doc line 17) **MVP Blockers:** - ✅ No LOW-confidence regulatory claims that block MVP - ⚠️ BiH e-invoicing pending (MEDIUM confidence) — NOT blocking (can use PDF invoices initially) - ⚠️ Serbia digital cert (MEDIUM confidence) — NOT blocking (can defer e-invoicing integration to post-MVP) **Issues:** None (2 MEDIUM-confidence items are not MVP blockers) --- ### Gate 8: CEO Approval — **PENDING** **Evidence:** Awaiting Alem review **Findings:** **Executive Summary for CEO:** 1. **Business Case:** - TAM: €50-150M (348K businesses across Serbia, BiH, Croatia) - Forcing function: Croatia 2026 e-invoicing mandate - Pricing: €8-25/month (competitive with Fiken, undercuts QuickBooks) - Bootstrap budget: €2K MVP, €11-17K Phase 1 2. **Technical Architecture:** - Next.js 15 + React 19 + PostgreSQL + Prisma (proven stack) - Frontend: 10 pages implemented with mock data (ready for API integration) - Database: 15 models, fully validated against PRD - Hosting: €21/mo MVP (Vercel + Railway) 3. **Regulatory Compliance:** - All 3 target countries researched (Serbia, BiH, Croatia) - Tax rates verified, e-invoicing requirements documented - Chart of Accounts standards identified - No blocking compliance issues 4. **Documentation Quality:** - 23 documentation files, 12,127 lines total - Backend specification complete (50 API endpoints) - Frontend specification complete (design system + component inventory) - Testing strategy defined (Vitest + Supertest + Playwright) - Security architecture planned (JWT, RBAC, encryption) 5. **Resource Plan:** - Timeline: 8-10 weeks MVP - Team: 1 developer (€3-5K/month), 1 accounting advisor (€500/month) - Next step: Hire developer, finalize brand name (Bilko reserved) 6. **Risk Assessment:** - **LOW RISK:** BiH e-invoicing pending (can use PDF invoices initially) - **LOW RISK:** Serbia SEF integration requires digital cert (defer to post-MVP) - **MEDIUM RISK:** Competitive market (mitigated by Balkan localization) 7. **Go-to-Market Strategy:** - Launch: Serbia first (largest market, SEF integration differentiator) - Expand: Croatia (e-invoicing mandate = forced adoption) - Expand: BiH (when e-invoicing regulations finalized) **Recommendation:** APPROVE — All gates validated, architecture sound, regulatory research complete, no blocking issues. **Next Steps (if approved):** 1. Hire backend developer (€3-5K/month) 2. Hire accounting advisor (€500/month, Serbia-based) 3. Backend implementation (8-10 weeks) 4. Beta testing with 5 SMBs + 3 accountants 5. Launch Serbia MVP **Issues:** None --- ## Cross-Document Consistency Check **CLAUDE.md files:** - ✅ /Users/makinja/ALAI/products/Bilko/CLAUDE.md — Consistent with project structure, references PIPELINE.md correctly - ✅ /Users/makinja/ALAI/products/Bilko/apps/web/CLAUDE.md — Consistent with package.json, design system spec - ✅ /Users/makinja/ALAI/products/Bilko/packages/database/CLAUDE.md — Consistent with schema.prisma **Specs vs Docs:** - ✅ PRD features ↔ Database schema — All features have schema models - ✅ Wireframes ↔ Implemented pages — All wireframed screens implemented - ✅ Tech stack spec ↔ package.json — All specified packages installed - ✅ Brand identity ↔ Design system — Colors, typography, spacing match - ✅ Regulatory docs ↔ PRD — Tax rates consistent **No Contradictions Found:** - ✅ All file references valid (no phantom paths) - ✅ All version numbers consistent (Next.js 15, React 19, PostgreSQL 14+) - ✅ All numeric data consistent (TAM, pricing, timeline) --- ## Issues Found | # | Severity | Gate | Issue | Recommendation | |---|----------|------|-------|----------------| | 1 | INFO | 7 | Serbia digital certificate requirement has MEDIUM confidence | Consult local accounting advisor before SEF integration | | 2 | INFO | 7 | BiH e-invoicing regulations pending (draft law in Parliament) | Monitor UNO/ITA website, can launch with PDF invoices initially | **No HIGH-severity issues. No MEDIUM-severity issues blocking MVP.** --- ## Conclusion Bilko has passed all 7 pre-approval gates with **ZERO blocking issues**. The project demonstrates: 1. **Thorough research** — Real market data, real competitors, regulatory compliance verified 2. **Sound architecture** — Database schema validated, double-entry enforced, multi-currency correct 3. **Comprehensive documentation** — 23 files, 12,127 lines, covering backend, frontend, infrastructure, security, testing, regulatory 4. **Working prototype** — 10 pages implemented, design system consistent, mock data ready for API replacement 5. **No hallucinations** — All file paths valid, all companies real, all numbers cross-validated **READY FOR GATE 8 CEO APPROVAL.** --- **Validation completed by:** John (AI Director) **Timestamp:** 2026-02-20T11:45:00Z **Validator confidence:** HIGH (all source files read and cross-validated) # Bilko — Project Handbook # Bilko — Balkan Accounting SaaS ## BookStack — Provjeri PRVO Prije traženja bilo čega — provjeri BookStack (http://localhost:6875). Centralna baza znanja za tools, skills, hooks, agents, rules, projekte, klijente, dokumentaciju. Ako odgovor postoji tamo — NE TRAŽI dalje. ## Quick Info - **What:** Cloud accounting for Balkan SMBs (Serbia, BiH, Croatia) - **Target:** 50K-500K SMBs across Balkan region - **Inspiration:** Fiken (Norway) — simple, compliant, affordable - **Pipeline:** See PIPELINE.md (8-gate checklist) - **Project ID:** bbd77cc0 - **Domains:** bilko.io (primary), bilko.rs (Serbia redirect) ## Branding - **Name:** Bilko (from Serbian "bilans" = balance sheet) - **Primary Color:** #00E5A0 (mint green) - **Font:** Inter (Google Fonts) - **Grid:** 8px spacing system - **Icons:** Lucide React ## Tech Stack - **Frontend:** Next.js 15 + React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui - **Backend:** Express + TypeScript + PostgreSQL + Prisma (NOT BUILT YET) - **State:** Zustand (installed but mostly React hooks currently) - **Charts:** Recharts (BarChart, PieChart, LineChart) - **Monorepo:** Turborepo ## Project Structure ``` Bilko/ ├── apps/ │ ├── web/ # Next.js 15 frontend — 8+ pages, MOCK DATA │ └── api/ # Express backend — EMPTY (see api/CLAUDE.md) ├── packages/ │ ├── database/ # Prisma schema — 15 models, FULLY DEFINED │ └── ui/ # Shared UI — empty scaffold ├── docs/ # TO BE CREATED ├── CLAUDE.md # This file └── PIPELINE.md # Gate tracker ``` ## Frontend Status (apps/web/) **IMPLEMENTED:** - Dashboard (revenue, expenses, charts) - Invoices List + Create (6-step wizard) - Expenses List - Purchases (alias to expenses) - Banking (placeholder) - Reports Hub + VAT Report - Settings - Layout (sidebar + top-bar) **MOCK DATA:** All data from `apps/web/lib/mock-data.ts` — MUST be replaced with real API calls when backend ready. ## Database Status (packages/database/) **FULLY DEFINED:** 15 models in `prisma/schema.prisma` - Organization, User, AccountType, Account, Contact - Invoice, InvoiceItem, Expense, Transaction - BankAccount, BankTransaction, Currency, ExchangeRate - LoggedAction (audit), SchemaVersion **KEY DECISIONS:** - Double-entry bookkeeping (debit/credit in Transaction model) - Multi-currency with exchange rate locking at transaction date - NUMERIC(19,4) for ALL monetary amounts — NEVER use float - UUID primary keys throughout - Immutable audit trail (LoggedAction table is APPEND-ONLY) - Organization-scoped multi-tenancy - RBAC: owner, admin, accountant, viewer ## Backend Status (apps/api/) **NOT BUILT YET.** See `apps/api/CLAUDE.md` for target architecture. When building, follow `docs/backend/API-REFERENCE.md` (to be created). ## Development Rules 1. **Money = NUMERIC(19,4)** — NEVER use float or number for currency 2. **Double-entry always** — Every financial event = debit + credit entries 3. **Multi-currency locking** — Exchange rate locked at transaction date 4. **Immutable audit** — LoggedAction is append-only, NEVER delete 5. **Mock data replacement** — Flag all mock data usage, replace with API calls 6. **Schema migrations** — Always create new migration, NEVER edit existing ## Specs Location All specs in `~/system/specs/bilko-*.md`: - bilko-prd.md (product requirements) - bilko-tech-stack.md (technical decisions) - bilko-wireframes.md (UI specs) - bilko-brand-identity.md (branding) ## Documentation - Root index: `docs/INDEX.md` (to be created) - Backend API: `docs/backend/API-REFERENCE.md` (contract for api/ implementation) - Regulatory: `docs/regulatory/` (Serbia/BiH/Croatia accounting laws) # Pipeline Gate Tracker # Bilko Pipeline — 8-Gate Tracker ## Overview This document tracks Bilko's progress through the 8-gate pipeline from concept to CEO approval. **Project:** Bilko (Balkan Accounting SaaS) **Project ID:** bbd77cc0 **Company:** SnowIT Internal R&D **Created:** 2026-02-19 ## Gate Definitions 1. **Market Research** — TAM/SAM/SOM analysis, customer pain points 2. **Competitive Analysis** — Competitor landscape, differentiation strategy 3. **Tech Stack Decision** — Frontend, backend, database, hosting choices 4. **Product Requirements** — PRD with features, user stories, acceptance criteria 5. **Database Schema** — Full schema design validated against PRD 6. **UI/UX Design** — Wireframes, mockups, design system 7. **Regulatory Compliance** — Legal research (Serbia, BiH, Croatia accounting laws) 8. **CEO Approval** — Final go/no-go decision from Alem ## Current Status | Gate | Name | Status | Date | Evidence | |------|------|--------|------|----------| | 1 | Market Research | **PASS** | 2026-02-19 | ~/system/specs/bilko-prd.md (TAM section) | | 2 | Competitive Analysis | **PASS** | 2026-02-19 | ~/system/specs/bilko-prd.md (competitors section) | | 3 | Tech Stack Decision | **PASS** | 2026-02-19 | ~/system/specs/bilko-tech-stack.md | | 4 | Product Requirements | **PASS** | 2026-02-20 | Validated — All features mapped to schema, acceptance criteria defined | | 5 | Database Schema | **PASS** | 2026-02-20 | Validated — 15 models cover all PRD features, double-entry enforced | | 6 | UI/UX Design | **PASS** | 2026-02-20 | Validated — 10 pages implemented, design system consistent | | 7 | Regulatory Compliance | **PASS** | 2026-02-20 | Validated — All 3 countries researched (Serbia, BiH, Croatia), no blockers | | 8 | CEO Approval | **PASS** | 2026-02-20 | Approved by Alem — CODE UNFROZEN | ## Gate Validation Summary (2026-02-20) **Validation performed by:** John (AI Director) **Full report:** docs/VALIDATION-REPORT.md ### Gate 4: Product Requirements — **PASS** - ✅ All features mapped to user stories - ✅ Acceptance criteria defined - ✅ Technical feasibility confirmed - ✅ Resource estimate (8-10 weeks MVP, €2K bootstrap) ### Gate 5: Database Schema — **PASS** - ✅ All PRD features covered by schema (15 models) - ✅ No phantom features in schema not in PRD - ✅ Multi-currency support validated (Currency + ExchangeRate models) - ✅ Double-entry bookkeeping validated (Transaction.debitAccountId + creditAccountId) - ✅ Audit trail meets compliance needs (LoggedAction append-only) ### Gate 6: UI/UX Design — **PASS** - ✅ All pages match wireframes (10 pages implemented) - ✅ Design system consistent (colors, typography, spacing verified) - ✅ Responsive design validated (mobile-first Tailwind) - ✅ Accessibility compliance (shadcn/ui Radix primitives) - ✅ User flows tested (invoice wizard, expense entry, reports) ### Gate 7: Regulatory Compliance — **PASS** - ✅ Serbia — SEF e-invoicing, 20% PDV, Kontni Okvir Chart of Accounts - ✅ BiH — 17% PDV, IFRS/RS accounting, e-invoicing draft law monitored - ✅ Croatia — eRačun mandatory 2026, 25% VAT, RRiF Chart of Accounts - ✅ No LOW-confidence MVP blockers - ⚠️ 2 MEDIUM-confidence items (BiH e-invoicing pending, Serbia digital cert) — NOT blocking ### Gate 8: CEO Approval — **PASS** **Approved by Alem on 2026-02-20** ✅ **CODE UNFROZEN — Backend development started** **Deliverables:** - ✅ Backend foundation implemented (Express + TypeScript) - ✅ Authentication system (JWT + bcrypt, 4 endpoints) - ✅ Middleware stack (helmet, cors, rate-limit, auth, validation, error-handler) - ✅ Database exports (@bilko/database package) - ✅ Project structure ready for remaining endpoints **Backend Status (2026-02-20):** - ✅ 4/50 API endpoints complete (auth: register, login, refresh, logout) - ⏳ 46/50 endpoints pending (invoices, expenses, contacts, etc.) - ✅ All middleware and utilities implemented - ✅ Route aggregator ready for expansion **Next Steps:** 1. Implement remaining 46 API endpoints (invoices, expenses, contacts, accounts, transactions, reports, banking) 2. Create Zod validators for all endpoints 3. Add integration tests for auth flow 4. Connect frontend to real backend (replace mock data) 5. Beta testing with 5 SMBs + 3 accountants ## Status: DEVELOPMENT IN PROGRESS **All 8 gates PASSED — Project approved and active** ## Decision Log | Date | Gate | Decision | Rationale | |------|------|----------|-----------| | 2026-02-19 | 1 | PASS | TAM €50-150M validated, clear pain points identified | | 2026-02-19 | 2 | PASS | 3 competitors analyzed (Fiken, QuickBooks, local solutions), differentiation clear | | 2026-02-19 | 3 | PASS | Tech stack chosen — Next.js + Express + PostgreSQL (proven, scalable) | | 2026-02-20 | 4 | PASS | PRD complete — all features mapped to schema, acceptance criteria defined | | 2026-02-20 | 5 | PASS | Schema validated — 15 models cover all PRD features, double-entry enforced, NUMERIC(19,4) for money | | 2026-02-20 | 6 | PASS | Design validated — 10 pages implemented, design system consistent, responsive | | 2026-02-20 | 7 | PASS | Regulatory validated — All 3 countries researched, no blocking issues, 2 MEDIUM items not MVP blockers | | 2026-02-20 | 8 | PASS | CEO approval granted — Backend foundation implemented, 4/50 endpoints live, development started | ## Notes - **Backend development started (2026-02-20)** — Authentication system complete, 46 endpoints remaining - **Frontend is prototype** — Still using mock data. Backend connection pending full API implementation. - **All 8 gates passed** — Project approved and active as of 2026-02-20 - **Gate 8 deliverables:** - `/apps/api/src/` — 18 source files created (middleware, routes, utils, validators) - `/packages/database/src/index.ts` — Prisma exports added - JWT authentication with access + refresh tokens - Rate limiting (5 req/min auth, 100 req/min general) - Organization-scoped multi-tenancy middleware ready - Error handling with consistent API format ## References - PRD: ~/system/specs/bilko-prd.md - Tech Stack: ~/system/specs/bilko-tech-stack.md - Wireframes: ~/system/specs/bilko-wireframes.md - Brand Identity: ~/system/specs/bilko-brand-identity.md - Database Schema: packages/database/prisma/schema.prisma - Frontend Code: apps/web/ # ADR-022 — Document Archive Strategy
**MC #100025** | Published 2026-05-08 | Status: Approved (Pattern 3 — Skybound) **Related:** [SPEC-022](https://docs.alai.no/books/bilko-balkan-accounting-saas/page/spec-022-document-archive-implementation) • [COMPLIANCE-022](https://docs.alai.no/books/bilko-balkan-accounting-saas/page/compliance-022-archive-review-hipaagdprcqc)
# ADR-022: Document Archive Strategy for Paperless-ngx Integration **Status:** Proposed **Date:** 2026-05-08 **Author:** Skybound (ALAI SaaS Architecture) **Related:** MC #100025, MC #100004 (IMAP→Paperless pipe) \--- ## Context ### Business Need Bilko generates high-value, low-frequency documents requiring long-term archival in a centralized, searchable repository: - **Signed contracts** (customer/vendor onboarding) - **Invoices** (generated PDF with QR code, pdfkit) - **Care plan PDFs** (if Bilko expands to healthcare use cases) - **Incident reports** (audit trail documentation) - **Signed onboarding documents** (scanned receipts, identity verification) Current state: documents generated in-app (PDF via pdfkit), stored in Cloudflare R2 (configured, see BUILD-BLUEPRINT.md line 64), but **no archival pipe to Paperless-ngx** at archive.alai.no. CEO question (2026-05-08): "Does Bilko have email→Paperless integration?" Answer: NO. This ADR selects the archival pattern before implementation begins. ### Paperless-ngx Environment - **URL:** `https://archive.alai.no` - **Access:** Behind Cloudflare Access (service token required) - **Credentials:** Paperless API token in Bitwarden (`Paperless API Token — anvil`, user=alembasic, created 2026-05-03) - **Hosting:** Separate Azure VM (not GCP like Bilko) - **Cross-cloud path:** GCP Cloud Run (europe-north1) → Azure VM (westeurope assumed) - **IMAP pipe (MC #100004):** Daemon polls `alem@alai.no`, uploads attachments to Paperless. BookStack runbook page #2862. **Operational, general-purpose.** ### Bilko Technical Constraints From BUILD-BLUEPRINT.md: - **Multi-tenancy:** Organization-scoped (`organizationId` discriminator). Every DB record carries `organizationId`. Middleware (`org-scope.ts`) extracts from JWT. No cross-tenant data leak. - **Stack:** Kotlin/Ktor backend (apps/api/, port 8080), Next.js 15 frontend, PostgreSQL 15, Cloudflare R2 (S3-compatible), SendGrid (SMTP), GCP Cloud Run (multi-region). - **Auth:** JWT (access token 15min, refresh token 7d httpOnly). - **File storage:** Cloudflare R2 bucket (AWS\_S3\_BUCKET, S3-compatible API). - **Document volumes:** Low-frequency, high-value (estimated <100 docs/day across all tenants at MVP scale, 10–50 orgs). - **Regions:** EU residency for GDPR (data must stay in EU). - **Deployment:** GCP Cloud Run (apps/api/ + apps/web/), Cloud SQL PostgreSQL, Terraform IaC. ### Paperless-ngx Multi-Tenant Capabilities Paperless-ngx is NOT multi-tenant at the DB schema level. Tenant isolation MUST be enforced via: 1\. **Tags** (e.g., `org:uuid-abc123`) 2. **Correspondent** field (one correspondent per tenant, e.g., "Org: Firma AS") 3. **Document Type** field (e.g., "Invoice", "Contract", "Care Plan") 4. **Custom Fields** (optional key-value metadata) All three can be set via `POST /api/documents/post_document/` API. \--- ## Decision **Recommended Pattern: Pattern 3 — App→Shared Blob→Archiver Job (Batch)** Bilko will write documents to a **Cloudflare R2 bucket** (already in use) with metadata attached (organizationId, documentType, timestamp). A separate **Cloud Run job** (or Cron Worker, TBD in implementation phase) reads the queue and uploads to Paperless-ngx via direct API call, applying multi-tenant tags (org:uuid-xxx), correspondent, and document type. **Fallback during outages:** If archiver job fails or Paperless is unavailable, documents remain in R2 with idempotent retry semantics. Bilko user experience is never degraded by Paperless downtime. \--- ## Decision Drivers
CriterionWeightPattern 1 (Email)Pattern 2 (Direct API)Pattern 3 (Blob Queue)
---------------------------------------------------------------------------------------------
Multi-tenant scopingHIGH3/54/55/5
Bilko couplingHIGH5/52/55/5
Paperless couplingHIGH4/51/55/5
Retry/idempotencyHIGH2/53/55/5
Auth modelMED5/52/54/5
Dev velocityMED5/54/53/5
Ops surfaceMED4/55/53/5
Cross-cloud friendlinessMED5/53/55/5
Dedup strategyLOW2/54/55/5
Scalability (>1k docs/day)LOW2/55/55/5
**TOTAL (weighted sum)**—**3.6/5****3.2/5****4.6/5**
**Scoring rationale:** - **Multi-tenant scoping:** Pattern 3 allows worker to read `organizationId` from R2 metadata and apply consistent Paperless tags (org:uuid-xxx) + correspondent. Pattern 1 must encode tenant in email subject or attachment metadata (fragile). Pattern 2 requires Bilko backend to hold tenant-to-Paperless-tag mapping (extra logic in hot path). - **Bilko coupling:** Pattern 3 decouples Bilko completely (fire-and-forget to R2). Pattern 2 tightly couples Bilko to Paperless availability (degraded UX if archive.alai.no is down). - **Paperless coupling:** Pattern 3 isolates Paperless availability from Bilko runtime. Pattern 2 makes Paperless a hot-path dependency. - **Retry/idempotency:** Pattern 3 uses R2 versioning + worker retry (Cloud Run job cron or queue). Pattern 1 has weak email delivery guarantees (no DLQ). Pattern 2 requires Bilko to implement retry logic (failed upload = user sees error). - **Auth model:** Pattern 1 reuses existing IMAP→Paperless pipe (zero new auth surface). Pattern 3 requires worker to hold CF Access token + Paperless API token (already exists in Bitwarden, see MC #100004). Pattern 2 requires Bilko backend to hold CF Access creds (rotation surface, Bilko team must manage Paperless tokens). - **Dev velocity:** Pattern 1 is fastest (SMTP send, zero new code in Bilko). Pattern 3 requires worker provisioning + monitoring. - **Ops surface:** Pattern 2 is simplest (no worker). Pattern 3 adds worker component. - **Cross-cloud friendliness:** Pattern 3 is cloud-agnostic (R2 bucket is S3-compatible, worker can run anywhere). Pattern 2 crosses GCP→Azure directly (network latency, no queue). - **Dedup:** Pattern 3 can use R2 object key = SHA256 of doc (idempotent). Pattern 1 relies on email Message-ID (can duplicate if retry). Pattern 2 requires Bilko to track uploaded doc IDs. - **Scalability:** Pattern 1 has email attachment size limits (SendGrid = 30MB total, one.com Dovecot = unknown). Pattern 3 and 2 scale to multi-GB PDFs if needed. \--- ## Consequences ### Positive 1\. **Bilko never blocks on Paperless downtime.** User uploads document, gets immediate success (R2 write ~50ms), archival happens async. 2. **Idempotent retry semantics.** Worker crashes mid-upload? R2 object still there, retry on next cron run (dedupe via object key or Paperless custom\_fields SHA256). 3. **Multi-tenant isolation enforced at archival layer.** Worker reads `organizationId` from R2 metadata → applies `tags=org:uuid-abc123` + `correspondent="Firma AS (uuid-abc123)"` in Paperless. Search in Paperless UI: filter by tag = instant tenant-scoped results. 4. **Scales to additional archive targets.** Worker can fan-out to Paperless + S3 Glacier + OneDrive (future). Bilko unchanged. 5. **Zero cross-cloud hot-path latency.** Bilko writes to R2 (same Cloudflare edge region as app), worker polls async. 6. **Reuses existing R2 bucket.** No new storage provisioning. R2 lifecycle policy can auto-delete after N days post-archive (cost optimization). ### Negative 1\. **Eventual consistency.** Document archived 1–15 minutes after user upload (depends on worker cron interval). If CEO searches Paperless 30 seconds after upload, doc not yet there. 2. **Additional ops surface.** Worker must be monitored (cron health check, dead-letter queue for failed uploads). 3. **Dev velocity slower than Pattern 1.** Must scaffold worker + deploy pipeline + monitoring. ### Neutral 1\. **Auth surface expands slightly.** Worker holds CF Access token + Paperless API token. Rotation = worker redeploy or Secret Manager update (already standard for GCP Cloud Run). 2. **R2 becomes queue.** If worker stops (VM crash, deployment), R2 accumulates unprocessed docs. Recovery = restart worker, process backlog. \--- ## Alternatives Considered ### Pattern 1 — App→Email→Paperless (Relay) **How it works:** Bilko backend sends document as attachment to dedicated inbox (e.g., `bilko-archive@alai.no`). Daemon (MC #100004 pipe) polls inbox, uploads to Paperless. **Pros:** - **Zero code in Bilko backend.** Just `sendgrid.send({ to: 'bilko-archive@alai.no', attachment: pdfBuffer })`. Reuses existing SendGrid integration. - **Reuses MC #100004 pipe 1:1.** Daemon already operational. - **Low coupling.** Bilko unaware of Paperless API. - **Cross-cloud friendly.** Email = universal transport. - **Easy to add more sources.** Any system can email attachments to dedicated inbox. **Cons:** - **Email is a weak queue.** No ordering guarantees, delivery can fail silently, dedup harder (Message-ID not unique across retries). - **Attachment size limits.** SendGrid = 30MB total per email. Large invoice batches or scanned multi-page contracts may exceed. - **Latency.** IMAP daemon polls every N minutes (configured in MC #100004). User uploads doc at 10:00, daemon polls at 10:15 → 15min delay. - **Multi-tenant scoping fragile.** Must encode `organizationId` in email subject (e.g., "Archive Invoice | org:uuid-abc123") or attachment filename. Daemon must parse subject/filename to apply Paperless tags. Parsing errors = wrong tenant tag. - **Dedup complexity.** If Bilko retries email send (network timeout), daemon sees 2 emails with same attachment. Must SHA256 attachments and dedupe in Paperless query before upload. **Rejection rationale:** Multi-tenant scoping via email subject/filename parsing is fragile. Email attachment size limits block future use cases (e.g., scanned multi-page contracts = 50MB PDF). No idempotent retry (email duplicates on send retry). \--- ### Pattern 2 — App→Direct Paperless API (Push) **How it works:** Bilko backend calls `POST https://archive.alai.no/api/documents/post_document/` directly with app-scoped CF Access service token + Paperless API token. Synchronous upload during user request. **Pros:** - **Synchronous feedback.** User uploads doc, Bilko immediately gets Paperless document ID, can display "Archived as #12345" in UI. - **Full metadata control.** Bilko sets `correspondent`, `document_type`, `tags`, `custom_fields` in single API call. No parsing. - **Strong dedup.** Bilko can query Paperless `GET /api/documents/?custom_fields__sha256=abc123` before upload to skip duplicates. - **Simplest ops surface.** No worker. Bilko backend + Paperless only. **Cons:** - **Bilko must hold CF Access credentials.** New secret in Bilko backend (Secret Manager entry, rotation burden). If CF Access token leaks, attacker can access Paperless directly. - **Paperless becomes hot-path dependency.** If archive.alai.no is down (Azure VM maintenance, network partition), Bilko document upload **fails**. User sees error: "Failed to archive invoice". Degrades UX. - **Tight coupling.** Bilko backend must know Paperless API contract (`POST /api/documents/post_document/`, multipart/form-data with `document` + `title` + `correspondent` + `tags` fields). API change in Paperless = Bilko backend update required. - **Cross-cloud latency in user hot path.** GCP Cloud Run (europe-north1) → Azure VM (westeurope assumed) = 20–50ms network RTT + Paperless processing ~200ms = 250ms added to user upload response time. - **No retry buffer.** If Paperless returns 500, Bilko must decide: fail user request, or queue retry internally (adds complexity). **Rejection rationale:** Paperless availability becomes Bilko UX blocker. User uploads signed contract, archive.alai.no is down, user sees "Upload failed" even though contract PDF saved to R2. Unacceptable UX degradation for external dependency. Cross-cloud latency (250ms) in hot path for low-value sync feedback. \--- ### Pattern 3 — App→Shared Blob→Archiver Job (Batch) \[RECOMMENDED\] **How it works:** Bilko writes document to **Cloudflare R2 bucket** (`alai-bilko-archive-queue/` prefix or separate bucket) with metadata: ```json { "organizationId": "uuid-abc123", "organizationName": "Firma AS", "documentType": "invoice", "invoiceNumber": "2024-001", "timestamp": "2026-05-08T10:30:00Z", "sha256": "abc123...def" } ``` Separate **Cloud Run job** (cron every 5 minutes, or Cloud Tasks queue) reads R2 objects, uploads to Paperless via `POST /api/documents/post_document/` with: - `correspondent` = "Firma AS (uuid-abc123)" - `document_type` = "Invoice" - `tags` = "org:uuid-abc123,invoice,bilko" - `custom_fields` = `{ "sha256": "abc123", "invoiceNumber": "2024-001", "uploadedAt": "2026-05-08T10:30:00Z" }` After successful upload, worker **deletes R2 object** (or moves to `archived/` prefix). On failure, object remains, retry on next cron run. **Pros:** - **Full decoupling.** Bilko writes to R2 (fire-and-forget, <50ms). Worker handles Paperless upload async. Bilko unaware of Paperless downtime. - **Idempotent retry.** R2 object key = `{organizationId}/{documentType}/{sha256}.pdf`. Duplicate upload (network retry) = same key, R2 overwrites. Worker can query Paperless `custom_fields__sha256` before upload to skip duplicates. - **Multi-tenant tagging trivial.** Worker reads `organizationId` from R2 metadata → applies `tags=org:{organizationId}` in Paperless. No parsing, no guessing. - **Scalable.** R2 = unlimited objects. Worker can batch-process 1000+ docs/run if needed. Paperless bulk upload API available. - **Platform-agnostic.** R2 is S3-compatible. Worker can run on GCP Cloud Run, Azure Container Apps, AWS Lambda, Cloudflare Workers (D1 queue). No vendor lock-in. - **Future-proof.** Add OneDrive archival target? Worker fans out to Paperless + OneDrive + S3 Glacier. Bilko unchanged. - **Audit trail in R2.** If worker crashes mid-upload, R2 object = source of truth. Re-run = idempotent. **Cons:** - **Eventual consistency.** User uploads doc at 10:00, worker cron runs at 10:05 → doc visible in Paperless at 10:05:30. 5.5min delay. - **Additional ops component.** Worker must be deployed, monitored (cron health check via Cloud Monitoring uptime check, alert on 3 consecutive failures). - **Dev velocity slower.** Must scaffold worker (Cloud Run job + cloudbuild-worker.yaml + Terraform module), deploy pipeline, monitoring dashboard. - **R2 becomes queue.** If worker stops (VM crash, deployment), R2 accumulates unprocessed docs. Must monitor queue depth (R2 ListObjectsV2 count). **Why this pattern wins:** 1\. **Bilko UX never degrades.** Paperless down? User still uploads doc successfully (R2 write). Worker retries until Paperless recovers. 2. **Multi-tenant isolation enforced structurally.** Worker applies `org:{uuid}` tag from R2 metadata. No chance of cross-tenant leak (Paperless search by tag = instant tenant filter). 3. **Scales to 10,000 orgs × 100 docs/day.** R2 = unlimited storage, worker processes batch (100 docs/run = 6 seconds at 60ms/doc). 4. **Idempotent by design.** R2 object key = content hash. Worker crash mid-upload? Re-run processes same doc, Paperless dedupes via `custom_fields.sha256`. 5. **Reuses existing Bilko infrastructure.** R2 bucket already configured (BUILD-BLUEPRINT line 64). Worker = new Cloud Run service (Terraform module = 20 lines). **Implementation complexity accepted because:** - Bilko is a **B2B SaaS** with multi-tenant data sovereignty requirements. Eventual consistency (5min delay) is acceptable for archival. Real-time feedback ("Archived as #12345") is nice-to-have, not must-have. - Pattern 2 (direct API) makes Paperless a **hot-path dependency** → UX risk unacceptable. - Pattern 1 (email) has **multi-tenant scoping fragility** (parsing subject lines) + attachment size limits (30MB SendGrid). \--- ## Implementation Spec (High-Level) ### Phase 1: Bilko Backend Changes (CodeCraft) 1\. **Add R2 archive write function** in `apps/api/src/main/kotlin/no/alai/bilko/services/ArchiveService.kt`: ```kotlin suspend fun archiveDocument( organizationId: UUID, organizationName: String, documentType: String, // "invoice" | "contract" | "care_plan" documentBuffer: ByteArray, metadata: Map // { "invoiceNumber": "2024-001", ... } ): String { val sha256 = documentBuffer.sha256() val objectKey = "archive-queue/${organizationId}/${documentType}/${sha256}.pdf"

s3Client.putObject( bucket = "alai-bilko-files", key = objectKey, body = documentBuffer, metadata = mapOf( "organizationId" to organizationId.toString(), "organizationName" to organizationName, "documentType" to documentType, "timestamp" to Instant.now().toString(), "sha256" to sha256 ) + metadata )

return objectKey }

``` 2\. **Call `archiveDocument()` after invoice PDF generation** in `InvoiceService.generatePDF()`: ```kotlin val pdfBuffer = pdfGenerator.generate(invoice) s3Client.putObject(...) // existing code archiveService.archiveDocument( organizationId = invoice.organizationId, organizationName = organization.name, documentType = "invoice", documentBuffer = pdfBuffer, metadata = mapOf("invoiceNumber" to invoice.number) ) ``` 3\. **Same pattern for contracts, care plans, onboarding docs.** ### Phase 2: Archiver Worker (CodeCraft + FlowForge) 1\. **New Cloud Run service** `bilko-archiver-worker` (Kotlin/Ktor or Node.js, TBD): ```kotlin // apps/archiver-worker/src/main/kotlin/no/alai/bilko/archiver/Main.kt

fun main() { val s3Client = S3Client(/* R2 config */) val paperlessClient = PaperlessClient( baseUrl = "https://archive.alai.no", cfAccessClientId = System.getenv("CF_ACCESS_CLIENT_ID"), cfAccessClientSecret = System.getenv("CF_ACCESS_CLIENT_SECRET"), apiToken = System.getenv("PAPERLESS_API_TOKEN") )

runBlocking { val objects = s3Client.listObjectsV2("alai-bilko-files", prefix = "archive-queue/") objects.forEach { obj -> try { val metadata = obj.metadata val documentBuffer = s3Client.getObject(obj.key)

// Check if already uploaded (dedup) val existing = paperlessClient.searchBySHA256(metadata["sha256"]!!) if (existing != null) { logger.info("Document ${obj.key} already archived as Paperless #${existing.id}, skipping") s3Client.deleteObject(obj.key) return@forEach }

// Upload to Paperless val paperlessDoc = paperlessClient.uploadDocument( document = documentBuffer, title = "${metadata["documentType"]} - ${metadata["organizationName"]}", correspondent = "${metadata["organizationName"]} (${metadata["organizationId"]})", documentType = metadata["documentType"]!!.capitalize(), tags = listOf("org:${metadata["organizationId"]}", metadata["documentType"]!!, "bilko"), customFields = mapOf( "sha256" to metadata["sha256"]!!, "uploadedAt" to metadata["timestamp"]!!, "organizationId" to metadata["organizationId"]!! ) )

logger.info("Archived ${obj.key} → Paperless #${paperlessDoc.id}") s3Client.deleteObject(obj.key)

} catch (e: Exception) { logger.error("Failed to archive ${obj.key}: ${e.message}", e) // Leave object in R2, retry on next run } } } }

``` 2\. **Deploy as Cloud Run job** (triggered by Cloud Scheduler every 5 minutes): ```yaml

infrastructure/gcp/terraform/modules/archiver-worker/main.tf

resource "google_cloud_run_v2_job" "bilko_archiver_worker" { name = "bilko-archiver-worker" location = var.region

template { template { containers { image = "europe-north1-docker.pkg.dev/${var.project_id}/bilko/archiver-worker:latest"

env { name = "CF_ACCESS_CLIENT_ID" value_source { secret_key_ref { secret = "cf-access-client-id" version = "latest" } } } env { name = "CF_ACCESS_CLIENT_SECRET" value_source { secret_key_ref { secret = "cf-access-client-secret" version = "latest" } } } env { name = "PAPERLESS_API_TOKEN" value_source { secret_key_ref { secret = "paperless-api-token" version = "latest" } } } }

timeout = "600s" # 10min max } } }

resource "google_cloud_scheduler_job" "archiver_trigger" { name = "bilko-archiver-cron" schedule = "*/5 * * * *" # Every 5 minutes time_zone = "Europe/Oslo"

http_target { uri = "https://${var.region}-run.googleapis.com/apis/run.googleapis.com/v1/namespaces/${var.project_id}/jobs/${google_cloud_run_v2_job.bilko_archiver_worker.name}:run" http_method = "POST"

oauth_token { service_account_email = google_service_account.archiver_worker.email } } }

``` 3\. **Monitoring dashboard** (Cloud Monitoring): - Queue depth (R2 objects in `archive-queue/` prefix) — alert if >500 - Worker success rate — alert if <95% over 1h - Worker execution time — alert if >300s - Paperless API error rate — alert if >5% over 15min ### Phase 3: Paperless-ngx Configuration (FlowForge + Proveo) 1\. **Create Paperless correspondents** (one per Bilko org, OR dynamic via worker): - Option A: Worker auto-creates correspondent if not exists (`POST /api/correspondents/` with name="Firma AS (uuid-abc123)"). - Option B: Manual setup (CEO creates correspondent in Paperless UI for each new Bilko customer). **Recommend Option A** for scalability. 2\. **Create Paperless document types**: - Invoice - Contract - Care Plan - Onboarding Document - Incident Report 3\. **Create Paperless custom fields**: - `sha256` (text, unique identifier for dedup) - `organizationId` (text, Bilko tenant UUID) - `uploadedAt` (datetime, original upload timestamp) - `invoiceNumber` (text, optional) - `contractId` (text, optional) 4\. **Tag taxonomy**: - `org:{uuid}` (one tag per Bilko tenant, e.g., `org:abc-123-def`) - `invoice` | `contract` | `care-plan` | `onboarding` | `incident` - `bilko` (source system tag) ### Phase 4: Retention Policy (Dr. Sarah Chen — Healthcare Compliance) **Question for CEO:** 1\. **How long to keep docs in R2 after successful Paperless upload?** - Option A: Delete immediately (worker deletes R2 object after Paperless confirms upload). - Option B: Keep 30 days (R2 lifecycle policy auto-deletes after 30d). Allows re-upload if Paperless doc accidentally deleted. - **Recommendation:** Option A (immediate delete). Paperless is source of truth post-archival. R2 = queue only. 2\. **Paperless retention policy?** - Invoices: 7 years (Norway Bokføringsloven, Serbia/Croatia equivalent) - Contracts: Indefinite (until contract expires + 5 years) - Care plans: 10 years (HIPAA if US expansion, GDPR Article 17 deletion rights) - **Recommendation:** Configure per-document-type in Paperless via workflow rules (out of scope for this ADR). 3\. **GDPR Article 17 (Right to Erasure) handling?** - When Bilko org deletes account (GDPR erasure request), worker must: 1. Query Paperless `GET /api/documents/?tags__name=org:{uuid}` 2. Delete all matching docs `DELETE /api/documents/{id}/` 3. Delete correspondent `DELETE /api/correspondents/{id}/` - **Recommendation:** Separate MC for GDPR compliance (erasure worker). Out of scope for archival MVP. \--- ## Stakeholders - **CEO (Alem Basic):** Final approval on pattern choice + retention policy decisions. - **CodeCraft (Petter Graff, Hadi Hariri):** Bilko backend changes + archiver worker implementation. - **FlowForge (Kelsey Hightower):** GCP Cloud Run job + Cloud Scheduler + Terraform IaC. - **Proveo (Angie Jones):** End-to-end validation (upload invoice in Bilko → verify appears in Paperless with correct tags/metadata). - **Dr. Sarah Chen (Healthcare Compliance):** HIPAA/GDPR retention policy review if Bilko expands to care plan archival. - **Skillforge:** BookStack runbook page for archiver worker (operational playbook, troubleshooting). \--- ## Open Questions for CEO 1\. **Worker cron interval:** 5 minutes (recommended) vs 15 minutes (lower Cloud Run invocation cost)? - 5min = faster archival, users see docs in Paperless <6min after upload. - 15min = lower cost (~$0.50/month vs ~$1.50/month for Cloud Run invocations), acceptable delay for archival use case. - **Awaiting CEO decision.** 2\. **R2 retention after upload:** Delete immediately (recommended) vs keep 30 days (safety buffer)? - Immediate = lower storage cost, cleaner queue. - 30 days = allows re-upload if Paperless doc accidentally deleted (rare edge case). - **Awaiting CEO decision.** 3\. **Multi-tenant correspondent strategy in Paperless:** - Option A: One correspondent per Bilko org (e.g., "Firma AS (uuid-abc123)"). Pro: clean correspondent filter in Paperless UI. Con: 10,000 orgs = 10,000 correspondents (Paperless UI clutter). - Option B: Single correspondent "Bilko" + rely on `org:{uuid}` tags for tenant isolation. Pro: clean Paperless correspondent list. Con: must always filter by tag (cannot filter by correspondent alone). - **Recommendation:** Option A (one correspondent per org). Paperless search by correspondent is more intuitive than tag filter for non-technical users (CEO searching for customer docs). - **Awaiting CEO decision.** \--- ## References - **MC #100025** — This task (pattern decision + ADR) - **MC #100004** — IMAP→Paperless pipe (operational, BookStack #2862) - **BUILD-BLUEPRINT.md** — Bilko tech stack, multi-tenancy model, R2 config (lines 64, 192–193) - **Paperless-ngx API docs** — https://docs.paperless-ngx.com/api/ - **Cloudflare R2 docs** — https://developers.cloudflare.com/r2/api/s3/api/ - **GCP Cloud Run jobs** — https://cloud.google.com/run/docs/create-jobs - **ADR-020** — Bilko backend canonical path (`apps/api/`) - **ADR-021** — Bilko blueprint realignment (Kotlin/Ktor sole backend) \--- ## Next Steps (Child MCs) **Upon CEO approval of Pattern 3:** 1\. **MC #TBD (CodeCraft):** Implement `ArchiveService.kt` in Bilko backend + call from `InvoiceService.generatePDF()`. **Estimate:** 2h. **Priority:** M. 2. **MC #TBD (CodeCraft):** Scaffold archiver worker (`apps/archiver-worker/`) with R2→Paperless upload logic + dedup via SHA256. **Estimate:** 4h. **Priority:** M. 3. **MC #TBD (FlowForge):** Deploy archiver worker as Cloud Run job + Cloud Scheduler cron (Terraform IaC). **Estimate:** 3h. **Priority:** M. 4. **MC #TBD (FlowForge):** Provision CF Access service token for archiver worker + store in Secret Manager. **Estimate:** 1h. **Priority:** M. 5. **MC #TBD (Proveo):** End-to-end validation — upload test invoice in Bilko stage, verify appears in Paperless with `org:{uuid}` tag + correspondent. **Estimate:** 2h. **Priority:** M. 6. **MC #TBD (Skillforge):** BookStack runbook page for archiver worker (troubleshooting, monitoring dashboard links, manual queue drain). **Estimate:** 1h. **Priority:** L. **Total estimate:** 13h across 3 specialists (CodeCraft 6h, FlowForge 4h, Proveo 2h, Skillforge 1h). \--- **Decision Status:** Awaiting CEO approval on: 1\. Pattern 3 acceptance (vs Pattern 1 or 2) 2. Worker cron interval (5min vs 15min) 3. R2 retention policy (immediate delete vs 30d) 4. Paperless correspondent strategy (one-per-org vs single "Bilko" correspondent) **Next action:** CEO review → approve → create 6 child MCs → dispatch to CodeCraft/FlowForge/Proveo/Skillforge. # SPEC-022 — Document Archive Implementation
**MC #100025** | Published 2026-05-08 | Status: Approved (Pattern 3 — Skybound) **Related:** [ADR-022](https://docs.alai.no/books/bilko-balkan-accounting-saas/page/adr-022-document-archive-strategy) • [COMPLIANCE-022](https://docs.alai.no/books/bilko-balkan-accounting-saas/page/compliance-022-archive-review-hipaagdprcqc)
# SPEC-022: Document Archive Implementation — Pattern 3 (Blob Queue) **Status:** Draft — awaiting CodeCraft + FlowForge dispatch **Date:** 2026-05-08 **Author:** CodeCraft (MC #100025, Subtask 2) **ADR:** ADR-022-document-archive-strategy.md (Pattern 3 selected, 4.6/5 weighted score) **CEO Decisions baked in:** D1 (5min cron), D2 (delete immediately on success), D3 (one correspondent per org) **Related:** MC #100025 (this task), MC #100004 (IMAP→Paperless pipe, BookStack #2862) \--- ## 1. Overview Pattern 3 (App→Shared Blob→Archiver Job) is the selected architecture for Bilko→Paperless-ngx document archival. Bilko backend writes generated PDFs plus a `.meta.json` sidecar to a dedicated Cloudflare R2 staging bucket (`bilko-archive-queue`). A separate Cloud Run job (`archiver-worker`) polls the queue on a 5-minute cron (per CEO decision D1), uploads each document to Paperless-ngx at `archive.alai.no` via the Paperless REST API, and deletes the R2 object immediately upon confirmed upload (per CEO decision D2). Multi-tenant isolation is enforced by the worker reading `organizationId` from R2 object metadata and applying an `org:` tag plus a per-org correspondent (per CEO decision D3) on every Paperless document. Bilko user experience is never degraded by Paperless downtime; R2 is the authoritative queue and all retry semantics live in the worker. See ADR-022 §Decision Drivers for the full pattern comparison and rejection rationale for Patterns 1 and 2. \--- ## 2. Components
ComponentLocationTypePurpose
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`ArchiveService``apps/api/src/main/kotlin/no/alai/bilko/services/ArchiveService.kt`New Kotlin serviceWrites PDF + `.meta.json` sidecar to R2 `bilko-archive-queue` bucket; returns `ArchiveJobId`
R2 bucket `bilko-archive-queue`Cloudflare R2 (separate from existing `AWS_S3_BUCKET`)New bucketStaging queue for pending Paperless uploads
R2 bucket `bilko-archive-dlq`Cloudflare R2New bucketDead-letter queue for objects that failed 3 upload attempts
`archiver-worker``apps/archiver-worker/`New Cloud Run job (Node.js — see §10)Polls R2 → uploads to Paperless → deletes R2 objects
Cloud Scheduler triggerGCP Cloud Scheduler `bilko-archiver-cron`New scheduler jobFires `archiver-worker` Cloud Run job every 5 minutes (per CEO decision D1)
Flyway migration `V_archive_status``apps/api/src/main/resources/db/migration/`New migrationAdds `archive_status`, `archive_job_id`, `paperless_doc_url`, `archived_at` columns to `invoices` and future document tables
`ArchiveAuditLog``apps/api/src/main/kotlin/no/alai/bilko/model/ArchiveAuditLog.kt` + Flyway migrationNew DB tablePer-document archive status: `pending`, `archived`, `failed`
Bilko DB table `org_paperless_cache`PostgreSQL, Flyway migrationNew tableCaches `organizationId → paperless_correspondent_id` and `organizationId → paperless_org_tag_id` to avoid repeat API calls
\--- ## 3. Interfaces ### 3.1 ArchiveService — Kotlin signature ``` // File: apps/api/src/main/kotlin/no/alai/bilko/services/ArchiveService.kt // Package: no.alai.bilko.services

data class SourceDoc( val organizationId: UUID, val organizationName: String, val documentType: DocumentType, // enum: INVOICE | CONTRACT | CARE_PLAN | INCIDENT_REPORT | ONBOARDING val documentBuffer: ByteArray, // raw PDF bytes val sha256: String, // hex SHA-256 of documentBuffer val metadata: Map // e.g. { "invoiceNumber": "2024-001", "contractId": "abc" } )

data class ArchiveOptions( val priority: ArchivePriority = ArchivePriority.NORMAL // NORMAL | HIGH (for future urgency flag) )

// Return type — opaque job ID (R2 object key) typealias ArchiveJobId = String

// Primary entry point — called by InvoiceService, ContractService, etc. // Throws ArchiveWriteException (wraps R2 S3 error) on R2 write failure. // NEVER throws on Paperless unavailability (async path). suspend fun archive(sourceDoc: SourceDoc, options: ArchiveOptions = ArchiveOptions()): ArchiveJobId

``` Callers (e.g. `InvoiceService.generatePDF()`) catch `ArchiveWriteException` and return HTTP 503 to the user with body `{"error": "Document archived pending. Retry in 5 minutes.", "code": "ARCHIVE_QUEUE_FAILURE"}`. The Bilko UX is decoupled per ADR-022 §Consequences (Positive #1): R2 write failure is the only user-visible failure; Paperless unavailability is invisible to the user. ### 3.2 R2 Object Schema **Object key convention:** ``` org///.pdf org///.meta.json ``` Example: ``` org/550e8400-e29b-41d4-a716-446655440000/invoice/a1b2c3d4...ef.pdf org/550e8400-e29b-41d4-a716-446655440000/invoice/a1b2c3d4...ef.meta.json ``` Using SHA-256 as the object key suffix provides idempotent R2 writes: re-upload of identical PDF bytes overwrites the same key (R2 last-writer-wins), preventing queue bloat on Bilko retry paths. **`.meta.json` schema:** ```json { "schemaVersion": "1", "r2Uuid": "", "organizationId": "550e8400-e29b-41d4-a716-446655440000", "organizationName": "Firma AS", "documentType": "invoice", "bilkoDocumentId": "", "invoiceNumber": "2024-001", "contractId": null, "timestamp": "2026-05-08T10:30:00Z", "sha256": "a1b2c3d4...ef", "retryCount": 0, "lastAttemptAt": null, "lastError": null } ``` - `retryCount` and `lastError` are mutated in-place by the worker on failure (R2 PUT of updated `.meta.json`). - `r2Uuid` (= `sha256`) is the Paperless dedup key: `bilko-source-uuid:` tag on the Paperless document. - `bilkoDocumentId` allows the worker to write back the Paperless doc URL to the Bilko DB audit row. **Content-type:** PDF object → `application/pdf`. `.meta.json` → `application/json`. **Retention class:** Standard (no Infrequent Access — objects are short-lived by design). ### 3.3 Worker → Paperless API call The worker calls `POST https://archive.alai.no/api/documents/post_document/` as `multipart/form-data`: ``` POST /api/documents/post_document/ Host: archive.alai.no CF-Access-Client-Id: CF-Access-Client-Secret: Authorization: Token Content-Type: multipart/form-data

Fields: document — PDF binary (required) title — " — " (e.g. "Invoice — Firma AS 2026-05-08") correspondent — (integer, pre-resolved by worker — see §5) document_type — (integer, mapped from documentType enum) tags — [, , , ] created — custom_fields — [{"field": , "value": ""}, {"field": , "value": ""}, {"field": , "value": ""}]

``` The worker resolves `correspondent_id`, `document_type_id`, and tag IDs prior to the upload call, using the `org_paperless_cache` Bilko DB table (see §5). All IDs are integers assigned by Paperless on creation. **Reuse of paperless-upload.js:** The worker is Node.js (see §10 for language decision). It may directly import or inline logic equivalent to `~/system/tools/paperless-upload.js` (MC #100004). The worker should NOT import the file at runtime from the system tools path — instead, the logic (multipart form construction, CF Access header injection, retry) is copied into `apps/archiver-worker/src/paperlessClient.js` with full ownership by the Bilko repo. This avoids coupling the Bilko Cloud Run container to the ALAI system tools directory. **Worker side-effect on success (D2):** 1\. `DELETE` R2 PDF object key. 2. `DELETE` R2 `.meta.json` sidecar key (per CEO decision D2 — delete immediately, no buffer). 3. `UPDATE` Bilko DB `archive_audit_log` row: `archive_status = 'archived'`, `paperless_doc_url = `, `archived_at = NOW()`. 4. `UPDATE` Bilko DB source document table (e.g. `invoices`): `archive_status = 'archived'`, `paperless_doc_url = `, `archived_at = NOW()`. Worker updates the Bilko DB via a thin internal HTTP endpoint on `bilko-api` Cloud Run service (authenticated with a shared internal API key stored in Secret Manager), OR directly via Cloud SQL connection if the worker runs in the same GCP VPC. **Recommendation:** internal HTTP endpoint on `bilko-api` is safer (no direct DB access from worker, follows existing service boundary). Endpoint: `PATCH /internal/v1/archive-audit/{bilkoDocumentId}` — worker-to-api call, not user-facing. \--- ## 4. Auth Model ### 4.1 Bilko backend → R2 (write to `bilko-archive-queue`) Reuses existing R2 credentials already in Bilko Cloud Run environment: `AWS_S3_ENDPOINT`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `AWS_S3_BUCKET`. A new env var `AWS_S3_ARCHIVE_BUCKET=bilko-archive-queue` routes `ArchiveService` writes to the separate archive bucket. The same Cloudflare R2 token is scoped to both buckets via R2 token policy. No new SA credential needed for Bilko backend. ### 4.2 Worker → R2 (read + delete from `bilko-archive-queue`) **Recommendation: separate R2 API token for the worker**, scoped to `bilko-archive-queue` and `bilko-archive-dlq` with read + delete permissions. Do NOT share the Bilko production R2 token (which has write access to the main receipts/PDF bucket) with the worker. Principle of least privilege: worker should not be able to touch the main Bilko file storage bucket. Worker credential: new Cloudflare R2 API token stored in GCP Secret Manager as `bilko-archiver-r2-access-key-id` and `bilko-archiver-r2-secret-access-key`. Provisioned by FlowForge as part of the worker deployment Terraform module. ### 4.3 Worker → Paperless (archive.alai.no) Worker requires two credentials: - `CF_ACCESS_CLIENT_ID` + `CF_ACCESS_CLIENT_SECRET` — Cloudflare Access service token - `PAPERLESS_API_TOKEN` — Paperless-ngx API token **Recommendation: create a new dedicated Bitwarden item `Paperless API Token — bilko-archiver-worker`**(separate from the existing `Paperless API Token — anvil` item referenced in MC #100004). Rationale: the existing anvil token is shared with the IMAP→Paperless daemon (MC #100004). If the worker token is rotated (e.g. Bilko security incident), the IMAP daemon must not be affected. Separate tokens allow independent rotation. Both tokens have equal Paperless API access (same permissions) but are separate credentials with separate audit trails in Paperless and Bitwarden. Similarly, create a new CF Access service token `bilko-archiver-worker` in Cloudflare Zero Trust, separate from any existing `archive-alai-no CF Access` token. Stored as: `bilko-archiver-cf-access-client-id` and `bilko-archiver-cf-access-client-secret` in GCP Secret Manager. ### 4.4 Bilko backend → Paperless **FORBIDDEN.** The Bilko backend NEVER calls Paperless directly. Pattern 3 rationale from ADR-022 §Pattern 2 rejection: "Paperless becomes hot-path dependency — if archive.alai.no is down, Bilko document upload fails. User sees error." The R2 queue decouples Bilko from Paperless availability entirely. \--- ## 5. Multi-Tenant Scoping ### 5.1 Correspondent strategy (per CEO decision D3 — one per org) Correspondent name pattern: `org-` (e.g. `org-550e8400-e29b-41d4-a716-446655440000`). On first archive for a new organization, the worker calls: ``` POST https://archive.alai.no/api/correspondents/ { "name": "org-", "match": "", "matching_algorithm": 0, "is_insensitive": false } ``` The returned `correspondent.id` is stored in Bilko DB table `org_paperless_cache`: ```sql CREATE TABLE org_paperless_cache ( organization_id UUID PRIMARY KEY REFERENCES organizations(id), paperless_correspondent_id INTEGER NOT NULL, paperless_org_tag_id INTEGER NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); ``` On subsequent archives for the same org, the worker reads from `org_paperless_cache` (HTTP GET to `bilko-api` internal endpoint `GET /internal/v1/paperless-cache/{organizationId}`). Cache miss triggers correspondent + tag creation and cache write. This avoids one Paperless API round-trip per document after first archive. The human-readable org name (`organizationName` from the `.meta.json`) is NOT used as the Paperless correspondent name — `org-` is canonical to prevent name collisions and to survive org renames in Bilko. ### 5.2 Tag strategy Every archived document receives exactly these tags:
TagPurposeCreated by
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`org:`Tenant isolation — one tag per Bilko orgWorker on first archive for org
`doc-type:invoice` (or contract, care-plan, incident-report, onboarding)Document type filterWorker — static set, pre-created in Paperless during initial setup
`bilko-source`Identifies all documents archived from Bilko (across all orgs)Pre-created in Paperless during initial setup
`bilko-source-uuid:`Idempotency dedup key — prevents duplicate Paperless documentsWorker — unique per document
The worker stores `paperless_org_tag_id` in `org_paperless_cache` alongside `paperless_correspondent_id`. Document-type tag IDs and the `bilko-source` tag ID are stored in worker environment config (`PAPERLESS_TAG_IDS_MAP` env var as JSON: `{"invoice": 12, "contract": 13, ...}`). These are set once during initial Paperless setup and do not change. ### 5.3 Tenant search in Paperless To retrieve all documents for an org: ``` GET https://archive.alai.no/api/documents/?tags__id__in=&page=1&page_size=25 ``` For filtering by doc type within an org: ``` GET https://archive.alai.no/api/documents/?tags__id__in=, ``` This is the canonical Paperless query pattern. Cross-tenant queries are impossible if the caller only has access to their own `org_tag_id`. (Note: Paperless does not natively enforce per-tag ACLs — isolation is enforced by the Bilko application layer controlling which `org_tag_id` each user can query.) \--- ## 6. Retention Policy ### 6.1 R2 staging bucket (`bilko-archive-queue`) - **On successful upload to Paperless:** DELETE immediately (per CEO decision D2). No buffer. Rationale (ADR-022 §Open Questions, CEO decision D2): Paperless is source of truth post-archival. R2 is a queue, not a backup. - **On failed upload (retry count < 3):** Object remains in R2. Worker increments `retryCount` in `.meta.json` on each failure. Object will be retried on next cron invocation. - **On failed upload (retry count = 3):** Worker moves object (COPY then DELETE) to `bilko-archive-dlq` bucket and sends alert (Slack or email to `dev@alai.no`, the existing alert address per BUILD-BLUEPRINT line 302). Object in DLQ retained for 7 days then auto-deleted via R2 lifecycle rule. - **Orphan protection:** R2 lifecycle rule on `bilko-archive-queue`: objects older than 7 days trigger alert (Cloud Monitoring metric → alert policy). This catches worker failures that leave objects stranded without incrementing retry count. ### 6.2 Paperless retention TBD — pending legal/compliance review by Dr. Sarah Chen (S3, healthcare compliance). Interim recommendations based on applicable law:
Document TypeRecommended RetentionLegal Basis
-----------------------------------------------------------------------------------------------------------------------------
Invoices7 yearsNorway Bokføringsloven §13; Serbia Zakon o računovodstvu; BiH equivalent
ContractsIndefinite until expiry + 5 yearsStandard contract law (Norway, Serbia, BiH, Croatia)
Care plans25 yearsNHS/CQC standard (applicable if Bilko expands to UK healthcare)
Incident reports7 yearsGeneral audit retention standard
Onboarding documents5 years post-customer-offboardingGDPR Art. 5(1)(e) storage limitation
Paperless retention enforcement is OUT OF SCOPE for this implementation phase. Configure via Paperless Workflow rules in a subsequent MC (FlowForge + Dr. Sarah Chen). \--- ## 7. Retry Semantics ### 7.1 Worker retry loop On each 5-minute cron invocation (per CEO decision D1), the worker: 1\. Lists all objects under `org/` prefix in `bilko-archive-queue` (R2 `ListObjectsV2` equivalent). 2. For each `.meta.json` sidecar found (PDF existence implied by paired key): a. Read `retryCount`. If `retryCount >= 3`: move to DLQ, skip. b. Fetch corresponding PDF bytes. c. Attempt Paperless dedup check: `GET /api/documents/?custom_fields__value=` — if document already exists in Paperless (Bilko double-run), skip upload, DELETE R2 object, update Bilko DB (idempotent cleanup). d. Attempt upload. On success: DELETE R2 objects, update Bilko DB audit log. e. On failure: increment `retryCount` in `.meta.json`, write updated `.meta.json` back to R2, log error. Leave PDF object in place. ### 7.2 Idempotency R2 object key = `org///.pdf`. If Bilko backend calls `ArchiveService.archive()`twice for the same document (e.g. invoice regenerated), R2 write is idempotent (same key, same bytes). Worker sees one object, uploads once. Paperless dedup via `bilko-source-uuid:` tag: if worker runs twice before completing a DELETE (e.g. crash between upload and delete), the second run finds the tag already present in Paperless and skips re-upload. Only deletes R2 + updates Bilko DB. ### 7.3 DLQ and alerting Object moved to `bilko-archive-dlq` after 3 failures. Alert fires to `dev@alai.no`(Cloud Monitoring alert via existing `TF_VAR_alert_email` in BUILD-BLUEPRINT line 302). DLQ objects require manual triage — either re-queue by moving back to `bilko-archive-queue` (resets `retryCount`) or manually upload to Paperless and delete from DLQ. \--- ## 8. Error Handling ### 8.1 Bilko backend — R2 write failure `ArchiveService.archive()` throws `ArchiveWriteException`. Caller (e.g. `InvoiceService.generatePDF()`) catches and: - Returns HTTP 503 to user: `{"error": "Document archived pending, retry in 5 minutes.", "code": "ARCHIVE_QUEUE_FAILURE"}`. - Writes `archive_status = 'failed'` to `archive_audit_log` (allows re-trigger from admin UI in future). - Does NOT fail the invoice PDF generation itself (PDF is already in main R2 bucket). Per ADR-022 §Consequences (Positive #1): R2 write failure is a degraded but non-blocking UX state. The invoice PDF is already saved to the main Bilko R2 bucket. Only archival is deferred. ### 8.2 Worker — Paperless API errors
ErrorAction
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
401 UnauthorizedToken expired/rotated. Alert `dev@alai.no` immediately. Worker stops processing (do not retry — all subsequent calls will also 401). Manual token rotation required.
403 ForbiddenCF Access token issue. Same action as 401.
429 Rate LimitedExponential backoff within single cron run: wait 2s, 4s, 8s (cap at 30s). If still failing after 3 attempts, leave object in R2 for next cron.
500/502/503Retry up to 3 times within cron run with exponential backoff (2s, 4s, 8s). If all fail, increment `retryCount` in `.meta.json`, leave for next cron.
Network timeoutSame as 5xx. Worker `fetch()` timeout = 30 seconds per request.
### 8.3 Worker — Cloud Run job retry policy Cloud Scheduler retry policy: max 3 retries with 30s backoff on Cloud Run job invocation failure (distinction: this is job-launch failure, not Paperless upload failure — separate from §7 object-level retries). If the job crashes mid-run, objects remain in R2 and are processed on next cron invocation. ### 8.4 Worker — structured logging All worker log lines emit JSON to stdout (Cloud Run log aggregation reads stdout). Required fields: ```json { "severity": "INFO|WARNING|ERROR", "timestamp": "", "r2Key": "", "organizationId": "", "documentType": "", "action": "UPLOAD_SUCCESS|UPLOAD_FAILED|DEDUP_SKIP|DLQ_MOVE", "paperlessDocId": , "retryCount": , "durationMs": , "error": "" } ``` \--- ## 9. Observability ### 9.1 Worker metrics (Cloud Monitoring custom metrics or stdout-JSON)
MetricTypeDescription
--------------------------------------------------------------------------------------------------------------------------
`archive_jobs_processed_total`CounterTotal R2 objects successfully uploaded to Paperless
`archive_jobs_failed_total`CounterTotal R2 objects that failed upload (all retry attempts)
`archive_queue_depth`GaugeCount of objects currently in `bilko-archive-queue` (R2 ListObjectsV2 at job start)
`archive_e2e_latency_seconds`HistogramTime from R2 object `timestamp` in `.meta.json` to confirmed Paperless upload
`archive_dlq_depth`GaugeCount of objects in `bilko-archive-dlq` (alert if > 0)
Metrics emitted as structured log lines (Cloud Run → Cloud Logging → Log-based metrics) OR via Cloud Monitoring custom metric API from worker. **Recommendation:** log-based metrics (simpler, no extra SDK dependency in worker). Cloud Monitoring log-based metric filter on `action` field. ### 9.2 Alert policies
ConditionSeverityChannel
-------------------------------------------------------------------------------------------------------
`archive_dlq_depth > 0`P1`dev@alai.no` (existing Cloud Monitoring alert email)
`archive_queue_depth > 500` for 15 minutesP2`dev@alai.no` — worker may have stopped
Worker job not invoked in >10 minutesP2Cloud Scheduler missed execution alert
`archive_jobs_failed_total` > 5 in 1 hourP2`dev@alai.no`
Paperless 401 in worker logsP1`dev@alai.no` — token rotation required
### 9.3 Bilko DB audit log Every document that passes through `ArchiveService.archive()` gets a row in `archive_audit_log`: ```sql CREATE TABLE archive_audit_log ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), organization_id UUID NOT NULL REFERENCES organizations(id), bilko_document_id UUID NOT NULL, -- FK to invoices.id, contracts.id, etc. document_type VARCHAR(50) NOT NULL, r2_object_key TEXT NOT NULL, sha256 TEXT NOT NULL, archive_status VARCHAR(20) NOT NULL DEFAULT 'pending', -- pending | archived | failed paperless_doc_id INTEGER, paperless_doc_url TEXT, archived_at TIMESTAMPTZ, retry_count INTEGER NOT NULL DEFAULT 0, last_error TEXT, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); CREATE INDEX idx_archive_audit_log_org ON archive_audit_log(organization_id); CREATE INDEX idx_archive_audit_log_doc ON archive_audit_log(bilko_document_id); CREATE INDEX idx_archive_audit_log_status ON archive_audit_log(archive_status) WHERE archive_status != 'archived'; ``` The worker updates this table via `PATCH /internal/v1/archive-audit/{bilkoDocumentId}` on the `bilko-api` service (authenticated internal call). The `bilko-api` internal endpoint is protected by a shared secret (`INTERNAL_API_KEY`) stored in Secret Manager, injected into both `bilko-api`Cloud Run service and `archiver-worker` Cloud Run job at deploy time. \--- ## 10. Open Questions for Next Phase 1\. **Worker language — Kotlin vs Node.js:** ADR-022 §Phase 2 lists "Kotlin/Ktor or Node.js, TBD." Recommendation: **Node.js**, reusing paperless-upload.js logic (inlined into `apps/archiver-worker/src/paperlessClient.js`). Rationale: (a) faster to ship — Node worker requires zero Gradle/JVM setup, shorter Docker image, simpler Cloud Run job config; (b) the heaviest logic (multipart Paperless upload) already exists in Node (MC #100004); (c) Kotlin adds value for domain-heavy Bilko services, not for a thin queue-poller. Downside: two runtimes in the Bilko repo (Kotlin + Node). Acceptable given worker is a standalone job in `apps/archiver-worker/`, isolated from `apps/api/`. \*\*CodeCraft must confirm this choice before implementation starts.\*\* 2\. **Backfill for existing Bilko documents not yet archived:** Out of scope for first ship. All pre-existing invoices, contracts in Bilko DB are unarchived. A backfill worker (one-shot Cloud Run job, reads Bilko DB → writes to R2 queue → worker picks up) is a natural Phase 2 task. Create child MC when this phase ships. 3\. **DR — Paperless VM outage >24h:** Worker retries indefinitely (R2 objects accumulate). At 24h queue backlog (estimated ~2,880 cron invocations), `archive_queue_depth > 500` alert fires to ops. Worker will self-heal on Paperless recovery without intervention. If VM is permanently lost: restore Paperless from Azure VM backup (existing backup schedule assumed — verify with FlowForge). R2 queue is the authoritative backlog; no documents are lost. 4\. **GDPR Art. 17 erasure flow:** When a Bilko org deletes their account, all archived documents must be deleted from Paperless (`DELETE /api/documents/{id}`) and the correspondent deleted (`DELETE /api/correspondents/{id}`). This is a separate erasure worker, out of scope for this implementation phase. File child MC at same time as backfill MC (Phase 2). 5\. **Bilko internal API endpoint auth (`/internal/v1/`):** The worker-to-api callback for updating `archive_audit_log` requires an internal auth mechanism. Shared secret (`INTERNAL_API_KEY`) is recommended for MVP. mTLS (Cloud Run service-to-service auth via OIDC token) is more secure and already supported by GCP — recommend upgrading to mTLS in Phase 2. Child MC for FlowForge. \--- ## References - ADR-022-document-archive-strategy.md — pattern decision, rejection rationale, CEO decisions - BUILD-BLUEPRINT.md line 64 — Cloudflare R2 existing configuration (`AWS_S3_BUCKET`, `AWS_S3_ENDPOINT`) - BUILD-BLUEPRINT.md lines 192-193 — multi-tenancy model (`organizationId` discriminator) - BUILD-BLUEPRINT.md line 302 — alert email (`dev@alai.no`, `TF_VAR_alert_email`) - BUILD-BLUEPRINT.md §9 — GCP Cloud Run deployment model, Terraform IaC structure, Secret Manager - MC #100004 — IMAP→Paperless pipe, `~/system/tools/paperless-upload.js`, BookStack #2862 - MC #100025 — parent task (ADR + spec) - Paperless-ngx API: https://docs.paperless-ngx.com/api/ - Cloudflare R2 S3-compatible API: https://developers.cloudflare.com/r2/api/s3/api/ - GCP Cloud Run jobs: https://cloud.google.com/run/docs/create-jobs - GCP Cloud Scheduler: https://cloud.google.com/scheduler/docs # COMPLIANCE-022 — Archive Review (HIPAA/GDPR/CQC)
**MC #100025** | Published 2026-05-08 | Status: Approved (Pattern 3 — Skybound) / Compliance gate pending (Dr. Sarah Chen M3+M5 blockers) **Related:** [ADR-022](https://docs.alai.no/books/bilko-balkan-accounting-saas/page/adr-022-document-archive-strategy) • [SPEC-022](https://docs.alai.no/books/bilko-balkan-accounting-saas/page/spec-022-document-archive-implementation)
**⚠️ PRE-EMPTIVE BLOCKERS** — Pattern 3 cannot ship to production with EU personal data until: - **(M3)** Azure VM disk encryption verified - **(M5)** GDPR Art. 28(4) sub-processor DPA chain documented in Bilko Terms + Privacy Notice See section 9 for full MUST list.
# COMPLIANCE-022: Healthcare & Privacy Compliance Review ## Bilko Document Archive — Pattern 3 (Blob Queue) ADR-022 / SPEC-022 **Reviewer:** Dr. Sarah Chen, Healthcare IT Systems Architect **Date:** 2026-05-08 **MC:** #100025 Subtask 3 of 5 **Status:** Final — sign-off conditions in §10 \--- ## 1. Scope — Applicable Regulations ### Jurisdiction and context Bilko is a Balkan accounting SaaS (Serbia, BiH, Croatia), EU residency claimed (GCP europe-north1), operated by ALAI Holding AS (Norway). The doc types named in ADR-022 §Context include care plans and incident reports. Those two types trigger healthcare regulatory scope even in an accounting product. ### Regulations evaluated
RegulationTriggerApplies?
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
GDPR / EU GDPR (Regulation 2016/679)EU residency, Balkan clients in EU data space, special category Art. 9 data possible in care plansYES — primary
HITECH Act (US)Only if Bilko serves US-based covered entities or their BAs. No US presence confirmed in BUILD-BLUEPRINT.NOT YET — but architecture must not preclude compliance if US expansion occurs
HIPAA Privacy + Security RulesSame trigger as HITECH.NOT YET — apply when US expansion scoped
CQC / Health and Social Care Act 2008Only if Bilko serves UK-registered domiciliary care agencies. Not confirmed.NOT YET — same comment
NIS2 Directive (EU 2022/2555)ALAI Holding AS as digital infrastructure provider processing health data above medium-enterprise threshold. Likely not in scope at current scale but architecture must support NIS2-compliant incident response by design.MONITOR — review at 50+ orgs
Norway Bokføringsloven §13Invoices, financial records, 7-year retentionYES — invoices
Serbia Zakon o računovodstvu / Croatia equivalentsSame financial retentionYES — domain packages
GDPR Art. 17 (Right to Erasure)Active for all EU data subjectsYES — open gap in SPEC-022 §10.4
GDPR Art. 28 (Sub-processor chain)ALAI Azure VM Paperless is a sub-processor of BilkoYES — gap in both documents
### Legal basis assumed For care plans and incident reports: **GDPR Art. 6(1)(b)** (contract performance) as primary basis; **Art. 9(2)(h)** (health/social care purposes) as special-category basis. This must be reflected in Bilko's Privacy Notice and any DPA issued to tenants. \--- ## 2. Data Classification
Document TypeGDPR ClassificationSpecial Category (Art. 9)?Financial Record?Recommended Paperless Tag
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
InvoicePersonal data (contact name, address, VAT ID)NoYes (Bokføringsloven, 7y)`data-class:financial`
ContractPersonal data (signatories, company data)NoQuasi-financial (5y post-expiry)`data-class:legal`
Care plan**Special category health data**YES — diagnosis, medication, functional statusNo`data-class:health` `sensitivity:high`
Incident report**Special category health/social data**YES — if describes injury, clinical eventPotentially`data-class:health` `sensitivity:high`
Onboarding documentPersonal data (identity verification, scanned ID)No (unless medical screen)No`data-class:identity`
### Tag strategy amendment SPEC-022 §5.2 defines four tag types: `org:`, `doc-type:*`, `bilko-source`, `bilko-source-uuid:`. **Missing: data classification tags.** The `PAPERLESS_TAG_IDS_MAP` env var must include entries for `data-class:health`, `data-class:financial`, `data-class:legal`, `data-class:identity`, and `sensitivity:high`. These are required for: - Retention policy enforcement (different rules per class) - Access control (human admins in Paperless must not see `sensitivity:high` docs without justification) - Incident response scoping (breach = all `data-class:health` docs in affected org) \--- ## 3. Audit Trail Requirements ### 3.1 What SPEC-022 §9.3 provides `archive_audit_log` records: who queued the archive (implicit — ArchiveService called in user request context), R2 object key, sha256, status transitions, timestamps, Paperless doc ID, retry count, errors. This covers the **archival pipeline itself** adequately. ### 3.2 Critical gap — per-access logging for archived documents SPEC-022 contains **no provision** for logging human access to archived documents in Paperless. When a CEO-level user or ALAI admin opens a care plan or incident report in the Paperless UI at `archive.alai.no`, there is no audit record in any Bilko system. **GDPR Art. 5(1)(f)** (integrity and confidentiality) and, when US healthcare clients are added, **HIPAA §164.312(b)** (audit controls) require that every access to records containing personal or health data is logged with: - Viewer identity (Paperless username or service account) - Document ID and document type - Timestamp (UTC) - Source IP address - Access outcome (viewed, downloaded, printed) Paperless-ngx does not natively emit per-document access logs to an external SIEM. It maintains an internal Django audit trail (`auditlog` tables), but that trail lives on the Azure VM and is not exported to GCP Cloud Logging where Bilko's other audit records live. **Gap: no tamper-evident export of Paperless access logs.** ### 3.3 Retention of access logs GDPR Article 5 + Recital 39 require demonstrability — logs must be retained long enough to respond to a subject access request or supervisory authority inquiry. Minimum: same retention as the documents they describe. For care plans (25 years per SPEC-022 §6.2), access logs must survive 25 years. For invoices, 7 years. SPEC-022 §6.2 is silent on access log retention. ### 3.4 Tamper evidence The `archive_audit_log` table in Bilko DB is defined in SPEC-022 §9.3. It has no tamper-evidence mechanism (no hash chaining, no write-once constraint beyond application code). PostgreSQL row-level updates are possible for any user with DB access. **Minimum required:** ensure `archive_audit_log` has no application-level UPDATE path for `created_at`and core fields (`sha256`, `organization_id`, `bilko_document_id`). A DB-level check constraint or trigger preventing modification of those columns after insert provides tamper-resistance without requiring a separate append-only log infrastructure. \--- ## 4. Access Control Deltas ### 4.1 Worker process — least privilege (SPEC-022 §4) SPEC-022 §4.2 recommends a separate R2 API token for the worker scoped to the two archive buckets. SPEC-022 §4.3 recommends a separate Paperless API token. Both are correct. No gap here from an access control standpoint. ### 4.2 Human admin access to Paperless — unaddressed Neither ADR-022 nor SPEC-022 defines who may log into `archive.alai.no` as a human user and what they can access. Currently, the only documented credential is `alembasic` (Bitwarden item referenced in ADR-022 §Context). That is a single superuser account. For multi-tenant data containing health records: - Superuser access = unrestricted cross-tenant document access - No audit of which documents the superuser viewed - No segregation between financial docs (low sensitivity) and care plan / incident docs (high sensitivity) **Required additions:** - Create a Paperless `bilko-ops` service account for operational tasks (queue monitoring, DLQ triage) with access scoped to `bilko-source` tagged documents only, no `sensitivity:high` filter bypass. - The CEO (`alembasic`) personal account must not be used for routine Paperless access once healthcare doc types are live. A named admin account with restricted permissions per document type is required. - Paperless does not natively enforce per-tag ACLs. This means cross-tenant isolation in the Paperless UI relies entirely on the discipline of human users to filter by `org:` tag. This is not adequate for healthcare data. ### 4.3 Cross-tenant containment — tag-based vs. physical separation SPEC-022 §5.3 states: "Cross-tenant queries are impossible if the caller only has access to their own `org_tag_id`. Isolation is enforced by the Bilko application layer controlling which `org_tag_id` each user can query." This is **correct for machine-to-machine access** (worker reads, API queries). It is \*\*not sufficient for human access\*\* to the Paperless UI, where all documents from all tenants are visible to any logged-in user. Until Paperless supports per-tag or per-user-group ACLs (which it does not as of v2.x), physical separation — one Paperless instance per tenant — is the only way to enforce tenant isolation for human UI access. \*\*Recommendation (SHOULD — not an immediate ship blocker provided care plans are not in scope for MVP):\*\* Before enabling care plan or incident report archival through this pipeline, deploy per-tenant Paperless instances or ensure the Paperless UI is not accessible to any human user other than a designated compliance officer who has executed an appropriate access agreement and whose access is logged separately. ### 4.4 Break-glass access procedure Neither document defines a break-glass procedure: how does ALAI access a specific tenant's archived documents if the Bilko DB `org_paperless_cache` is corrupted or unavailable? **Required:** Document and test a break-glass procedure: (a) query Paperless directly by `org:` tag using the bilko-ops service account, (b) log the access reason and approver, (c) notify the affected tenant within 72 hours if the access was to health data. \--- ## 5. Sub-Processor Analysis ### 5.1 The data flow chain ``` Bilko tenant (data subject's data) → Bilko Cloud Run API (controller / data processor acting on behalf of tenant) → Cloudflare R2 (sub-processor #1 — staging queue) → archiver-worker Cloud Run (internal processor — ALAI infrastructure) → ALAI Azure VM / Paperless-ngx (sub-processor #2 — long-term storage) ``` ### 5.2 Gap: no GDPR Art. 28 chain documented GDPR Art. 28(4) requires that where a processor engages a sub-processor, the same data protection obligations as set out in the controller-processor contract are imposed on the sub-processor. ADR-022 notes "Paperless-ngx at archive.alai.no = ALAI Azure VM (separate org from Bilko tenants). Cross-org data flow = sub-processor relationship; needs DPA articulation" — and then defers to this review. SPEC-022 does not address it at all. **Minimum required DPA chain articulation:** 1\. Bilko's Terms of Service / DPA with each tenant must list: - Cloudflare (R2) as a sub-processor - ALAI Holding AS hosting (Azure VM, Paperless) as a sub-processor 2\. The existing ALAI AI Services Legal Pack (BookStack shelf `https://docs.alai.no/shelves/ai-services-legal-pack`, TOMs published) provides a DPA template. That template must be extended with a Schedule listing sub-processors and their processing purposes. For the archive pipeline: Purpose = "Long-term document retention for audit and compliance purposes"; Location = EU (Azure westeurope); Retention per §6.2 of SPEC-022. 3\. ALAI must have a DPA with Microsoft Azure (for the VM hosting Paperless). Standard Microsoft Online Services DPA covers this if the Azure subscription is enrolled — verify this is in place. 4\. Bilko tenants uploading care plans or incident reports must be explicitly informed (Privacy Notice update) that health data is stored in Paperless on an ALAI-operated EU server. ### 5.3 Cloudflare R2 sub-processor status Cloudflare R2 is covered by Cloudflare's standard Data Processing Addendum. ALAI should confirm it is signed as part of the Cloudflare account setup. The R2 bucket must be configured to a confirmed EU jurisdiction (Cloudflare R2 location hint `WEUR` or `EEUR`). \--- ## 6. Encryption Requirements ### 6.1 At rest — R2 (staging queue) Cloudflare R2 provides AES-256 encryption at rest by default for all objects. No customer-managed key option was selected per SPEC-022 §4. For current Bilko document types (invoices, contracts), platform-managed encryption is adequate. For care plans and incident reports (special category health data), consider whether tenant-controlled encryption keys are a contractual requirement with any healthcare clients before that doc type goes live. ### 6.2 At rest — Paperless on Azure VM SPEC-022 does not confirm disk encryption on the Azure VM hosting Paperless. Azure VM OS disks are **not encrypted by default** — Azure Disk Encryption (ADE using BitLocker/DM-Crypt) or server-side encryption with customer-managed keys must be explicitly enabled. This must be verified by FlowForge before any healthcare document type is archived. **Required (MUST):** Confirm Azure VM hosting Paperless has disk encryption enabled. Run `az vm encryption show --name --resource-group ` and include output in the ship checklist evidence. ### 6.3 In transit — GCP Cloud Run to R2 Cloudflare R2 S3-compatible API enforces TLS 1.2+ on all endpoints. Confirmed adequate. ### 6.4 In transit — archiver-worker to Paperless (archive.alai.no) ADR-022 §Context: Paperless is "behind Cloudflare Access (service token required)". Cloudflare Access enforces HTTPS on all traffic to the origin. The origin-to-Cloudflare tunnel should use Cloudflare Tunnel (cloudflared) or an authenticated origin pull — confirm this is configured so the Azure VM does not expose port 443 directly to the internet. If the Azure VM is exposed directly (no cloudflared), a misconfigured security group could allow direct HTTP access bypassing CF Access entirely. FlowForge must confirm the network path. ### 6.5 Field-level encryption Field-level encryption of PDF content is not feasible within this architecture and is not required at this stage. The PDF is the record. Encryption at transport and at rest is the appropriate control. If any structured extracted fields from care plans are ever stored in Bilko DB as queryable columns, those columns must be treated as special category data and assessed for column-level encryption. \--- ## 7. Erasure / Right to Be Forgotten (GDPR Art. 17) ### 7.1 Current state SPEC-022 §10.4 acknowledges erasure as an open question: "a separate erasure worker, out of scope for this implementation phase." ADR-022 §Phase 4 (Q3) provides a three-step Paperless erasure process (query by `org:` tag, delete documents, delete correspondent). This is architecturally sound. ### 7.2 Interim recommendation (required before care plans go live, SHOULD before MVP) GDPR Art. 17(1) requires that erasure be executed "without undue delay." For a SaaS with a documented erasure process, "without undue delay" means the capability must exist and be operable when a valid erasure request arrives — it does not require automatic self-service. For MVP (invoices, contracts, onboarding — not health data): an operationally-documented manual erasure procedure is acceptable interim. The procedure must be documented in the RUNBOOK.md and tested before any EU data subject data reaches production. Manual erasure procedure (document in RUNBOOK.md before MVP ship): 1\. Receive verified erasure request (tenant admin or data subject via support ticket). 2. Confirm no legal hold applies (Bokføringsloven 7-year financial record exception — invoices cannot be erased within retention period under legitimate interest override). 3. Delete Bilko DB records for the org (existing DB delete cascade paths — confirm with CodeCraft). 4. Query R2 for any pending queue objects: `aws s3 ls s3://bilko-archive-queue/org//` and delete all. 5. Query Paperless: `GET /api/documents/?tags__id__in=`, delete all results. 6. Delete Paperless correspondent: `DELETE /api/correspondents/`. 7. Delete `org_paperless_cache` row for the org. 8. Log erasure completion with timestamp and executor identity. Before care plans or incident reports are archived: an automated erasure worker is required (child MC, FlowForge). Manual erasure for health records under Art. 17 is too slow and too error-prone. ### 7.3 Financial record exception Invoices subject to Bokføringsloven §13 (Norway) or equivalent (Serbia, Croatia, BiH) cannot be erased within the mandatory retention period even on Art. 17 request. The Privacy Notice must inform data subjects of this limitation. The erasure procedure must check document type and skip financial records with a logged exception. \--- ## 8. Incident Response / Breach Notification ### 8.1 Breach scenarios
ScenarioSeverityGDPR notificationResponsible party
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Bilko Cloud Run API compromise (R2 staging queue exposed)HIGH if health data in queue72h to supervisory authority (Datatilsynet, Norway; or relevant Balkan DPA)ALAI (as Bilko operator)
Azure VM compromise (Paperless data exposed)HIGH72h — triggers sub-processor notification chain: ALAI Azure → ALAI Bilko team → tenant notificationALAI (as sub-processor); tenant notifies their data subjects
Worker credential leak (CF Access + Paperless API token)MEDIUM-HIGH (allows read of all archived docs across all tenants)72h if PHI/health data accessibleALAI
Cross-tenant Paperless UI access (human error)MEDIUM72h if health data accessedALAI
### 8.2 Notification chain (required in RUNBOOK.md) Neither ADR-022 nor SPEC-022 defines a breach notification chain. The following must be documented: 1\. **Detection:** Cloud Monitoring alert (unauthorised 401/403 spike, DLQ depth spike, anomalous ListObjectsV2 calls from unexpected IP) fires to `dev@alai.no`. 2. **Triage:** Within 1 hour — ALAI ops determines whether PHI/PII was exposed. 3. **Internal declaration:** ALAI Compliance (Alem Basic as DPO for current scale) declares breach. 4. **Supervisory authority notification:** Within 72 hours of awareness — notify Datatilsynet (Norway) via `https://www.datatilsynet.no/en/about-privacy/notification-of-a-data-breach/`. If Serbian or Croatian data subjects affected: notify relevant authority (POVP, Serbia; AZOP, Croatia) simultaneously. 5. **Tenant notification:** Within 72 hours — notify affected tenant(s) via documented contact (tenant owner email on record in Bilko DB). 6. **Data subject notification:** If "likely to result in a high risk to rights and freedoms" (Art. 34), notify data subjects directly. Care plan or incident report exposure = high risk threshold met automatically. \--- ## 9. Recommended Changes ### MUST — compliance blockers (must fix before production ship)
IDDocumentSectionRequired change
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
M1SPEC-022§5.2Add `data-class:health`, `data-class:financial`, `data-class:legal`, `data-class:identity`, and `sensitivity:high` to `PAPERLESS_TAG_IDS_MAP`. Worker must apply `data-class` and (for care plans / incident reports) `sensitivity:high` tag on every archive call.
M2SPEC-022§9.3Add DB-level protection on `archive_audit_log`: a Postgres trigger or check constraint must prevent UPDATE of `organization_id`, `sha256`, `bilko_document_id`, and `created_at` after row insert. Append-only semantics enforced at DB layer, not only application layer.
M3ADR-022 + SPEC-022§4 / §ContextDocument and verify Azure VM disk encryption is enabled before care plans or incident reports are archived. Add to ship checklist: `az vm encryption show` output as evidence.
M4SPEC-022§10.4Document manual erasure procedure in RUNBOOK.md (see §7.2 of this review) before MVP ship. Must include: financial record exception logic, Paperless deletion steps, audit log of erasure.
M5ADR-022§ConsequencesUpdate Bilko Terms of Service / Privacy Notice and sub-processor DPA to list Cloudflare R2 and ALAI Azure VM (Paperless) as sub-processors per GDPR Art. 28(4). This must exist before any EU personal data flows through the archive pipeline. Must reference ALAI AI Services Legal Pack DPA template on BookStack.
M6SPEC-022§4 / §9Paperless access log export: configure Paperless Django audit log export (or Cloudflare Access request logging for `archive.alai.no`) to ship access events to Cloud Logging. Access log entries must contain: user/service account identity, document ID, document type, timestamp, source IP. Retain per document class retention period.
### SHOULD — best practice (not immediate ship blockers)
IDDocumentSectionRecommended change
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
S1SPEC-022§5.3Before enabling care plan or incident report doc types, assess whether tag-based isolation in the shared Paperless instance is sufficient or whether a dedicated per-healthcare-tenant Paperless instance is required. Tag isolation is adequate for machine queries but not for human Paperless UI access.
S2SPEC-022§4.3Replace `INTERNAL_API_KEY` shared secret for worker-to-api callback with GCP Cloud Run service-to-service OIDC auth (already in SPEC-022 §10.5 as Phase 2 item). Shared secret is a credential management risk. This is already flagged; confirm it is a Phase 2 child MC, not indefinitely deferred.
S3ADR-022§Phase 4Create child MC for automated erasure worker before enabling care plan archival. Manual erasure is not appropriate for health data under GDPR Art. 17.
S4SPEC-022§6.2Add care plan retention to 25 years in Paperless Workflow rule (SPEC-022 already notes this as out of scope). File the child MC before health doc types go live. 25-year retention is a CQC/NHS standard; for Balkan jurisdiction equivalents, confirm with local counsel (no equivalent statutory period confirmed for Serbia/BiH/Croatia).
S5SPEC-022§10Add Breach Notification Runbook to RUNBOOK.md (§8.2 of this review) as child MC. Required before any production data flows through the pipeline.
S6ADR-022§ContextVerify Cloudflare R2 bucket `bilko-archive-queue` location hint is set to `WEUR` or `EEUR` to maintain EU data residency. Not confirmed in either document.
\--- ## 10. Sign-Off Conditions The following must be true before Pattern 3 ships to production. Each item maps to a MUST above. 1\. **\[M5\] Sub-processor DPA chain published.** Bilko ToS / Privacy Notice lists Cloudflare R2 and ALAI Azure VM as sub-processors. Bilko tenant DPA template updated. Evidence: BookStack page with published DPA addendum (reference ALAI AI Services Legal Pack shelf). 2\. **\[M1\] Data classification tags deployed in Paperless.** `data-class:*` and `sensitivity:high` tags exist in Paperless, IDs populated in `PAPERLESS_TAG_IDS_MAP`, worker applies them. Evidence: Proveo test showing a care plan doc archived with `data-class:health` + `sensitivity:high` tags visible in Paperless. 3\. **\[M3\] Azure VM disk encryption verified.** FlowForge provides `az vm encryption show` output confirming encryption enabled on the VM hosting Paperless. Evidence: output attached to ship checklist. 4\. **\[M2\] Archive audit log tamper-protection deployed.** Flyway migration adds DB-level constraint on `archive_audit_log`. Evidence: Proveo attempts direct SQL UPDATE on `created_at` and `sha256` columns and confirms rejection. 5\. **\[M6\] Paperless access log export live.** Cloudflare Access request logs for `archive.alai.no` (or Paperless Django auditlog export) flowing to Cloud Logging. Evidence: Cloud Logging query showing access log entries from a test document retrieval. 6\. **\[M4\] RUNBOOK.md updated with manual erasure procedure.** Procedure includes financial record exception, Paperless deletion steps, confirmation of `org_paperless_cache` cleanup. Evidence: Proveo executes erasure procedure end-to-end in staging and documents result. **Pre-emption clause:** Items M3 (Azure disk encryption) and M5 (DPA chain) are pre-emptive — they must be resolved before any personal data of any kind is archived in Paperless production. They are not "ship before care plans go live" items; they are "ship before any data flows" items. If either is unresolved at production launch, the pipeline must be restricted to internal test data only via a feature flag. \--- \_Reviewed against: ADR-022 (all sections), SPEC-022 (all sections §1–§10), BUILD-BLUEPRINT.md (multi-tenancy model, GCP deployment, R2 config). GDPR 2016/679 Arts. 5, 6, 9, 17, 28, 34; HIPAA §164.312 (noted for future US expansion); CQC Key Lines of Enquiry Safe domain (noted for future UK healthcare expansion); NIS2 Directive 2022/2555 (monitor threshold).\_ # HR eRačun — Architecture Decision Record (ADR) + Build Plan
**STATUS: design accepted; build in progress (WP1+). Production activation PARKED pending legal (B1/B2) + the multi-tenant decision.** NOTE: `app-api.bilko.cloud` maps to `bilko-api-demo` — the demo backend serves the bilko.cloud domain; activation is a real-domain decision, not a code toggle.
**Status:** ACCEPTED **Date:** 2026-06-11 **Lead Architect:** Petter Graff (synthesized from team inputs) **Input Authors:** Martin Kleppmann, Bruce Momjian, Markos Zachariadis, Parisa Tabriz **MC:** [\#103453](https://boards.alai.no) (architecture documentation) | [\#103464](https://boards.alai.no) (build execution) **Cross-link:** [Bilko HR eRačun — sveRačun (PostLink) Integration & Status Model](https://docs.alai.no/books/bilko-balkan-accounting-saas/page/bilko-hr-eracun-sveracun-postlink-integration-status-model) **CEO directive:** "tim arhitekata, Petter Graff lead, plan → dokumentuju → build, BEZ HAKOVA." --- ## 1. Context and Problem ### 1.1 What Exists Bilko has a Croatia HR eRačun adapter (`SveRacunHrEInvoiceAdapter`) with three implemented methods — `serialize()`, `submit()`, `pollStatus()` — and 42 unit tests. A Proveo-verified live TEST submission to the sveRačun (PostLink d.o.o.) TEST API returns HTTP 200 with a `documentId`. The status mapping (`mapStatusPair`) correctly implements the real sveRačun two-layer status model (corrected MC #103445). ### 1.2 The Three Structural Problems **Problem 1 — The wiring gap (critical).** No route, no service, and no persistence layer connects the product UI/API to the adapter. `POST /invoices/{id}/submit-to-sef` exists for Serbia (RS); HR has no equivalent. `PluginHR.submitToFiscalPlatform` is `NOT_IMPLEMENTED` by design (it uses `FiscalReceipt`, not `CanonicalInvoice`). An operator cannot submit an HR invoice through Bilko today. This is the primary gap this ADR closes. **Problem 2 — Live double-fiscalization bug (critical, exists in the code today).** `SveRacunHttpClient` installs `HttpRequestRetry` globally with `retryOnServerErrors(maxRetries = 3)`. This plugin fires on all 5xx responses — including those returned after sveRačun has already accepted and queued the document (transient 500 on the response-write path). A retry would POST the same UBL XML with the same invoice number to sveRačun a second time. In the Croatian fiscal model, that is a second fiscalization of the same invoice number — a criminal tax offence (Kazneni zakon, čl. 256). *This bug exists in the current codebase and must be fixed before any live call, including TEST calls.* **Problem 3 — The single-issuer ceiling (architectural).** `serialize()` reads the XML sender OIB from `httpClient.configuredSenderVat`, which maps to the global env var `SVERACUN_SENDER_VAT`. sveRačun's etapa-1 rule requires that the initiator OIB (the API-key-holder) equal the XML sender OIB. With a single global env var, Bilko can only ever submit invoices as one legal entity. A multi-tenant SaaS requires each tenant to issue under their own OIB. The CEO decision parks multi-tenant for production, but the architecture must not hardcode assumptions that prevent it. ### 1.3 Compliance Blockers from Vlado Brkanić Memo (MC #103443) - **B4 (CRITICAL):** UNKNOWN status from sveRačun means "still processing" — never auto-resubmit. Double fiscalization. - **B5 (CRITICAL):** Invoice number reserved before submit, non-returnable even on failure. Gapless per fiscal year per issuer OIB. - **B6 (CRITICAL):** Archive original fiscalized UBL XML bytes with integrity proof, 11 years immutable. - **B1/B2 (PARKED):** ALAI legal status as HR OIB holder and PostLink intermediary contract — separate legal/commercial track. Out of scope for this build. --- ## 2. Decisions ### 2.1 The IssuerProfile Abstraction (Zachariadis Model C) **Decision:** Introduce `IssuerProfile` as the single abstraction for "who is the legal sender and what credentials does the system use." The adapter and service NEVER read global env vars for sender identity after this change. The demo is built on this abstraction with a single ALAI profile. **Rationale:** The PostLink `companyVatNumber` header is already architecturally separate from the `Authorization` API key header. The IssuerProfile abstraction now means the production multi-tenant path is a credential-config change, not a code rewrite. ``` data class IssuerProfile( val profileId: UUID, val orgId: UUID, // FK to organizations.id val legalSenderOib: String, // HR-prefixed, e.g. HR91276104352 val legalSenderName: String, val submissionMode: SubmissionMode, // DIRECT | INTERMEDIARY val apiKeySecretRef: String, // GCP Secret Manager path — NEVER the raw key val sveRacunBaseUrl: String, // TEST or PROD endpoint val intermediaryOib: String? = null, val posrednikRef: String? = null, val enabled: Boolean ) enum class SubmissionMode { DIRECT, INTERMEDIARY } ``` For demo: one row, `submissionMode = DIRECT`, `legalSenderOib = HR91276104352`, `apiKeySecretRef = "projects/.../secrets/bilko-sveracun-test-api-key/versions/latest"`. For production: per-tenant rows, `submissionMode = INTERMEDIARY`, shared platform key, per-tenant `legalSenderOib`. ### 2.2 Adapter Refactor: IssuerProfile Injection Over Env Vars **Decision:** `SveRacunHrEInvoiceAdapter.serialize()` receives `senderOib: String` explicitly. `SveRacunHttpClient` is instantiated with per-profile `apiKeyOverride` and `senderVatOverride`. The global-env-var constructor path is preserved for tests only; the production code path always resolves via `IssuerProfile`. ### 2.3 Retry Policy: Split Send-Path from Poll-Path **Decision:** `SveRacunHttpClient` will use TWO separate `HttpClient` instances: one for the send path with `maxRetries = 0`, one for the poll path with `maxRetries = 3` and exponential backoff. **Rationale:** This is the Kleppmann non-negotiable. The current single `HttpClient` with global retry is a live bug. Splitting into two instances is the cleanest fix without touching retry configuration in a way that could be accidentally reverted. ``` // Send path — zero retries; double-submit is a tax offence private val sendClient = HttpClient(sendEngine) { install(HttpTimeout) { requestTimeoutMillis = TIMEOUT_MS; connectTimeoutMillis = 10_000L } // NO HttpRequestRetry installed } // Poll path — safe to retry; reads are idempotent private val pollClient = HttpClient(pollEngine) { install(HttpTimeout) { requestTimeoutMillis = TIMEOUT_MS; connectTimeoutMillis = 10_000L } install(HttpRequestRetry) { maxRetries = MAX_RETRIES retryOnServerErrors(maxRetries = MAX_RETRIES) exponentialDelay(base = 2.0, maxDelayMs = 8_000L) } } ``` ### 2.4 State Machine (Canonical Definition) The canonical state machine for an HR eRačun submission in Bilko. All service code and all DB column values reference these states and only these states.
State`internal_status``sveracun_document_id`Meaning
NOT\_SUBMITTEDNULL (no row)NULLInvoice exists; no submission row
NUMBER\_RESERVED`NUMBER_RESERVED`NULLFiscal number locked; XML serialized; GCS written; HTTP not yet called
SUBMITTED`SUBMITTED```HTTP 200 + documentId received and persisted
SUBMIT\_UNCERTAIN`SUBMIT_UNCERTAIN`NULLSent (maybe); no documentId received (timeout / conn err / no docId in 200 body)
PENDING`PENDING```sveRačun still processing (UNKNOWN or null external)
ACCEPTED`ACCEPTED```Terminal success: internal=OK + external=FISCALIZATION:OK
REJECTED`REJECTED``` or NULLTerminal failure: FAILED/UNDELIVERABLE/FISCALIZATION:ERROR/4xx etapa-1
**Legal transitions (one-way; no backwards, no auto-resubmit):** ``` NOT_SUBMITTED -> NUMBER_RESERVED NUMBER_RESERVED -> SUBMITTED | SUBMIT_UNCERTAIN | REJECTED SUBMITTED -> PENDING | ACCEPTED | REJECTED PENDING -> ACCEPTED | REJECTED | PENDING (keep polling) SUBMIT_UNCERTAIN -> SUBMITTED (reconcile found docId) | REJECTED (confirmed not found) ACCEPTED -> (terminal, immutable) REJECTED -> (terminal; operator action + new fiscal number required for re-send) ``` **Forbidden transitions:** - `SUBMITTED -> NUMBER_RESERVED` (never) - `ACCEPTED -> anything` (immutable terminal) - `REJECTED -> SUBMITTED` (no auto-resubmit; operator must issue new fiscal number) *Note on naming alignment: Momjian uses APPROVED where Kleppmann uses ACCEPTED. The ADR adopts ACCEPTED to align with EU e-invoicing terminology and the DB CHECK constraint in V77. The adapter's EInvoiceStatus.APPROVED is the adapter-interface value; the service layer translates it to the ACCEPTED DB state.* ### 2.5 Persist-Before / Persist-After Protocol (Kleppmann Non-Negotiable #3) Every submit call follows this exact ordering: **BEFORE the HTTP call — one DB transaction:** 1. `SELECT ... FOR UPDATE` on the invoice row (concurrent-submit guard) 2. Check `internal_status NOT IN (NUMBER_RESERVED, SUBMITTED, SUBMIT_UNCERTAIN, PENDING)` — reject 409 CONFLICT if already in flight 3. `UPSERT` `hr_einvoice_number_counters` and `SELECT ... FOR UPDATE` to allocate next fiscal number (gapless, Momjian §1) 4. Compute `idempotencyKey = SHA-256(orgId + "|" + invoiceId + "|" + fiscalInvoiceNumber)` 5. Call `adapter.serialize(invoice, senderOib = issuerProfile.legalSenderOib)` to build UBL XML bytes 6. Compute `sha256Hex = SHA-256(xmlBytes)` (hex string) 7. Write XML bytes to GCS at `{orgId}/{fiscalYear}/{fiscalInvoiceNumber}/{submissionId}.xml` (write-once; must succeed before row insert) 8. INSERT `hr_einvoice_submissions` row with `internal_status = NUMBER_RESERVED` 9. COMMIT **HTTP call (outside any transaction):** - `sendClient.sendDocument(xmlBytes)` — NO retry **AFTER the HTTP call — separate DB transaction:** - Case A (HTTP 200 + documentId): UPDATE `internal_status = SUBMITTED`, `sveracun_document_id = docId` - Case B (HTTP 200 no docId, OR timeout, OR connection error): UPDATE `internal_status = SUBMIT_UNCERTAIN` - Case C (HTTP 4xx): UPDATE `internal_status = REJECTED`, `last_error = body` ### 2.6 OIB Binding Invariant (Tabriz Non-Negotiable) The service layer (`HrEInvoiceService.submitInvoice()`) MUST enforce this invariant before any HTTP call: ``` require(invoice.organizationId == principal.organizationId) { "Invoice org mismatch" } require(issuerProfile.orgId == principal.organizationId) { "Credential org mismatch" } require(issuerProfile.legalSenderOib == xmlSenderOib) { "OIB binding violated" } ``` If any assertion fails: HTTP 422, write `LoggedAction` with `event = "hr_einvoice_oib_binding_violation"`, do NOT proceed. A broken OIB binding causes Bilko to file a fiscalized tax document under the wrong entity's identity with Porezna uprava — that is tax fraud. ### 2.7 UNIQUE(invoice\_id) on hr\_einvoice\_submissions (Momjian Non-Negotiable) The `UNIQUE (invoice_id)` constraint in migration V77 is the architectural load-bearing constraint for this feature. It must be present in the migration before any submission code is merged. Any code path that attempts to create a second active submission row for the same invoice receives a unique constraint violation — the DB-level guard for double-fiscalization even if service-layer checks have a bug. --- ## 3. Target Architecture ### 3.1 Layered View ``` [HTTP Route] POST /invoices/{id}/submit-to-sveracun GET /invoices/{id}/sveracun-status GET /invoices/{id}/sveracun-xml (admin debug) POST /invoices/{id}/poll-sveracun-status (manual poll trigger) | | JWT principal -> requirePermission("sveracun:submit") | organizationId from JWT (never from request body) v [HrEInvoiceService] - IssuerProfileRepository.findByOrgId(orgId) -> IssuerProfile - OIB binding invariant assertion (hard, not soft) - Persist-before-tx (number allocation, XML serialize, GCS write, DB insert) - SveRacunHttpClient(apiKeyOverride, senderVatOverride) — per-profile instantiation - SveRacunHrEInvoiceAdapter.submit(xmlBytes, invoice, senderOib) — NO retry - Persist-after-tx - HrEInvoiceNumberService.reserveNextNumber(orgId, issuerOib, fiscalYear) - LoggedAction audit write per submit | v [SveRacunHrEInvoiceAdapter] (already implemented; adapter-level changes only) - serialize(invoice, senderOib: String) — senderOib injected, not from env - submit(xmlBytes, invoice) -> SubmitResult - pollStatus(documentId, invoice) -> EInvoiceStatus - mapStatusPair() (unchanged — correct per MC #103445) [SveRacunHttpClient] (two client instances after fix) - sendClient (NO retry) -> sendDocument() - pollClient (retry OK) -> getInternalStatus(), getExternalStatus() [Postgres — four new tables via Flyway V75-V78] hr_einvoice_issuer_config (IssuerProfile persistence; one row for demo) hr_einvoice_number_counters (gapless fiscal year sequence via FOR UPDATE) hr_einvoice_submissions (submission lifecycle; UNIQUE(invoice_id)) hr_einvoice_archive (integrity manifest; INSERT-only; points to GCS) [GCS — bilko-hr-einvoice-archive-{env}] - Write-once per submission at NUMBER_RESERVED (before HTTP call) - Integrity verified on retrieve (SHA-256 re-hash comparison) - Retention policy: 4015 days LOCKED (11 years WORM) for prod bucket - Demo bucket: same write-once pattern; 90-day retention (not locked) ``` ### 3.2 IssuerProfileRepository Interface ``` interface IssuerProfileRepository { fun findByOrgId(orgId: UUID): IssuerProfile? } // Demo implementation: reads from DB table hr_einvoice_issuer_config (V75 migration) class DbIssuerProfileRepository( private val secretManager: GcpSecretManagerClient ) : IssuerProfileRepository { override fun findByOrgId(orgId: UUID): IssuerProfile? { // SELECT from hr_einvoice_issuer_config WHERE org_id = ? AND enabled = true // Resolve apiKey from GCP Secret Manager by api_key_secret_ref } } ``` For demo: one row in `hr_einvoice_issuer_config` with `enabled = false` by default. A manual `UPDATE ... SET enabled = true` plus `SVERACUN_HR_LIVE = true` env flip is required to activate live submit. Two explicit gates, both required, neither accidental. ### 3.3 Route Pattern (Mirrors SefRoutes.kt) ``` fun Route.sveRacunRoutes() { val service by di() post("/invoices/{id}/submit-to-sveracun") { val principal = call.principal()!! if (requirePermission(principal, "sveracun:submit")) return@post val invoiceId = call.parameters["id"] ?: ... val organizationId = principal.organizationId // from JWT, never from request try { val result = dbQuery { service.submitInvoice(invoiceId, organizationId, principal) } call.respond(HttpStatusCode.OK, mapOf(...)) } catch (e: OibBindingException) { call.respond(422, ...) } catch (e: NotFoundException) { call.respond(404, ...) } catch (e: ConflictException) { call.respond(409, ...) } } get("/invoices/{id}/sveracun-status") { /* requirePermission("sveracun:status") */ } get("/invoices/{id}/sveracun-xml") { /* admin only; verify SHA-256 before serving */ } post("/invoices/{id}/poll-sveracun-status") { /* manual trigger for demo */ } } ``` ### 3.4 Persistence Schema — Flyway V75–V78 #### V75 — hr\_einvoice\_issuer\_config Per-tenant IssuerProfile persistence. One row for demo (ALAI, DIRECT mode). RLS on `org_id`. The `api_key_secret_ref` column stores the GCP Secret Manager resource name — the raw API key is never stored in the DB. Key columns: `org_id UUID NOT NULL`, `issuer_oib VARCHAR(13) NOT NULL`, `api_key_secret_ref VARCHAR(1024) NOT NULL`, `api_base_url VARCHAR(500) NOT NULL DEFAULT 'https://test.sveracun.hr/api'`, `submission_mode VARCHAR(20) NOT NULL DEFAULT 'DIRECT'`, `enabled BOOLEAN NOT NULL DEFAULT FALSE`. Constraint: `UNIQUE (org_id, issuer_oib)`. #### V76 — hr\_einvoice\_number\_counters Gapless fiscal year invoice number counter. One row per `(org_id, issuer_oib, fiscal_year)`. Allocated via `SELECT ... FOR UPDATE` inside the BEFORE transaction. Never decrements. Numbers are non-returnable even on submission failure. Key columns: `org_id UUID NOT NULL`, `issuer_oib VARCHAR(13) NOT NULL`, `fiscal_year SMALLINT NOT NULL`, `last_number INTEGER NOT NULL DEFAULT 0`. Constraint: `UNIQUE (org_id, issuer_oib, fiscal_year)`. Year rollover: automatic on UPSERT. #### V77 — hr\_einvoice\_submissions The submission lifecycle table. One row per invoice (`UNIQUE invoice_id`). Created at number-reservation time. Updated through polling until terminal. Key columns: `org_id UUID NOT NULL`, `invoice_id UUID NOT NULL` (FK invoices.id ON DELETE RESTRICT), `fiscal_invoice_number VARCHAR(20) NOT NULL` (format `YYYY-NNNNNN`), `idempotency_key VARCHAR(64) NOT NULL`, `sveracun_document_id VARCHAR(255) NULL`, `internal_status VARCHAR(30) NOT NULL DEFAULT 'NUMBER_RESERVED'`, `xml_sha256_hex CHAR(64) NOT NULL`, `submitted_xml_gcs_path VARCHAR(1024) NOT NULL`, `submitted_by UUID NOT NULL`. **Critical constraints:** - `CONSTRAINT uq_hr_einvoice_submissions_invoice UNIQUE (invoice_id)` — THE load-bearing constraint; prevents double fiscalization at the DB layer - `CONSTRAINT uq_hr_einvoice_submissions_idempotency UNIQUE (idempotency_key)` - `CONSTRAINT uq_hr_einvoice_submissions_fiscal_number_org UNIQUE (org_id, fiscal_invoice_number)` - `CONSTRAINT chk_hr_einvoice_internal_status CHECK (internal_status IN ('NUMBER_RESERVED','SUBMITTED','SUBMIT_UNCERTAIN','PENDING','ACCEPTED','REJECTED'))` #### V78 — hr\_einvoice\_archive Integrity manifest for 11-year UBL XML archival. Append-only. `bilko_app` role has INSERT-only grant (no UPDATE). All FKs are ON DELETE RESTRICT. Key columns: `submission_id UUID NOT NULL` (FK, UNIQUE — one archive row per submission), `gcs_bucket VARCHAR(255)`, `gcs_object_path VARCHAR(1024)`, `sha256_hex CHAR(64) NOT NULL`, `retain_until DATE GENERATED ALWAYS AS ((archived_at AT TIME ZONE 'UTC')::DATE + INTERVAL '11 years') STORED`. Archive is written AFTER `ACCEPTED` state is confirmed (internal=OK + external=FISCALIZATION:OK). The submitted XML written to GCS at `NUMBER_RESERVED` is the same bytes; the archive row formalizes it as the compliance record. **RLS on all four tables:** Standard Bilko pattern from V46/V55. `USING (org_id = NULLIF(current_setting('app.current_org_id', true), '')::UUID)`. FORCE ROW LEVEL SECURITY on all tables. Phase 2C RESTRICTIVE mode activation is a prod prerequisite. ### 3.5 GCS Archival Bucket: `bilko-hr-einvoice-archive-{env}` (e.g. `bilko-hr-einvoice-archive-demo`). Object path: `{org_id}/{fiscal_year}/{fiscal_invoice_number}/{submission_id}.xml`. Write timing: at `NUMBER_RESERVED`, before HTTP call. Same bytes sent to sveRačun. Write-once enforcement: Cloud Run SA has `storage.objects.create` only; `storage.objects.delete` denied. Prod bucket: retention policy `4015 days` LOCKED (WORM). Demo bucket: same write-once pattern; retention 90 days (not locked). Integrity verification on every retrieval via `/invoices/{id}/sveracun-xml`: fetch `sha256_hex`, download GCS bytes, recompute SHA-256, assert equals. If mismatch: HTTP 500 `ARCHIVE_INTEGRITY_FAILURE`, alert, do not serve bytes. ### 3.6 Audit Trail Every submit, poll, and OIB-binding-violation event writes to `LoggedAction` (existing append-only table). Log structural/operational metadata only — do NOT log invoice line items, buyer/seller names, amounts, tax IDs, IBAN, API key value, or raw XML body (GDPR + Croatian tax secrecy). --- ## 4. Demo vs Production Boundary **"No hacks"** means the demo is built on the real schema, real idempotency, real OIB binding invariant, and real state machine — with one issuer instead of many. The demo is not a prototype. It is the production system at scale=1.
CapabilityDemo (build now)Prod (parked / future)
IssuerProfile abstractionYES — one ALAI/DIRECT profile in DBSame table; N tenant rows; INTERMEDIARY mode
Schema V75-V78YES — full schema from day oneSame migrations; no change
OIB binding invariantYES — enforced at service layerSame code; more profiles
UNIQUE(invoice\_id) on submissionsYES — in V77 before any submit codeSame constraint
Retry-fix on send pathYES — sendClient (no retry)Same fix
Persist-before/after protocolYES — full protocolSame protocol
SUBMIT\_UNCERTAIN stateYES — must be representableSame state
GCS write at NUMBER\_RESERVEDYES — write-once, SHA-256Same; LOCKED retention policy added
Gapless numbering (FOR UPDATE)YES — counter table V76Same; per-tenant issuer\_oib separates sequences
HR einvoice archive row (V78)YES — written on ACCEPTEDSame; 11-year LOCKED policy for prod
sveRačun base URLTEST (test.sveracun.hr)PROD (hr.sveracun.hr)
SVERACUN\_HR\_LIVE gateExplicit flip required (default false)PROD env flag; separate secret
IssuerProfile.enabled gateExplicit DB update requiredSame; per-tenant enable flow
Background poll workerManual: POST /invoices/{id}/poll-sveracun-statusScheduled job (Cloud Run Job or scheduler)
GCS retention policy90 days (demo bucket; not locked)4015 days LOCKED (WORM)
RLS modePERMISSIVE (current ADR-017 state)RESTRICTIVE (Phase 2C; Securion gate)
PostLink posrednik contract (B2)Not required; DIRECT modeRequired before multi-tenant; legal track
ALAI Norwegian entity HR OIB (B1)Not required; using existing TEST credsLegal confirmation required
Credit note (InvoiceTypeCode 381)Not built; domain model records the typeMust be built for full B2B accounting
Rate limiting (durable)In-memory sliding window; 10/min, 100/day per orgRedis-backed (Cloud Memorystore)
### Items NOT Deferred (frequently deferred in prototype builds; not here) 1. Flyway migrations V75-V78 — schema before any submit code 2. The `UNIQUE (invoice_id)` constraint — non-negotiable from the first migration 3. The retry fix on `sendDocument()` — before any live call, including TEST 4. The OIB binding invariant — runtime enforcement, not just a comment 5. The GCS write at NUMBER\_RESERVED — even for demo; write-once pattern identical to prod 6. The `SUBMIT_UNCERTAIN` state — sveRačun TEST is not perfectly reliable 7. `LoggedAction` audit write per submit --- ## 5. Phased Build Plan (7 Work Packages) ### WP1 — Foundation: Schema + Retry Fix + OIB Binding + IssuerProfile **Owner:** CodeCraft (backend) | **Depends on:** None Must land atomically — all in the same PR, before any route code. 1. Flyway migrations V75, V76, V77, V78 — all four tables with constraints, indexes, RLS, grants 2. `SveRacunHttpClient`: split into `sendClient` (maxRetries=0) + `pollClient` (maxRetries=3). Existing 42 tests remain green; add test asserting no retry on `sendDocument()` for 5xx 3. `IssuerProfile` data class + `SubmissionMode` enum 4. `IssuerProfileRepository` interface + `DbIssuerProfileRepository` 5. `SveRacunHrEInvoiceAdapter.serialize(invoice, senderOib: String)` — add `senderOib` param; remove `httpClient.configuredSenderVat` usage 6. `HrEInvoiceNumberService.reserveNextNumber(orgId, issuerOib, fiscalYear): String` — UPSERT + SELECT FOR UPDATE + increment 7. `OibBindingException` + `ConflictException` exception types **Acceptance criteria:** All 42 existing adapter tests pass. Flyway migrate runs clean V74→V78. New test: `sendDocument()` with 5xx does NOT retry (exactly one call). New test: concurrent `reserveNextNumber()` produces distinct sequential numbers. ### WP2 — Service + Persist Protocol: HrEInvoiceService **Owner:** CodeCraft (backend) | **Depends on:** WP1 1. `HrEInvoiceService.submitInvoice()` — full persist-before/after protocol, OIB binding invariant, status gate (409 if in flight), IssuerProfile lookup, GCS write, LoggedAction 2. `HrEInvoiceService.pollAndUpdateStatus()` — only if SUBMITTED/PENDING/SUBMIT\_UNCERTAIN; archive write on ACCEPTED 3. `HrEInvoiceService.getXmlForDownload()` — SHA-256 verification on every retrieval; 500 ARCHIVE\_INTEGRITY\_FAILURE on mismatch **Acceptance criteria:** BEFORE tx written before HTTP call. AFTER tx reflects correct state for each case. OIB binding test: mismatched org → 422 + LoggedAction. Concurrent submit → one succeeds, one gets 409. SHA-256 mismatch on download → 500. ### WP3 — Route: SveRacunRoutes **Owner:** CodeCraft (backend) | **Depends on:** WP2 1. All four route handlers (thin layer over service, mirrors SefRoutes.kt) 2. Rate limit middleware: 10 submit requests/org/minute, 100/org/day (in-memory ConcurrentHashMap sliding window) 3. Mount in Application.kt alongside `sefRoutes()` **Acceptance criteria:** Unauthenticated → 401. Insufficient role → 403. Wrong org → 404 (not 403; no existence leak). Already SUBMITTED → 409. SVERACUN\_HR\_LIVE=false → 501. Rate limit: 101st submit in same day → 429. ### WP4 — Infra: GCS Bucket + Secret Wiring **Owner:** FlowForge (infra) | **Depends on:** WP1 1. Terraform: `bilko-hr-einvoice-archive-demo` GCS bucket — versioning, write-once IAM, 90-day lifecycle 2. Verify `bilko-sveracun-test-api-key` exists and Cloud Run SA has `secretmanager.versions.access` 3. Secret rotation runbook documented in BookStack 4. Terraform: `bilko-hr-einvoice-archive-prod` bucket definition (commented out; LOCKED retention command documented but not executed) **Acceptance criteria:** `gcloud storage buckets describe bilko-hr-einvoice-archive-demo` shows versioning=enabled and no delete in bilko-api SA binding. CI integration test: `DbIssuerProfileRepository.findByOrgId(DEMO_ORG_ID)` resolves non-null API key. Terraform plan = zero diff after apply. ### WP5 — Dead Code Removal **Owner:** CodeCraft (backend) | **Depends on:** WP3 1. Delete `StorecoveHrFiskEInvoiceAdapter.kt` (652 lines, abandoned provider, confirmed CEO decision MC #8675) 2. Remove DI wiring, test references, import statements **Acceptance criteria:** `./gradlew build` passes with zero Storecove warnings. `grep -r "StorecoveHrFisk" apps/api/src` returns zero results. ### WP6 — Proveo E2E Validation **Owner:** Proveo (Angie Jones) | **Depends on:** WP3, WP4 1. Submit a real invoice through the route (SVERACUN\_HR\_LIVE=true, TEST env, IssuerProfile.enabled=true) 2. Assert HTTP 200 + non-null documentId received and persisted in DB 3. Assert GCS object exists and SHA-256(GCS bytes) == xml\_sha256\_hex from DB 4. Trigger poll; assert status transitions (PENDING → ACCEPTED on TEST env) 5. Verify status and XML download routes 6. Security checks: wrong orgId → 404; already SUBMITTED → 409; invalid OIB → 422; unauthenticated → 401 7. Rate limit: 101st submit → 429 8. Audit: LoggedAction row present with correct event, no PII in values 9. Verify zero retry attempts on sendDocument() via structured log count **Acceptance criteria (PASS/FAIL; no partial credit):** Real sveRačun TEST HTTP 200 + documentId. GCS object written and SHA-256 verified. All security checks return expected codes. No PII in LoggedAction. Zero retries on send. No StorecoveHrFisk references in deployed artifact. ### WP7 — BookStack Documentation **Owner:** Skillforge | **Depends on:** WP6 (Proveo validation passed) 1. This ADR page (published) 2. BookStack page: "HR eRačun — Prod Prerequisites Checklist" (Bilko book, Legal & Compliance chapter) — B1/B2 legal track, Phase 2C RLS activation gate, GCS LOCK command, PostLink posrednik contract steps, Securion gate checklist --- ## 6. Open Questions for PostLink (Zachariadis Carry-Forward) Must be answered before any production activation. Parked in the prod track.
\#Question
Q1**Posrednik / Intermediary Model:** Does sveRačun support an intermediary registration where a single API key holder (Bilko) is authorised to submit on behalf of multiple sender OIBs? If yes: is registration self-service via API or manual per-sender?
Q2**companyVatNumber Header Semantics:** The existing API separates Authorization (API key) from companyVatNumber (sender OIB). Is this header already the posrednik mechanism, or is etapa-1 currently hardcoded to reject unless the two match?
Q3**PROD API Credentials:** Rate limits on PROD vs TEST. Is the PROD auth scheme identical? Is there a staging environment with real OIBs but test FINA fiscalization path?
Q4**Fiscalization Identifier:** When FISCALIZATION:OK is returned, does the response body include a FINA fiscal identifier (ZKI/JIR equivalent)? Field name? Must Bilko store and display it?
Q5**REJECTION\_REPORT Payload:** What structured data is in FISCALIZATION\_REJECTION\_REPORT? Rejection reason code and free text?
Q6**Document Retrieval API:** Does sveRačun provide a GET /documents/{id}/download endpoint? Critical for SUBMIT\_UNCERTAIN reconciliation path.
Q7**List by Sender Reference:** Can Bilko query sveRačun for all documents submitted by sender OIB X in the last N hours? Required for SUBMIT\_UNCERTAIN reconciliation when no documentId was received.
Q8**Norwegian Entity Eligibility (B1):** Is ALAI Holding AS (Norwegian org.nr, holding HR OIB HR91276104352) eligible as a platform intermediary under PostLink's terms?
Q9**Pricing:** Per-document pricing for an intermediary platform account. Setup fee per registered sender OIB.
--- ## 7. Risk Register
RiskProbabilityImpactMitigation
Crash between HTTP 200 and AFTER tx (Kleppmann §5)Low (Cloud Run reliability)CRITICALClarify Q7 (list-by-reference API) with PostLink. Admin recovery endpoint in WP2 as fallback. Document the gap explicitly.
sveRačun TEST API unreliable during demoMediumHIGHSUBMIT\_UNCERTAIN state is representable; demo recovery endpoint allows operator to manually enter docId. Brief the demo presenter.
UNIQUE(invoice\_id) constraint blocks a legitimate re-send after REJECTEDLow (by design)LowService layer must support soft-delete of REJECTED row + insert of new row with new fiscal number + incremented attempt\_seq. Document the re-send flow.
GCS write fails between number allocation and HTTP callLowMEDIUMIf GCS write fails, rollback DB insert. Number is consumed (non-returnable per B5) but absence of submission row signals no send occurred.
Phase 2C RLS not activated before multi-tenant prodCertain (currently PERMISSIVE)CRITICAL for multi-tenantSecurion prod gate checklist (WP7 BookStack). Block prod activation on this item.
PostLink posrednik contract takes longer than expectedHigh (legal/commercial)HIGH for multi-tenant; LOW for demoDemo runs DIRECT mode; no contract required. Architecture does not change.
sveRačun PROD base URL differs in auth schemeUnknownMEDIUMQ3 to PostLink. The baseUrlOverride + apiKeyOverride parameters allow runtime configuration without code change.
Double-fiscal number if FOR UPDATE not atomic in pgBouncerMedium without careCRITICALUse hr\_einvoice\_number\_counters counter table with SELECT ... FOR UPDATE inside a transaction. pgBouncer transaction pooling mode is fine for FOR UPDATE (released at COMMIT).
Developer accidentally wires env-var path instead of IssuerProfileMediumHIGHThe serialize() signature change (WP1) removes httpClient.configuredSenderVat call; senderOib parameter is required (non-nullable). Caught at compile time.
--- ## 8. Parked Items (Separate Strategic Decision Required) - **B1:** Legal confirmation of ALAI Holding AS (Norwegian entity) as a valid HR OIB holder and eRačun issuer. Legal track; no code dependency. - **B2:** PostLink intermediary (posrednik) contract, power-of-attorney template for each tenant, per-sender OIB registration. Commercial track; IssuerProfile abstraction already built (WP1). - **InvoiceTypeCode 381 (credit note):** Zachariadis §4.2 is the authoritative spec. Separate MC. - **TaxExemptionReason BT-120:** Required for EN 16931 business rules BR-E-10 and BR-Z-10 (0%/exempt VAT). Post-demo. - **FISCALIZATION\_REJECTION\_REPORT workflow:** User-facing notification + credit note issuance path. Post-demo. - **NOT\_DELIVERED\_REPORT distinct state:** Fiscalized-but-not-delivered accounting problem. Post-demo. - **Background poll worker:** Cloud Run Job or Cloud Scheduler. Architecture designed for it (next\_poll\_at + partial index); not built in this sprint. - **Phase 2C RLS RESTRICTIVE mode:** Securion gate before any multi-tenant prod activation. Currently PERMISSIVE (ADR-017). - **Fiscal identifier storage (Q4):** If PostLink confirms ZKI/JIR equivalent on FISCALIZATION:OK, add fiscal\_identifier column in V79 migration. - **Redis-backed rate limiting:** In-memory acceptable for demo. Prod requires Cloud Memorystore (Redis) for durability across multiple Cloud Run instances. --- ## 9. Architectural Decisions Log (Conflict Resolutions) **State name: ACCEPTED vs APPROVED (Kleppmann vs Momjian).** Kleppmann uses ACCEPTED; Momjian uses APPROVED. Decision: DB column and CHECK constraint use ACCEPTED. EInvoiceStatus.APPROVED remains the adapter-interface value (matches existing interface); service translates to ACCEPTED when writing to DB. Rationale: ACCEPTED matches common EU e-invoicing terminology; APPROVED is the accounting approval concept (different thing). **Archive timing: at NUMBER\_RESERVED vs at ACCEPTED (Tabriz vs Momjian).** Tabriz: write XML to GCS inside BEFORE transaction. Momjian: archive only after ACCEPTED. Decision: write XML bytes to GCS at NUMBER\_RESERVED (Tabriz wins). Create hr\_einvoice\_archive integrity manifest row only at ACCEPTED (Momjian wins for the archive table write). Rationale: GCS object = bytes store (available from day one for recovery/audit); archive manifest = compliance record (formalized only when FISCALIZATION:OK confirmed). Both layers required. **SUBMIT\_UNCERTAIN: Kleppmann has it; Momjian's original CHECK constraint omits it.** Decision: ADD SUBMIT\_UNCERTAIN to V77 CHECK constraint. ADR replaces FAILED (Bilko-internal naming) with SUBMIT\_UNCERTAIN (semantically precise for sveRačun poll-only model) and ACCEPTED (aligned with adapter interface). Full CHECK list: NUMBER\_RESERVED, SUBMITTED, SUBMIT\_UNCERTAIN, PENDING, ACCEPTED, REJECTED. FAILED is retired. **IssuerProfile in DB vs config file (Zachariadis vs simplicity).** Zachariadis recommends DB-backed IssuerProfile for demo. Decision: DB-backed from day one (Momjian V75 table). Rationale: single-row demo config in DB is trivial; gives RLS and audit from the start; is the same code path as multi-tenant production. A config-file implementation would need to be ripped out and replaced. --- *Petter Graff — Lead Architect, HR eRačun Architecture Team, 2026-06-11* *Synthesized from inputs by Martin Kleppmann, Bruce Momjian, Markos Zachariadis, Parisa Tabriz.* *MC #103453 (architecture documentation) | MC #103464 (build execution)* # Backend # Backend — Target Architecture # Bilko API — Express Backend ## BookStack — Provjeri PRVO Prije traženja bilo čega — provjeri BookStack (http://localhost:6875). Centralna baza znanja za tools, skills, hooks, agents, rules, projekte, klijente, dokumentaciju. Ako odgovor postoji tamo — NE TRAŽI dalje. ## Status: NOT BUILT YET **This directory is EMPTY.** The CLAUDE.md describes the target architecture. When building, follow `docs/backend/API-REFERENCE.md` as the implementation contract. ## Target Tech Stack - **Framework:** Express + TypeScript - **Database:** PostgreSQL 15 via Prisma - **Auth:** JWT (15min access + 7d refresh) + Passport.js - **Validation:** Zod - **Middleware:** helmet, cors, rate-limit, auth-guard, zod-validation, error-handler ## Route Structure All routes under `/api/v1/{resource}`: - `/api/v1/auth` — login, register, refresh, logout - `/api/v1/organizations` — org CRUD - `/api/v1/users` — user management - `/api/v1/accounts` — chart of accounts - `/api/v1/invoices` — invoice CRUD - `/api/v1/expenses` — expense CRUD - `/api/v1/transactions` — transaction ledger - `/api/v1/contacts` — customer/vendor contacts - `/api/v1/banking` — bank account integration - `/api/v1/reports` — financial reports ## Middleware Stack (Order Matters) 1. **helmet** — Security headers 2. **cors** — CORS with whitelist 3. **express.json()** — Body parser 4. **rate-limit** — 100 req/15min per IP 5. **auth-guard** — JWT validation (protected routes) 6. **zod-validation** — Request validation 7. **route-handler** — Business logic 8. **error-handler** — Centralized error responses ## Error Response Format ```json { "error": "Error message", "code": "ERROR_CODE", "details": {} // optional } ``` **HTTP Status Codes:** - 400 — Validation error - 401 — Unauthorized (missing/invalid token) - 403 — Forbidden (insufficient permissions) - 404 — Not found - 500 — Internal server error ## Database Access - **ORM:** Prisma Client from `@bilko/database` package - **Connection:** Read `DATABASE_URL` from env - **Transactions:** Use Prisma transactions for multi-step operations - **NEVER:** Raw SQL for business logic (use for migrations only) ## Authentication - **Strategy:** JWT (access + refresh tokens) - **Access token:** 15min expiry, httpOnly cookie - **Refresh token:** 7d expiry, httpOnly cookie, stored in DB - **Password:** bcrypt hash with salt rounds = 12 - **2FA:** Optional TOTP (stored in User.twoFactorSecret) ## Validation Rules All requests validated with Zod schemas: - **Money:** Must be string or number, converted to Decimal - **Currency:** 3-letter ISO code (EUR, RSD, BAM, HRK) - **Dates:** ISO 8601 format (YYYY-MM-DD) - **UUIDs:** Valid v4 UUIDs for all IDs - **Emails:** RFC 5322 compliant ## Double-Entry Rules (CRITICAL) Every financial transaction MUST: 1. Have both debit and credit accounts 2. Equal amounts (debit = credit) 3. Reference the source (invoice ID, expense ID) 4. Lock exchange rate at transaction date 5. Create audit log entry (LoggedAction) ## Development Rules 1. **NEVER hold money** — This is an accounting tool, not a payment processor 2. **Immutable transactions** — Once locked, NEVER modify 3. **Audit everything** — All mutations logged to LoggedAction 4. **Multi-currency always** — Even single-currency orgs need exchange rate support 5. **Test with real accounting scenarios** — Invoice → payment → reconciliation ## API Reference Full endpoint documentation in `docs/backend/API-REFERENCE.md` (to be created). This file will be the contract for implementation. # Database — Schema & Models # Bilko Database — Prisma + PostgreSQL ## BookStack — Provjeri PRVO Prije traženja bilo čega — provjeri BookStack (http://localhost:6875). Centralna baza znanja za tools, skills, hooks, agents, rules, projekte, klijente, dokumentaciju. Ako odgovor postoji tamo — NE TRAŽI dalje. ## Schema Location `prisma/schema.prisma` — 15 models, fully defined ## Database Models (15) **Core:** - Organization — Multi-tenant root (baseCurrency, country, language) - User — RBAC (owner, admin, accountant, viewer) **Chart of Accounts:** - AccountType — Asset, Liability, Equity, Revenue, Expense - Account — Hierarchical CoA with parent-child relations **Contacts:** - Contact — Customers, vendors, or both (type enum) **Invoicing:** - Invoice — Sales invoices with multi-currency support - InvoiceItem — Line items with tax rates **Expenses:** - Expense — Purchase tracking with approval workflow **Transactions:** - Transaction — Double-entry ledger (debit + credit accounts) **Banking:** - BankAccount — Bank account metadata - BankTransaction — Bank statement imports for reconciliation **Multi-Currency:** - Currency — Currency definitions (EUR, RSD, BAM, HRK, etc.) - ExchangeRate — Historical exchange rates by date **Audit:** - LoggedAction — Immutable audit trail (APPEND-ONLY) - SchemaVersion — Migration tracking ## Key Design Decisions ### 1. NUMERIC(19,4) for Money **NEVER use float or JavaScript number for currency.** - Prisma type: `Decimal` (maps to PostgreSQL NUMERIC) - Precision: 19 digits total, 4 decimal places - Range: -999,999,999,999,999.9999 to +999,999,999,999,999.9999 ### 2. Double-Entry Bookkeeping Every financial event creates a `Transaction` with: - `debitAccountId` — Account to debit - `creditAccountId` — Account to credit - `amount` — MUST be equal for both sides - Balance = sum(debits) - sum(credits) per account ### 3. Multi-Currency with Rate Locking - `Invoice.exchangeRate` — Locked at invoice date - `Transaction.exchangeRate` — Locked at transaction date - `baseAmount` — Amount converted to org's baseCurrency - **NEVER recalculate** historical transactions with current rates ### 4. Immutable Audit Trail `LoggedAction` table: - **APPEND-ONLY** — NEVER delete or update - Captures: table name, user ID, action (INSERT/UPDATE/DELETE), old/new values - Used for: compliance, debugging, rollback simulation ### 5. Transaction Locking - `Transaction.locked` — Once true, record is immutable - Locked transactions cannot be edited or deleted - Used for: end-of-period close, tax reporting ### 6. Organization-Scoped Multi-Tenancy - Every record has `organizationId` foreign key - Queries MUST filter by org (enforced in API middleware) - No cross-org data access ### 7. UUID Primary Keys - All IDs: `uuid_generate_v4()` (PostgreSQL function) - NEVER use auto-increment for business data - Portable across systems, no collisions ## Migration Rules 1. **Never edit existing migrations** — Always create new ones 2. **Test migrations on copy** — Never run on production first 3. **Backward compatible** — Additive changes only 4. **Data migrations separate** — Use Prisma seed or custom scripts 5. **Rollback plan** — Document how to undo breaking changes ## Naming Conventions - **DB columns:** snake_case (via `@map`) - **Prisma fields:** camelCase - **Indexes:** `idx_{table}_{column(s)}` - **Foreign keys:** Auto-generated by Prisma ## Indexes Defined for: - All foreign keys (automatic) - Common query patterns (org + date, org + status) - Unique constraints (org + code, org + invoice number) ## Enums - UserRole: owner, admin, accountant, viewer - NormalBalance: debit, credit - ContactType: customer, vendor, both - InvoiceStatus: draft, sent, viewed, paid, overdue, cancelled - ExpenseStatus: pending, approved, paid, rejected - AuditAction: INSERT, UPDATE, DELETE ## Development Commands ```bash # Generate Prisma Client npx prisma generate # Create migration npx prisma migrate dev --name migration_name # Apply migrations (production) npx prisma migrate deploy # Reset database (dev only) npx prisma migrate reset # Open Prisma Studio npx prisma studio ``` ## Critical Rules 1. **NUMERIC for money** — NEVER float 2. **Double-entry enforced** — Every transaction has debit + credit 3. **Exchange rates locked** — At transaction date, NEVER recalculate 4. **Audit is append-only** — NEVER delete LoggedAction records 5. **UUID everywhere** — NEVER expose auto-increment IDs # API Reference # Bilko API Reference > **Status:** SPECIFICATION (backend not implemented) > **Base URL:** `http://localhost:4000/api/v1` (development) > **Production URL:** `https://api.bilko.io/api/v1` > **Last updated:** 2026-02-20 --- ## Purpose This document is the implementation contract for Bilko's backend. All ~35 endpoints are specified with: - HTTP method + path - Authentication requirements - Request/response TypeScript interfaces - Query parameters - Error responses - Example requests/responses **CRITICAL:** Backend is NOT BUILT. This is the spec that apps/api/ MUST implement. --- ## Table of Contents 1. [Authentication](#authentication) (5 endpoints) 2. [Organization](#organization) (2 endpoints) 3. [Users](#users) (4 endpoints) 4. [Contacts](#contacts) (5 endpoints) 5. [Invoices](#invoices) (8 endpoints) 6. [Expenses](#expenses) (6 endpoints) 7. [Bank Accounts](#bank-accounts) (4 endpoints) 8. [Reports](#reports) (7 endpoints) 9. [Chart of Accounts](#chart-of-accounts) (3 endpoints) 10. [Transactions](#transactions) (2 endpoints) 11. [Settings](#settings) (2 endpoints) 12. [Currencies](#currencies) (2 endpoints) **Total:** 50 endpoints --- ## API Architecture Overview ```mermaid graph LR subgraph CLIENT [Client] FE[Next.js Frontend\nbilko.io:3000] end subgraph API [Express API — api.bilko.io:4000] AUTH_R[/auth/*\nPublic] ORG_R[/organization\nAll roles] USR_R[/users/*\nowner, admin] CON_R[/contacts/*\nAll roles] INV_R[/invoices/*\nAll roles] EXP_R[/expenses/*\nAll roles] BANK_R[/bank-accounts/*\nAll roles] RPT_R[/reports/*\nAll roles] ACC_R[/accounts/*\nAll roles] TXN_R[/transactions/*\nAll roles] SET_R[/settings/*\nowner, admin] CUR_R[/currencies\nAll roles] end FE -->|Bearer token\nin Authorization header| API FE -->|refreshToken\nhttpOnly cookie| AUTH_R style AUTH_R fill:#e2e8f0,color:#000 style FE fill:#00E5A0,color:#000 ``` --- ## Global Response Patterns ### Pagination All list endpoints support pagination: ```typescript interface PaginatedResponse { data: T[] meta: { total: number // Total records page: number // Current page (1-indexed) perPage: number // Records per page totalPages: number // Total pages } } ``` **Query parameters:** - `page` (default: 1) - `perPage` (default: 20, max: 100) - `sort` (field name, default varies by endpoint) - `order` (`asc` or `desc`, default: `desc`) ### Error Responses ```typescript interface ApiError { error: string // Human-readable error message code: string // Machine-readable error code details?: Record // Field-level validation errors } ``` **HTTP Status Codes:** - `400 Bad Request` — Invalid request body/params - `401 Unauthorized` — Missing or invalid auth token - `403 Forbidden` — User lacks required role - `404 Not Found` — Resource does not exist - `422 Unprocessable Entity` — Validation failed - `500 Internal Server Error` — Server error --- ## 1. Authentication ### POST /api/v1/auth/register Create new organization and owner user. **Auth:** None **Rate limit:** 5 req/min **Request:** ```typescript interface RegisterRequest { // Organization organizationName: string country: 'RS' | 'BA' | 'HR' // Serbia, BiH, Croatia baseCurrency: 'EUR' | 'RSD' | 'BAM' | 'HRK' language: 'sr' | 'bs' | 'hr' registrationNumber?: string // Company tax ID vatNumber?: string // User email: string // Must be unique password: string // Min 8 chars, 1 upper, 1 lower, 1 number fullName: string } ``` **Response (201):** ```typescript interface RegisterResponse { user: { id: string email: string fullName: string role: 'owner' } organization: { id: string name: string country: string baseCurrency: string } tokens: { accessToken: string // JWT, expires in 15 min refreshToken: string // Expires in 7 days } } ``` **Errors:** - `400` — Email already exists - `422` — Validation failed (weak password, invalid country, etc.) --- ### POST /api/v1/auth/login Authenticate with email + password. **Auth:** None **Rate limit:** 5 req/min **Request:** ```typescript interface LoginRequest { email: string password: string rememberMe?: boolean // If true, refreshToken expires in 30 days } ``` **Response (200):** ```typescript interface LoginResponse { user: { id: string email: string fullName: string role: 'owner' | 'admin' | 'accountant' | 'viewer' organizationId: string organizationName: string } tokens: { accessToken: string // JWT, expires in 15 min refreshToken: string // httpOnly cookie } } ``` **Errors:** - `401` — Invalid credentials - `403` — Account disabled or requires 2FA --- ### POST /api/v1/auth/refresh Get new access token using refresh token. **Auth:** Refresh token (httpOnly cookie) **Rate limit:** 100 req/min **Request:** None (uses cookie) **Response (200):** ```typescript interface RefreshResponse { accessToken: string } ``` **Errors:** - `401` — Invalid or expired refresh token --- ### POST /api/v1/auth/logout Invalidate refresh token. **Auth:** Bearer token **Rate limit:** 100 req/min **Request:** None **Response (204):** No content --- ### GET /api/v1/auth/me Get current user info. **Auth:** Bearer token **Rate limit:** 100 req/min **Response (200):** ```typescript interface CurrentUser { id: string email: string fullName: string role: 'owner' | 'admin' | 'accountant' | 'viewer' twoFactorEnabled: boolean lastLoginAt: string | null organization: { id: string name: string country: string baseCurrency: string language: string } } ``` --- ## 2. Organization ### GET /api/v1/organization Get organization details. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Response (200):** ```typescript interface Organization { id: string name: string registrationNumber: string | null vatNumber: string | null baseCurrency: string country: string language: string fiscalYearStart: string // ISO date, e.g., "2026-01-01" createdAt: string updatedAt: string } ``` --- ### PUT /api/v1/organization Update organization details. **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 10 req/min **Request:** ```typescript interface UpdateOrganizationRequest { name?: string registrationNumber?: string vatNumber?: string baseCurrency?: 'EUR' | 'RSD' | 'BAM' | 'HRK' language?: 'sr' | 'bs' | 'hr' fiscalYearStart?: string // ISO date } ``` **Response (200):** Organization object (same as GET) **Errors:** - `422` — Validation failed (invalid currency code, etc.) --- ## 3. Users ### GET /api/v1/users List all users in organization. **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 100 req/min **Query:** - `role` (filter by role) **Response (200):** ```typescript interface UserListResponse { data: Array<{ id: string email: string fullName: string role: 'owner' | 'admin' | 'accountant' | 'viewer' twoFactorEnabled: boolean lastLoginAt: string | null createdAt: string }> } ``` --- ### POST /api/v1/users/invite Invite new user to organization. **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 10 req/min **Request:** ```typescript interface InviteUserRequest { email: string fullName: string role: 'admin' | 'accountant' | 'viewer' // Cannot create 'owner' } ``` **Response (201):** ```typescript interface InviteUserResponse { user: { id: string email: string fullName: string role: string } inviteLink: string // One-time setup link, expires in 7 days } ``` **Errors:** - `400` — Email already exists in organization - `422` — Invalid role --- ### PUT /api/v1/users/:id/role Change user role. **Auth:** Bearer token **Roles:** owner **Rate limit:** 10 req/min **Request:** ```typescript interface ChangeRoleRequest { role: 'admin' | 'accountant' | 'viewer' } ``` **Response (200):** User object **Errors:** - `403` — Cannot change owner role or demote yourself - `404` — User not found --- ### DELETE /api/v1/users/:id Remove user from organization. **Auth:** Bearer token **Roles:** owner **Rate limit:** 10 req/min **Response (204):** No content **Errors:** - `403` — Cannot delete owner or yourself - `404` — User not found --- ## 4. Contacts ### GET /api/v1/contacts List contacts (customers/vendors). **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Query:** - `type` (`customer`, `vendor`, `both`) - `page`, `perPage`, `sort`, `order` **Response (200):** ```typescript type ContactListResponse = PaginatedResponse interface Contact { id: string type: 'customer' | 'vendor' | 'both' name: string email: string | null phone: string | null registrationNumber: string | null vatNumber: string | null addressLine1: string | null addressLine2: string | null city: string | null postalCode: string | null country: string | null currencyCode: string paymentTerms: number // Days isActive: boolean createdAt: string updatedAt: string } ``` --- ### POST /api/v1/contacts Create new contact. **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 50 req/min **Request:** ```typescript interface CreateContactRequest { type: 'customer' | 'vendor' | 'both' name: string email?: string phone?: string registrationNumber?: string vatNumber?: string addressLine1?: string addressLine2?: string city?: string postalCode?: string country?: string // ISO 3166-1 alpha-2 (e.g., 'RS') currencyCode?: string // ISO 4217 (default: org baseCurrency) paymentTerms?: number // Default: 30 days notes?: string } ``` **Response (201):** Contact object **Errors:** - `422` — Validation failed (invalid country code, currency code, etc.) --- ### GET /api/v1/contacts/:id Get contact details. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Response (200):** Contact object + notes field --- ### PUT /api/v1/contacts/:id Update contact. **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 50 req/min **Request:** Same as CreateContactRequest (all fields optional) **Response (200):** Contact object --- ### DELETE /api/v1/contacts/:id Soft-delete contact (sets isActive = false). **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 10 req/min **Response (204):** No content **Errors:** - `400` — Contact has active invoices or expenses --- ## 5. Invoices ### GET /api/v1/invoices List invoices. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Query:** - `status` (`draft`, `sent`, `viewed`, `paid`, `overdue`, `cancelled`) - `customerId` (UUID) - `fromDate`, `toDate` (ISO dates) - `page`, `perPage`, `sort`, `order` **Response (200):** ```typescript type InvoiceListResponse = PaginatedResponse interface InvoiceSummary { id: string invoiceNumber: string customerId: string customerName: string invoiceDate: string dueDate: string currencyCode: string totalAmount: string // Decimal as string, e.g., "125000.0000" status: 'draft' | 'sent' | 'viewed' | 'paid' | 'overdue' | 'cancelled' createdAt: string } ``` --- ### Invoice Creation — Full Sequence ```mermaid sequenceDiagram participant FE as Frontend participant MW as Middleware Stack\n(auth, roleGuard, validate) participant H as Invoice Handler participant DB as PostgreSQL\n(Prisma) participant EX as Exchange Rate\nService FE->>MW: POST /api/v1/invoices\nAuthorization: Bearer {accessToken} MW->>MW: authGuard: verify JWT\nAttach req.user {id, role, orgId} MW->>MW: roleGuard: check owner/admin/accountant MW->>MW: validate(createInvoiceSchema)\ncustomerId UUID, dates, items[] MW->>H: Validated request H->>DB: Find Contact by customerId\nwhere orgId matches DB-->>H: Contact { email, currencyCode } H->>EX: getExchangeRate(invoiceCurrency, orgBaseCurrency, invoiceDate) EX-->>H: rate (locked at invoiceDate — NEVER changes) H->>H: Calculate:\nlineTotal = qty × unitPrice\ntaxAmount = SUM(lineTotal × taxRate/100)\ntotalAmount = subtotal + taxAmount - discount\nbaseAmount = totalAmount × exchangeRate H->>DB: BEGIN TRANSACTION\nGenerate invoiceNumber INV-YYYY-NNN\nINSERT Invoice { status: draft }\nINSERT InvoiceItems[] DB-->>H: Invoice created H->>DB: INSERT LoggedAction\n{ action: INSERT, tableName: Invoice } DB-->>H: Logged H->>FE: 201 Created\n{ id, invoiceNumber, status: draft, items, totals } ``` ### POST /api/v1/invoices Create invoice. **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 50 req/min **Request:** ```typescript interface CreateInvoiceRequest { customerId: string invoiceDate: string // ISO date dueDate: string // ISO date currencyCode?: string // Default: customer's currency items: Array<{ description: string quantity: number // Decimal as number unitPrice: number // Decimal as number taxRate: number // Percentage, e.g., 20 for 20% accountId?: string // Revenue account }> notes?: string terms?: string } ``` **Response (201):** ```typescript interface Invoice { id: string invoiceNumber: string // Auto-generated customerId: string customerName: string invoiceDate: string dueDate: string currencyCode: string exchangeRate: string // Decimal as string subtotal: string taxAmount: string discountAmount: string totalAmount: string baseAmount: string // Converted to org baseCurrency status: 'draft' items: Array<{ id: string lineNumber: number description: string quantity: string unitPrice: string taxRate: string lineTotal: string accountId: string | null }> notes: string | null terms: string | null pdfUrl: string | null createdBy: string createdAt: string updatedAt: string } ``` **Errors:** - `404` — Customer not found - `422` — Validation failed (invalid date, negative amount, etc.) --- ### GET /api/v1/invoices/:id Get invoice details. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Response (200):** Invoice object (same as POST response) --- ### PUT /api/v1/invoices/:id Update invoice (draft only). **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 50 req/min **Request:** Same as CreateInvoiceRequest **Response (200):** Invoice object **Errors:** - `400` — Invoice is not in draft status --- ### Invoice Status Transition — Send Flow ```mermaid sequenceDiagram participant FE as Frontend participant API as Bilko API participant PDF as Puppeteer\nPDF Service participant R2 as Cloudflare R2 participant SG as SendGrid participant DB as PostgreSQL FE->>API: PATCH /invoices/:id/status\n{ action: "send" } API->>DB: Fetch Invoice with items, customer, org DB-->>API: Invoice (must be status=draft) API->>PDF: generateInvoicePDF(invoice data) PDF-->>API: PDF Buffer API->>R2: PUT invoices/{orgId}/INV-2026-001.pdf R2-->>API: pdfUrl stored API->>DB: BEGIN TRANSACTION API->>DB: INSERT Transaction {\n DR: Accounts Receivable (1200)\n CR: Revenue (4000)\n amount: invoice.totalAmount\n referenceType: 'invoice'\n} API->>DB: UPDATE Invoice SET\n status='sent', sentAt=now()\n pdfUrl=url API->>SG: sendEmail({\n to: customer.email,\n subject: "Invoice INV-2026-001 from Org",\n html: template,\n attachment: pdf\n}) SG-->>API: { messageId } DB-->>API: COMMIT API->>FE: 200 { status: sent, sentAt, pdfUrl } Note over API: If SendGrid fails:\nKeep invoice as draft\nAdd note: "Email delivery failed"\nAlert admin via Slack ``` ### PATCH /api/v1/invoices/:id/status Change invoice status. **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 50 req/min **Request:** ```typescript interface ChangeInvoiceStatusRequest { action: 'send' | 'mark-paid' | 'cancel' paidAt?: string // Required if action = 'mark-paid' } ``` **Response (200):** Invoice object **Business logic:** - `send`: draft → sent (generates PDF, sends email via SendGrid) - `mark-paid`: sent/viewed → paid (creates Transaction: debit BankAccount, credit AccountsReceivable) - `cancel`: any → cancelled (reverses Transaction if paid) **Errors:** - `400` — Invalid status transition --- ### GET /api/v1/invoices/:id/pdf Get invoice PDF. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Response (200):** - Content-Type: application/pdf - Content-Disposition: attachment; filename="INV-2026-001.pdf" **Errors:** - `404` — Invoice or PDF not found --- ### POST /api/v1/invoices/:id/send Send invoice email to customer. **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 10 req/min **Request:** ```typescript interface SendInvoiceRequest { to?: string // Override customer email cc?: string[] subject?: string // Override default subject message?: string // Custom message } ``` **Response (200):** ```typescript interface SendInvoiceResponse { sentAt: string sentTo: string emailId: string // SendGrid message ID } ``` **Errors:** - `400` — Customer has no email - `500` — SendGrid error --- ## 6. Expenses ### GET /api/v1/expenses List expenses. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Query:** - `status` (`pending`, `approved`, `paid`, `rejected`) - `category` - `vendorId` - `fromDate`, `toDate` - `page`, `perPage`, `sort`, `order` **Response (200):** ```typescript type ExpenseListResponse = PaginatedResponse interface ExpenseSummary { id: string expenseNumber: string vendorId: string | null vendorName: string | null expenseDate: string category: string amount: string currencyCode: string status: 'pending' | 'approved' | 'paid' | 'rejected' receiptUrl: string | null createdAt: string } ``` --- ### POST /api/v1/expenses Create expense. **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 50 req/min **Request:** ```typescript interface CreateExpenseRequest { vendorId?: string expenseDate: string category: string // Free text or predefined categories amount: number currencyCode?: string // Default: org baseCurrency taxAmount?: number paymentMethod?: string // 'cash', 'card', 'bank_transfer', etc. accountId?: string // Expense account description?: string receiptFile?: File // Multipart form upload (max 10MB) } ``` **Response (201):** ```typescript interface Expense { id: string expenseNumber: string // Auto-generated vendorId: string | null vendorName: string | null expenseDate: string category: string currencyCode: string exchangeRate: string amount: string baseAmount: string taxAmount: string paymentMethod: string | null accountId: string | null description: string | null receiptUrl: string | null // Cloudflare R2 URL status: 'pending' createdBy: string createdAt: string updatedAt: string } ``` **Errors:** - `422` — Validation failed (negative amount, invalid date, etc.) - `413` — File too large --- ### GET /api/v1/expenses/:id Get expense details. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Response (200):** Expense object --- ### PUT /api/v1/expenses/:id Update expense (pending only). **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 50 req/min **Request:** Same as CreateExpenseRequest **Response (200):** Expense object **Errors:** - `400` — Expense is not pending --- ### Expense Approval — Full Sequence ```mermaid sequenceDiagram participant FE as Frontend\n(admin/owner) participant MW as Middleware Stack participant H as Expense Handler participant DB as PostgreSQL FE->>MW: PATCH /api/v1/expenses/:id/approve\nAuthorization: Bearer {accessToken} MW->>MW: authGuard: verify JWT MW->>MW: roleGuard: owner or admin ONLY\n(accountant CANNOT approve) MW->>H: Request passes H->>DB: Find Expense by id\nwhere organizationId = req.orgId DB-->>H: Expense { status: pending, amount, accountId } H->>H: Validate: status must be 'pending'\nIf not → 400 Bad Request H->>DB: BEGIN TRANSACTION H->>DB: Find ExpenseAccount\n(expense.accountId or default 5xxx) H->>DB: Find AccountsPayable account\n(2110 or configured account) H->>DB: INSERT Transaction {\n debitAccountId: expenseAccountId,\n creditAccountId: accountsPayableId,\n amount: expense.amount,\n referenceType: 'expense',\n referenceId: expense.id\n} H->>DB: UPDATE Expense SET\n status='approved',\n approvedBy=req.user.id,\n approvedAt=now() H->>DB: INSERT LoggedAction DB-->>H: COMMIT H->>FE: 200 OK\n{ id, status: approved, approvedBy, approvedAt } ``` ### PATCH /api/v1/expenses/:id/approve Approve expense. **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 50 req/min **Response (200):** Expense object (status = approved) **Business logic:** - Creates Transaction: debit ExpenseAccount, credit AccountsPayable **Errors:** - `400` — Expense already approved/paid/rejected --- ### DELETE /api/v1/expenses/:id Delete expense (pending only). **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 10 req/min **Response (204):** No content **Errors:** - `400` — Expense is not pending --- ## 7. Bank Accounts ### GET /api/v1/bank-accounts List bank accounts. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Response (200):** ```typescript interface BankAccountListResponse { data: Array<{ id: string accountId: string // GL account ID accountCode: string // GL account code bankName: string accountNumber: string | null iban: string | null currencyCode: string currentBalance: string isActive: boolean createdAt: string updatedAt: string }> } ``` --- ### POST /api/v1/bank-accounts Create bank account. **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 10 req/min **Request:** ```typescript interface CreateBankAccountRequest { accountId: string // Must be Asset account bankName: string accountNumber?: string iban?: string currencyCode: string currentBalance?: number // Default: 0 } ``` **Response (201):** BankAccount object **Errors:** - `404` — Account not found - `422` — Account is not Asset type --- ### GET /api/v1/bank-accounts/:id/transactions Get bank transactions. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Query:** - `fromDate`, `toDate` - `reconciled` (true/false) - `page`, `perPage`, `sort`, `order` **Response (200):** ```typescript type BankTransactionListResponse = PaginatedResponse interface BankTransaction { id: string transactionDate: string amount: string // Positive = credit, negative = debit description: string | null reference: string | null reconciled: boolean matchedTransactionId: string | null createdAt: string } ``` --- ### POST /api/v1/bank-accounts/:id/import Import bank statement (CSV). **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 10 req/min **Request:** - Multipart form: `file` (CSV, max 5MB) **CSV format:** ```csv Date,Description,Amount,Reference 2026-02-19,"Payment from customer",3500.00,INV-2026-002 2026-02-18,"AWS Invoice",-850.00, ``` **Response (200):** ```typescript interface ImportStatementResponse { imported: number duplicates: number errors: Array<{ line: number error: string }> } ``` **Errors:** - `422` — Invalid CSV format - `413` — File too large --- ### Bank Reconciliation — Full Sequence ```mermaid sequenceDiagram participant FE as Frontend participant API as Bilko API participant DB as PostgreSQL Note over FE,DB: Step 1 — Import Bank Statement FE->>API: POST /bank-accounts/:id/import\n[multipart: CSV file, max 5MB] API->>API: Parse CSV\nDate, Description, Amount, Reference API->>DB: INSERT BankTransaction[] records\n{ bankAccountId, transactionDate, amount, reference } DB-->>API: Imported count API->>FE: 200 { imported: 45, duplicates: 2, errors: [] } Note over FE,DB: Step 2 — Auto-Match Suggestions FE->>API: GET /bank-accounts/:id/transactions?reconciled=false API->>DB: Fetch unreconciled BankTransactions DB-->>API: BankTransaction[] API->>DB: Fetch unreconciled GL Transactions\nfor same date range DB-->>API: Transaction[] API->>API: calculateMatchScore() for each pair\nAmount match +50\nDate match +30/+20/+10\nReference match +20 API->>FE: 200 { bankTransactions, suggestions[{ bankTxId, glTxId, score }] } Note over FE,DB: Step 3 — Confirm Reconciliation FE->>API: POST /bank-accounts/:id/reconcile\n{ bankTransactionId, transactionId } API->>DB: Find both records, verify same org API->>DB: UPDATE BankTransaction SET\n reconciled=true\n matchedTransactionId=glTxId API->>DB: UPDATE Transaction SET\n reconciled=true\n reconciledAt=now() DB-->>API: Both updated API->>FE: 200 { bankTransaction, transaction, confidence: 95 } ``` ### POST /api/v1/bank-accounts/:id/reconcile Reconcile bank transactions with GL transactions. **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 10 req/min **Request:** ```typescript interface ReconcileRequest { bankTransactionId: string transactionId: string // GL transaction ID } ``` **Response (200):** ```typescript interface ReconcileResponse { bankTransaction: BankTransaction transaction: Transaction confidence: number // 0-100 match score } ``` **Errors:** - `404` — Bank transaction or GL transaction not found - `400` — Already reconciled --- ## 8. Reports ### GET /api/v1/reports/dashboard Get dashboard metrics. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Response (200):** ```typescript interface DashboardMetrics { cashBalance: string // Total across all bank accounts (in baseCurrency) revenueMTD: string // Month-to-date revenue unpaidInvoices: string // Total unpaid invoices expensesMTD: string // Month-to-date expenses profitMTD: string // revenueMTD - expensesMTD cashFlowChange: number // Percentage change from last month // Chart data monthlyPL: Array<{ month: string revenue: string expenses: string profit: string }> receivablesAging: { current: string // 0-30 days days30: string // 31-60 days days60: string // 61-90 days days90plus: string // 90+ days } expensesByCategory: Array<{ category: string amount: string currencyCode: string }> } ``` --- ### GET /api/v1/reports/profit-loss Profit & Loss statement. **Auth:** Bearer token **Roles:** All **Rate limit:** 50 req/min **Query:** - `from` (ISO date, required) - `to` (ISO date, required) **Response (200):** ```typescript interface ProfitLossReport { period: { from: string to: string } baseCurrency: string revenue: { total: string accounts: Array<{ accountCode: string accountName: string amount: string }> } expenses: { total: string accounts: Array<{ accountCode: string accountName: string amount: string }> } netProfit: string // revenue.total - expenses.total } ``` --- ### GET /api/v1/reports/balance-sheet Balance Sheet. **Auth:** Bearer token **Roles:** All **Rate limit:** 50 req/min **Query:** - `date` (ISO date, default: today) **Response (200):** ```typescript interface BalanceSheetReport { asOfDate: string baseCurrency: string assets: { total: string current: { total: string accounts: Array } fixed: { total: string accounts: Array } } liabilities: { total: string current: { total: string accounts: Array } longTerm: { total: string accounts: Array } } equity: { total: string accounts: Array } } interface AccountBalance { accountCode: string accountName: string balance: string } ``` --- ### GET /api/v1/reports/cash-flow Cash Flow statement. **Auth:** Bearer token **Roles:** All **Rate limit:** 50 req/min **Query:** - `from`, `to` (ISO dates, required) **Response (200):** ```typescript interface CashFlowReport { period: { from: string to: string } baseCurrency: string operating: { total: string items: Array<{ description: string amount: string }> } investing: { total: string items: Array<{ description: string amount: string }> } financing: { total: string items: Array<{ description: string amount: string }> } netCashFlow: string openingBalance: string closingBalance: string } ``` --- ### GET /api/v1/reports/vat VAT/PDV report. **Auth:** Bearer token **Roles:** All **Rate limit:** 50 req/min **Query:** - `from`, `to` (ISO dates, required) **Response (200):** ```typescript interface VATReport { period: { from: string to: string } country: string // Organization country outputVAT: { total: string invoices: Array<{ invoiceNumber: string customerName: string invoiceDate: string baseAmount: string vatAmount: string vatRate: string }> } inputVAT: { total: string expenses: Array<{ expenseNumber: string vendorName: string expenseDate: string baseAmount: string vatAmount: string vatRate: string }> } netVAT: string // outputVAT.total - inputVAT.total reconciliationStatus: { allInvoicesPaid: boolean allExpensesApproved: boolean unmatchedTransactions: number } } ``` --- ### GET /api/v1/reports/trial-balance Trial Balance. **Auth:** Bearer token **Roles:** All **Rate limit:** 50 req/min **Query:** - `date` (ISO date, default: today) **Response (200):** ```typescript interface TrialBalanceReport { asOfDate: string baseCurrency: string accounts: Array<{ accountCode: string accountName: string accountType: string debitTotal: string creditTotal: string balance: string }> totals: { debit: string credit: string } balanced: boolean // totals.debit === totals.credit } ``` --- ## 9. Chart of Accounts ### GET /api/v1/accounts List chart of accounts. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Query:** - `accountTypeId` (filter by type) - `isActive` (true/false) **Response (200):** ```typescript interface AccountListResponse { data: Array<{ id: string code: string // e.g., "1000", "4000" name: string // e.g., "Bank Account EUR", "Revenue" accountTypeId: number accountTypeName: string // Asset, Liability, Equity, Revenue, Expense normalBalance: 'debit' | 'credit' currencyCode: string parentAccountId: string | null parentAccountCode: string | null isActive: boolean currentBalance: string // Calculated from transactions createdAt: string updatedAt: string }> } ``` --- ### POST /api/v1/accounts Create account. **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 10 req/min **Request:** ```typescript interface CreateAccountRequest { code: string // Must be unique within organization name: string accountTypeId: number // 1-5 (Asset, Liability, Equity, Revenue, Expense) currencyCode?: string // Default: org baseCurrency parentAccountId?: string // For sub-accounts } ``` **Response (201):** Account object **Errors:** - `400` — Code already exists - `404` — Parent account not found - `422` — Invalid account type --- ### PUT /api/v1/accounts/:id Update account. **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 10 req/min **Request:** ```typescript interface UpdateAccountRequest { name?: string isActive?: boolean } ``` **Response (200):** Account object **Errors:** - `400` — Cannot deactivate account with transactions --- ## 10. Transactions ### GET /api/v1/transactions List general ledger transactions. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Query:** - `fromDate`, `toDate` - `accountId` (show transactions for specific account) - `referenceType` (`invoice`, `expense`, `payment`, `manual`) - `page`, `perPage`, `sort`, `order` **Response (200):** ```typescript type TransactionListResponse = PaginatedResponse interface Transaction { id: string transactionDate: string description: string debitAccountId: string debitAccountCode: string debitAccountName: string creditAccountId: string creditAccountCode: string creditAccountName: string amount: string currencyCode: string exchangeRate: string baseAmount: string referenceType: string | null referenceId: string | null locked: boolean reconciled: boolean createdBy: string createdAt: string } ``` --- ### POST /api/v1/transactions Create manual journal entry. **Auth:** Bearer token **Roles:** owner, admin, accountant **Rate limit:** 20 req/min **Request:** ```typescript interface CreateTransactionRequest { transactionDate: string description: string debitAccountId: string creditAccountId: string amount: number currencyCode?: string // Default: org baseCurrency notes?: string } ``` **Response (201):** Transaction object **Errors:** - `404` — Account not found - `422` — Validation failed (debit = credit account, negative amount, etc.) --- ## 11. Settings ### GET /api/v1/settings/tax-rates Get tax rate configuration. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Response (200):** ```typescript interface TaxRatesResponse { country: string defaultVATRate: number // e.g., 20 for Serbia, 17 for BiH rates: Array<{ name: string // "Standard", "Reduced", "Zero" rate: number description: string }> } ``` --- ### PUT /api/v1/settings/tax-rates Update tax rate configuration. **Auth:** Bearer token **Roles:** owner, admin **Rate limit:** 10 req/min **Request:** ```typescript interface UpdateTaxRatesRequest { defaultVATRate: number rates: Array<{ name: string rate: number description: string }> } ``` **Response (200):** TaxRatesResponse --- ## 12. Currencies ### GET /api/v1/currencies List supported currencies. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Response (200):** ```typescript interface CurrencyListResponse { data: Array<{ code: string // ISO 4217 name: string symbol: string | null decimalPlaces: number isActive: boolean }> } ``` --- ### GET /api/v1/exchange-rates Get exchange rates. **Auth:** Bearer token **Roles:** All **Rate limit:** 100 req/min **Query:** - `base` (currency code, required) - `target` (currency code, required) - `date` (ISO date, default: today) **Response (200):** ```typescript interface ExchangeRateResponse { baseCurrency: string targetCurrency: string rate: string // Decimal as string effectiveDate: string source: string // "ECB", "fixer.io", "manual" lastUpdated: string } ``` **Errors:** - `404` — No rate found for date (return nearest available) --- ## Endpoint Summary Map ```mermaid graph TD subgraph AUTH [Authentication — No auth required] A1[POST /auth/register] A2[POST /auth/login] A3[POST /auth/refresh] A4[POST /auth/logout] A5[GET /auth/me] end subgraph ORG [Organization] O1[GET /organization] O2[PUT /organization] end subgraph USR [Users] U1[GET /users] U2[POST /users/invite] U3[PUT /users/:id/role] U4[DELETE /users/:id] end subgraph CON [Contacts] C1[GET /contacts] C2[POST /contacts] C3[GET /contacts/:id] C4[PUT /contacts/:id] C5[DELETE /contacts/:id] end subgraph INV [Invoices] I1[GET /invoices] I2[POST /invoices] I3[GET /invoices/:id] I4[PUT /invoices/:id] I5[PATCH /invoices/:id/status] I6[GET /invoices/:id/pdf] I7[POST /invoices/:id/send] end subgraph EXP [Expenses] E1[GET /expenses] E2[POST /expenses] E3[GET /expenses/:id] E4[PUT /expenses/:id] E5[PATCH /expenses/:id/approve] E6[DELETE /expenses/:id] end subgraph BANK [Bank Accounts] B1[GET /bank-accounts] B2[POST /bank-accounts] B3[GET /bank-accounts/:id/transactions] B4[POST /bank-accounts/:id/import] B5[POST /bank-accounts/:id/reconcile] end subgraph RPT [Reports] R1[GET /reports/dashboard] R2[GET /reports/profit-loss] R3[GET /reports/balance-sheet] R4[GET /reports/cash-flow] R5[GET /reports/vat] R6[GET /reports/trial-balance] end subgraph MISC [Other] M1[GET /accounts] M2[POST /accounts] M3[PUT /accounts/:id] M4[GET /transactions] M5[POST /transactions] M6[GET /settings/tax-rates] M7[PUT /settings/tax-rates] M8[GET /currencies] M9[GET /exchange-rates] end ``` ## Implementation Notes ### Request Validation All requests validated with Zod schemas. Invalid requests return `422` with field-level errors. ### Database Transactions All write operations wrapped in database transactions. Rollback on error. ### Audit Logging All INSERT/UPDATE/DELETE captured in `LoggedAction` table via Prisma middleware. ### Rate Limiting - General: 100 req/min per user - Auth: 5 req/min per IP - Write ops: 10-50 req/min per user ### File Uploads - Max size: 10MB (receipts), 5MB (CSV) - Allowed: PDF, PNG, JPG, CSV - Storage: Cloudflare R2 - Virus scanning: ClamAV ### CORS - Allowed origins: `https://bilko.io`, `http://localhost:3000` - Credentials: true (cookies) ### Error Logging - Sentry for production errors - Winston for structured logs --- ## Example Requests ### Create Invoice ```bash curl -X POST http://localhost:4000/api/v1/invoices \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": "550e8400-e29b-41d4-a716-446655440000", "invoiceDate": "2026-02-20", "dueDate": "2026-03-20", "items": [ { "description": "Web Development", "quantity": 40, "unitPrice": 100, "taxRate": 20 } ] }' ``` ### Get Dashboard Metrics ```bash curl http://localhost:4000/api/v1/reports/dashboard \ -H "Authorization: Bearer $TOKEN" ``` --- **End of API Reference** # Database Schema # Bilko Database Schema > **Status:** IMPLEMENTED (Prisma schema exists) > **Location:** `/Users/makinja/ALAI/products/Bilko/packages/database/prisma/schema.prisma` > **Database:** PostgreSQL 14+ > **ORM:** Prisma 5.x > **Last updated:** 2026-02-20 --- ## Purpose This document describes the complete database schema for Bilko. The schema is IMPLEMENTED in Prisma and ready for migration. This doc explains the relationships, constraints, and design decisions. --- ## Entity Relationship Overview ``` Organization (1) ──┬── (N) User ├── (N) Account ├── (N) Contact ├── (N) Invoice ├── (N) Expense ├── (N) Transaction └── (N) BankAccount Contact (1) ────┬── (N) Invoice └── (N) Expense Invoice (1) ──── (N) InvoiceItem Account (1) ───┬── (N) InvoiceItem ├── (N) Expense ├── (N) BankAccount ├── (N) Transaction (debit) ├── (N) Transaction (credit) └── (N) Account (parent-child hierarchy) BankAccount (1) ── (N) BankTransaction Currency (1) ───┬── (N) ExchangeRate (base) └── (N) ExchangeRate (target) User (1) ───┬── (N) Invoice (creator) ├── (N) Expense (creator) ├── (N) Expense (approver) ├── (N) Transaction (creator) └── (N) LoggedAction ``` ### Full ER Diagram ```mermaid erDiagram Organization { UUID id PK VARCHAR name VARCHAR registrationNumber VARCHAR vatNumber CHAR baseCurrency CHAR country CHAR language DATE fiscalYearStart TIMESTAMP createdAt TIMESTAMP updatedAt } User { UUID id PK UUID organizationId FK VARCHAR email VARCHAR passwordHash VARCHAR fullName ENUM role BOOLEAN twoFactorEnabled VARCHAR twoFactorSecret TIMESTAMP lastLoginAt TIMESTAMP createdAt TIMESTAMP updatedAt } AccountType { INT id PK VARCHAR name ENUM normalBalance TIMESTAMP createdAt } Account { UUID id PK UUID organizationId FK VARCHAR code VARCHAR name INT accountTypeId FK CHAR currencyCode UUID parentAccountId FK BOOLEAN isActive TIMESTAMP createdAt TIMESTAMP updatedAt } Contact { UUID id PK UUID organizationId FK ENUM type VARCHAR name VARCHAR email VARCHAR phone VARCHAR vatNumber VARCHAR addressLine1 VARCHAR city CHAR country CHAR currencyCode INT paymentTerms BOOLEAN isActive TIMESTAMP createdAt TIMESTAMP updatedAt } Invoice { UUID id PK UUID organizationId FK UUID customerId FK VARCHAR invoiceNumber DATE invoiceDate DATE dueDate CHAR currencyCode DECIMAL exchangeRate DECIMAL subtotal DECIMAL taxAmount DECIMAL discountAmount DECIMAL totalAmount DECIMAL baseAmount ENUM status TIMESTAMP sentAt TIMESTAMP paidAt VARCHAR pdfUrl UUID createdBy FK TIMESTAMP createdAt TIMESTAMP updatedAt } InvoiceItem { UUID id PK UUID invoiceId FK INT lineNumber VARCHAR description DECIMAL quantity DECIMAL unitPrice DECIMAL taxRate DECIMAL lineTotal UUID accountId FK TIMESTAMP createdAt } Expense { UUID id PK UUID organizationId FK UUID vendorId FK VARCHAR expenseNumber DATE expenseDate CHAR currencyCode DECIMAL exchangeRate DECIMAL amount DECIMAL baseAmount DECIMAL taxAmount VARCHAR category VARCHAR paymentMethod UUID accountId FK ENUM status UUID approvedBy FK TIMESTAMP approvedAt UUID createdBy FK TIMESTAMP createdAt TIMESTAMP updatedAt } Transaction { UUID id PK UUID organizationId FK DATE transactionDate VARCHAR description UUID debitAccountId FK UUID creditAccountId FK DECIMAL amount CHAR currencyCode DECIMAL exchangeRate DECIMAL baseAmount VARCHAR referenceType UUID referenceId BOOLEAN locked BOOLEAN reconciled UUID createdBy FK TIMESTAMP createdAt } BankAccount { UUID id PK UUID organizationId FK UUID accountId FK VARCHAR bankName VARCHAR accountNumber VARCHAR iban CHAR currencyCode DECIMAL currentBalance BOOLEAN isActive TIMESTAMP createdAt TIMESTAMP updatedAt } BankTransaction { UUID id PK UUID bankAccountId FK DATE transactionDate DECIMAL amount VARCHAR description VARCHAR reference BOOLEAN reconciled UUID matchedTransactionId TIMESTAMP createdAt } Currency { CHAR code PK VARCHAR name VARCHAR symbol SMALLINT decimalPlaces BOOLEAN isActive TIMESTAMP createdAt } ExchangeRate { UUID id PK CHAR baseCurrency FK CHAR targetCurrency FK DECIMAL rate DATE effectiveDate VARCHAR source TIMESTAMP lastUpdated } LoggedAction { BIGINT eventId PK TEXT schemaName TEXT tableName UUID userId FK TIMESTAMP actionTimestamp ENUM action JSONB rowData JSONB changedFields INET clientIp } SchemaVersion { VARCHAR version PK TIMESTAMP appliedAt TEXT description } Organization ||--o{ User : "has" Organization ||--o{ Account : "owns" Organization ||--o{ Contact : "manages" Organization ||--o{ Invoice : "issues" Organization ||--o{ Expense : "tracks" Organization ||--o{ Transaction : "records" Organization ||--o{ BankAccount : "holds" User ||--o{ Invoice : "createdBy" User ||--o{ Expense : "createdBy" User ||--o{ Expense : "approvedBy" User ||--o{ Transaction : "createdBy" User ||--o{ LoggedAction : "performed" AccountType ||--o{ Account : "categorizes" Account ||--o{ Account : "parentOf" Account ||--o{ InvoiceItem : "revenueAccount" Account ||--o{ Expense : "expenseAccount" Account ||--o| BankAccount : "glAccount" Account ||--o{ Transaction : "debitAccount" Account ||--o{ Transaction : "creditAccount" Contact ||--o{ Invoice : "customer" Contact ||--o{ Expense : "vendor" Invoice ||--o{ InvoiceItem : "contains" BankAccount ||--o{ BankTransaction : "has" Currency ||--o{ ExchangeRate : "base" Currency ||--o{ ExchangeRate : "target" ``` --- ### Multi-Tenant Scoping ```mermaid graph LR ORG[Organization\nMulti-tenant Root] ORG --> U[Users\nowner/admin/accountant/viewer] ORG --> COA[Chart of Accounts\nHierarchical GL] ORG --> C[Contacts\nCustomers & Vendors] ORG --> INV[Invoices\nOutgoing] ORG --> EXP[Expenses\nIncoming] ORG --> TXN[Transactions\nDouble-Entry Ledger] ORG --> BANK[BankAccounts\nReconciliation] INV --> ITEM[InvoiceItems\nLine Items] BANK --> BTXN[BankTransactions\nStatement Import] TXN --> LOG[LoggedAction\nAudit Trail] style ORG fill:#00E5A0,color:#000 style TXN fill:#ffd700,color:#000 ``` --- ## Core Tables ### 1. Organization **Purpose:** Multi-tenant root. Every business is one organization. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK, default uuid_generate_v4() | Primary key | | name | VARCHAR(255) | NOT NULL | Business name | | registrationNumber | VARCHAR(50) | NULL | Company tax ID | | vatNumber | VARCHAR(50) | NULL | VAT registration number | | baseCurrency | CHAR(3) | NOT NULL, default 'EUR' | ISO 4217 currency code | | country | CHAR(2) | NOT NULL | ISO 3166-1 alpha-2 country code | | language | CHAR(2) | NOT NULL, default 'sr' | ISO 639-1 language code | | fiscalYearStart | DATE | NOT NULL, default '2026-01-01' | Fiscal year start date | | createdAt | TIMESTAMP | NOT NULL, default now() | Record creation timestamp | | updatedAt | TIMESTAMP | NOT NULL, default now() | Last update timestamp | **Indexes:** - Primary key: `id` **Business rules:** - baseCurrency determines default currency for all transactions - country determines tax rules (Serbia 20%, BiH 17%, Croatia 25%) - fiscalYearStart used for annual reports --- ### 2. User **Purpose:** Users within an organization. Role-based access control. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | organizationId | UUID | FK → Organization, NOT NULL, CASCADE | Organization membership | | email | VARCHAR(255) | UNIQUE, NOT NULL | Login email | | passwordHash | VARCHAR(255) | NOT NULL | bcrypt hash (12 rounds) | | fullName | VARCHAR(255) | NOT NULL | Display name | | role | ENUM | NOT NULL | owner, admin, accountant, viewer | | twoFactorEnabled | BOOLEAN | NOT NULL, default false | 2FA status | | twoFactorSecret | VARCHAR(255) | NULL | TOTP secret | | lastLoginAt | TIMESTAMP | NULL | Last login timestamp | | createdAt | TIMESTAMP | NOT NULL | Account creation | | updatedAt | TIMESTAMP | NOT NULL | Last update | **Indexes:** - Primary key: `id` - Unique: `email` - Foreign key: `organizationId` → Organization(id) - Index: `idx_users_organization` on organizationId - Index: `idx_users_email` on email **Enums:** ```prisma enum UserRole { owner // Full access, can delete org admin // Can manage users and settings accountant // Can create invoices/expenses viewer // Read-only access } ``` **Business rules:** - One owner per organization (enforced in API) - Cannot delete owner - Password must be bcrypt hashed, NEVER plain text --- ## Chart of Accounts ### Account Hierarchy & Normal Balances ```mermaid graph TD COA[Chart of Accounts] COA --> A[1xxx Assets\nnormalBalance: debit] COA --> L[2xxx Liabilities\nnormalBalance: credit] COA --> E[3xxx Equity\nnormalBalance: credit] COA --> R[4xxx Revenue\nnormalBalance: credit] COA --> EX[5xxx Expenses\nnormalBalance: debit] A --> CA[1100 Current Assets] A --> FA[1500 Fixed Assets] CA --> Cash[1110 Cash] CA --> Bank[1120 Bank Accounts] CA --> AR[1200 Accounts Receivable] Bank --> B1[1121 Intesa RSD] Bank --> B2[1122 Raiffeisen EUR] L --> CL[2100 Current Liabilities] L --> LL[2500 Long-term] CL --> AP[2110 Accounts Payable] CL --> VAT[2120 VAT Payable] E --> SC[3100 Share Capital] E --> RE[3900 Retained Earnings] R --> SR[4100 Service Revenue] R --> PR[4200 Product Sales] EX --> OE[5100 Operating Expenses] OE --> SAL[5110 Salaries] OE --> RENT[5120 Rent] style A fill:#4ade80,color:#000 style L fill:#f87171,color:#000 style E fill:#60a5fa,color:#000 style R fill:#a78bfa,color:#000 style EX fill:#fb923c,color:#000 ``` ### 3. AccountType **Purpose:** Defines account categories for double-entry bookkeeping. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | INT | PK, AUTOINCREMENT | Primary key | | name | VARCHAR(50) | UNIQUE, NOT NULL | Asset, Liability, Equity, Revenue, Expense | | normalBalance | ENUM | NOT NULL | debit or credit | | createdAt | TIMESTAMP | NOT NULL | Record creation | **Enums:** ```prisma enum NormalBalance { debit // Asset, Expense accounts increase with debits credit // Liability, Equity, Revenue accounts increase with credits } ``` **Seed data:** ``` 1 | Asset | debit 2 | Liability | credit 3 | Equity | credit 4 | Revenue | credit 5 | Expense | debit ``` --- ### 4. Account **Purpose:** Chart of Accounts. Hierarchical GL accounts. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | organizationId | UUID | FK → Organization, NOT NULL | Organization scope | | code | VARCHAR(10) | NOT NULL | Account code (e.g., "1000", "4000") | | name | VARCHAR(255) | NOT NULL | Account name (e.g., "Cash", "Revenue") | | accountTypeId | INT | FK → AccountType, NOT NULL | Account category | | currencyCode | CHAR(3) | NOT NULL, default 'EUR' | Account currency | | parentAccountId | UUID | FK → Account, NULL | Parent account (for sub-accounts) | | isActive | BOOLEAN | NOT NULL, default true | Active status | | createdAt | TIMESTAMP | NOT NULL | Record creation | | updatedAt | TIMESTAMP | NOT NULL | Last update | **Indexes:** - Primary key: `id` - Unique: `(organizationId, code)` - Index: `idx_accounts_organization` on organizationId - Index: `idx_accounts_type` on accountTypeId **Business rules:** - Code MUST be unique within organization - Cannot delete account with transactions - Parent-child hierarchy for sub-accounts (e.g., 1000 → 1001, 1002) --- ## Contacts (Customers & Vendors) ### 5. Contact **Purpose:** Customers (invoice recipients) and vendors (expense payees). | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | organizationId | UUID | FK → Organization, NOT NULL | Organization scope | | type | ENUM | NOT NULL | customer, vendor, both | | name | VARCHAR(255) | NOT NULL | Contact name | | email | VARCHAR(255) | NULL | Email address | | phone | VARCHAR(50) | NULL | Phone number | | registrationNumber | VARCHAR(50) | NULL | Company registration number | | vatNumber | VARCHAR(50) | NULL | VAT number | | addressLine1 | VARCHAR(255) | NULL | Street address | | addressLine2 | VARCHAR(255) | NULL | Apt/suite | | city | VARCHAR(100) | NULL | City | | postalCode | VARCHAR(20) | NULL | Postal/ZIP code | | country | CHAR(2) | NULL | ISO 3166-1 alpha-2 | | currencyCode | CHAR(3) | NOT NULL, default 'EUR' | Preferred currency | | paymentTerms | INT | NOT NULL, default 30 | Payment terms in days | | notes | TEXT | NULL | Free-text notes | | isActive | BOOLEAN | NOT NULL, default true | Active status | | createdAt | TIMESTAMP | NOT NULL | Record creation | | updatedAt | TIMESTAMP | NOT NULL | Last update | **Indexes:** - Primary key: `id` - Index: `idx_contacts_organization` on organizationId - Index: `idx_contacts_type` on type **Enums:** ```prisma enum ContactType { customer // Invoice recipient vendor // Expense payee both // Can be both customer and vendor } ``` **Business rules:** - Soft delete (isActive = false) if has invoices/expenses - currencyCode determines default invoice/expense currency --- ## Invoicing ### 6. Invoice **Purpose:** Sales invoices (outgoing). Revenue recognition. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | organizationId | UUID | FK → Organization, NOT NULL | Organization scope | | customerId | UUID | FK → Contact, NOT NULL | Invoice recipient | | invoiceNumber | VARCHAR(50) | NOT NULL | Auto-generated (e.g., INV-2026-001) | | invoiceDate | DATE | NOT NULL | Invoice issue date | | dueDate | DATE | NOT NULL | Payment due date | | currencyCode | CHAR(3) | NOT NULL | Invoice currency | | exchangeRate | DECIMAL(12,6) | NOT NULL, default 1.0 | Exchange rate at invoiceDate | | subtotal | DECIMAL(19,4) | NOT NULL | Sum of line totals (before tax) | | taxAmount | DECIMAL(19,4) | NOT NULL, default 0 | Total VAT/tax | | discountAmount | DECIMAL(19,4) | NOT NULL, default 0 | Total discount | | totalAmount | DECIMAL(19,4) | NOT NULL | subtotal + taxAmount - discountAmount | | baseAmount | DECIMAL(19,4) | NOT NULL | Converted to org baseCurrency | | status | ENUM | NOT NULL, default 'draft' | Invoice status | | sentAt | TIMESTAMP | NULL | When invoice was sent | | viewedAt | TIMESTAMP | NULL | When customer viewed (email tracking) | | paidAt | TIMESTAMP | NULL | When marked as paid | | notes | TEXT | NULL | Internal notes | | terms | TEXT | NULL | Payment terms text | | pdfUrl | VARCHAR(500) | NULL | Cloudflare R2 URL | | createdBy | UUID | FK → User, NULL | Creator user | | createdAt | TIMESTAMP | NOT NULL | Record creation | | updatedAt | TIMESTAMP | NOT NULL | Last update | **Indexes:** - Primary key: `id` - Unique: `(organizationId, invoiceNumber)` - Index: `idx_invoices_organization` on organizationId - Index: `idx_invoices_customer` on customerId - Index: `idx_invoices_status` on status - Index: `idx_invoices_due_date` on dueDate - Composite: `idx_invoices_org_status_date` on (organizationId, status, invoiceDate) **Enums:** ```prisma enum InvoiceStatus { draft // Being edited sent // Sent to customer viewed // Customer viewed email paid // Payment received overdue // Past dueDate and unpaid cancelled // Voided } ``` **Invoice Status Transitions:** ```mermaid stateDiagram-v2 [*] --> draft : Created draft --> sent : Send email\n(creates GL Transaction) sent --> viewed : Tracking pixel loaded viewed --> paid : Mark as paid\n(creates GL Transaction) sent --> paid : Mark as paid\n(creates GL Transaction) draft --> cancelled : Cancel sent --> cancelled : Cancel\n(reverses Transaction) viewed --> cancelled : Cancel\n(reverses Transaction) paid --> [*] cancelled --> [*] note right of draft Can edit line items,\ndates, amounts end note note right of sent Locked — no edits\nPDF generated & stored in R2 end note note right of overdue Automated check: dueDate < today\nAND status != paid end note ``` **Business rules:** - invoiceNumber auto-generated on first save - exchangeRate locked at invoiceDate (NEVER recalculate) - baseAmount = totalAmount * exchangeRate - Cannot edit invoice unless status = draft - When status changes to 'paid', create Transaction (debit BankAccount, credit AccountsReceivable) --- ### 7. InvoiceItem **Purpose:** Line items on invoices. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | invoiceId | UUID | FK → Invoice, CASCADE, NOT NULL | Parent invoice | | lineNumber | INT | NOT NULL | Line order (1, 2, 3...) | | description | VARCHAR(500) | NOT NULL | Item description | | quantity | DECIMAL(10,2) | NOT NULL | Quantity sold | | unitPrice | DECIMAL(19,4) | NOT NULL | Price per unit | | taxRate | DECIMAL(5,2) | NOT NULL, default 0 | VAT rate (20 = 20%) | | lineTotal | DECIMAL(19,4) | NOT NULL | quantity * unitPrice | | accountId | UUID | FK → Account, NULL | Revenue account | | createdAt | TIMESTAMP | NOT NULL | Record creation | **Indexes:** - Primary key: `id` - Index: `idx_invoice_items_invoice` on invoiceId **Business rules:** - lineTotal = quantity * unitPrice (calculated before save) - Tax amount = lineTotal * (taxRate / 100) - accountId determines which revenue account is credited --- ## Expenses ### 8. Expense **Purpose:** Purchase tracking (incoming). Expense recognition. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | organizationId | UUID | FK → Organization, NOT NULL | Organization scope | | vendorId | UUID | FK → Contact, NULL | Vendor (optional) | | expenseNumber | VARCHAR(50) | NOT NULL | Auto-generated (e.g., EXP-2026-001) | | expenseDate | DATE | NOT NULL | Expense date | | currencyCode | CHAR(3) | NOT NULL | Expense currency | | exchangeRate | DECIMAL(12,6) | NOT NULL, default 1.0 | Exchange rate at expenseDate | | amount | DECIMAL(19,4) | NOT NULL | Total expense amount | | baseAmount | DECIMAL(19,4) | NOT NULL | Converted to org baseCurrency | | taxAmount | DECIMAL(19,4) | NOT NULL, default 0 | VAT amount | | category | VARCHAR(100) | NOT NULL | Expense category | | paymentMethod | VARCHAR(50) | NULL | cash, card, bank_transfer, etc. | | accountId | UUID | FK → Account, NULL | Expense account | | description | TEXT | NULL | Expense description | | receiptUrl | VARCHAR(500) | NULL | Cloudflare R2 URL | | status | ENUM | NOT NULL, default 'pending' | Approval status | | approvedBy | UUID | FK → User, NULL | Approver user | | approvedAt | TIMESTAMP | NULL | Approval timestamp | | paidAt | TIMESTAMP | NULL | Payment timestamp | | createdBy | UUID | FK → User, NULL | Creator user | | createdAt | TIMESTAMP | NOT NULL | Record creation | | updatedAt | TIMESTAMP | NOT NULL | Last update | **Indexes:** - Primary key: `id` - Unique: `(organizationId, expenseNumber)` - Index: `idx_expenses_organization` on organizationId - Index: `idx_expenses_vendor` on vendorId - Index: `idx_expenses_category` on category - Index: `idx_expenses_date` on expenseDate - Composite: `idx_expenses_org_date_category` on (organizationId, expenseDate, category) **Enums:** ```prisma enum ExpenseStatus { pending // Awaiting approval approved // Approved, ready to pay paid // Payment made rejected // Approval denied } ``` **Business rules:** - expenseNumber auto-generated - exchangeRate locked at expenseDate - baseAmount = amount * exchangeRate - When status → approved, create Transaction (debit ExpenseAccount, credit AccountsPayable) - When status → paid, create Transaction (debit AccountsPayable, credit BankAccount) --- ## Transactions (Double-Entry Ledger) ### 9. Transaction **Purpose:** General ledger transactions. Every financial event creates a transaction. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | organizationId | UUID | FK → Organization, NOT NULL | Organization scope | | transactionDate | DATE | NOT NULL | Transaction date | | description | VARCHAR(255) | NOT NULL | Transaction description | | debitAccountId | UUID | FK → Account, NOT NULL | Account to debit | | creditAccountId | UUID | FK → Account, NOT NULL | Account to credit | | amount | DECIMAL(19,4) | NOT NULL | Transaction amount | | currencyCode | CHAR(3) | NOT NULL | Transaction currency | | exchangeRate | DECIMAL(12,6) | NOT NULL, default 1.0 | Exchange rate at transactionDate | | baseAmount | DECIMAL(19,4) | NOT NULL | Converted to org baseCurrency | | referenceType | VARCHAR(50) | NULL | invoice, expense, payment, manual | | referenceId | UUID | NULL | Invoice/Expense ID | | locked | BOOLEAN | NOT NULL, default false | Immutable if true | | lockedAt | TIMESTAMP | NULL | When locked | | reconciled | BOOLEAN | NOT NULL, default false | Matched to bank transaction | | reconciledAt | TIMESTAMP | NULL | When reconciled | | notes | TEXT | NULL | Free-text notes | | createdBy | UUID | FK → User, NULL | Creator user | | createdAt | TIMESTAMP | NOT NULL | Record creation | **Indexes:** - Primary key: `id` - Index: `idx_transactions_organization` on organizationId - Index: `idx_transactions_date` on transactionDate - Index: `idx_transactions_debit` on debitAccountId - Index: `idx_transactions_credit` on creditAccountId - Index: `idx_transactions_reference` on (referenceType, referenceId) - Composite: `idx_transactions_org_date` on (organizationId, transactionDate) **Business rules:** - **DEBITS = CREDITS** — Every transaction has exactly one debit and one credit - debitAccountId ≠ creditAccountId (enforced in API) - Cannot edit if locked = true - Cannot delete if reconciled = true - exchangeRate locked at transactionDate - baseAmount = amount * exchangeRate **Common transaction patterns:** 1. **Invoice created (draft → sent):** - Debit: Accounts Receivable (Asset) - Credit: Revenue (Revenue) 2. **Invoice paid:** - Debit: Bank Account (Asset) - Credit: Accounts Receivable (Asset) 3. **Expense approved:** - Debit: Expense Account (Expense) - Credit: Accounts Payable (Liability) 4. **Expense paid:** - Debit: Accounts Payable (Liability) - Credit: Bank Account (Asset) --- ## Banking & Reconciliation ### 10. BankAccount **Purpose:** Bank account metadata. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | organizationId | UUID | FK → Organization, NOT NULL | Organization scope | | accountId | UUID | FK → Account, NOT NULL | GL account (must be Asset) | | bankName | VARCHAR(255) | NOT NULL | Bank name | | accountNumber | VARCHAR(50) | NULL | Account number | | iban | VARCHAR(50) | NULL | IBAN | | currencyCode | CHAR(3) | NOT NULL, default 'EUR' | Account currency | | currentBalance | DECIMAL(19,4) | NOT NULL, default 0 | Current balance | | isActive | BOOLEAN | NOT NULL, default true | Active status | | createdAt | TIMESTAMP | NOT NULL | Record creation | | updatedAt | TIMESTAMP | NOT NULL | Last update | **Indexes:** - Primary key: `id` - Index: `idx_bank_accounts_organization` on organizationId **Business rules:** - accountId MUST be Asset type account - currentBalance updated when transactions created - Soft delete (isActive = false) --- ### 11. BankTransaction **Purpose:** Bank statement imports. For reconciliation. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | bankAccountId | UUID | FK → BankAccount, CASCADE, NOT NULL | Parent bank account | | transactionDate | DATE | NOT NULL | Transaction date | | amount | DECIMAL(19,4) | NOT NULL | Positive = credit, negative = debit | | description | VARCHAR(500) | NULL | Bank description | | reference | VARCHAR(255) | NULL | Reference number | | reconciled | BOOLEAN | NOT NULL, default false | Matched to GL transaction | | matchedTransactionId | UUID | NULL | GL transaction ID | | createdAt | TIMESTAMP | NOT NULL | Record creation | **Indexes:** - Primary key: `id` - Index: `idx_bank_transactions_account` on bankAccountId - Index: `idx_bank_transactions_date` on transactionDate **Business rules:** - Imported from CSV bank statements - Matched to GL transactions via reconciliation workflow - reconciled = true when matched --- ## Multi-Currency ### 12. Currency **Purpose:** Supported currencies. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | code | CHAR(3) | PK | ISO 4217 currency code | | name | VARCHAR(100) | NOT NULL | Currency name | | symbol | VARCHAR(10) | NULL | Currency symbol | | decimalPlaces | SMALLINT | NOT NULL, default 2 | Decimal precision | | isActive | BOOLEAN | NOT NULL, default true | Active status | | createdAt | TIMESTAMP | NOT NULL | Record creation | **Seed data:** ``` EUR | Euro | € | 2 RSD | Serbian Dinar | din. | 2 BAM | Bosnian Mark | KM | 2 HRK | Croatian Kuna | kn | 2 USD | US Dollar | $ | 2 ``` --- ### 13. ExchangeRate **Purpose:** Historical exchange rates. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | UUID | PK | Primary key | | baseCurrency | CHAR(3) | FK → Currency, NOT NULL | From currency | | targetCurrency | CHAR(3) | FK → Currency, NOT NULL | To currency | | rate | DECIMAL(12,6) | NOT NULL | Exchange rate | | effectiveDate | DATE | NOT NULL | Rate effective date | | source | VARCHAR(50) | NULL | ECB, fixer.io, manual | | lastUpdated | TIMESTAMP | NOT NULL | Last update timestamp | **Indexes:** - Primary key: `id` - Unique: `(baseCurrency, targetCurrency, effectiveDate)` - Index: `idx_exchange_rates_date` on effectiveDate - Index: `idx_exchange_rates_pair` on (baseCurrency, targetCurrency) **Business rules:** - Rates fetched daily from ECB or fixer.io API - When creating transaction, rate is locked at transaction date - If no rate for exact date, use nearest available (warn in logs) --- ## Audit Trail ### 14. LoggedAction **Purpose:** Immutable audit log. Captures all INSERT/UPDATE/DELETE. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | eventId | BIGINT | PK, AUTOINCREMENT | Event ID | | schemaName | TEXT | NOT NULL | Database schema (default: public) | | tableName | TEXT | NOT NULL | Table name | | userId | UUID | FK → User, NULL | User who performed action | | actionTimestamp | TIMESTAMP | NOT NULL, default now() | When action occurred | | action | ENUM | NOT NULL | INSERT, UPDATE, DELETE | | rowData | JSONB | NULL | Full row data before change | | changedFields | JSONB | NULL | Changed fields (UPDATE only) | | queryText | TEXT | NULL | SQL query (if available) | | clientIp | INET | NULL | Client IP address | | applicationName | TEXT | NOT NULL, default 'fiken-clone-api' | Application identifier | **Indexes:** - Primary key: `eventId` - Index: `idx_logged_actions_timestamp` on actionTimestamp - Index: `idx_logged_actions_table` on tableName - Index: `idx_logged_actions_user` on userId **Enums:** ```prisma enum AuditAction { INSERT UPDATE DELETE } ``` **Business rules:** - **APPEND-ONLY** — NEVER delete or update records - Triggered via Prisma middleware (automatic) - Used for: compliance, debugging, rollback simulation --- ## Schema Version ### 15. SchemaVersion **Purpose:** Migration tracking. | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | version | VARCHAR(20) | PK | Version string (e.g., "1.0.0") | | appliedAt | TIMESTAMP | NOT NULL, default now() | Migration timestamp | | description | TEXT | NULL | Migration description | **Business rules:** - Updated by Prisma migrations - Used to verify schema version matches application version --- ## Data Types & Precision ### NUMERIC(19,4) for ALL Money **CRITICAL:** NEVER use `float`, `double`, or JavaScript `number` for currency. - Precision: 19 digits total, 4 decimal places - Range: -999,999,999,999,999.9999 to +999,999,999,999,999.9999 - Prisma type: `Decimal` - PostgreSQL type: `NUMERIC(19,4)` **Why:** - JavaScript `number` has 53-bit precision (safe up to 2^53 - 1 = 9,007,199,254,740,991) - Financial calculations require exact decimal precision - Example: 0.1 + 0.2 = 0.30000000000000004 (float error) **Usage in code:** ```typescript import { Decimal } from '@prisma/client/runtime' const amount = new Decimal('125000.0000') const taxRate = new Decimal('0.20') const taxAmount = amount.times(taxRate) // 25000.0000 ``` --- ## Constraints Summary ### Primary Keys All tables use UUID primary keys (except AccountType uses INT auto-increment). ### Foreign Keys All foreign keys have `onDelete: Cascade` (deleting organization deletes all data). ### Unique Constraints - User.email - Account.(organizationId, code) - Invoice.(organizationId, invoiceNumber) - Expense.(organizationId, expenseNumber) - ExchangeRate.(baseCurrency, targetCurrency, effectiveDate) ### Check Constraints (Enforced in API layer, not database): - amount > 0 for all financial amounts - dueDate >= invoiceDate for invoices - debitAccountId ≠ creditAccountId for transactions --- ## Indexes Strategy ### Query Patterns Optimized 1. **List by organization + filter:** - `(organizationId, status, date)` composite index on invoices - `(organizationId, category, date)` composite index on expenses 2. **Foreign key lookups:** - All foreign keys have indexes 3. **Date range queries:** - Dedicated indexes on `transactionDate`, `invoiceDate`, `expenseDate`, `dueDate` 4. **Reconciliation:** - Index on `(referenceType, referenceId)` for transaction lookups --- ## Migration Commands ```bash # Generate Prisma Client npx prisma generate # Create migration npx prisma migrate dev --name migration_name # Apply migrations (production) npx prisma migrate deploy # Reset database (dev only) npx prisma migrate reset # Seed initial data npx prisma db seed ``` --- ## Seed Data ### AccountType ```sql INSERT INTO account_types (id, name, normal_balance) VALUES (1, 'Asset', 'debit'), (2, 'Liability', 'credit'), (3, 'Equity', 'credit'), (4, 'Revenue', 'credit'), (5, 'Expense', 'debit'); ``` ### Currency ```sql INSERT INTO currencies (code, name, symbol, decimal_places) VALUES ('EUR', 'Euro', '€', 2), ('RSD', 'Serbian Dinar', 'din.', 2), ('BAM', 'Bosnian Mark', 'KM', 2), ('HRK', 'Croatian Kuna', 'kn', 2), ('USD', 'US Dollar', '$', 2); ``` --- **End of Database Schema** # Authentication & Authorization # Bilko Authentication & Authorization > **Status:** SPECIFICATION (backend not implemented) > **Last updated:** 2026-02-20 --- ## Purpose This document specifies the authentication and authorization system for Bilko's backend. Covers JWT tokens, password hashing, 2FA, role-based access control (RBAC), and session management. --- ## Authentication Flow ### System Overview ```mermaid graph LR CLIENT[Frontend\nbilko.io] subgraph AUTH [Auth Layer] LOGIN[POST /auth/login] REGISTER[POST /auth/register] REFRESH[POST /auth/refresh] LOGOUT[POST /auth/logout] end subgraph TOKENS [Token Storage] AT[Access Token\nBearer header\n15 min TTL] RT[Refresh Token\nhttpOnly Cookie\n7-30 days TTL] BL[Blacklist\nRevoked JTIs] end subgraph GUARDS [Middleware Guards] AG[authGuard\nVerify JWT] RG[roleGuard\nCheck role] RL[rateLimiter\n5 req/min auth] end CLIENT --> LOGIN CLIENT --> REGISTER CLIENT --> REFRESH CLIENT --> LOGOUT LOGIN --> AT LOGIN --> RT REGISTER --> AT REGISTER --> RT REFRESH --> AT LOGOUT --> BL AT --> AG AG --> RG RG --> HANDLER[Route Handler] style AT fill:#00E5A0,color:#000 style RT fill:#ffd700,color:#000 style BL fill:#f87171,color:#fff ``` ### 1. Registration **Endpoint:** `POST /api/v1/auth/register` ```mermaid sequenceDiagram participant C as Client participant API as Express API participant DB as PostgreSQL participant JWT as JWT Service C->>API: POST /auth/register\n{email, password, orgName, country} API->>API: Validate Zod schema\nCheck password strength API->>DB: Check email uniqueness DB-->>API: Email available API->>API: bcrypt.hash(password, 12) API->>DB: BEGIN TRANSACTION\nCreate Organization\nCreate User (role=owner)\nCreate default Chart of Accounts DB-->>API: Organization + User created API->>JWT: Generate access token (15min)\nGenerate refresh token (7days) JWT-->>API: { accessToken, refreshToken } API->>C: 201 Created\n{ user, organization, tokens }\nSet-Cookie: refreshToken (httpOnly) ``` **Steps:** 1. Validate request body (email uniqueness, password strength, country/currency codes) 2. Hash password with bcrypt (12 rounds) 3. Create database transaction: - Create Organization - Create User (role = 'owner') - Create default Chart of Accounts (seed accounts based on country) 4. Generate JWT access token (15 min expiry) 5. Generate refresh token (7 days expiry) 6. Set refresh token in httpOnly cookie 7. Return user + organization + tokens **Password Requirements:** - Minimum 8 characters - At least 1 uppercase letter - At least 1 lowercase letter - At least 1 number - Optional: 1 special character **Password Hashing:** ```typescript import bcrypt from 'bcrypt' const SALT_ROUNDS = 12 async function hashPassword(password: string): Promise { return bcrypt.hash(password, SALT_ROUNDS) } async function verifyPassword(password: string, hash: string): Promise { return bcrypt.compare(password, hash) } ``` **Errors:** - `400 Bad Request` — Email already exists - `422 Unprocessable Entity` — Weak password, invalid country code --- ### 2. Login **Endpoint:** `POST /api/v1/auth/login` ```mermaid sequenceDiagram participant C as Client participant RL as Rate Limiter\n5 req/min/IP participant API as Express API participant DB as PostgreSQL participant JWT as JWT Service C->>RL: POST /auth/login\n{email, password} RL-->>C: 429 Too Many Requests (if exceeded) RL->>API: Pass through API->>DB: Find user by email DB-->>API: User record API->>API: bcrypt.compare(password, hash) alt Invalid credentials API-->>C: 401 Unauthorized else 2FA required API-->>C: 403 { requiresTwoFactor: true } C->>API: POST /auth/verify-2fa { code } API->>API: speakeasy.totp.verify() end API->>DB: UPDATE users SET lastLoginAt = now() API->>JWT: Generate access token (15min)\nGenerate refresh token\n(7d or 30d if rememberMe) JWT-->>API: Tokens API->>C: 200 OK { user, tokens }\nSet-Cookie: refreshToken (httpOnly, Secure, SameSite=Strict) ``` **Steps:** 1. Find user by email 2. Verify password with bcrypt.compare() 3. If 2FA enabled, send TOTP challenge (not covered in MVP) 4. Update user.lastLoginAt 5. Generate JWT access token (15 min expiry) 6. Generate refresh token (7 days or 30 days if rememberMe = true) 7. Set refresh token in httpOnly cookie 8. Return user + tokens **Rate Limiting:** - Max 5 login attempts per 1 minute per IP address - After 5 failed attempts, return `429 Too Many Requests` - Lockout duration: 15 minutes **Errors:** - `401 Unauthorized` — Invalid email or password - `403 Forbidden` — Account disabled or requires 2FA - `429 Too Many Requests` — Rate limit exceeded --- ### 3. Token Refresh **Endpoint:** `POST /api/v1/auth/refresh` ```mermaid sequenceDiagram participant C as Client participant API as Express API participant BL as Blacklist\n(Redis/PostgreSQL) participant JWT as JWT Service C->>API: POST /auth/refresh\n[Cookie: refreshToken] API->>API: Extract JWT from httpOnly cookie API->>JWT: Verify signature & expiry JWT-->>API: RefreshTokenPayload { sub, jti, exp } API->>BL: Check if jti is blacklisted BL-->>API: Not blacklisted API->>JWT: Generate new access token (15min) JWT-->>API: New accessToken API->>C: 200 OK { accessToken } note over C,API: Access token expires every 15min\nClient must silently refresh via cookie ``` **Steps:** 1. Extract refresh token from httpOnly cookie 2. Verify refresh token signature 3. Check if token is blacklisted (revoked) 4. Check expiry 5. Generate new access token (15 min expiry) 6. Return new access token **Refresh Token Storage:** - Stored in httpOnly cookie (prevents XSS attacks) - Secure flag = true (HTTPS only) - SameSite = Strict (prevents CSRF attacks) - Path = /api/v1/auth/refresh **Token Revocation:** - On logout, add refresh token to blacklist (Redis or PostgreSQL) - Blacklist stores token JTI (JWT ID) + expiry - Expired blacklist entries auto-deleted after 30 days **Errors:** - `401 Unauthorized` — Invalid or expired refresh token --- ### 4. Logout **Endpoint:** `POST /api/v1/auth/logout` **Steps:** 1. Extract refresh token from cookie 2. Add token JTI to blacklist 3. Clear httpOnly cookie 4. Return 204 No Content --- ## JWT Tokens ### Access Token **Purpose:** Short-lived token for API authentication. **Claims:** ```typescript interface AccessTokenPayload { sub: string // User ID (UUID) email: string // User email role: UserRole // owner, admin, accountant, viewer orgId: string // Organization ID (UUID) iat: number // Issued at (Unix timestamp) exp: number // Expires at (Unix timestamp, iat + 15 min) } ``` **Expiry:** 15 minutes **Header:** ```json { "alg": "HS256", "typ": "JWT" } ``` **Usage:** - Sent in `Authorization: Bearer ` header - Verified on every API request via `authGuard` middleware - If expired, client requests new token via `/auth/refresh` --- ### Refresh Token **Purpose:** Long-lived token for obtaining new access tokens. **Claims:** ```typescript interface RefreshTokenPayload { sub: string // User ID (UUID) jti: string // JWT ID (for revocation) iat: number // Issued at (Unix timestamp) exp: number // Expires at (Unix timestamp, iat + 7 days or 30 days) } ``` **Expiry:** 7 days (default) or 30 days (if rememberMe = true) **Storage:** - httpOnly cookie (client cannot access via JavaScript) - Secure = true (HTTPS only in production) - SameSite = Strict (prevents CSRF) **Revocation:** - On logout, JTI added to blacklist - On password change, all refresh tokens revoked - On user deletion, all refresh tokens revoked --- ## JWT Secret Management **CRITICAL:** JWT secret MUST be stored securely. **Environment Variables:** ```bash # .env JWT_SECRET=<256-bit random string, minimum 32 chars> JWT_REFRESH_SECRET= ``` **Generation:** ```bash # Generate secure random secret openssl rand -base64 32 ``` **Best Practices:** - Use different secrets for access and refresh tokens - Rotate secrets every 90 days (requires re-login for all users) - Store in environment variables, NEVER in code - Use Vaultwarden or similar secret manager in production --- ## Two-Factor Authentication (2FA) **Status:** OPTIONAL in MVP, implement in v2 ```mermaid sequenceDiagram participant U as User participant APP as Frontend participant API as Backend participant DB as PostgreSQL Note over U,DB: 2FA Setup Flow U->>APP: Enable 2FA in settings APP->>API: POST /settings/2fa/enable API->>API: Generate 32-char base32 TOTP secret API->>APP: { secret, qrCodeUrl } APP->>U: Display QR code U->>U: Scan with Google Authenticator / Authy U->>APP: Enter 6-digit code to verify APP->>API: POST /settings/2fa/verify { code } API->>API: speakeasy.totp.verify(secret, code) API->>DB: UPDATE users SET twoFactorEnabled=true\ntwoFactorSecret=encrypted API->>APP: 2FA activated Note over U,DB: Login with 2FA U->>APP: Enter email + password APP->>API: POST /auth/login API->>DB: Find user, verify password API->>APP: 403 { requiresTwoFactor: true } APP->>U: Prompt for 6-digit code U->>APP: Enter TOTP code APP->>API: POST /auth/verify-2fa { code } API->>API: Verify TOTP (30-second window ±1 step) API->>APP: 200 OK { user, tokens } ``` **Flow:** 1. User enables 2FA in settings 2. Generate TOTP secret (32-char base32 string) 3. Display QR code (Google Authenticator, Authy compatible) 4. User scans QR code 5. User enters 6-digit code to verify 6. Store `twoFactorSecret` (encrypted) in `users` table 7. Set `twoFactorEnabled = true` **Login with 2FA:** 1. User enters email + password 2. If `twoFactorEnabled = true`, return `403` with `requiresTwoFactor: true` 3. Frontend prompts for 6-digit code 4. User submits code via `POST /api/v1/auth/verify-2fa` 5. Verify TOTP code (30-second window) 6. If valid, issue tokens **TOTP Verification:** ```typescript import speakeasy from 'speakeasy' function verifyTOTP(secret: string, token: string): boolean { return speakeasy.totp.verify({ secret, encoding: 'base32', token, window: 1 // Allow 1 time step before/after (30s window) }) } ``` --- ## Role-Based Access Control (RBAC) ### RBAC Model ```mermaid graph TD subgraph ROLES [User Roles — Hierarchy] OW[owner\nFull control] AD[admin\nManage users + all financials] AC[accountant\nCreate financials only] VW[viewer\nRead-only] end subgraph ACTIONS [Protected Actions] direction LR INV_C[Create Invoice] INV_S[Send Invoice] INV_P[Mark Invoice Paid] EXP_C[Create Expense] EXP_AP[Approve Expense] TXN[Create Transaction] USR_I[Invite User] USR_R[Change User Role] USR_D[Delete User] ORG_S[Org Settings] ORG_D[Delete Organization] RPT[View Reports] end OW --> INV_C & INV_S & INV_P OW --> EXP_C & EXP_AP OW --> TXN OW --> USR_I & USR_R & USR_D OW --> ORG_S & ORG_D OW --> RPT AD --> INV_C & INV_S & INV_P AD --> EXP_C & EXP_AP AD --> TXN AD --> USR_I AD --> ORG_S AD --> RPT AC --> INV_C & INV_S & INV_P AC --> EXP_C AC --> TXN AC --> RPT VW --> RPT style OW fill:#00E5A0,color:#000 style AD fill:#60a5fa,color:#000 style AC fill:#fbbf24,color:#000 style VW fill:#94a3b8,color:#000 ``` ### Roles | Role | Permissions | |------|-------------| | **owner** | Full access: manage users, delete organization, change settings, all financial operations | | **admin** | Manage users (except owner), change settings, all financial operations | | **accountant** | Create/edit invoices, expenses, transactions. View reports. Cannot manage users or settings. | | **viewer** | Read-only access to all financial data. Cannot create or edit. | ### Permission Matrix | Action | owner | admin | accountant | viewer | |--------|-------|-------|------------|--------| | Create invoice | ✅ | ✅ | ✅ | ❌ | | Edit invoice (draft) | ✅ | ✅ | ✅ | ❌ | | Send invoice | ✅ | ✅ | ✅ | ❌ | | Mark invoice paid | ✅ | ✅ | ✅ | ❌ | | Create expense | ✅ | ✅ | ✅ | ❌ | | Approve expense | ✅ | ✅ | ❌ | ❌ | | Create manual transaction | ✅ | ✅ | ✅ | ❌ | | View reports | ✅ | ✅ | ✅ | ✅ | | Invite user | ✅ | ✅ | ❌ | ❌ | | Change user role | ✅ | ❌ | ❌ | ❌ | | Delete user | ✅ | ❌ | ❌ | ❌ | | Update org settings | ✅ | ✅ | ❌ | ❌ | | Delete organization | ✅ | ❌ | ❌ | ❌ | ### Middleware Implementation **Role Guard:** ```typescript import { Request, Response, NextFunction } from 'express' type UserRole = 'owner' | 'admin' | 'accountant' | 'viewer' function roleGuard(allowedRoles: UserRole[]) { return (req: Request, res: Response, next: NextFunction) => { const user = req.user // Attached by authGuard middleware if (!user) { return res.status(401).json({ error: 'Unauthorized', code: 'NO_AUTH' }) } if (!allowedRoles.includes(user.role)) { return res.status(403).json({ error: 'Forbidden', code: 'INSUFFICIENT_PERMISSIONS', details: { required: allowedRoles, current: user.role } }) } next() } } // Usage in routes app.post('/api/v1/invoices', authGuard, roleGuard(['owner', 'admin', 'accountant']), createInvoice ) ``` --- ## Session Management ### Session Storage **Option 1: JWT-only (stateless, recommended for MVP):** - No server-side session storage - All state in JWT claims - Fast, scales horizontally - Cannot revoke access tokens (must wait for expiry) **Option 2: Redis sessions (for v2):** - Store session data in Redis - JWT contains only session ID - Can revoke immediately - Requires Redis infrastructure **Recommended for MVP:** JWT-only (stateless) --- ### Session Invalidation **On password change:** 1. Hash new password 2. Update `users.passwordHash` 3. Delete all refresh tokens from blacklist older than 1 hour (force re-login) 4. Return success **On account deletion:** 1. Soft-delete user (set `isActive = false`) 2. Add all user's refresh tokens to blacklist 3. Revoke access immediately --- ## Security Best Practices ### 1. Password Storage - **NEVER** store plain text passwords - Use bcrypt with 12 rounds (2^12 iterations) - Bcrypt auto-salts (no need to store salt separately) ### 2. Token Security - Access tokens in `Authorization` header (NOT cookies to avoid CSRF) - Refresh tokens in httpOnly cookies (prevent XSS) - Use Secure flag (HTTPS only) - Use SameSite=Strict (prevent CSRF) ### 3. Rate Limiting - Login: 5 attempts per minute per IP - Register: 5 attempts per minute per IP - Refresh: 100 attempts per minute per user - All other endpoints: 100 requests per minute per user ### 4. HTTPS Only - All traffic over HTTPS in production - Redirect HTTP → HTTPS - HSTS header: `Strict-Transport-Security: max-age=31536000; includeSubDomains` ### 5. CORS Configuration ```typescript const corsOptions = { origin: ['https://bilko.io', 'http://localhost:3000'], credentials: true, // Allow cookies methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'], allowedHeaders: ['Content-Type', 'Authorization'] } app.use(cors(corsOptions)) ``` ### 6. Input Validation - Validate all inputs with Zod schemas - Sanitize SQL inputs (Prisma prevents SQL injection) - Escape HTML in user-generated content --- ## Example Implementation ### Auth Middleware ```typescript import jwt from 'jsonwebtoken' import { Request, Response, NextFunction } from 'express' interface AuthRequest extends Request { user?: { id: string email: string role: UserRole organizationId: string } } async function authGuard(req: AuthRequest, res: Response, next: NextFunction) { const authHeader = req.headers.authorization if (!authHeader || !authHeader.startsWith('Bearer ')) { return res.status(401).json({ error: 'Unauthorized', code: 'NO_TOKEN' }) } const token = authHeader.substring(7) // Remove 'Bearer ' try { const payload = jwt.verify(token, process.env.JWT_SECRET!) as AccessTokenPayload // Attach user to request req.user = { id: payload.sub, email: payload.email, role: payload.role, organizationId: payload.orgId } next() } catch (error) { if (error.name === 'TokenExpiredError') { return res.status(401).json({ error: 'Token expired', code: 'TOKEN_EXPIRED' }) } return res.status(401).json({ error: 'Invalid token', code: 'INVALID_TOKEN' }) } } export { authGuard, roleGuard } ``` --- ## Environment Variables ```bash # JWT JWT_SECRET=<256-bit secret for access tokens> JWT_REFRESH_SECRET=<256-bit secret for refresh tokens> JWT_ACCESS_EXPIRY=15m JWT_REFRESH_EXPIRY=7d # Rate Limiting RATE_LIMIT_AUTH=5 # Max login attempts per minute RATE_LIMIT_GENERAL=100 # Max requests per minute # Session SESSION_COOKIE_SECURE=true # HTTPS only (production) SESSION_COOKIE_SAMESITE=strict ``` --- **End of Authentication Documentation** # Business Logic # Bilko Business Logic > **Status:** SPECIFICATION (backend not implemented) > **Last updated:** 2026-02-20 --- ## Purpose This document defines the accounting domain rules that Bilko's backend MUST enforce. These are non-negotiable business requirements for financial accuracy and compliance. --- ## Table of Contents 1. [Double-Entry Bookkeeping](#double-entry-bookkeeping) 2. [Invoice Workflow](#invoice-workflow) 3. [Expense Workflow](#expense-workflow) 4. [VAT Calculation](#vat-calculation) 5. [Multi-Currency](#multi-currency) 6. [Bank Reconciliation](#bank-reconciliation) 7. [Chart of Accounts](#chart-of-accounts) 8. [Fiscal Year](#fiscal-year) 9. [Audit Trail](#audit-trail) --- ## 1. Double-Entry Bookkeeping ### Core Principle **EVERY financial event creates a `Transaction` with exactly one debit and one credit.** **The fundamental equation:** ``` DEBITS = CREDITS ``` ### Double-Entry Flow ```mermaid flowchart TD EVENT[Financial Event\ne.g. Invoice sent, Expense approved, Payment received] EVENT --> TXN[Create Transaction\ndebitAccountId + creditAccountId + amount] TXN --> CHK{Validate:\ndebit ≠ credit\namount > 0} CHK -->|FAIL| ERR[422 Validation Error] CHK -->|PASS| DEBIT[Debit Account\nIncrease if Asset/Expense\nDecrease if Liability/Equity/Revenue] DEBIT --> CREDIT[Credit Account\nIncrease if Liability/Equity/Revenue\nDecrease if Asset/Expense] CREDIT --> BAL{Trial Balance\nSum Debits = Sum Credits?} BAL -->|Balanced| LOCK[Lock Transaction\nappend to GL] BAL -->|Unbalanced| ALERT[System Alert\nCritical Error] style EVENT fill:#00E5A0,color:#000 style ERR fill:#f87171,color:#fff style ALERT fill:#f87171,color:#fff style LOCK fill:#60a5fa,color:#000 ``` ### Common Transaction Patterns ```mermaid flowchart LR subgraph INV_SENT [Invoice Sent] IS_D[Debit: 1200 Accounts Receivable\nAsset ↑] IS_C[Credit: 4000 Revenue\nRevenue ↑] IS_D -. "amount" .- IS_C end subgraph INV_PAID [Invoice Paid] IP_D[Debit: 1000 Bank Account\nAsset ↑] IP_C[Credit: 1200 Accounts Receivable\nAsset ↓] IP_D -. "amount" .- IP_C end subgraph EXP_APR [Expense Approved] EA_D[Debit: 5100 Expense Account\nExpense ↑] EA_C[Credit: 2000 Accounts Payable\nLiability ↑] EA_D -. "amount" .- EA_C end subgraph EXP_PAID [Expense Paid] EP_D[Debit: 2000 Accounts Payable\nLiability ↓] EP_C[Credit: 1000 Bank Account\nAsset ↓] EP_D -. "amount" .- EP_C end style IS_D fill:#4ade80,color:#000 style IP_D fill:#4ade80,color:#000 style EA_D fill:#fb923c,color:#000 style EP_D fill:#4ade80,color:#000 ``` **Account types and normal balances:** | Account Type | Normal Balance | Increases with | Decreases with | |--------------|----------------|----------------|----------------| | Asset | Debit | Debit | Credit | | Liability | Credit | Credit | Debit | | Equity | Credit | Credit | Debit | | Revenue | Credit | Credit | Debit | | Expense | Debit | Debit | Credit | ### Transaction Rules 1. **Debit Account ≠ Credit Account** - A transaction cannot debit and credit the same account - Enforced at API validation layer 2. **Amount > 0** - Transaction amount must be positive - Sign is determined by debit/credit, not amount 3. **Balanced Entries** - Debit amount = Credit amount - No split transactions in MVP (one debit, one credit only) 4. **Locked Transactions** - Once `transaction.locked = true`, cannot be edited or deleted - Locked at end-of-period close or when reconciled ### Common Transaction Patterns #### 1. Invoice Created (draft → sent) ``` Debit: 1200 - Accounts Receivable (Asset) +125,000 RSD Credit: 4000 - Revenue (Revenue) +125,000 RSD ``` **Effect:** Increases asset (money owed to us), increases revenue. #### 2. Invoice Paid ``` Debit: 1000 - Bank Account (Asset) +125,000 RSD Credit: 1200 - Accounts Receivable (Asset) -125,000 RSD ``` **Effect:** Increases cash, decreases receivables (converted to cash). #### 3. Expense Approved ``` Debit: 5100 - Infrastructure Expense (Expense) +850 EUR Credit: 2000 - Accounts Payable (Liability) +850 EUR ``` **Effect:** Increases expense, increases liability (we owe money). #### 4. Expense Paid ``` Debit: 2000 - Accounts Payable (Liability) -850 EUR Credit: 1000 - Bank Account (Asset) -850 EUR ``` **Effect:** Decreases liability, decreases cash. ### Balance Calculation **Account balance** = Sum(debits) - Sum(credits) for **debit-normal accounts** (Asset, Expense) **Account balance** = Sum(credits) - Sum(debits) for **credit-normal accounts** (Liability, Equity, Revenue) **Trial Balance:** - Sum of all debit balances = Sum of all credit balances - If unbalanced, there is an error in the ledger --- ## 2. Invoice Workflow ### Status Transitions ``` draft → sent → viewed → paid ↓ ↓ ↓ └─────→ cancelled ``` ```mermaid stateDiagram-v2 [*] --> draft : POST /invoices\n(auto-number: INV-YYYY-NNN) draft --> sent : PATCH /invoices/:id/status\naction=send\n[generates PDF → R2]\n[sends email via SendGrid]\n[creates Transaction:\nDR Receivable / CR Revenue] sent --> viewed : Email tracking pixel loaded\n[updates invoice.viewedAt] viewed --> paid : PATCH status action=mark-paid\n[creates Transaction:\nDR Bank / CR Receivable] sent --> paid : PATCH status action=mark-paid\n[creates Transaction:\nDR Bank / CR Receivable] draft --> cancelled : PATCH status action=cancel sent --> cancelled : PATCH status action=cancel\n[reverses Transaction] viewed --> cancelled : PATCH status action=cancel\n[reverses Transaction] paid --> [*] cancelled --> [*] note right of draft Editable: items, dates, amounts Invoice number locked on first save end note note right of sent LOCKED — cannot edit amounts PDF stored in Cloudflare R2 exchangeRate locked at invoiceDate end note note right of paid 2 GL Transactions created total: 1. draft→sent: DR Receivable / CR Revenue 2. paid: DR Bank / CR Receivable end note ``` ### Invoice Calculation Flow ```mermaid flowchart TD ITEMS[Invoice Items\nquantity × unitPrice = lineTotal] ITEMS --> SUB[subtotal = SUM all lineTotals] SUB --> TAX[taxAmount = SUM lineTotal × taxRate/100] TAX --> DISC[Apply discountAmount] DISC --> TOTAL[totalAmount = subtotal + taxAmount - discountAmount] TOTAL --> BASE[baseAmount = totalAmount × exchangeRate\nexchangeRate locked at invoiceDate] BASE --> LOCK[Store — NEVER recalculate\nfrom future exchange rates] style LOCK fill:#f87171,color:#fff style BASE fill:#ffd700,color:#000 ``` **Status rules:** | From | To | Action | Transaction Created? | |------|------|--------|---------------------| | draft | sent | Send email | Yes (Debit Receivable, Credit Revenue) | | sent | viewed | Email opened | No | | viewed | paid | Mark paid | Yes (Debit Bank, Credit Receivable) | | sent | paid | Mark paid | Yes (Debit Bank, Credit Receivable) | | any | cancelled | Cancel | Reverses original transaction | ### Business Rules #### Rule 1: Invoice Number Auto-Generation - Format: `INV-YYYY-NNN` (e.g., `INV-2026-001`) - Generated on first save (when status changes from null → draft) - Sequential within organization per year - NEVER reuse cancelled invoice numbers #### Rule 2: Draft-Only Editing - Can only edit invoice if `status = 'draft'` - Once sent, cannot change line items or amounts - Can still update notes/terms #### Rule 3: Overdue Detection - Invoice becomes `overdue` if `dueDate < today AND status != 'paid'` - Checked automatically via scheduled job (daily at 00:00 UTC) #### Rule 4: Subtotal Calculation ``` subtotal = SUM(lineTotal) for all invoice items lineTotal = quantity * unitPrice ``` #### Rule 5: Tax Calculation ``` taxAmount = SUM(lineTotal * (taxRate / 100)) for all items ``` #### Rule 6: Total Calculation ``` totalAmount = subtotal + taxAmount - discountAmount ``` #### Rule 7: Base Amount Conversion ``` baseAmount = totalAmount * exchangeRate ``` - `exchangeRate` locked at `invoiceDate` - NEVER recalculated #### Rule 8: PDF Generation - PDF generated when status → sent - Stored in Cloudflare R2 - URL saved to `invoice.pdfUrl` - PDF includes: org branding, line items, tax breakdown, payment terms #### Rule 9: Email Delivery - Sent to `contact.email` - Subject: "Invoice [invoiceNumber] from [organizationName]" - Attachment: PDF - Tracking pixel for `viewedAt` timestamp --- ## 3. Expense Workflow ### Status Transitions ``` pending → approved → paid ↓ rejected ``` ```mermaid stateDiagram-v2 [*] --> pending : POST /expenses\n(auto-number: EXP-YYYY-NNN)\ncreatedBy: accountant/admin/owner pending --> approved : PATCH /expenses/:id/approve\nRoles: owner, admin ONLY\n[creates Transaction:\nDR Expense / CR Accounts Payable] pending --> rejected : PATCH /expenses/:id/reject\nRoles: owner, admin ONLY\n[no Transaction created] approved --> paid : PATCH /expenses/:id/pay\n[creates Transaction:\nDR Accounts Payable / CR Bank] paid --> [*] rejected --> [*] note right of pending Can be edited before approval Receipt upload optional (max 10MB) PDF/PNG/JPG formats end note note right of approved Cannot edit after approval Stored in Cloudflare R2 receipts/ exchangeRate locked at expenseDate end note ``` **Status rules:** | From | To | Action | Transaction Created? | |------|------|--------|---------------------| | pending | approved | Approve | Yes (Debit Expense, Credit Payable) | | pending | rejected | Reject | No | | approved | paid | Mark paid | Yes (Debit Payable, Credit Bank) | ### Business Rules #### Rule 1: Expense Number Auto-Generation - Format: `EXP-YYYY-NNN` (e.g., `EXP-2026-001`) - Generated on creation - Sequential within organization per year #### Rule 2: Approval Required - Expenses created with `status = 'pending'` - Only `owner` or `admin` can approve - `accountant` can create but cannot approve - Once approved, cannot be edited #### Rule 3: Receipt Upload - Optional but recommended - Max file size: 10MB - Allowed formats: PDF, PNG, JPG - Stored in Cloudflare R2 - URL saved to `expense.receiptUrl` #### Rule 4: Category Tracking - Free-text category field - Common categories suggested: Infrastructure, Software, Office, Travel, Marketing, Utilities - Used for expense reports by category #### Rule 5: Tax Amount - Optional `taxAmount` field - If provided, represents input VAT (can be deducted from output VAT) - Used in VAT report #### Rule 6: Base Amount Conversion ``` baseAmount = amount * exchangeRate ``` - `exchangeRate` locked at `expenseDate` --- ## 4. VAT Calculation ### VAT Calculation Flow ```mermaid flowchart TD subgraph OUTPUT [Output VAT — Sales] INV[Invoice sent to customer] INV --> OLINE[For each line item:\nlineTotal = qty × unitPrice\nlineTaxAmount = lineTotal × taxRate/100] OLINE --> OTOT[Invoice taxAmount = SUM all lineTaxAmounts] OTOT --> OREC[Recorded as Output VAT\nin VAT Report] end subgraph INPUT [Input VAT — Purchases] EXP[Expense from vendor] EXP --> ETAX[expense.taxAmount field\nUser-entered or calculated] ETAX --> IREC[Recorded as Input VAT\nin VAT Report] end subgraph NET [Net VAT Calculation] OREC --> CALC[netVAT = outputVAT - inputVAT] IREC --> CALC CALC --> POS{netVAT > 0?} POS -->|Yes| OWE[Owe to tax authority\nFile PDV/VAT return] POS -->|No| REF[Tax authority owes refund\nRare for SMBs] end style OWE fill:#f87171,color:#fff style REF fill:#4ade80,color:#000 ``` ### VAT Rates by Country | Country | Standard VAT | Reduced VAT | Zero VAT | |---------|-------------|------------|----------| | Serbia (RS) | 20% | 10% | 0% | | BiH (BA) | 17% | - | 0% | | Croatia (HR) | 25% | 13% | 0% | ### Business Rules #### Rule 1: Tax Rate Application - Invoice items have `taxRate` field (percentage) - Default to organization's country standard rate - User can override per line item #### Rule 2: Tax Amount Calculation ``` For each invoice item: lineTotal = quantity * unitPrice lineTaxAmount = lineTotal * (taxRate / 100) For invoice: subtotal = SUM(lineTotal) taxAmount = SUM(lineTaxAmount) totalAmount = subtotal + taxAmount - discountAmount ``` #### Rule 3: Output VAT (Sales) - VAT collected on invoices sent to customers - Recorded when invoice status → sent - Included in VAT report as "Output VAT" #### Rule 4: Input VAT (Purchases) - VAT paid on expenses from vendors - Recorded from `expense.taxAmount` field - Included in VAT report as "Input VAT" #### Rule 5: Net VAT Calculation ``` netVAT = outputVAT - inputVAT ``` - If positive: owe VAT to tax authority - If negative: tax authority owes refund (rare for small businesses) ### VAT Report Structure ```typescript interface VATReport { period: { from: string, to: string } outputVAT: { total: Decimal // Total VAT collected invoices: Array<{ invoiceNumber: string customerName: string invoiceDate: string baseAmount: Decimal // Subtotal vatAmount: Decimal // Tax amount vatRate: Decimal // Tax rate % }> } inputVAT: { total: Decimal // Total VAT paid expenses: Array<{ expenseNumber: string vendorName: string expenseDate: string baseAmount: Decimal vatAmount: Decimal vatRate: Decimal }> } netVAT: Decimal // outputVAT - inputVAT reconciliationStatus: { allInvoicesPaid: boolean // All invoices in period are paid allExpensesApproved: boolean // All expenses in period are approved unmatchedTransactions: number // Unreconciled bank transactions } } ``` --- ## 5. Multi-Currency ### Supported Currencies **MVP:** - EUR (Euro) — default - RSD (Serbian Dinar) - BAM (Bosnian Mark) - HRK (Croatian Kuna) - USD (US Dollar) ### Exchange Rate Locking **CRITICAL RULE:** Exchange rates are locked at transaction date. **Why:** - Financial reports must be consistent over time - Cannot recalculate historical transactions with current rates - Accounting standards require rate at transaction date **How it works:** 1. **Invoice created on 2026-02-20:** - `currencyCode = 'RSD'` - `exchangeRate = 117.50` (EUR to RSD rate on 2026-02-20) - `totalAmount = 125,000 RSD` - `baseAmount = 125,000 / 117.50 = 1,063.83 EUR` (locked) 2. **Today (2026-03-15), rate is now 120.00:** - Invoice `baseAmount` stays 1,063.83 EUR - NEVER recalculated to `125,000 / 120.00 = 1,041.67 EUR` ### Exchange Rate Sources **Primary:** European Central Bank (ECB) API - Free - Daily updates - Reliable **Fallback:** fixer.io API - Freemium (1000 requests/month free) - Real-time rates **Manual Entry:** - If API unavailable, user can enter rate manually - Stored with `source = 'manual'` ### Base Currency Conversion All reports displayed in organization's `baseCurrency`. **Example:** - Organization baseCurrency = EUR - Invoice 1: 125,000 RSD → 1,063.83 EUR (rate 117.50) - Invoice 2: 3,500 EUR → 3,500 EUR (rate 1.0) - Expense 1: 850 USD → 794.39 EUR (rate 1.07) **Total Revenue:** 1,063.83 + 3,500 = 4,563.83 EUR --- ## 6. Bank Reconciliation ### Purpose Match bank transactions (from statements) to general ledger transactions (from invoices/expenses). ```mermaid flowchart TD CSV[Bank Statement CSV\nDate, Description, Amount, Reference] CSV --> PARSE[Parse & validate CSV\nCreate BankTransaction records] PARSE --> LINK[Link to BankAccount] LINK --> MATCH[Auto-Match Algorithm\nScore 0-100] subgraph SCORE [Match Score Calculation] S1[+50 pts: Exact amount match] S2[+30 pts: Same date\n+20 pts: ±1 day\n+10 pts: ±3 days] S3[+20 pts: Reference contains\ninvoice/expense number] end MATCH --> SCORE SCORE --> THRESH{Score?} THRESH -->|≥ 90| AUTO[Auto-match\nreconciled = true] THRESH -->|70-89| SUGGEST[Suggest to user\nUser confirms] THRESH -->|< 70| MANUAL[Manual review\nUser links manually] SUGGEST --> CONFIRM{User\nconfirms?} CONFIRM -->|Yes| RECONCILE[Set reconciled = true\nmatchedTransactionId = glTxId] CONFIRM -->|No| MANUAL MANUAL --> RECONCILE AUTO --> RECONCILE RECONCILE --> REPORT[Reconciliation Report\nbalanceDiscrepancy should = 0] style AUTO fill:#4ade80,color:#000 style MANUAL fill:#fb923c,color:#000 style REPORT fill:#60a5fa,color:#000 ``` ### Process 1. **Import bank statement (CSV):** - Parse CSV file - Create `BankTransaction` records - Link to `BankAccount` 2. **Auto-match transactions:** - Match by amount + date (within ±3 days) - Match by reference (invoice number in description) - Calculate confidence score (0-100) 3. **Manual reconciliation:** - User links `BankTransaction` to `Transaction` - Set `bankTransaction.reconciled = true` - Set `bankTransaction.matchedTransactionId = transaction.id` 4. **Unmatched transactions:** - Flag in reconciliation report - User must create manual journal entry or mark as miscellaneous ### Matching Algorithm **Score calculation:** ```typescript function calculateMatchScore( bankTx: BankTransaction, glTx: Transaction ): number { let score = 0 // Exact amount match if (Math.abs(bankTx.amount) === glTx.amount) { score += 50 } // Date within ±3 days const daysDiff = Math.abs( daysBetween(bankTx.transactionDate, glTx.transactionDate) ) if (daysDiff === 0) score += 30 else if (daysDiff <= 1) score += 20 else if (daysDiff <= 3) score += 10 // Reference contains invoice/expense number if (glTx.referenceType === 'invoice' && bankTx.description?.includes(glTx.referenceId)) { score += 20 } return score } ``` **Auto-match threshold:** - Score ≥ 90 → Auto-match - Score 70-89 → Suggest match (user confirms) - Score < 70 → No match suggested ### Reconciliation Report ```typescript interface ReconciliationReport { bankAccount: { id: string name: string currentBalance: Decimal } period: { from: string, to: string } bankTransactions: { total: number reconciled: number unreconciled: number totalAmount: Decimal } glTransactions: { total: number reconciled: number unreconciled: number totalAmount: Decimal } unmatchedBankTransactions: Array unmatchedGLTransactions: Array balanceDiscrepancy: Decimal // Should be 0 when fully reconciled } ``` --- ## 7. Chart of Accounts ### Structure **Hierarchical account codes:** - 1xxx = Assets - 2xxx = Liabilities - 3xxx = Equity - 4xxx = Revenue - 5xxx = Expenses **Example Serbian Chart of Accounts:** ``` 1000 Assets 1100 Current Assets 1110 Cash 1120 Bank Accounts 1121 Intesa RSD Account 1122 Raiffeisen EUR Account 1200 Accounts Receivable 1500 Fixed Assets 1510 Equipment 1520 Vehicles 2000 Liabilities 2100 Current Liabilities 2110 Accounts Payable 2120 VAT Payable 2500 Long-term Liabilities 2510 Loans Payable 3000 Equity 3100 Share Capital 3900 Retained Earnings 4000 Revenue 4100 Service Revenue 4200 Product Sales 5000 Expenses 5100 Operating Expenses 5110 Salaries 5120 Rent 5130 Utilities 5200 Cost of Goods Sold ``` ### Business Rules #### Rule 1: Account Hierarchy - Parent account codes must exist before creating child accounts - Cannot delete parent account if child accounts exist - Sub-account balance rolls up to parent #### Rule 2: Account Deactivation - Cannot deactivate account with transactions - Deactivated accounts hidden from dropdowns but visible in reports #### Rule 3: Reserved Accounts - System creates default accounts on organization registration - Cannot delete: Cash, Bank Account, Accounts Receivable, Accounts Payable, Revenue, Expense --- ## 8. Fiscal Year ### Definition **Fiscal year:** 12-month period for financial reporting. **Default:** January 1 - December 31 **Configurable:** Organization can set custom fiscal year start (e.g., April 1 for UK-style fiscal year) ### Business Rules #### Rule 1: Year-End Close - At fiscal year end, close Revenue and Expense accounts - Transfer net profit/loss to Retained Earnings - Lock all transactions for closed fiscal year - Cannot edit locked transactions #### Rule 2: Period-Based Reports - Profit & Loss: always for a period (from → to) - Balance Sheet: always as of a date (point in time) - Cash Flow: always for a period --- ## 9. Audit Trail ### Purpose **Immutable log** of all data changes for: - Compliance (GDPR, financial regulations) - Debugging (track down errors) - Rollback simulation (undo mistakes) ### What is Logged **ALL** INSERT/UPDATE/DELETE operations on: - Invoices - Expenses - Transactions - Contacts - Users - Organization settings **Captured data:** - Table name - User ID (who made the change) - Timestamp - Action (INSERT, UPDATE, DELETE) - Old values (before change) - New values (after change) - Client IP address ### Implementation **Via Prisma Middleware:** ```typescript prisma.$use(async (params, next) => { const result = await next(params) if (['create', 'update', 'delete'].includes(params.action)) { await prisma.loggedAction.create({ data: { tableName: params.model, userId: getCurrentUserId(), action: params.action.toUpperCase(), rowData: params.action === 'delete' ? params.args.where : null, changedFields: params.action === 'update' ? params.args.data : null, clientIp: getClientIp(), applicationName: 'bilko-api' } }) } return result }) ``` ### Retention Policy - Audit logs retained for **7 years** (financial compliance requirement) - After 7 years, archived to cold storage (AWS S3 Glacier) - NEVER deleted --- ## Summary of Critical Business Rules 1. **Double-entry:** Every transaction has one debit and one credit 2. **Debits = Credits:** Ledger must always balance 3. **Exchange rate locking:** Rates locked at transaction date, NEVER recalculated 4. **Invoice workflow:** draft → sent → paid (creates 2 transactions) 5. **Expense workflow:** pending → approved → paid (creates 2 transactions) 6. **VAT calculation:** `taxAmount = lineTotal * (taxRate / 100)` 7. **Account hierarchy:** Parent-child relationships in Chart of Accounts 8. **Audit trail:** ALL changes logged immutably 9. **Fiscal year close:** Lock transactions, transfer P&L to Retained Earnings 10. **Reconciliation:** Match bank transactions to GL transactions **End of Business Logic Documentation** # Middleware Stack # Bilko Middleware Stack > **Status:** SPECIFICATION (backend not implemented) > **Last updated:** 2026-02-20 --- ## Purpose This document specifies the Express middleware stack for Bilko's backend. Middleware order is CRITICAL — security, authentication, validation, and error handling must execute in the correct sequence. --- ## Middleware Execution Order **The order matters.** Middleware executes top-to-bottom: ### Full Middleware Pipeline ```mermaid flowchart TD REQ[Incoming HTTP Request] REQ --> H[1. Helmet\nSecurity Headers\nHSTS, CSP, X-Frame-Options,\nX-Content-Type-Options] H --> CORS[2. CORS\nAllow: bilko.io, localhost:3000\ncredentials: true\nmaxAge: 86400] CORS --> BP[3. Body Parser\nexpress.json limit=10mb\nexpress.urlencoded] BP --> RL{4. Rate Limiter\nAuth: 5 req/min\nGeneral: 100 req/min} RL -->|Exceeded| R429[429 Too Many Requests] RL -->|OK| LOG[5. Morgan Logger\nWinston transport\nCombined format] LOG --> ROUTE[6. Router\n/api/v1/*] ROUTE --> AUTH{authGuard\nVerify Bearer JWT} AUTH -->|No token| R401A[401 NO_TOKEN] AUTH -->|Expired| R401B[401 TOKEN_EXPIRED] AUTH -->|Invalid| R401C[401 INVALID_TOKEN] AUTH -->|Valid| ATTACH[Attach req.user\n{id, email, role, orgId}] ATTACH --> ROLE{roleGuard\nCheck allowed roles} ROLE -->|Insufficient| R403[403 INSUFFICIENT_PERMISSIONS] ROLE -->|Authorized| VALID{validate\nZod schema} VALID -->|Fails| R422[422 VALIDATION_ERROR] VALID -->|Passes| SCOPE[organizationScope\nAttach req.organizationId] SCOPE --> HANDLER[Route Handler\nBusiness Logic + Prisma] HANDLER --> AUDIT[Prisma Middleware\nLoggedAction INSERT] AUDIT --> RESP[200/201/204 Response] HANDLER -->|Error thrown| ERR[7. Error Handler\nMUST be last middleware] ERR --> FMTERR[Format error response\n{error, code, details}] FMTERR --> ERRRESP[4xx/500 Response] style REQ fill:#00E5A0,color:#000 style R429 fill:#f87171,color:#fff style R401A fill:#f87171,color:#fff style R401B fill:#f87171,color:#fff style R401C fill:#f87171,color:#fff style R403 fill:#f87171,color:#fff style R422 fill:#f87171,color:#fff style RESP fill:#4ade80,color:#000 ``` ```typescript import express from 'express' import helmet from 'helmet' import cors from 'cors' import rateLimit from 'express-rate-limit' import { authGuard, roleGuard } from './middleware/auth' import { validate } from './middleware/validation' import { errorHandler } from './middleware/error-handler' const app = express() // 1. Security headers (helmet) app.use(helmet()) // 2. CORS configuration app.use(cors(corsOptions)) // 3. Body parsing app.use(express.json({ limit: '10mb' })) app.use(express.urlencoded({ extended: true })) // 4. Rate limiting app.use(rateLimiter) // 5. Request logging (Morgan) app.use(morgan('combined')) // 6. Routes (with auth + validation per-route) app.use('/api/v1', routes) // 7. Error handler (MUST be last) app.use(errorHandler) ``` --- ## 1. Helmet (Security Headers) **Purpose:** Sets HTTP security headers to prevent common attacks. **Installation:** ```bash npm install helmet ``` **Configuration:** ```typescript import helmet from 'helmet' app.use(helmet({ contentSecurityPolicy: { directives: { defaultSrc: ["'self'"], styleSrc: ["'self'", "'unsafe-inline'"], // Allow inline styles for Next.js scriptSrc: ["'self'"], imgSrc: ["'self'", "data:", "https://r2.bilko.io"], // Cloudflare R2 connectSrc: ["'self'", "https://api.bilko.io"], fontSrc: ["'self'"], objectSrc: ["'none'"], upgradeInsecureRequests: [] } }, hsts: { maxAge: 31536000, // 1 year includeSubDomains: true, preload: true }, frameguard: { action: 'deny' }, // Prevent clickjacking noSniff: true, // Prevent MIME sniffing xssFilter: true // Enable XSS filter })) ``` **Headers set:** - `Strict-Transport-Security` — Force HTTPS - `X-Content-Type-Options: nosniff` — Prevent MIME sniffing - `X-Frame-Options: DENY` — Prevent clickjacking - `X-XSS-Protection: 1; mode=block` — Enable XSS filter - `Content-Security-Policy` — Restrict resource loading --- ## 2. CORS (Cross-Origin Resource Sharing) **Purpose:** Allow frontend (Next.js) to call backend API from different origin. **Installation:** ```bash npm install cors ``` **Configuration:** ```typescript import cors from 'cors' const corsOptions = { origin: (origin, callback) => { const allowedOrigins = [ 'https://bilko.io', 'https://www.bilko.io', 'http://localhost:3000' // Development only ] if (!origin || allowedOrigins.includes(origin)) { callback(null, true) } else { callback(new Error('Not allowed by CORS')) } }, credentials: true, // Allow cookies (refresh tokens) methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'], allowedHeaders: ['Content-Type', 'Authorization'], exposedHeaders: ['X-Total-Count', 'X-Page-Count'], // For pagination maxAge: 86400 // Cache preflight for 24h } app.use(cors(corsOptions)) ``` **Why credentials: true?** - Allows httpOnly cookies (refresh tokens) - Frontend must set `credentials: 'include'` in fetch() --- ## 3. Body Parsing **Purpose:** Parse JSON request bodies. **Built-in Express middleware:** ```typescript app.use(express.json({ limit: '10mb', // Max request body size strict: true, // Reject non-arrays/objects type: 'application/json' })) app.use(express.urlencoded({ extended: true, limit: '10mb' })) ``` **Limits:** - 10MB for file uploads (receipts, CSV imports) - Reject if Content-Length > 10MB - Return `413 Payload Too Large` --- ## 4. Rate Limiting **Purpose:** Prevent abuse, brute-force attacks, DDoS. **Installation:** ```bash npm install express-rate-limit ``` **Configuration:** ```typescript import rateLimit from 'express-rate-limit' // General API rate limiter const apiLimiter = rateLimit({ windowMs: 60 * 1000, // 1 minute max: 100, // Max 100 requests per minute message: { error: 'Too many requests', code: 'RATE_LIMIT_EXCEEDED', retryAfter: 60 }, standardHeaders: true, // Return RateLimit-* headers legacyHeaders: false, handler: (req, res) => { res.status(429).json({ error: 'Too many requests', code: 'RATE_LIMIT_EXCEEDED', retryAfter: 60 }) } }) // Auth rate limiter (stricter) const authLimiter = rateLimit({ windowMs: 60 * 1000, // 1 minute max: 5, // Max 5 login attempts per minute skipSuccessfulRequests: true, // Don't count successful logins keyGenerator: (req) => { return req.ip // Rate limit by IP } }) // Apply to routes app.use('/api/v1', apiLimiter) app.use('/api/v1/auth/login', authLimiter) app.use('/api/v1/auth/register', authLimiter) ``` **Rate limits by endpoint:** | Endpoint | Limit | Window | Why | |----------|-------|--------|-----| | /api/v1/auth/login | 5 | 1 min | Prevent brute-force | | /api/v1/auth/register | 5 | 1 min | Prevent spam registration | | /api/v1/* (general) | 100 | 1 min | General API protection | | Write ops (POST/PUT/PATCH) | 50 | 1 min | Prevent resource exhaustion | --- ## 5. Request Logging **Purpose:** Log all HTTP requests for debugging and monitoring. **Installation:** ```bash npm install morgan npm install winston ``` **Configuration:** ```typescript import morgan from 'morgan' import winston from 'winston' // Winston logger const logger = winston.createLogger({ level: 'info', format: winston.format.json(), transports: [ new winston.transports.File({ filename: 'error.log', level: 'error' }), new winston.transports.File({ filename: 'combined.log' }) ] }) if (process.env.NODE_ENV !== 'production') { logger.add(new winston.transports.Console({ format: winston.format.simple() })) } // Morgan HTTP logging app.use(morgan('combined', { stream: { write: (message) => logger.info(message.trim()) } })) ``` **Log format:** ``` :remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length] ":referrer" ":user-agent" ``` **Example:** ``` 192.168.1.100 - user@example.com [20/Feb/2026:10:30:15 +0000] "POST /api/v1/invoices HTTP/1.1" 201 512 "https://bilko.io" "Mozilla/5.0..." ``` --- ### Per-Route Middleware Composition ```mermaid graph LR subgraph PUBLIC [Public Routes — No Auth] P1["POST /auth/register\n[rateLimiter(5/min)] → handler"] P2["POST /auth/login\n[rateLimiter(5/min)] → handler"] P3["POST /auth/refresh\n[rateLimiter(100/min)] → handler"] P4["GET /track/email/:id\n[handler — tracking pixel]"] end subgraph VIEWER [Viewer Routes — All Roles] V1["GET /invoices\n[auth] → [orgScope] → handler"] V2["GET /reports/*\n[auth] → [orgScope] → handler"] V3["GET /contacts\n[auth] → [orgScope] → handler"] end subgraph ACCOUNTANT [Accountant+ Routes] A1["POST /invoices\n[auth] → [role:owner,admin,accountant]\n→ [validate] → [orgScope] → handler"] A2["POST /expenses\n[auth] → [role:owner,admin,accountant]\n→ [validate] → handler"] A3["POST /transactions\n[auth] → [role:owner,admin,accountant]\n→ [validate] → handler"] end subgraph ADMIN [Admin+ Routes] AD1["PATCH /expenses/:id/approve\n[auth] → [role:owner,admin] → handler"] AD2["POST /users/invite\n[auth] → [role:owner,admin] → handler"] AD3["PUT /organization\n[auth] → [role:owner,admin] → handler"] end subgraph OWNER [Owner-Only Routes] O1["DELETE /users/:id\n[auth] → [role:owner] → handler"] O2["PUT /users/:id/role\n[auth] → [role:owner] → handler"] O3["DELETE /organization\n[auth] → [role:owner] → handler"] end style PUBLIC fill:#e2e8f0,color:#000 style VIEWER fill:#dcfce7,color:#000 style ACCOUNTANT fill:#fef9c3,color:#000 style ADMIN fill:#dbeafe,color:#000 style OWNER fill:#fce7f3,color:#000 ``` ## 6. Authentication Middleware **Purpose:** Verify JWT access token, attach user to request. **Implementation:** ```typescript import jwt from 'jsonwebtoken' import { Request, Response, NextFunction } from 'express' interface AuthRequest extends Request { user?: { id: string email: string role: 'owner' | 'admin' | 'accountant' | 'viewer' organizationId: string } } export async function authGuard(req: AuthRequest, res: Response, next: NextFunction) { const authHeader = req.headers.authorization if (!authHeader || !authHeader.startsWith('Bearer ')) { return res.status(401).json({ error: 'Unauthorized', code: 'NO_TOKEN' }) } const token = authHeader.substring(7) // Remove 'Bearer ' try { const payload = jwt.verify(token, process.env.JWT_SECRET!) as { sub: string email: string role: string orgId: string } // Attach user to request req.user = { id: payload.sub, email: payload.email, role: payload.role as any, organizationId: payload.orgId } next() } catch (error) { if (error.name === 'TokenExpiredError') { return res.status(401).json({ error: 'Token expired', code: 'TOKEN_EXPIRED' }) } if (error.name === 'JsonWebTokenError') { return res.status(401).json({ error: 'Invalid token', code: 'INVALID_TOKEN' }) } return res.status(500).json({ error: 'Authentication error', code: 'AUTH_ERROR' }) } } ``` **Usage in routes:** ```typescript app.get('/api/v1/invoices', authGuard, getInvoices) ``` --- ## 7. Role-Based Access Control (RBAC) **Purpose:** Restrict endpoints by user role. **Implementation:** ```typescript type UserRole = 'owner' | 'admin' | 'accountant' | 'viewer' export function roleGuard(allowedRoles: UserRole[]) { return (req: AuthRequest, res: Response, next: NextFunction) => { if (!req.user) { return res.status(401).json({ error: 'Unauthorized', code: 'NO_AUTH' }) } if (!allowedRoles.includes(req.user.role)) { return res.status(403).json({ error: 'Forbidden', code: 'INSUFFICIENT_PERMISSIONS', details: { required: allowedRoles, current: req.user.role } }) } next() } } ``` **Usage in routes:** ```typescript // Only owner and admin can delete users app.delete('/api/v1/users/:id', authGuard, roleGuard(['owner', 'admin']), deleteUser ) // Everyone can view invoices app.get('/api/v1/invoices', authGuard, getInvoices ) // Only owner, admin, accountant can create invoices app.post('/api/v1/invoices', authGuard, roleGuard(['owner', 'admin', 'accountant']), createInvoice ) ``` --- ## 8. Request Validation **Purpose:** Validate request body, query, params with Zod schemas. **Installation:** ```bash npm install zod ``` **Implementation:** ```typescript import { z } from 'zod' import { Request, Response, NextFunction } from 'express' type ValidateTarget = 'body' | 'query' | 'params' export function validate(schema: z.ZodSchema, target: ValidateTarget = 'body') { return (req: Request, res: Response, next: NextFunction) => { try { const data = req[target] const validated = schema.parse(data) // Replace with validated data (coerced types) req[target] = validated next() } catch (error) { if (error instanceof z.ZodError) { return res.status(422).json({ error: 'Validation failed', code: 'VALIDATION_ERROR', details: error.flatten().fieldErrors }) } return res.status(500).json({ error: 'Validation error', code: 'VALIDATION_ERROR' }) } } } ``` **Usage in routes:** ```typescript import { z } from 'zod' const createInvoiceSchema = z.object({ customerId: z.string().uuid(), invoiceDate: z.string().date(), dueDate: z.string().date(), items: z.array(z.object({ description: z.string().min(1).max(500), quantity: z.number().positive(), unitPrice: z.number().positive(), taxRate: z.number().min(0).max(100) })).min(1) }) app.post('/api/v1/invoices', authGuard, roleGuard(['owner', 'admin', 'accountant']), validate(createInvoiceSchema, 'body'), createInvoice ) ``` **Error response:** ```json { "error": "Validation failed", "code": "VALIDATION_ERROR", "details": { "customerId": ["Invalid UUID"], "items.0.quantity": ["Must be positive"] } } ``` --- ## 9. Organization Scoping **Purpose:** Automatically filter all queries by `organizationId` to enforce multi-tenancy. **Implementation:** ```typescript export function organizationScope(req: AuthRequest, res: Response, next: NextFunction) { if (!req.user) { return res.status(401).json({ error: 'Unauthorized', code: 'NO_AUTH' }) } // Attach organizationId to request for easy access req.organizationId = req.user.organizationId next() } ``` **Usage in Prisma queries:** ```typescript async function getInvoices(req: AuthRequest, res: Response) { const invoices = await prisma.invoice.findMany({ where: { organizationId: req.user!.organizationId // Always filter by org } }) res.json({ data: invoices }) } ``` **CRITICAL:** NEVER allow cross-organization queries. Always filter by `organizationId`. --- ## 10. Error Handler **Purpose:** Catch all errors, format consistently, log, return to client. **MUST be the last middleware.** ```mermaid flowchart TD ERR[Error Thrown by any Middleware or Handler] ERR --> LOG_ERR[Log to Winston:\nmessage, stack, path, method, userId] LOG_ERR --> TYPE{Error Type?} TYPE -->|PrismaClientKnownRequestError| PRISMA{Prisma Code?} PRISMA -->|P2002 Unique violation| R400A[400 DUPLICATE_RESOURCE\n{field: target}] PRISMA -->|P2003 Foreign key| R404A[404 FOREIGN_KEY_ERROR] PRISMA -->|P2025 Record not found| R404B[404 NOT_FOUND] PRISMA -->|Other| R500[500 INTERNAL_ERROR] TYPE -->|ValidationError| R422[422 VALIDATION_ERROR] TYPE -->|JsonWebTokenError| R401A[401 INVALID_TOKEN] TYPE -->|TokenExpiredError| R401B[401 AUTH_ERROR] TYPE -->|Custom AppError| CUSTOM[err.status / err.code] TYPE -->|Unknown| R500 R400A & R404A & R404B & R422 & R401A & R401B & CUSTOM & R500 --> FORMAT[Format Response:\n{ error, code, details? }] FORMAT --> SEND[Send to Client] style ERR fill:#f87171,color:#fff style R500 fill:#dc2626,color:#fff style FORMAT fill:#60a5fa,color:#000 ``` **Implementation:** ```typescript import { Request, Response, NextFunction } from 'express' import { Prisma } from '@prisma/client' export function errorHandler(err: any, req: Request, res: Response, next: NextFunction) { // Log error logger.error('Error:', { message: err.message, stack: err.stack, path: req.path, method: req.method, user: req.user?.id }) // Prisma errors if (err instanceof Prisma.PrismaClientKnownRequestError) { // Unique constraint violation if (err.code === 'P2002') { return res.status(400).json({ error: 'Resource already exists', code: 'DUPLICATE_RESOURCE', details: { field: err.meta?.target } }) } // Foreign key constraint violation if (err.code === 'P2003') { return res.status(404).json({ error: 'Related resource not found', code: 'FOREIGN_KEY_ERROR' }) } // Record not found if (err.code === 'P2025') { return res.status(404).json({ error: 'Resource not found', code: 'NOT_FOUND' }) } } // Validation errors (already handled by validate middleware) if (err.name === 'ValidationError') { return res.status(422).json({ error: err.message, code: 'VALIDATION_ERROR' }) } // JWT errors (already handled by authGuard) if (err.name === 'JsonWebTokenError' || err.name === 'TokenExpiredError') { return res.status(401).json({ error: 'Authentication failed', code: 'AUTH_ERROR' }) } // Default error res.status(err.status || 500).json({ error: err.message || 'Internal server error', code: err.code || 'INTERNAL_ERROR' }) } ``` **Error response format:** ```json { "error": "Human-readable error message", "code": "MACHINE_READABLE_CODE", "details": { "field": "Additional context" } } ``` --- ## Complete Middleware Stack Example ```typescript import express from 'express' import helmet from 'helmet' import cors from 'cors' import morgan from 'morgan' import rateLimit from 'express-rate-limit' import { authGuard, roleGuard, organizationScope } from './middleware/auth' import { validate } from './middleware/validation' import { errorHandler } from './middleware/error-handler' import routes from './routes' const app = express() // 1. Security headers app.use(helmet(helmetConfig)) // 2. CORS app.use(cors(corsOptions)) // 3. Body parsing app.use(express.json({ limit: '10mb' })) app.use(express.urlencoded({ extended: true })) // 4. Rate limiting app.use('/api/v1', apiLimiter) app.use('/api/v1/auth/login', authLimiter) app.use('/api/v1/auth/register', authLimiter) // 5. Request logging app.use(morgan('combined', { stream: logger.stream })) // 6. Routes app.use('/api/v1', routes) // 7. Error handler (MUST be last) app.use(errorHandler) // Start server const PORT = process.env.PORT || 4000 app.listen(PORT, () => { console.log(`Server running on port ${PORT}`) }) ``` --- ## Middleware Testing **Unit tests for each middleware:** ```typescript import { describe, it, expect } from 'vitest' import request from 'supertest' import app from '../app' describe('Auth Middleware', () => { it('blocks request without token', async () => { const res = await request(app).get('/api/v1/invoices') expect(res.status).toBe(401) expect(res.body.code).toBe('NO_TOKEN') }) it('blocks request with expired token', async () => { const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' const res = await request(app) .get('/api/v1/invoices') .set('Authorization', `Bearer ${expiredToken}`) expect(res.status).toBe(401) expect(res.body.code).toBe('TOKEN_EXPIRED') }) it('allows request with valid token', async () => { const validToken = generateToken({ sub: 'user-id', role: 'owner', orgId: 'org-id' }) const res = await request(app) .get('/api/v1/invoices') .set('Authorization', `Bearer ${validToken}`) expect(res.status).not.toBe(401) }) }) describe('Role Guard', () => { it('blocks accountant from deleting users', async () => { const token = generateToken({ sub: 'user-id', role: 'accountant', orgId: 'org-id' }) const res = await request(app) .delete('/api/v1/users/other-user-id') .set('Authorization', `Bearer ${token}`) expect(res.status).toBe(403) expect(res.body.code).toBe('INSUFFICIENT_PERMISSIONS') }) }) ``` --- **End of Middleware Documentation** # External Services Integration # Bilko External Services > **Status:** SPECIFICATION (backend not implemented) > **Last updated:** 2026-02-20 --- ## Purpose This document specifies the external service integrations for Bilko's backend. Covers email delivery, file storage, exchange rates, and PDF generation. --- ## Service Integration Architecture ```mermaid graph TD subgraph BILKO [Bilko Backend — apps/api] API[Express API\nPort 4000] PDF[PDF Service\nPuppeteer] RATE[Exchange Rate Service\nCron: daily 00:00 UTC] AUDIT[Prisma Middleware\nAudit Logger] end subgraph EXTERNAL [External Services] SG[SendGrid\nnoreply@bilko.io\n100 emails/day free] R2[Cloudflare R2\nbilko-files bucket\n10GB free] ECB[ECB API\nexchangerate.host\nFree, daily rates] FIXER[Fixer.io\n100 req/month free\nFallback] CLAM[ClamAV\nVirus Scanner\nlocalhost:3310] end subgraph STORAGE [Database] PG[PostgreSQL 14+\nAll data\nExchangeRate cache] end API -->|Invoice email + PDF| SG API -->|Receipt upload| R2 PDF -->|Store generated PDF| R2 RATE -->|Primary rates fetch| ECB RATE -->|Fallback if ECB fails| FIXER ECB & FIXER -->|Store in DB| PG API -->|Scan uploaded files| CLAM API -->|All reads/writes| PG AUDIT -->|Append-only log| PG style SG fill:#00b0f0,color:#fff style R2 fill:#f6821f,color:#fff style ECB fill:#0070f3,color:#fff style FIXER fill:#6366f1,color:#fff style PG fill:#336791,color:#fff style CLAM fill:#e53e3e,color:#fff ``` --- ## Table of Contents 1. [SendGrid (Email Delivery)](#sendgrid-email-delivery) 2. [Cloudflare R2 (File Storage)](#cloudflare-r2-file-storage) 3. [Exchange Rate APIs](#exchange-rate-apis) 4. [PDF Generation](#pdf-generation) 5. [Error Handling & Fallbacks](#error-handling--fallbacks) --- ## 1. SendGrid (Email Delivery) ### Purpose Send invoice emails, payment reminders, user invitations, and password resets. ### Invoice Email + Tracking Flow ```mermaid sequenceDiagram participant API as Bilko API participant PDF as PDF Service\n(Puppeteer) participant R2 as Cloudflare R2 participant SG as SendGrid participant CUSTOMER as Customer Email Note over API,CUSTOMER: Invoice Send Flow API->>PDF: generateInvoicePDF(invoiceId) PDF->>PDF: Launch headless Chromium\nRender HTML template\nExport A4 PDF PDF-->>API: PDF Buffer API->>R2: PUT invoices/{orgId}/INV-2026-001.pdf R2-->>API: Public URL stored API->>API: Update invoice.pdfUrl API->>SG: sendEmail({ to, subject, html, attachment:pdf }) SG-->>API: { messageId } API->>API: Update invoice.sentAt, status='sent' SG->>CUSTOMER: Deliver email with PDF attachment CUSTOMER->>API: GET /track/email/{invoiceId}\n[1x1 pixel load] API->>API: UPDATE invoice SET status='viewed'\nviewedAt=now() ``` ### Setup **Account:** SendGrid (free tier: 100 emails/day) **Installation:** ```bash npm install @sendgrid/mail ``` **Environment Variables:** ```bash SENDGRID_API_KEY=SG.xxxxx SENDGRID_FROM_EMAIL=noreply@bilko.io SENDGRID_FROM_NAME=Bilko ``` ### Configuration ```typescript import sgMail from '@sendgrid/mail' sgMail.setApiKey(process.env.SENDGRID_API_KEY!) interface SendEmailOptions { to: string | string[] cc?: string[] bcc?: string[] subject: string text: string html: string attachments?: Array<{ content: string // Base64 encoded filename: string type: string // MIME type disposition: 'attachment' | 'inline' }> } async function sendEmail(options: SendEmailOptions) { const msg = { to: options.to, cc: options.cc, bcc: options.bcc, from: { email: process.env.SENDGRID_FROM_EMAIL!, name: process.env.SENDGRID_FROM_NAME! }, subject: options.subject, text: options.text, html: options.html, attachments: options.attachments } try { const response = await sgMail.send(msg) return { success: true, messageId: response[0].headers['x-message-id'] } } catch (error) { logger.error('SendGrid error:', error) throw new Error('Failed to send email') } } ``` ### Email Templates #### 1. Invoice Email **Template variables:** - `{{ organizationName }}` - `{{ invoiceNumber }}` - `{{ customerName }}` - `{{ totalAmount }}` - `{{ currencyCode }}` - `{{ dueDate }}` - `{{ viewInvoiceUrl }}` **HTML template:** ```html Invoice {{ invoiceNumber }}

{{ organizationName }}

Dear {{ customerName }},

Your invoice {{ invoiceNumber }} is ready.

Amount:{{ totalAmount }} {{ currencyCode }}
Due Date:{{ dueDate }}

View Invoice

Thank you for your business!

Powered by Bilko

``` **Attachment:** Invoice PDF (generated via PDF service) #### 2. User Invitation Email **Template variables:** - `{{ organizationName }}` - `{{ inviterName }}` - `{{ inviteLink }}` - `{{ role }}` **Subject:** `{{ inviterName }} invited you to {{ organizationName }} on Bilko` #### 3. Password Reset Email **Template variables:** - `{{ resetLink }}` - `{{ expiresIn }}` (e.g., "15 minutes") **Subject:** `Reset your Bilko password` ### Email Tracking **Purpose:** Track when customer views invoice email (for `viewedAt` timestamp). **How it works:** 1. Embed 1x1 transparent pixel in email HTML 2. Pixel URL: `https://api.bilko.io/track/email/{{ invoiceId }}` 3. When customer opens email, browser loads pixel 4. Backend endpoint logs view: ```typescript app.get('/track/email/:invoiceId', async (req, res) => { const { invoiceId } = req.params await prisma.invoice.update({ where: { id: invoiceId }, data: { status: 'viewed', viewedAt: new Date() } }) // Return 1x1 transparent GIF const pixel = Buffer.from( 'R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7', 'base64' ) res.writeHead(200, { 'Content-Type': 'image/gif', 'Content-Length': pixel.length }) res.end(pixel) }) ``` ### Rate Limits **SendGrid free tier:** - 100 emails/day - 40,000 emails first 30 days - After 30 days: $0.00025/email **Recommendation for MVP:** Free tier sufficient for testing. Upgrade to paid plan at launch. --- ## 2. Cloudflare R2 (File Storage) ### Purpose Store invoice PDFs and expense receipts. **Why R2 over S3:** - S3-compatible API (easy migration) - Zero egress fees (S3 charges $0.09/GB) - Cheaper storage: $0.015/GB (vs S3 $0.023/GB) ### Setup **Account:** Cloudflare (free tier: 10GB storage) **Installation:** ```bash npm install @aws-sdk/client-s3 npm install @aws-sdk/s3-request-presigner ``` **Environment Variables:** ```bash R2_ACCOUNT_ID=your-account-id R2_ACCESS_KEY_ID=your-access-key R2_SECRET_ACCESS_KEY=your-secret-key R2_BUCKET_NAME=bilko-files R2_PUBLIC_URL=https://r2.bilko.io ``` ### Configuration ```typescript import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3' import { getSignedUrl } from '@aws-sdk/s3-request-presigner' const s3 = new S3Client({ region: 'auto', endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`, credentials: { accessKeyId: process.env.R2_ACCESS_KEY_ID!, secretAccessKey: process.env.R2_SECRET_ACCESS_KEY! } }) interface UploadFileOptions { key: string // File path (e.g., "invoices/INV-2026-001.pdf") body: Buffer | Uint8Array contentType: string // MIME type metadata?: Record } async function uploadFile(options: UploadFileOptions): Promise { const command = new PutObjectCommand({ Bucket: process.env.R2_BUCKET_NAME!, Key: options.key, Body: options.body, ContentType: options.contentType, Metadata: options.metadata }) await s3.send(command) // Return public URL return `${process.env.R2_PUBLIC_URL}/${options.key}` } async function getSignedDownloadUrl(key: string, expiresIn: number = 3600): Promise { const command = new GetObjectCommand({ Bucket: process.env.R2_BUCKET_NAME!, Key: key }) return getSignedUrl(s3, command, { expiresIn }) } ``` ### File Organization **Bucket structure:** ``` bilko-files/ ├── invoices/ │ ├── org-uuid-1/ │ │ ├── INV-2026-001.pdf │ │ └── INV-2026-002.pdf │ └── org-uuid-2/ │ └── INV-2026-001.pdf ├── receipts/ │ ├── org-uuid-1/ │ │ ├── EXP-2026-001.jpg │ │ └── EXP-2026-002.pdf │ └── org-uuid-2/ └── exports/ └── org-uuid-1/ └── report-2026-02-20.xlsx ``` **Key format:** `{category}/{organizationId}/{filename}` ### File Upload Workflow **Invoice PDF:** ```typescript async function storeInvoicePDF(invoiceId: string, organizationId: string, pdf: Buffer): Promise { const invoice = await prisma.invoice.findUnique({ where: { id: invoiceId } }) const filename = `${invoice.invoiceNumber}.pdf` const key = `invoices/${organizationId}/${filename}` const url = await uploadFile({ key, body: pdf, contentType: 'application/pdf', metadata: { invoiceId, organizationId, uploadedAt: new Date().toISOString() } }) await prisma.invoice.update({ where: { id: invoiceId }, data: { pdfUrl: url } }) return url } ``` **Expense Receipt:** ```typescript async function storeExpenseReceipt(expenseId: string, organizationId: string, file: Express.Multer.File): Promise { const expense = await prisma.expense.findUnique({ where: { id: expenseId } }) const ext = file.mimetype.split('/')[1] // 'pdf', 'jpeg', 'png' const filename = `${expense.expenseNumber}.${ext}` const key = `receipts/${organizationId}/${filename}` const url = await uploadFile({ key, body: file.buffer, contentType: file.mimetype, metadata: { expenseId, organizationId, uploadedAt: new Date().toISOString() } }) await prisma.expense.update({ where: { id: expenseId }, data: { receiptUrl: url } }) return url } ``` ### Security **1. Signed URLs for private files:** - Invoice PDFs: public (anyone with URL can view) - Expense receipts: private (require signed URL) - Signed URLs expire in 1 hour **2. Virus scanning:** - Use ClamAV to scan uploaded files - Reject if virus detected ```bash npm install clamscan ``` ```typescript import NodeClam from 'clamscan' const clam = await new NodeClam().init({ clamdscan: { host: 'localhost', port: 3310 } }) async function scanFile(filePath: string): Promise { const { isInfected } = await clam.scanFile(filePath) return !isInfected } ``` --- ## 3. Exchange Rate APIs ### Purpose Fetch daily exchange rates for multi-currency support. ### Exchange Rate Fetch & Fallback Flow ```mermaid flowchart TD CRON[Cron Job\nDaily at 00:00 UTC] CRON --> ECB[Fetch from ECB API\nexchangerate.host/latest?base=EUR] ECB --> ECB_OK{Success?} ECB_OK -->|Yes| STORE[Upsert ExchangeRate records\nsource='ECB'] ECB_OK -->|No| FIXER[Fallback: Fixer.io\napi.fixer.io/latest] FIXER --> FIX_OK{Success?} FIX_OK -->|Yes| STORE2[Upsert ExchangeRate records\nsource='fixer.io'] FIX_OK -->|No| PREV[Use yesterday's rates\nWarn in logs] STORE & STORE2 & PREV --> AVAIL[Rates available in DB\nfor transaction date locking] subgraph LOOKUP [Rate Lookup at Transaction Time] L1[getExchangeRate\nbaseCurrency, targetCurrency, date] L2{Same currency?} L3[Return rate = 1.0] L4[Find exact date in DB] L5{Found?} L6[Return rate] L7[Find nearest available date\norderBy effectiveDate DESC] L8[Warn in logs\nReturn nearest rate] L1 --> L2 L2 -->|Yes| L3 L2 -->|No| L4 L4 --> L5 L5 -->|Yes| L6 L5 -->|No| L7 L7 --> L8 end AVAIL --> LOOKUP style PREV fill:#fb923c,color:#000 style L8 fill:#fb923c,color:#000 ``` ### Primary: European Central Bank (ECB) **Endpoint:** `https://api.exchangerate.host/latest` **Free:** Yes (unlimited) **Example:** ```typescript async function fetchECBRates(baseCurrency: string = 'EUR'): Promise> { const url = `https://api.exchangerate.host/latest?base=${baseCurrency}` const response = await fetch(url) const data = await response.json() if (!data.success) { throw new Error('ECB API error') } return data.rates // { RSD: 117.50, BAM: 1.95, HRK: 7.53, USD: 1.07 } } ``` ### Fallback: Fixer.io **Endpoint:** `https://api.fixer.io/latest` **Free tier:** 100 requests/month **Environment Variables:** ```bash FIXER_API_KEY=your-api-key ``` **Example:** ```typescript async function fetchFixerRates(baseCurrency: string = 'EUR'): Promise> { const url = `https://api.fixer.io/latest?base=${baseCurrency}&access_key=${process.env.FIXER_API_KEY}` const response = await fetch(url) const data = await response.json() if (!data.success) { throw new Error('Fixer.io API error') } return data.rates } ``` ### Exchange Rate Service ```typescript async function updateExchangeRates(): Promise { try { // Try ECB first const rates = await fetchECBRates('EUR') // Store in database for (const [targetCurrency, rate] of Object.entries(rates)) { await prisma.exchangeRate.upsert({ where: { baseCurrency_targetCurrency_effectiveDate: { baseCurrency: 'EUR', targetCurrency, effectiveDate: new Date() } }, update: { rate, source: 'ECB', lastUpdated: new Date() }, create: { baseCurrency: 'EUR', targetCurrency, rate, effectiveDate: new Date(), source: 'ECB' } }) } logger.info('Exchange rates updated', { source: 'ECB', count: Object.keys(rates).length }) } catch (error) { // Fallback to Fixer.io try { const rates = await fetchFixerRates('EUR') for (const [targetCurrency, rate] of Object.entries(rates)) { await prisma.exchangeRate.upsert({ where: { baseCurrency_targetCurrency_effectiveDate: { baseCurrency: 'EUR', targetCurrency, effectiveDate: new Date() } }, update: { rate, source: 'fixer.io', lastUpdated: new Date() }, create: { baseCurrency: 'EUR', targetCurrency, rate, effectiveDate: new Date(), source: 'fixer.io' } }) } logger.info('Exchange rates updated', { source: 'fixer.io', count: Object.keys(rates).length }) } catch (fallbackError) { logger.error('Failed to update exchange rates', { error: fallbackError }) // Use yesterday's rates (better than nothing) } } } // Schedule: Daily at 00:00 UTC cron.schedule('0 0 * * *', updateExchangeRates) ``` ### Get Exchange Rate ```typescript async function getExchangeRate( baseCurrency: string, targetCurrency: string, date: Date = new Date() ): Promise { // If same currency, rate = 1.0 if (baseCurrency === targetCurrency) { return 1.0 } // Find rate for exact date let rate = await prisma.exchangeRate.findUnique({ where: { baseCurrency_targetCurrency_effectiveDate: { baseCurrency, targetCurrency, effectiveDate: date } } }) // If not found, use nearest available rate if (!rate) { rate = await prisma.exchangeRate.findFirst({ where: { baseCurrency, targetCurrency }, orderBy: { effectiveDate: 'desc' } }) } if (!rate) { throw new Error(`No exchange rate found for ${baseCurrency} → ${targetCurrency}`) } return parseFloat(rate.rate.toString()) } ``` --- ## 4. PDF Generation ### Purpose Generate invoice PDFs with organization branding. ### Option 1: Puppeteer (Server-Side Rendering) **Installation:** ```bash npm install puppeteer ``` **Implementation:** ```typescript import puppeteer from 'puppeteer' async function generateInvoicePDF(invoiceId: string): Promise { const invoice = await prisma.invoice.findUnique({ where: { id: invoiceId }, include: { customer: true, organization: true, items: true } }) // Render HTML template const html = renderInvoiceHTML(invoice) // Launch headless browser const browser = await puppeteer.launch({ headless: true, args: ['--no-sandbox', '--disable-setuid-sandbox'] }) const page = await browser.newPage() await page.setContent(html, { waitUntil: 'networkidle0' }) // Generate PDF const pdf = await page.pdf({ format: 'A4', printBackground: true, margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' } }) await browser.close() return pdf } ``` ### Option 2: @react-pdf/renderer (React Components) **Installation:** ```bash npm install @react-pdf/renderer ``` **Implementation:** ```typescript import { Document, Page, Text, View, StyleSheet, pdf } from '@react-pdf/renderer' const styles = StyleSheet.create({ page: { padding: 30 }, header: { fontSize: 24, marginBottom: 20 }, table: { display: 'table', width: '100%' }, row: { flexDirection: 'row', borderBottomWidth: 1, borderColor: '#ddd' }, cell: { padding: 10 } }) function InvoicePDF({ invoice }) { return ( {invoice.organization.name} Invoice {invoice.invoiceNumber} {invoice.items.map((item) => ( {item.description} {item.quantity} {item.unitPrice} {item.lineTotal} ))} ) } async function generateInvoicePDF(invoiceId: string): Promise { const invoice = await fetchInvoiceData(invoiceId) const doc = const pdfBlob = await pdf(doc).toBlob() return Buffer.from(await pdfBlob.arrayBuffer()) } ``` **Recommendation:** Puppeteer for MVP (more flexible HTML/CSS), React PDF for v2 (better TypeScript support). --- ## 5. Error Handling & Fallbacks ### Circuit Breaker & Retry Pattern ```mermaid stateDiagram-v2 [*] --> closed : Initial state closed --> open : failures >= threshold (5)\nService marked as unavailable open --> half_open : timeout elapsed (60s)\nAttempt single test call half_open --> closed : Test call succeeded\nReset failure count half_open --> open : Test call failed\nReset timeout note right of closed Normal operation All calls pass through Failures counted end note note right of open All calls REJECTED immediately Error: "Circuit breaker is open" No calls to external service end note note right of half_open Single probe call allowed Determines if service recovered end note ``` ### Retry Strategy **For transient errors (network timeouts, rate limits):** ```typescript async function withRetry( fn: () => Promise, maxRetries: number = 3, delay: number = 1000 ): Promise { for (let i = 0; i < maxRetries; i++) { try { return await fn() } catch (error) { if (i === maxRetries - 1) throw error logger.warn(`Retry ${i + 1}/${maxRetries}`, { error }) await new Promise((resolve) => setTimeout(resolve, delay * (i + 1))) } } throw new Error('Retry limit exceeded') } // Usage const rates = await withRetry(() => fetchECBRates('EUR')) ``` ### Circuit Breaker **For external services that frequently fail:** ```typescript class CircuitBreaker { private failures = 0 private threshold = 5 private timeout = 60000 // 1 minute private state: 'closed' | 'open' | 'half-open' = 'closed' private nextAttempt = 0 async execute(fn: () => Promise): Promise { if (this.state === 'open') { if (Date.now() < this.nextAttempt) { throw new Error('Circuit breaker is open') } this.state = 'half-open' } try { const result = await fn() this.onSuccess() return result } catch (error) { this.onFailure() throw error } } private onSuccess() { this.failures = 0 this.state = 'closed' } private onFailure() { this.failures++ if (this.failures >= this.threshold) { this.state = 'open' this.nextAttempt = Date.now() + this.timeout logger.warn('Circuit breaker opened', { failures: this.failures }) } } } const sendGridBreaker = new CircuitBreaker() async function sendEmailWithBreaker(options: SendEmailOptions) { return sendGridBreaker.execute(() => sendEmail(options)) } ``` ### Graceful Degradation **If external service fails, degrade gracefully:** **Example: Invoice email delivery** ```typescript async function sendInvoiceEmail(invoiceId: string) { try { await sendEmail({ /* ... */ }) await prisma.invoice.update({ where: { id: invoiceId }, data: { sentAt: new Date(), status: 'sent' } }) } catch (error) { logger.error('Failed to send invoice email', { invoiceId, error }) // Fallback: Mark invoice as sent but flag for manual email await prisma.invoice.update({ where: { id: invoiceId }, data: { status: 'draft', // Keep in draft notes: `Email delivery failed: ${error.message}. Please send manually.` } }) // Alert admin await sendSlackAlert('Invoice email delivery failed', { invoiceId }) } } ``` --- ## Environment Variables Summary ```bash # SendGrid SENDGRID_API_KEY=SG.xxxxx SENDGRID_FROM_EMAIL=noreply@bilko.io SENDGRID_FROM_NAME=Bilko # Cloudflare R2 R2_ACCOUNT_ID=your-account-id R2_ACCESS_KEY_ID=your-access-key R2_SECRET_ACCESS_KEY=your-secret-key R2_BUCKET_NAME=bilko-files R2_PUBLIC_URL=https://r2.bilko.io # Fixer.io (fallback) FIXER_API_KEY=your-api-key # Feature Flags ENABLE_EMAIL_TRACKING=true ENABLE_VIRUS_SCANNING=false # For MVP ``` --- **End of Services Documentation** # API Coverage Report # API Coverage Report **Date:** 2026-02-20 **Purpose:** Map every frontend page to required API endpoints. Verify 100% coverage. **Status:** Backend NOT implemented (specification only) --- ## Coverage Matrix ### Dashboard Page (/) | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Cash Balance metric | Total bank account balances in base currency | GET /api/v1/reports/dashboard | COVERED | | Revenue MTD metric | Month-to-date revenue | GET /api/v1/reports/dashboard | COVERED | | Unpaid Invoices metric | Total unpaid invoices | GET /api/v1/reports/dashboard | COVERED | | Expenses MTD metric | Month-to-date expenses | GET /api/v1/reports/dashboard | COVERED | | Profit MTD metric | Month-to-date profit | GET /api/v1/reports/dashboard | COVERED | | Cash Flow Change | Percentage change from last month | GET /api/v1/reports/dashboard | COVERED | | P&L Bar Chart | 6-month monthly P&L data | GET /api/v1/reports/dashboard | COVERED | | Receivables Aging Chart | Receivables breakdown by age (current, 30d, 60d, 90d+) | GET /api/v1/reports/dashboard | COVERED | | Expenses by Category Chart | Expenses grouped by category | GET /api/v1/reports/dashboard | COVERED | | Recent Transactions table | Last 5 transactions | GET /api/v1/transactions?perPage=5&sort=transactionDate&order=desc | COVERED | --- ### Invoices List Page (/invoices) | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Invoice list (all filters) | Paginated invoices with filter/sort/search | GET /api/v1/invoices?status=X&search=Y&fromDate=Z&toDate=W&page=P&perPage=20&sort=field&order=desc | COVERED | | Status filter options | Invoice list filtered by status | GET /api/v1/invoices?status={draft\|sent\|viewed\|paid\|overdue\|cancelled} | COVERED | | Search (customer/number) | Invoice list filtered by search query | GET /api/v1/invoices?search={query} | COVERED | | Date range filter | Invoice list filtered by date range | GET /api/v1/invoices?fromDate=YYYY-MM-DD&toDate=YYYY-MM-DD | COVERED | | Summary totals by status | Client-side calculation from filtered list | N/A (client-side) | COVERED | | Edit invoice action | Get invoice details for editing | GET /api/v1/invoices/:id | COVERED | | Delete invoice action | Delete invoice | DELETE /api/v1/invoices/:id | MISSING | | Send invoice action | Send invoice via email | POST /api/v1/invoices/:id/send | COVERED | | Download PDF action | Get invoice PDF | GET /api/v1/invoices/:id/pdf | COVERED | **MISSING ENDPOINT:** - **DELETE /api/v1/invoices/:id** — Delete invoice (only draft invoices should be deletable) - Method: DELETE - Auth: Bearer token - Roles: owner, admin, accountant - Rate limit: 10 req/min - Response: 204 No Content - Errors: - 400 — Invoice is not in draft status - 404 — Invoice not found --- ### Invoice Creation Wizard (/invoices/new) | Step | UI Element | Data Required | API Endpoint | Status | |------|-----------|--------------|-------------|--------| | 1 | Customer dropdown | List of customers | GET /api/v1/contacts?type=customer | COVERED | | 1 | Add customer dialog | Create new customer | POST /api/v1/contacts | COVERED | | 2 | Invoice number | Auto-generated invoice number | Client-side generation (format: INV-YYYY-NNN) | COVERED | | 2 | Currency options | List of supported currencies | GET /api/v1/currencies | COVERED | | 3 | Line items | Form input (no API needed) | N/A | COVERED | | 3 | VAT rate options | Tax rate configuration | GET /api/v1/settings/tax-rates | COVERED | | 4 | Notes/Terms | Form input (no API needed) | N/A | COVERED | | 5 | Preview | Client-side rendering of form data | N/A | COVERED | | 6 | Save as Draft | Create invoice with status=draft | POST /api/v1/invoices | COVERED | | 6 | Send Invoice | Create + send invoice | POST /api/v1/invoices (then) POST /api/v1/invoices/:id/send | COVERED | | 6 | Download PDF | Generate PDF | GET /api/v1/invoices/:id/pdf | COVERED | --- ### Expenses List Page (/expenses) | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Expense list | Paginated expenses with filters | GET /api/v1/expenses?period=X&category=Y&search=Z&page=P&perPage=20 | COVERED | | Period filter | Expenses filtered by date range | GET /api/v1/expenses?fromDate=YYYY-MM-DD&toDate=YYYY-MM-DD | COVERED | | Category filter | Expenses filtered by category | GET /api/v1/expenses?category={category} | COVERED | | Search (description/vendor) | Expenses filtered by search query | GET /api/v1/expenses (client-side search on fetched data) | COVERED | | Summary stats | Client-side calculation from filtered list | N/A (client-side) | COVERED | | Create expense | Create new expense | POST /api/v1/expenses | COVERED | | Upload receipt | Upload receipt file | POST /api/v1/expenses (multipart with receiptFile) | COVERED | | Edit expense | Update expense (pending only) | PUT /api/v1/expenses/:id | COVERED | | Approve expense | Approve expense | PATCH /api/v1/expenses/:id/approve | COVERED | | Delete expense | Delete expense (pending only) | DELETE /api/v1/expenses/:id | COVERED | | Download receipt | Get receipt file | GET /api/v1/expenses/:id/receipt | MISSING | **MISSING ENDPOINT:** - **GET /api/v1/expenses/:id/receipt** — Download expense receipt - Method: GET - Auth: Bearer token - Roles: All - Rate limit: 100 req/min - Response: 200 OK - Content-Type: image/jpeg, image/png, or application/pdf - Content-Disposition: attachment; filename="receipt-{expenseNumber}.{ext}" - Errors: - 404 — Expense or receipt not found --- ### Purchases Page (/purchases) | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | (Same as /expenses) | Same data as expenses page | Same as /expenses | COVERED | **Note:** This is an alias route to the expenses page. No additional API endpoints needed. --- ### Banking Page (/banking) #### Accounts Tab | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Bank account list | List of bank accounts | GET /api/v1/bank-accounts | COVERED | | Add bank account | Create new bank account | POST /api/v1/bank-accounts | COVERED | | Account balance | Current balance per account | GET /api/v1/bank-accounts (included in response) | COVERED | #### Reconcile Tab | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Account selector | List of bank accounts | GET /api/v1/bank-accounts | COVERED | | Unreconciled transactions | Unreconciled bank transactions for selected account | GET /api/v1/bank-accounts/:id/transactions?reconciled=false | COVERED | | Match confidence | Client-side calculation based on amount/date/description | N/A (client-side) | COVERED | | Approve match | Mark transaction as reconciled | POST /api/v1/bank-accounts/:id/reconcile | COVERED | | Link to invoice/expense | Link bank transaction to existing record | POST /api/v1/bank-accounts/:id/reconcile (with transactionId) | COVERED | | Create new transaction | Create GL transaction from unmatched bank transaction | POST /api/v1/transactions | COVERED | #### Transactions Tab | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | All bank transactions | All bank transactions (paginated) | GET /api/v1/bank-accounts/:id/transactions | COVERED | | Reconciliation status filter | Bank transactions filtered by reconciled status | GET /api/v1/bank-accounts/:id/transactions?reconciled={true\|false} | COVERED | | Date range filter | Bank transactions filtered by date | GET /api/v1/bank-accounts/:id/transactions?fromDate=X&toDate=Y | COVERED | #### Import Transactions | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Import CSV | Upload bank statement CSV | POST /api/v1/bank-accounts/:id/import | COVERED | --- ### Reports Hub Page (/reports) | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | P&L Report preview | Profit & Loss data for current month | GET /api/v1/reports/profit-loss?from=YYYY-MM-01&to=YYYY-MM-DD | COVERED | | Balance Sheet preview | Balance sheet data (coming soon) | GET /api/v1/reports/balance-sheet?date=YYYY-MM-DD | COVERED | | Cash Flow preview | Cash flow data (coming soon) | GET /api/v1/reports/cash-flow?from=X&to=Y | COVERED | | VAT Report preview | VAT report data (live at /reports/vat) | GET /api/v1/reports/vat?from=X&to=Y | COVERED | | Trial Balance preview | Trial balance data (coming soon) | GET /api/v1/reports/trial-balance?date=YYYY-MM-DD | COVERED | | General Ledger preview | Transaction list (coming soon) | GET /api/v1/transactions | COVERED | --- ### VAT Report Page (/reports/vat) | Step | UI Element | Data Required | API Endpoint | Status | |------|-----------|--------------|-------------|--------| | 1 | Reconciliation status check | Count of unreconciled bank transactions | GET /api/v1/bank-accounts (aggregate unreconciled count client-side) | PARTIAL | | 2 | VAT transaction table | All invoices and expenses with VAT for period | GET /api/v1/reports/vat?from=X&to=Y | COVERED | | 2 | Summary boxes (collected/paid/due) | Calculated from VAT transaction data | GET /api/v1/reports/vat?from=X&to=Y | COVERED | | 3 | VAT return boxes | Formatted VAT return data | GET /api/v1/reports/vat?from=X&to=Y | COVERED | | 3 | Export PDF | Generate PDF report | GET /api/v1/reports/vat/export/pdf?from=X&to=Y | MISSING | | 3 | Export XML | Generate XML for e-filing | GET /api/v1/reports/vat/export/xml?from=X&to=Y | MISSING | | 3 | Submit return | Submit VAT return (Phase 2) | POST /api/v1/reports/vat/submit | MISSING | **MISSING ENDPOINTS:** - **GET /api/v1/reports/vat/export/pdf** — Export VAT report as PDF - Method: GET - Auth: Bearer token - Roles: All - Query: from (ISO date), to (ISO date) - Rate limit: 50 req/min - Response: 200 OK - Content-Type: application/pdf - Content-Disposition: attachment; filename="vat-report-{from}-{to}.pdf" - Errors: 422 — Invalid date range - **GET /api/v1/reports/vat/export/xml** — Export VAT report as XML for e-filing - Method: GET - Auth: Bearer token - Roles: All - Query: from (ISO date), to (ISO date) - Rate limit: 50 req/min - Response: 200 OK - Content-Type: application/xml - Content-Disposition: attachment; filename="vat-return-{from}-{to}.xml" - Errors: 422 — Invalid date range - **POST /api/v1/reports/vat/submit** — Submit VAT return to tax authority (Phase 2) - Method: POST - Auth: Bearer token - Roles: owner, admin, accountant - Rate limit: 5 req/min - Request: ```typescript interface SubmitVATRequest { period: string // ISO date range, e.g., "2026-02" confirmationEmail: string } ``` - Response: 201 Created ```typescript interface SubmitVATResponse { submissionId: string submittedAt: string status: 'pending' | 'accepted' | 'rejected' confirmationNumber: string | null } ``` - Errors: 400 — VAT period already submitted **PARTIAL COVERAGE:** - Reconciliation status check requires aggregating unreconciled count from GET /api/v1/bank-accounts response. Consider dedicated endpoint: - **GET /api/v1/bank-accounts/unreconciled-count** - Returns: `{ total: number, byAccount: Array<{accountId: string, count: number}> }` --- ### Settings Page (/settings) #### Company Section | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Company profile form | Organization data | GET /api/v1/organization | COVERED | | Save company profile | Update organization | PUT /api/v1/organization | COVERED | #### Users Section | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | User list | List of users in organization | GET /api/v1/users | COVERED | | Invite user | Send user invite | POST /api/v1/users/invite | COVERED | | Change user role | Update user role | PUT /api/v1/users/:id/role | COVERED | | Remove user | Delete user | DELETE /api/v1/users/:id | COVERED | #### Tax & Compliance Section | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Tax settings form | Tax rate configuration | GET /api/v1/settings/tax-rates | COVERED | | Save tax settings | Update tax rates | PUT /api/v1/settings/tax-rates | COVERED | | VAT registration toggle | Update organization (vatNumber field) | PUT /api/v1/organization | COVERED | #### Integrations Section | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Connected integrations | List of integrations | GET /api/v1/integrations | MISSING | | Available integrations | List of integrations | GET /api/v1/integrations | MISSING | | Connect integration | Connect to integration | POST /api/v1/integrations/:id/connect | MISSING | | Disconnect integration | Disconnect integration | DELETE /api/v1/integrations/:id/disconnect | MISSING | **MISSING ENDPOINTS (Integrations):** All integration-related endpoints are missing. These should be Phase 2, but placeholders needed: - **GET /api/v1/integrations** — List integrations - Method: GET - Auth: Bearer token - Roles: All - Response: 200 OK ```typescript interface IntegrationsResponse { connected: Array<{ id: string name: string type: string status: 'active' | 'inactive' | 'error' connectedAt: string lastSync: string | null }> available: Array<{ id: string name: string type: string description: string icon: string }> } ``` - **POST /api/v1/integrations/:id/connect** — Connect integration - Method: POST - Auth: Bearer token - Roles: owner, admin - Request body varies by integration type - Response: 201 Created - **DELETE /api/v1/integrations/:id/disconnect** — Disconnect integration - Method: DELETE - Auth: Bearer token - Roles: owner, admin - Response: 204 No Content #### Notifications Section | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Notification preferences | User notification settings | GET /api/v1/settings/notifications | MISSING | | Save preferences | Update notification settings | PATCH /api/v1/settings/notifications | MISSING | **MISSING ENDPOINTS (Notifications):** - **GET /api/v1/settings/notifications** — Get notification preferences - Method: GET - Auth: Bearer token - Roles: All - Response: 200 OK ```typescript interface NotificationSettings { email: { invoicePaid: boolean invoiceOverdue: boolean expenseApproved: boolean bankAccountSynced: boolean } inApp: { invoiceUpdates: boolean expenseUpdates: boolean reconciliationMatches: boolean } } ``` - **PATCH /api/v1/settings/notifications** — Update notification preferences - Method: PATCH - Auth: Bearer token - Roles: All - Request: Same as GET response (partial updates allowed) - Response: 200 OK (updated settings) #### Security Section | UI Element | Data Required | API Endpoint | Status | |-----------|--------------|-------------|--------| | Enable 2FA | Enable 2FA for user | POST /api/v1/auth/2fa/enable | MISSING | | Disable 2FA | Disable 2FA for user | DELETE /api/v1/auth/2fa/disable | MISSING | | Session timeout | User/org settings | GET /api/v1/settings/security | MISSING | | Save security settings | Update security settings | PATCH /api/v1/settings/security | MISSING | | View audit log | Audit trail | GET /api/v1/security/audit-log | MISSING | | Request data export | Export all data | POST /api/v1/security/data-export | MISSING | | Delete company | Delete organization | DELETE /api/v1/organization | MISSING | **MISSING ENDPOINTS (Security):** - **POST /api/v1/auth/2fa/enable** — Enable 2FA - Response: QR code + backup codes - **DELETE /api/v1/auth/2fa/disable** — Disable 2FA - Requires current password confirmation - **GET /api/v1/settings/security** — Get security settings - Returns: session timeout, password policy, etc. - **PATCH /api/v1/settings/security** — Update security settings - **GET /api/v1/security/audit-log** — Get audit log (paginated) - Query: fromDate, toDate, userId, action, tableName - Response: Paginated list of LoggedAction records - **POST /api/v1/security/data-export** — Request GDPR data export - Response: Job ID, email sent when ready - **DELETE /api/v1/organization** — Delete organization (danger zone) - Requires password confirmation - Cascades to all related data --- ## Forms → API Mapping | Form | Submit Action | API Endpoint | Request Body | Status | |------|-------------|-------------|-------------|--------| | Create Invoice (Step 6) | POST | POST /api/v1/invoices | CreateInvoiceRequest | COVERED | | Send Invoice (Step 6) | POST | POST /api/v1/invoices/:id/send | SendInvoiceRequest | COVERED | | Add Customer (Wizard Step 1) | POST | POST /api/v1/contacts | CreateContactRequest | COVERED | | Create Expense (Dialog) | POST | POST /api/v1/expenses | CreateExpenseRequest (multipart) | COVERED | | Upload Receipt (Expense Dialog) | POST | POST /api/v1/expenses (multipart receiptFile) | File upload | COVERED | | Update Company Profile | PUT | PUT /api/v1/organization | UpdateOrganizationRequest | COVERED | | Update Tax Settings | PUT | PUT /api/v1/settings/tax-rates | UpdateTaxRatesRequest | COVERED | | Invite User | POST | POST /api/v1/users/invite | InviteUserRequest | COVERED | | Change User Role | PUT | PUT /api/v1/users/:id/role | ChangeRoleRequest | COVERED | | Import Bank Statement | POST | POST /api/v1/bank-accounts/:id/import | CSV file upload | COVERED | | Create Manual Transaction | POST | POST /api/v1/transactions | CreateTransactionRequest | COVERED | | Update Notification Preferences | PATCH | PATCH /api/v1/settings/notifications | NotificationSettings | MISSING | | Update Security Settings | PATCH | PATCH /api/v1/settings/security | SecuritySettings | MISSING | | Connect Integration | POST | POST /api/v1/integrations/:id/connect | Integration-specific | MISSING | | Submit VAT Return | POST | POST /api/v1/reports/vat/submit | SubmitVATRequest | MISSING | --- ## Coverage Summary | Page | Endpoints Required | Endpoints Documented | Coverage | |------|-------------------|---------------------|----------| | Dashboard | 2 | 2 | 100% | | Invoices List | 6 | 5 | 83% (missing DELETE) | | Invoice Wizard | 6 | 6 | 100% | | Expenses | 7 | 6 | 86% (missing receipt download) | | Purchases | 7 | 6 | 86% (same as expenses) | | Banking | 7 | 7 | 100% | | Reports Hub | 6 | 6 | 100% | | VAT Report | 7 | 4 | 57% (missing PDF/XML export, submit) | | Settings - Company | 2 | 2 | 100% | | Settings - Users | 4 | 4 | 100% | | Settings - Tax | 2 | 2 | 100% | | Settings - Integrations | 3 | 0 | 0% (Phase 2) | | Settings - Notifications | 2 | 0 | 0% (missing) | | Settings - Security | 6 | 0 | 0% (missing) | | **TOTAL** | **67** | **50** | **75%** | --- ## Missing Endpoints ### High Priority (Core Features) 1. **DELETE /api/v1/invoices/:id** — Delete invoice (draft only) - Reason: Invoice list has delete action 2. **GET /api/v1/expenses/:id/receipt** — Download expense receipt - Reason: Expense list shows receipt indicator, needs download link 3. **GET /api/v1/reports/vat/export/pdf** — VAT report PDF export - Reason: VAT report has export button (placeholder currently) 4. **GET /api/v1/reports/vat/export/xml** — VAT report XML export (e-filing) - Reason: VAT report has export button (placeholder currently) ### Medium Priority (Settings) 5. **GET /api/v1/settings/notifications** — Get notification preferences - Reason: Settings page has notification section with checkboxes 6. **PATCH /api/v1/settings/notifications** — Update notification preferences - Reason: Settings page has save button for notification preferences 7. **GET /api/v1/settings/security** — Get security settings - Reason: Settings page has security section (session timeout, password policy) 8. **PATCH /api/v1/settings/security** — Update security settings - Reason: Settings page has save button for security settings 9. **GET /api/v1/security/audit-log** — Audit log - Reason: Settings security section has "View Audit Log" button 10. **POST /api/v1/security/data-export** — GDPR data export - Reason: Settings security section has "Request Data Export" button 11. **DELETE /api/v1/organization** — Delete company - Reason: Settings security section has "Delete Company" button (danger zone) 12. **POST /api/v1/auth/2fa/enable** — Enable 2FA - Reason: Settings security section has "Enable 2FA" button 13. **DELETE /api/v1/auth/2fa/disable** — Disable 2FA - Reason: Settings security section needs disable option if 2FA enabled ### Low Priority (Phase 2 Features) 14. **GET /api/v1/integrations** — List integrations - Reason: Settings integrations section (Phase 2) 15. **POST /api/v1/integrations/:id/connect** — Connect integration - Reason: Settings integrations section (Phase 2) 16. **DELETE /api/v1/integrations/:id/disconnect** — Disconnect integration - Reason: Settings integrations section (Phase 2) 17. **POST /api/v1/reports/vat/submit** — Submit VAT return - Reason: VAT report has submit button (explicitly marked "Coming in Phase 2") 18. **GET /api/v1/bank-accounts/unreconciled-count** — Unreconciled transaction count - Reason: VAT report Step 1 checks reconciliation status (currently client-side aggregation, could be dedicated endpoint) --- ## Redundant Endpoints None identified. All endpoints in API-REFERENCE.md are consumed by at least one frontend page. --- ## Recommendations ### 1. Add Missing Core Endpoints **Priority:** HIGH **Scope:** Endpoints 1-4 from Missing Endpoints list These are referenced directly in existing UI actions. Without them, users will encounter broken functionality: - Delete invoice button will not work - Receipt download links will not work - VAT export buttons will not work **Implementation Order:** 1. DELETE /api/v1/invoices/:id (simplest, no business logic) 2. GET /api/v1/expenses/:id/receipt (file download) 3. GET /api/v1/reports/vat/export/pdf (report generation + PDF library) 4. GET /api/v1/reports/vat/export/xml (report generation + XML serialization) ### 2. Implement Settings Endpoints **Priority:** MEDIUM **Scope:** Endpoints 5-13 from Missing Endpoints list Settings page is fully implemented with save buttons, but no backend to persist data. Current behavior: console.log() only. **Recommendation:** Implement all settings endpoints together in one feature branch. They share similar patterns (GET/PATCH pairs, org-scoped data). ### 3. Phase 2 Features as Stubs **Priority:** LOW **Scope:** Endpoints 14-18 from Missing Endpoints list These are explicitly marked as "Phase 2" or "Coming Soon" in the UI. Consider implementing stub endpoints that return: - 501 Not Implemented - Or minimal placeholder data This allows frontend to gracefully handle the "not yet implemented" state without errors. ### 4. Add Endpoint: GET /api/v1/bank-accounts/unreconciled-count **Priority:** LOW **Scope:** New endpoint not in API-REFERENCE.md VAT report Step 1 checks for unreconciled transactions. Currently, frontend must: 1. Fetch GET /api/v1/bank-accounts (all accounts) 2. For each account, fetch GET /api/v1/bank-accounts/:id/transactions?reconciled=false 3. Aggregate counts **Recommendation:** Add dedicated endpoint to avoid N+1 query pattern. ```typescript // Proposed endpoint GET /api/v1/bank-accounts/unreconciled-count Response: { total: number byAccount: Array<{ accountId: string accountName: string count: number }> } ``` ### 5. Verify TypeScript Interface Consistency **Priority:** MEDIUM API-REFERENCE.md defines TypeScript interfaces for request/response bodies. Frontend uses these types in forms and state management. **Action Items:** - Create shared types package (`packages/types/`) - Export all API interfaces from API-REFERENCE.md - Import in both `apps/api/` (backend validation) and `apps/web/` (frontend forms) - Use Zod schemas for runtime validation + TypeScript type generation **Example:** ```typescript // packages/types/src/invoice.ts import { z } from 'zod' export const CreateInvoiceRequestSchema = z.object({ customerId: z.string().uuid(), invoiceDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), currencyCode: z.enum(['EUR', 'RSD', 'BAM', 'HRK']).optional(), items: z.array(z.object({ description: z.string().min(1), quantity: z.number().positive(), unitPrice: z.number().nonnegative(), taxRate: z.number().nonnegative(), accountId: z.string().uuid().optional() })), notes: z.string().optional(), terms: z.string().optional() }) export type CreateInvoiceRequest = z.infer ``` Backend uses schema for validation: ```typescript // apps/api/src/routes/invoices.ts import { CreateInvoiceRequestSchema } from '@bilko/types' router.post('/invoices', async (req, res) => { const data = CreateInvoiceRequestSchema.parse(req.body) // Throws if invalid // ... }) ``` Frontend uses type for forms: ```typescript // apps/web/app/(dashboard)/invoices/new/page.tsx import { CreateInvoiceRequest } from '@bilko/types' const [formData, setFormData] = useState({...}) ``` ### 6. Authentication Endpoints Missing from Coverage **Priority:** HIGH Frontend has no login/register pages yet, but API-REFERENCE.md defines 5 auth endpoints: - POST /api/v1/auth/register - POST /api/v1/auth/login - POST /api/v1/auth/refresh - POST /api/v1/auth/logout - GET /api/v1/auth/me **Recommendation:** Create auth pages in Phase 2: - `/login` page - `/register` page - `/logout` action (server action) - Auth middleware to protect all /dashboard routes ### 7. Error Handling Pattern **Priority:** MEDIUM API-REFERENCE.md defines error response format: ```typescript interface ApiError { error: string code: string details?: Record } ``` **Recommendation:** Create frontend error handling utility: ```typescript // lib/api-error.ts export function handleApiError(error: Response) { const apiError: ApiError = await error.json() if (apiError.details) { // Field-level validation errors return Object.entries(apiError.details).map(([field, errors]) => ({ field, message: errors.join(', ') })) } // Generic error return { message: apiError.error, code: apiError.code } } ``` Use in forms: ```typescript try { await fetch('/api/v1/invoices', { method: 'POST', body: JSON.stringify(data) }) } catch (error) { const errors = handleApiError(error) // Display errors in form } ``` --- ## Implementation Priority Matrix | Endpoint | Priority | Reason | Est. Effort | |----------|---------|--------|------------| | DELETE /api/v1/invoices/:id | HIGH | Invoice list delete button | 2h | | GET /api/v1/expenses/:id/receipt | HIGH | Receipt download links | 3h | | GET /api/v1/reports/vat/export/pdf | HIGH | VAT export button | 8h | | GET /api/v1/reports/vat/export/xml | HIGH | VAT e-filing | 6h | | GET /api/v1/settings/notifications | MEDIUM | Settings page persistence | 3h | | PATCH /api/v1/settings/notifications | MEDIUM | Settings page persistence | 2h | | GET /api/v1/settings/security | MEDIUM | Settings page persistence | 4h | | PATCH /api/v1/settings/security | MEDIUM | Settings page persistence | 3h | | GET /api/v1/security/audit-log | MEDIUM | Audit log viewer | 5h | | POST /api/v1/security/data-export | MEDIUM | GDPR compliance | 8h | | DELETE /api/v1/organization | MEDIUM | Delete company action | 4h | | POST /api/v1/auth/2fa/enable | MEDIUM | 2FA setup | 8h | | DELETE /api/v1/auth/2fa/disable | MEDIUM | 2FA removal | 2h | | GET /api/v1/integrations | LOW | Phase 2 feature | 6h | | POST /api/v1/integrations/:id/connect | LOW | Phase 2 feature | 12h | | DELETE /api/v1/integrations/:id/disconnect | LOW | Phase 2 feature | 3h | | POST /api/v1/reports/vat/submit | LOW | Phase 2 feature | 16h | | GET /api/v1/bank-accounts/unreconciled-count | LOW | Performance optimization | 3h | **Total Estimated Effort:** 98 hours (~12-15 working days for 1 developer) **Suggested Implementation Phases:** **Phase 2a (Core Features)** — 19h - DELETE /api/v1/invoices/:id - GET /api/v1/expenses/:id/receipt - GET /api/v1/reports/vat/export/pdf - GET /api/v1/reports/vat/export/xml **Phase 2b (Settings Persistence)** — 31h - All settings endpoints (notifications, security, audit log, data export, org delete, 2FA) **Phase 2c (Integrations + VAT Submit)** — 37h - Integrations endpoints (stub or full implementation) - VAT submit endpoint (requires external API integration) **Phase 2d (Polish)** — 11h - Unreconciled count endpoint - Shared types package - Error handling utilities - Auth pages --- ## Conclusion **Overall Coverage:** 75% (50 out of 67 required endpoints documented) **API-REFERENCE.md is 75% complete.** The 50 documented endpoints cover all core business logic: - Invoice CRUD (except delete) - Expense CRUD (except receipt download) - Banking & reconciliation - Reporting (except export formats) - User management - Organization settings - Chart of accounts - Transactions **Missing 25%:** - 4 high-priority endpoints (delete invoice, receipt download, VAT exports) - 9 medium-priority settings endpoints - 4 low-priority Phase 2 endpoints **No redundant endpoints.** Every endpoint in API-REFERENCE.md is consumed by at least one frontend page. **Recommendation:** Implement Phase 2a (core features, 19h) before beta launch. Settings persistence can follow in Phase 2b after user feedback. **Next Steps:** 1. Review this coverage report with team 2. Prioritize missing endpoints based on business needs 3. Update API-REFERENCE.md with missing endpoint specs 4. Create implementation tickets in Mission Control 5. Build apps/api/ following API-REFERENCE.md contract # Bilko Authentication -- Entra External ID (CIAM) ## Overview Bilko uses **Microsoft Entra External ID (CIAM)** as its sole identity provider. Entra authenticates users; Bilko authorises them. Roles and permissions live exclusively in the Bilko database — no role claims are read from Entra tokens. **Decision anchor (ADR):** "Entra authenticates, Bilko authorises; single-role v1; multi-org deferred (MC #103089)." **Stage status:** Live on stage (branch stack WP1–WP4, feat/rbac-wp4-retire-legacy-auth commit 3ac1388). Production cutover pending consolidated PR. ## Tenant Configuration
FieldValue
Tenant ID`20bb17de-9be5-4143-a7e5-8c1ddae6a064`
Display nameBilko CIAM
Domain`bilkociam.onmicrosoft.com`
TypeEntra External ID (CIAM), EU data residency, Norway
BillingMAU — free tier from 2026-06-07
Authority (MSAL)`https://bilkociam.ciamlogin.com/20bb17de-9be5-4143-a7e5-8c1ddae6a064`
Issuer (exact, from OIDC discovery)`https://20bb17de-9be5-4143-a7e5-8c1ddae6a064.ciamlogin.com/20bb17de-9be5-4143-a7e5-8c1ddae6a064/v2.0`
JWKS URI`https://bilkociam.ciamlogin.com/20bb17de-9be5-4143-a7e5-8c1ddae6a064/discovery/v2.0/keys`
OIDC discovery`https://bilkociam.ciamlogin.com/20bb17de-9be5-4143-a7e5-8c1ddae6a064/v2.0/.well-known/openid-configuration`
**Issuer note:** OIDC discovery returns the issuer with the tenant-ID subdomain (`20bb17de-...ciamlogin.com`), NOT the named subdomain (`bilkociam.ciamlogin.com`). The Kotlin backend `ENTRA_EXTERNAL_ID_ISSUER` env var MUST match the discovery value exactly. See evidence: `/tmp/evidence-103076/phase0-config.md`. ## App Registrations
AppClient IDFlowNotes
Bilko API (resource)`fe39e0f5-513e-40af-93f0-c3ee624df56c`Exposes scopeScope: `access_as_user`; full scope string: `api://fe39e0f5-513e-40af-93f0-c3ee624df56c/access_as_user`; audience for token validation = client ID; no client secret (resource app)
Bilko Web SPA`c2902239-ea63-41bd-8619-6cf096d7d45a`PKCE auth code (SPA)Redirects: localhost:3000, stage Cloud Run URL, bilko-demo.alai.no, app.bilko.cloud, app.bilko.io, app.bilko.company (+ /auth/callback variants); no client secret
Bilko Mobile (native)`916bb9f3-658d-4729-b5a0-64b1f157c8c2`PKCE auth code (native/public)Redirect: `com.alai.bilko://auth`, `msauth.com.alai.bilko://auth`; `isFallbackPublicClient=true`; Expo Go workaround documented in Phase 0 config
Secrets (none exist — all public clients). Non-secret configuration is stored in GCP Secret Manager (`bilko-entra-issuer`, `bilko-entra-audience`, `bilko-entra-jwks-url`) and Bitwarden ("Bilko CIAM Tenant Config"). ## Token Claims - `oid` — object ID, immutable cross-app anchor; **mandatory identity key** (built-in in CIAM, always present) - `sub` — pairwise pseudonymous per app; NOT used as identity anchor (changes on app re-registration). The backend logs a warning when `sub != oid` (expected in CIAM) and uses `oid` exclusively. Confirmed live: E2E test showed `sub=053nt0lk` vs `oid=3b53a25a`. - `email` / `preferred_username` — informational only; mutable; NOT used for identity resolution in JWT claims issued by Bilko - `name`, `family_name`, `given_name` — optional claims Bilko JWTs issued after exchange use the internal Bilko user UUID as the subject claim — email is not the identity anchor in issued tokens. ## Authentication Flow — Web (MSAL Direct Bearer) 1. Browser opens login page → MSAL browser (`@azure/msal-browser` + `@azure/msal-react`) initiates PKCE auth code flow 2. Redirect to `bilkociam.ciamlogin.com` → user authenticates (email/password or social) → Entra issues auth code 3. MSAL exchanges code for tokens (PKCE, in memory — NOT localStorage) 4. MSAL acquires access token for scope `api://fe39e0f5.../access_as_user` 5. Web sends `Authorization: Bearer ` to Kotlin API 6. Kotlin `EntraExternalIdService.verifyIdToken()` validates: RS256 signature via live JWKS, issuer exact match, audience = `fe39e0f5...`, `oid` claim present, JWKS URL domain-pinned to `ciamlogin.com`/`microsoftonline.com` 7. JIT provisioning or email-match link (see JIT section below) → Bilko session returned 8. Session cookie (`SameSite=Lax`, httpOnly) established; subsequent requests use Bilko refresh token 9. Sign-out calls Entra logout endpoint to invalidate Entra session + clears local cookie ## Authentication Flow — Mobile (Token Exchange) 1. Expo native app initiates PKCE via `expo-auth-session` / `useEntraAuthRequest` 2. Redirect to Entra → auth code returned to `com.alai.bilko://auth` 3. MSAL exchanges code; **id\_token** (not access\_token) sent to `POST /auth/entra/session` 4. Kotlin backend verifies id\_token, runs JIT provisioning or link, returns `{ accessToken, refreshToken }` 5. Tokens stored in SecureStore; TTL aligns with Bilko 7-day refresh token window ## JIT Provisioning + Identity Linking Implemented in `AuthService.createSessionFromEntraIdToken()` (SERIALIZABLE transaction — martin-kleppmann race-prevention mandate): 1. Lookup `entra_external_identities` by `issuer + oid`. If found: return session. 2. If not found: email-match lookup in `users` (case-normalised, lowercase both sides). If unique match and `email_verified`: insert `entra_external_identities` row, log audit event `entra_jit_link`, return session. 3. If no match: call `UserProvisioningService.provisionNewUserForEntra()` — creates a new org + user with role `viewer` + inserts `entra_external_identities` row. New user must be promoted by an admin. **Design dissent on record (martin-kleppmann + bruce-momjian):** email-match JIT is risky if email is mutable or duplicate. Pre-provision by OID (via admin invite or MS Graph export script) is the safer path. JIT email-match is constrained with a serializable transaction as a partial mitigation. The pre-provision script path (D8 in MC #103075) is the recommended path for production migration. ## JWKS Cache + Key Rotation `EntraExternalIdService` maintains a time-bound JWKS key cache: - TTL: 12 hours per key (stored as `Pair`; evicted on read if age > 12h) - On `kid` miss: force re-fetch regardless of other cached keys - JWKS URL domain-pinned: must match `^https://([a-z0-9-]+\.)*ciamlogin\.com/` or `^https://login\.microsoftonline\.com/` - Startup fail-closed: if `ENTRA_EXTERNAL_ID_ISSUER` set but any config absent or URL fails domain assertion → `IllegalStateException` at Ktor module init (not lazy 503) - JWKS verification: live E2E test confirmed 6 RSA keys, all `kty=RSA`, TLS valid 2026-11-22 ## Refresh Token Revocation (Known Limitation) Bilko refresh tokens are 7-day HMAC validated locally. A disabled Entra account remains valid in Bilko for up to 7 days. **Open CEO/Securion decision (OC#4 from MC #103075):** - Option A (not yet implemented): revalidate Entra account status on every refresh (~50ms latency) - Option B (current default): 7-day window; immediate revocation requires an admin to also disable the user in the Bilko DB. Documented as a risk-acceptance decision in `AuthService.kt` (code comment references MC #103075). ## Legacy Email/Password — RETIRED (410 Gone) As of branch `feat/rbac-wp4-retire-legacy-auth` (commit 3ac1388), the following endpoints return `HTTP 410 Gone` with body `{"code":"ENDPOINT_RETIRED"}`: - `POST /auth/register` - `POST /auth/login` - `POST /auth/forgot-password` - `GET /auth/reset-password` - `POST /auth/reset-password` Kept active: `POST /auth/entra/session`, `POST /auth/refresh`, `POST /auth/mobile/refresh`, `POST /auth/2fa/challenge`. Web login page: email/password form removed; Entra primary CTA only. Self-serve register page removed; shows "contact your admin" message. Forgot/reset password redirects to Entra SSPR portal. Break-glass (first-admin bootstrap): run `./gradlew :apps:api:bootStrapAdmin` with `BOOTSTRAP_ADMIN_EMAIL` + `BOOTSTRAP_ADMIN_PASSWORD` env vars. Calls `AuthService.register()` directly; no HTTP endpoint exposed. ## Phase 0–4 Deployment Facts
Phase / WPScopeBranchStatus
Phase 0 (MC #103076)CIAM tenant provisioning, 3 app registrations, JWKS verificationFlowForge standaloneDONE — stage live
WP1 (MC #103141)RBAC permissions catalog V67, PermissionService, BilkoPrincipal, requirePermission, 204 matrix testsfeat/rbac-wp1-permissions-catalogDONE — Proveo PARTIAL (integration test fix applied post-verification)
WP2 (MC #103142)JIT provisioning V68, UserProvisioningService, admin/invite API, role-assign endpointfeat/rbac-wp2-user-provisioningDONE — Proveo PASS
WP3 (MC #103143)Web: Entra primary CTA, register retired, forgot/reset SSPR, RBAC admin UIfeat/rbac-wp3-web-entra-uiDONE — Proveo PASS
WP4 (MC #103144)Retire legacy endpoints (410), web login Entra-only, break-glass documentedfeat/rbac-wp4-retire-legacy-authDONE — Proveo PASS
WP5 (MC #103145)E2E: live CIAM token, OID anchor, JIT provision, RBAC enforcement, invalid token rejectionfeat/rbac-wp3-web-entra-uiDONE — PASS (browser MSAL flow deferred to Proveo pre-prod)
Evidence bundles: `/tmp/evidence-103141` through `/tmp/evidence-103145`, `/tmp/evidence-103076/phase0-config.md`. # Bilko RBAC -- Users / Roles / Permissions ## Overview Bilko uses a **flat RBAC model**: users have one role per organisation; roles map to a permission catalog via a DB seed table. Permission resolution is live from the database on every request (no JWT role claim for authorisation). The system was built in WP1 (MC #103141, branch `feat/rbac-wp1-permissions-catalog`). ## Roles
RoleLevelScope
`owner`3All permissions including billing, account deletion, user management
`admin`2All permissions except billing and account deletion; can manage users and roles
`accountant`1Create and manage financial records; cannot delete; cannot manage users
`viewer`0Read-only access; default for newly JIT-provisioned Entra users
Roles are stored in `users.role` (VARCHAR 50) with a CHECK constraint added in V67 limiting values to these four. Single role per user per organisation (multi-role/multi-org deferred, MC #103089). ## Permissions Catalog (V67 — 52 keys) Source: `apps/api/src/main/resources/db/migration/V67__rbac_permissions_catalog.sql` (commit 66629bd). The catalog is stored in the `permissions` table; all application code references permission keys as string constants. Format: `:` enforced by a DB CHECK constraint (`permission_key_format`). Example keys by resource group:
Resource groupExample keys
Invoices`invoice:read`, `invoice:create`, `invoice:update`, `invoice:delete`, `invoice:submit`
Expenses`expense:read`, `expense:create`, `expense:update`, `expense:delete`
Contacts`contact:read`, `contact:create`, `contact:update`, `contact:delete`
Transactions`transaction:read`, `transaction:create`, `transaction:reconcile`
Reports`report:read`, `report:export`
Settings / billing`settings:read`, `settings:update`, `billing:read`, `billing:update`
Users`users:read`, `users:manage`, `users:invite`
Account admin`account:delete`
Documents`document:read`, `document:upload`, `document:delete`
Articles / products`article:read`, `article:create`, `article:update`, `article:delete`
Full 52-key baseline stored in: `apps/api/src/main/resources/rbac/requireRole-baseline-v67.tsv` (commit 0bf18fd, 51 data rows). ## Role-to-Permission Seed (Strategy A — Flat Inheritance) Source: `role_permissions` table seeded in V67. Each row: `(role, permission_key)`. No runtime inheritance logic — the seed embeds the full flattened set for each role.
RolePermissions countPrinciple
viewer13Read-only: all :read + :export keys
accountant40viewer permissions + create/update on financial resources; no delete, no user management
admin49accountant permissions + delete + user management; no billing:update, no account:delete
owner52All 52 permissions (complete set)
The seed exactly reproduces the behaviour of the legacy `requireRole()` numeric hierarchy — verified by 204 RbacMatrixTest cases (0 failures). No behaviour regression. ## PermissionService — Live DB Resolution Source: `apps/api/src/main/kotlin/no/alai/bilko/services/PermissionService.kt` (commit dee4fb1) - Interface method: `fun resolve(role: String): Set` (2 implementations: interface + `DbPermissionService`) - Live DB query against `role_permissions` on every resolve call - **Fail-closed:** if role is unknown or DB returns empty set, resolves to `emptySet()` — no permissions granted - CEO OCD O1 decision: global per-role cache (4 known values); result cached per role string key. Per CEO spec, cache keyed `userId+role-version` was the ideal; current implementation uses global per-role cache (simpler, advisory gap noted in Proveo verdict) ## BilkoPrincipal + requirePermission Source: `apps/api/src/main/kotlin/no/alai/bilko/auth/BilkoPrincipal.kt` and `RbacHelper.kt` (commit dee4fb1) - `BilkoPrincipal` carries `permissions: Set` — resolved at authentication time via `PermissionService` - `RoutingContext.requirePermission(permissionKey: String)` — Kotlin extension function; throws `ForbiddenException` (HTTP 403 `BILKO-AUTH-003`) if key not in principal's permission set; calls `AuthzAuditLogger` - All 51 formerly-`requireRole()` call sites migrated to `requirePermission()` (17 route files, 0 residual `requireRole` in routes — verified by grep) - `requireRole()` is kept as a thin compatibility shim (RbacHelper.kt) ## Role-to-Permission Matrix
Permission keyvieweraccountantadminowner
`invoice:read`YYYY
`invoice:create`-YYY
`invoice:update`-YYY
`invoice:delete`--YY
`invoice:submit`-YYY
`expense:read`YYYY
`expense:create`-YYY
`expense:delete`--YY
`users:read`YYYY
`users:manage`--YY
`users:invite`--YY
`billing:read`---Y
`billing:update`---Y
`account:delete`---Y
`settings:read`YYYY
`settings:update`--YY
`report:read`YYYY
`report:export`YYYY
... (52 total)Full catalog in V67 seed
Full read-only matrix visible to admins/owners in the web admin UI at `/admin/users` (component: `lib/permissions.ts ROLE_PERMISSION_MATRIX`). ## Authorization Audit Log Source: `apps/api/src/main/kotlin/no/alai/bilko/auth/AuthzAuditLogger.kt` (commit dee4fb1) - Every `requirePermission()` call logs an `authz_decision` event (SLF4J structured log) - Log fields: `userId`, `orgId`, `permissionKey`, `granted` (boolean), `route` - `RbacHelper.kt` references `AuthzAuditLogger` at 4 call sites (verified) ## V67/V68 Migration Summary
MigrationContents
V67 (`V67__rbac_permissions_catalog.sql`)Creates `permissions` table (52 keys, format CHECK); `role_permissions` table with full 4-role seed; adds `users.role` CHECK constraint; GRANT SELECT to bilko\_app; no RLS (global catalog)
V68 (`V68__rbac_user_provisioning.sql`)Adds `users:manage` and `users:invite` permission keys; SECURITY DEFINER function `bilko_auth.provision_user_with_org(issuer, oid, email, fullName)` returning new user UUID; seeds new permissions to admin + owner roles
## Test Coverage - 204 RbacMatrixTest cases (all 51 call sites x 4 roles): 0 failures — `feat/rbac-wp1-permissions-catalog` - 8 UserProvisioningWp2Test cases (T1–T8: JIT, admin CRUD, role guards, self-escalation block): PASS - Total test suite: 2534 tests (1070 unit + 1283 integration + 181 web), 0 failures — WP5 E2E evidence `/tmp/evidence-103145` ## Out of Scope (v1) - Multi-role per user (single role per org; MC #103089) - Multi-org membership (single org per user; MC #103089) - ABAC / conditional permissions (e.g. "delete only own drafts") - Accountant Portal multi-tier permissions (Collaborator/Approver roles from ACCOUNTANT-PORTAL-SPEC.md §2.2) # Bilko Auth Migration Runbook + Admin Guide ## Scope This runbook covers: (1) how an operator bootstraps the first admin after legacy auth is retired, (2) how an admin creates and invites users, (3) how to assign and change roles, (4) the full user lifecycle via Entra, (5) migration notes from the WP1–WP4 branch stack. For architecture detail see [Bilko Authentication — Entra External ID (CIAM)](/books/bilko-balkan-accounting-saas/page/bilko-authentication-entra-external-id-ciam). ## 1. Bootstrapping the First Admin (Break-Glass) After legacy `/auth/register` is retired (HTTP 410), there is no HTTP endpoint for creating the first user. Use the Gradle break-glass task: ``` # Set environment variables (never commit these): export BOOTSTRAP_ADMIN_EMAIL="admin@yourorg.com" export BOOTSTRAP_ADMIN_PASSWORD="" # Run from the api project root: cd apps/api ./gradlew :apps:api:bootStrapAdmin ``` What this does: calls `AuthService.register()` directly (bypasses HTTP routing), creates an organisation + owner user. No HTTP endpoint is exposed — zero backdoor surface. The temporary password should be rotated immediately via Entra SSPR after the admin first signs in. Full runbook file: `apps/api/docs/runbooks/BREAK-GLASS-BOOTSTRAP.md` (on branch `feat/rbac-wp4-retire-legacy-auth`). ## 2. Creating / Inviting Users (Admin Flow) User creation is now admin-gated. Self-serve registration is retired. ### Via API ``` POST /api/v1/admin/users Authorization: Bearer { "email": "newuser@example.com", "fullName": "Full Name", "role": "viewer" // viewer | accountant | admin | owner } ``` Response: `HTTP 201 Created` — returns the new user object including their UUID. The user receives an invite; they sign in via Entra (JIT provisioning links their Entra identity on first sign-in). ### Permission required `users:manage` — held by `admin` and `owner` roles. ### Via Web Admin UI 1. Sign in as admin or owner 2. Navigate to **Settings > Users** (`/admin/users`) 3. Click **Invite User** 4. Enter email, full name, and select role 5. Submit — user receives invite email (Entra CIAM invitation flow) Viewers and accountants see a redirect to the dashboard if they navigate to `/admin/users`. ## 3. Assigning / Changing Roles ### Via API ``` PUT /api/v1/users/:id/role Authorization: Bearer { "role": "accountant" // viewer | accountant | admin | owner } ``` Constraints enforced: - Caller must have `users:manage` permission (admin+) - A user **cannot change their own role** (self-escalation blocked — HTTP 403) - The `owner` role cannot be changed via this endpoint (owner is protected in `SettingsService.changeUserRole()`) - Invalid role values return HTTP 400 ### Via Web Admin UI 1. Navigate to **Settings > Users** 2. Find the user row 3. Click the role dropdown (visible to admin/owner only) 4. Select the new role — saved immediately via `PUT /users/:id/role` ## 4. User Lifecycle 1. **Admin creates user** via `POST /admin/users` (role = viewer by default, or specified role) 2. **User receives Entra invite** (email from `bilkociam.onmicrosoft.com`) 3. **First sign-in**: user clicks Entra sign-in on Bilko web login → authenticates in Entra CIAM → Bilko backend calls `createSessionFromEntraIdToken()`: - Looks up `entra_external_identities` by `oid` → not found (first login) - Email-match lookup → finds pre-created user → inserts `entra_external_identities` row (JIT link) → audit event `entra_jit_link` - Bilko session returned; user is logged in as viewer 5. **Admin promotes role** if needed via `PUT /users/:id/role` 6. **Subsequent logins**: Entra → backend finds `entra_external_identities` by `oid` → direct session, no email-match step 7. **Sign-out**: MSAL calls Entra logout endpoint → Entra session invalidated → Bilko session cookie cleared → next visit redirects to Entra login ## 5. What Changed — Migration Notes (WP1–WP4)
AreaBefore (pre-WP1)After (WP1–WP4)
Backend auth enforcement`requireRole("admin")` inline in 51+ route handlers`requirePermission("invoice:create")` via extension fn; 0 residual requireRole in routes
Permission dataNo tables; hardcoded numeric hierarchy in RbacHelperV67: `permissions` table (52 keys), `role_permissions` seed; V68: provisioning function
User provisioningSelf-serve `POST /auth/register`Admin invite (`POST /admin/users`) + JIT Entra link on first sign-in; `UserProvisioningService`
Web loginEmail/password form + "Sign in with Microsoft" coexistingEntra-only CTA; no email/password form; register page shows "contact your admin"
Legacy endpointsActive: /auth/login, /auth/register, /auth/forgot-password, /auth/reset-passwordHTTP 410 Gone + ENDPOINT\_RETIRED body
Password resetEmail-based reset-password flow (V57 table)Redirect to Entra SSPR portal (self-service via Microsoft account)
RBAC admin UINo UI; role changes required direct DB queryWeb: Settings > Users page with role dropdown (admin/owner only)
## 6. Branch Stack (WP1–WP4 Stacked PRs)
WPBranchLatest commitKey files
WP1 — RBAC catalog`feat/rbac-wp1-permissions-catalog`890168d (last route commit)V67 migration, PermissionService, BilkoPrincipal, RbacHelper, 17 route files migrated
WP2 — Provisioning`feat/rbac-wp2-user-provisioning`a9fa67cV68 migration, UserProvisioningService, UserManagementRoutes
WP3 — Web UI`feat/rbac-wp3-web-entra-ui`3c1c019login/page.tsx (Entra CTA), register/page.tsx (retired), admin/users/page.tsx, lib/permissions.ts
WP4 — Retire legacy`feat/rbac-wp4-retire-legacy-auth`3ac1388AuthRoutes.kt (5 x 410), api.ts (removed methods), auth-store.ts, 13 new web tests
These branches are stacked and NOT yet merged to main. Production cutover requires a consolidated merge PR after CEO/Securion sign-off. ## 7. Rollback Procedure If the consolidated deploy to main needs to be rolled back: 1. **Feature flag path** (if `FEATURE_ENTRA_AUTH_ENABLED` env var is present): set to `false` to re-enable the password auth provider path (AuthProvider interface, D5 in MC #103075) 2. **Hard rollback**: revert to the pre-WP1 commit; Flyway handles down-migration if reversible V67/V68 down scripts were authored (check migration files) 3. **password\_hash**: column was made nullable in V66 but existing rows retain their hash values — password-based login can be re-enabled without data loss during the rollback window 4. **Password reset tokens table (V57)**: NOT dropped. Must not be dropped until the rollback window closes (minimum 30 days post-production cutover). See D8 plan in MC #103075 5. **Entra disable**: if Entra must be disabled urgently, also disable users in Bilko DB to enforce immediate revocation (7-day refresh window caveat — OC#4) ## 8. Database Schema Reference
TableKey columnsNotes
`users``id`, `organization_id`, `email`, `password_hash` (nullable), `role` (CHECK owner|admin|accountant|viewer), `two_factor_*`V66: password\_hash nullable; V67: role CHECK added
`entra_external_identities``issuer`, `subject` (= oid), `user_id`, `last_login_at`V64: created; UNIQUE(issuer,subject), UNIQUE(user\_id,issuer); RLS: V66
`permissions``permission_key` (PK, CHECK format)V67: 52 keys; global catalog, no RLS, GRANT SELECT bilko\_app
`role_permissions``role`, `permission_key`V67: exhaustive flat seed; V68: users:manage + users:invite added
## Evidence Files - WP1 verification: `/tmp/evidence-103141/wp1-verification.md`, proveo-verdict.json - WP2 verification: `/tmp/evidence-103142/wp2-verification.md`, proveo-wp2-verdict.json - WP3 Proveo: `/tmp/evidence-103143/proveo-wp3-validation.md` - WP4 verification: `/tmp/evidence-103144/wp4-verification.md` - WP5 E2E: `/tmp/evidence-103145/wp5-e2e.md`, verification.json - Phase 0 config: `/tmp/evidence-103076/phase0-config.md` # ADR-037 -- Entra Authenticates, Bilko Authorises; Single-Role v1; Multi-Org Deferred ## ADR-037 — Entra Authenticates, Bilko Authorises; Single-Role v1; Multi-Org Deferred
FieldValue
ADR numberADR-037
Date2026-06-08
StatusAccepted
AuthorJohn (AI Director, ALAI Holding AS)
CEO decisionAlem Basic — confirmed 2026-06-07 (CEO resolution addendum, MC #103075)
Related MCsMC #103075 (Entra migration plan), MC #103141–103146 (WP1–WP6 execution), MC #103089 (multi-org, parked)
SupersedesExisting inline requireRole() pattern (pre-WP1)
## Context Bilko had a custom email/password authentication system and a simple numeric role hierarchy (`requireRole()` inline in route handlers). No permission catalog, no RBAC tables, no admin UI for user management. The CEO decision (June 2026) was to: 1. Replace email/password authentication with Microsoft Entra External ID (CIAM) — hard REPLACE, not phased coexist 2. Build a real permission-catalog RBAC system with a DB-backed role-to-permission mapping Multiple design forks were evaluated by a multi-agent panel (Parisa Tabriz, Martin Kleppmann, Petter Graff, Bruce Momjian, Devils Advocate — MC #103075 forged prompt). Key unresolved tensions: web direct-bearer vs exchange, email-match JIT vs pre-provision-by-oid, roles-in-Entra-claims vs roles-in-Bilko-DB. ## Decision ### D1 — Identity Provider Boundary **Entra External ID (CIAM) authenticates. Bilko authorises.** - Entra issues tokens; Bilko backend validates JWKS RS256 signature, issuer, audience - Bilko reads `oid` from the Entra token as the sole identity anchor (`sub` is pairwise-pseudonymous per app and must NOT be used) - Bilko issues its own access + refresh tokens after Entra token exchange; downstream services consume Bilko tokens, not Entra tokens directly - Role and permission data live in `users.role` + `role_permissions` (Bilko DB). No role or permission claims are read from Entra tokens ### D2 — Single Role per User per Organisation (v1) One role per user per org: `owner | admin | accountant | viewer`. The role is stored in `users.role` (single column). Multi-role per user and multi-org membership are explicitly deferred to a separate epic (MC #103089). **Rationale:** zero live clients; single-org Entra tenant; keep scope tightly bounded; multi-org requires a `organization_members` join table and CIAM tenant model decisions that are not yet resolved. ### D3 — Permission Catalog in DB; Flat Inheritance Seed A `permissions` catalog table (52 keys, `resource:verb` format enforced by CHECK) and a `role_permissions` mapping table (V67) replace the inline `requireRole()` calls. Seed strategy: flat exhaustive rows per role (Strategy A) — no runtime hierarchy derivation. The seed exactly reproduces existing behaviour (no regression — verified by 204 RbacMatrixTest cases). ### D4 — Live DB Permission Resolution; Fail-Closed `PermissionService.resolve(role)` queries `role_permissions` at request time. Unknown role resolves to `emptySet()` (no permissions). `BilkoPrincipal` carries the resolved permission set. All route-level checks use `requirePermission("resource:verb")`. ### D5 — Multi-Org Deferred Entra CIAM is provisioned as a single tenant. JIT provisioning assigns a new Entra user to one Bilko organisation. Multi-org (one user in multiple orgs) requires: a `organization_members` join table, per-org permission resolution, and CIAM tenant model decisions. All deferred to MC #103089. ## Consequences ### Positive - Authentication complexity moved to Microsoft (password policies, MFA, SSPR, account lifecycle) - Bilko no longer stores password hashes for new users (`password_hash` is nullable) - Permission model is auditable and admin-configurable without code changes (role-to-permission seed is data) - Authz decisions are logged (`AuthzAuditLogger`) for incident investigation - Admin UI for user + role management (no more raw SQL for role changes) ### Negative / Trade-offs - Entra CIAM has MAU-based pricing; cost gate was raised (OC#1, MC #103075) — free tier starts June 2026 - 7-day refresh token revocation window: a disabled Entra account remains valid in Bilko for up to 7 days (documented risk OC#4; mitigation: admin disables user in Bilko DB) - Email-match JIT carries race risk if email is mutable or duplicated (martin-kleppmann + bruce-momjian dissent on record); serializable transaction is a partial mitigation; pre-provision-by-OID is the recommended production path - Single-role v1 limits fine-grained delegation scenarios (e.g. "viewer + approve-only on specific documents") — documented as out of scope ## Alternatives Considered
AlternativeRejected reason
Roles in Entra claims (Entra app roles)Couples authorisation to IdP; role changes require Entra admin action not Bilko admin action; prevents clean multi-IdP future. Rejected per petter-graff + parisa-tabriz panel consensus.
Phased coexist (email/password + Entra in parallel for 2+ weeks)CEO confirmed hard REPLACE. Panel devils-advocate raised phased coexist as safer; CEO re-confirmed hard REPLACE given zero live users. AuthProvider interface (D5 MC #103075) technically enables a revert if needed.
Denormalised entra\_oid on users table (bruce-momjian alternative)Separate-table V64 model kept; enables multi-IdP future; join cost is negligible at current scale. Fork preserved but not resolved — separate-table remains.
ABAC / policy engine (v1)Premature for current scale and requirements; adds complexity; deferred as explicit out-of-scope with comment in plan.
## Open Decisions Not Resolved by This ADR - **OC#4 — Refresh revalidation vs risk acceptance:** Option A (revalidate Entra account status on refresh, ~50ms) vs Option B (7-day window, documented risk). Requires CEO/Securion explicit decision. Code stub for Option A is in `AuthService.kt` referencing MC #103075. - **OC#2 — Hard REPLACE confirmed** but AuthProvider interface (D5, MC #103075) enables reversion if needed. - **Web direct-bearer vs mobile exchange (parisa-tabriz dissent LIVE):** Web: MSAL acquires Entra access token, sends as Bearer to API. Mobile: id\_token exchange at `POST /auth/entra/session`. Web direct-bearer is implemented; exchange path preserved as commented stub per spec. ## Document Links - [Bilko Authentication — Entra External ID (CIAM)](/books/bilko-balkan-accounting-saas/page/bilko-authentication-entra-external-id-ciam) - [Bilko RBAC — Users / Roles / Permissions](/books/bilko-balkan-accounting-saas/page/bilko-rbac-users-roles-permissions) - [Bilko Auth Migration Runbook + Admin Guide](/books/bilko-balkan-accounting-saas/page/bilko-auth-migration-runbook-admin-guide) - Source plan: `/Users/makinja/system/specs/bilko-web-entra-cutover-and-rbac-plan-2026-06-08.md` - Forged prompt (panel dissent log): `/Users/makinja/system/prompts/forged/103075.md` - Phase 0 config: `/tmp/evidence-103076/phase0-config.md` # Bilko Self-Serve Trial — CIAM Architecture and Auth Pattern (MC #103232) # Bilko Self-Serve Trial — CIAM Architecture & Auth Pattern **MC:** #103232 | **Status:** LIVE — Proveo 11/11 PASS | **Last updated:** 2026-06-09 | **Securion verdict:** LAUNCH WITH CONDITIONS --- ## 1. Overview A prospect navigates to `app.bilko.cloud` (or `bilko-demo.alai.no`), clicks **"Sign in or create a free account with your email"**, and completes a Microsoft CIAM Email-OTP sign-up. On first login, the backend JIT-provisions an empty Bilko organisation with a **7-day trial** directly on the real production database (`bilko-demo-db`). There is no separate demo build, no invite-only flow, and no org Microsoft account required — any personal email address works. The deployment target is the standard `bilko-main-deploy` semver-tag trigger. Stage and demo share the same Kotlin/Ktor binary and the same database instance (multi-tenant via RLS). The CIAM tenant (`bilkociam`) is a dedicated Microsoft Entra External ID tenant, completely separate from the Bilko staff Entra tenant. ### 1.1 Flow diagram ``` Prospect → app.bilko.cloud/login → "Sign in with Microsoft" (MSAL redirect) → bilkociam.ciamlogin.com [BilkoSignUpSignIn user flow] → Email OTP verification (8-digit code, ~6s delivery) → Consent pages (2 pages on first login only) → Redirect to app.bilko.cloud/auth/callback → MSAL: LOGIN_SUCCESS fires, payload.idToken available → POST /auth/entra/session { idToken } [B1 exchange fix] → bilko-api: JWKS RS256 verify → OID lookup → JIT provision → Response: Bilko HMAC JWT + org { trialEndsAt } → setAuthFromRegistration() [B1.2 session fix] → checkAuth() in-memory JWT fast-path [B1.3 session fix] → /dashboard — empty org, trial active ("Probno: 6 dana preostalo") ``` --- ## 2. CIAM Tenant Configuration
PropertyValue
Tenant namebilkociam
Tenant ID20bb17de-9be5-4143-a7e5-8c1ddae6a064
Tenant typeCIAM (Entra External ID)
SPA app nameBilko Web (SPA)
SPA client IDc2902239-ea63-41bd-8619-6cf096d7d45a
API resource app IDfe39e0f5-513e-40af-93f0-c3ee624df56c
Authority URLhttps://20bb17de-9be5-4143-a7e5-8c1ddae6a064.ciamlogin.com/20bb17de-9be5-4143-a7e5-8c1ddae6a064/v2.0
OIDC issuersame as authority URL (confirmed via discovery endpoint)
### 2.1 User flow: BilkoSignUpSignIn
PropertyValue
Flow IDaa86084b-01dc-453f-9e10-679dfefdd824
TypeexternalUsersSelfServiceSignUpEventsFlow
Display nameBilkoSignUpSignIn
Identity providerEmailOtpSignup-OAUTH (Email One Time Passcode)
isSignUpAllowedtrue
userTypeToCreatemember (not guest)
Attributes collectedemail (auto-filled by OTP verification)
Linked appc2902239-ea63-41bd-8619-6cf096d7d45a (Bilko Web SPA)
**Authority URL note:** Unlike Azure AD B2C, Entra External ID CIAM does *not* require a user flow policy name suffix in the authority URL. The BilkoSignUpSignIn flow is applied automatically at the tenant level when the SPA app is linked to it. The deployed authority URL requires no changes. ### 2.2 Registered SPA redirect URIs - https://app.bilko.cloud/auth/callback and https://app.bilko.cloud - https://app.bilko.company/auth/callback and https://app.bilko.company - https://app.bilko.io/auth/callback and https://app.bilko.io - https://bilko-demo.alai.no/auth/callback and https://bilko-demo.alai.no - https://bilko-web-stage-dh4m46blja-lz.a.run.app/auth/callback and .a.run.app - http://localhost:3000/auth/callback and http://localhost:3000 ### 2.3 Adding identity providers or attributes To add social identity providers (Google, Apple) or additional signup attributes (e.g. display name, company name): Microsoft Entra admin centre → External Identities → User flows → BilkoSignUpSignIn → Identity providers / Attributes. No code changes or redeploys are required for attribute-only changes. Adding a social provider requires app registration on the provider side and linking in the CIAM tenant. --- ## 3. Auth Flow — The Hard-Won Pattern This section documents three bugs that were discovered and fixed during Proveo E2E validation (MC #103232 WS-V). The fixes are canonical — do not revert them. ### B1 — Token exchange (commit 660f410, tag v0.2.45) **Problem:** MSAL's `LOGIN_SUCCESS` event fires with an Entra `access_token` (RS256, Microsoft-issued). The original code set this directly as the API Bearer header. The Bilko API validates HMAC256 JWTs only — all calls returned 401. **Fix:** After MSAL fires, pass `payload.idToken` (not `payload.accessToken`) to a `POST /auth/entra/session { idToken }` call. The backend verifies the CIAM RS256 idToken via JWKS, looks up or JIT-provisions the user, and returns a Bilko HMAC JWT. ``` // apps/web/lib/msal/msal-provider.tsx — corrected token selection const idToken = payload.idToken ?? payload.accessToken if (idToken) { handleEntraLogin(idToken) } // apps/web/lib/msal/use-entra-auth.ts — exchange call const sessionResult = await api.auth.entraSession(idToken) const bilkoJwt = sessionResult?.tokens?.accessToken setAccessToken(bilkoJwt) ``` ### B1.2 — Session persistence via setAuthFromRegistration (commit e1e31c5, tag v0.2.46) **Problem:** After the B1 exchange, `checkAuth()` was called to hydrate the store. `checkAuth()` internally calls `POST /auth/refresh` using the httpOnly refresh-token cookie. The CIAM exchange path does not set a cookie — so `/auth/refresh` returned 401, which cleared the Bilko JWT and redirected back to `/login`. **Fix:** Replace the `checkAuth()` call in `handleEntraLogin` with `setAuthFromRegistration()`, which hydrates the Zustand auth store directly from the `/auth/entra/session` response body. No cookie round-trip needed. ``` // apps/web/lib/msal/use-entra-auth.ts — hydrate from session response const { setAuthFromRegistration } = useAuthStore.getState() setAuthFromRegistration({ user: sessionResult.user, organization: sessionResult.organization, tokens: { accessToken: bilkoJwt }, }) // Navigate to /dashboard — Bilko JWT is in-memory Bearer ``` ### B1.3 — checkAuth in-memory JWT fast-path (commit 30a8c85, tag v0.2.47) **Problem:** Even with B1.2, `setAuthFromRegistration()` in `handleEntraLogin` correctly set `isAuthenticated=true`. However, `AuthProvider` mounts on every protected route and calls `checkAuth()`. That call hit `/auth/refresh` (cookie path) → 401 → store reset to unauthenticated → redirect to `/login` on every page navigation. **Fix:** Added an in-memory JWT fast-path at the top of `checkAuth()` in `auth-store.ts`. If a Bilko JWT is already in memory (set via the CIAM exchange), `checkAuth()` uses `GET /auth/me` with that Bearer token instead of falling through to the cookie-refresh path. ``` // apps/web/lib/stores/auth-store.ts — in-memory fast-path checkAuth: async () => { const inMemoryToken = getAccessToken() if (inMemoryToken) { try { const me = await api.auth.me() set({ isAuthenticated: true, isLoading: false, user: { ...me, name: me.fullName }, organization: me?.organization ?? null }) return true } catch { set({ isAuthenticated: false, isLoading: false, user: null, organization: null }) return false } } // Original cookie-refresh fallback (unchanged — non-CIAM sessions) ... } ``` ### ENTRA\_EXTERNAL\_ID\_AUDIENCE — critical build var (fixed in v0.2.47 trigger update) **Problem:** The `bilko-main-deploy` Cloud Build trigger had `_ENTRA_EXTERNAL_ID_AUDIENCE` set to `fe39e0f5` (the API resource app ID). This is wrong — the CIAM idToken audience is the *SPA client ID* (`c2902239`), because MSAL requests id\_tokens scoped to the requesting app. Every new deploy reverted the Cloud Run env to the wrong value, requiring a manual patch. **Fix:** The trigger substitution was updated: ``` # infrastructure/gcp/cloudbuild.yaml — correct value _ENTRA_EXTERNAL_ID_AUDIENCE: c2902239-ea63-41bd-8619-6cf096d7d45a # SPA client ID # NOT: fe39e0f5-513e-40af-93f0-c3ee624df56c (that is the API resource app — wrong for idToken aud) ``` This is now stable in the trigger — it will not revert on future deploys. --- ## 4. Backend JIT Provisioning ### 4.1 Database migrations (Flyway V66–V69)
MigrationPurpose
V66\_\_entra\_rls\_and\_password\_nullable.sqlMakes `password_hash` nullable (Entra-only users have no password). Adds RLS policy on `entra_external_identities` (FORCE + fail-closed). Adds CHECK constraint: issuer must not end with trailing slash.
V67\_\_rbac\_permissions\_catalog.sqlRBAC permissions catalog seeding.
V68\_\_rbac\_user\_provisioning.sqlSECURITY DEFINER function `bilko_auth.provision_user_with_org()`: creates org (7-day trial, `trial_starts_at`, `trial_ends_at = now() + 7 days`), creates user (`role='viewer'`, `password_hash=NULL`), inserts `entra_external_identities` row (issuer, OID, user\_id). Default: `country='BA'`, `currency='BAM'`.
V69\_\_fix\_provision\_rls.sqlRLS fix: calls `set_config('app.current_org_id', v_org_id, true)` before the users INSERT so that RLS policies on the users table pass during JIT provisioning.
### 4.2 JIT provisioning call flow ``` POST /auth/entra/session { idToken } → EntraExternalIdService.verifyIdToken() [RS256, JWKS, issuer+audience+exp] → AuthUserRepository.findByEntraIdentity(issuer, oid) → null (new user) → AuthUserRepository.findByEmail(email) → null (no existing Bilko account) → UserProvisioningService.provisionNewUserForEntra() → bilko_auth.provision_user_with_org() [SECURITY DEFINER, SERIALIZABLE] → INSERT organizations (trial 7 days) → INSERT users (role=viewer, password=null) → INSERT entra_external_identities (issuer, oid) → jwtService.signAccessToken(userId, email, role='viewer', orgId) → Response: { user, organization { trialEndsAt }, tokens { accessToken, refreshToken } } ``` **Idempotency:** Re-login with the same OID returns the existing user and org; trial end date is not reset. The `entra_external_identities` table has a UNIQUE constraint on `(issuer, subject)`. ### 4.3 trialEndsAt in /auth/me The `GET /auth/me` response includes `organization.trialEndsAt` (ISO 8601). The frontend auth store exposes this on the `Organization` interface. The trial expiry is enforced server-side by `TrialGatePlugin` which queries the DB on every gated request — the JWT does not embed expiry. ### 4.4 RLS isolation All JIT-provisioned tenants are isolated via PostgreSQL Row Level Security. The `app.current_org_id` session variable is set by `OrgScopePlugin` from the `BilkoPrincipal` (JWT-derived, not from any HTTP header). `orgTransaction()` uses `SET LOCAL` scoped to the transaction — connection pool does not carry state between requests. Cross-tenant isolation is verified by `RlsOrgIsolationV46IntegrationTest`. --- ## 5. Deploy
PropertyValue
Deploy triggerbilko-main-deploy (europe-north1, project tribal-sign-487920-k0)
Trigger typesemver tag on main: `git tag vX.Y.Z && git push origin vX.Y.Z`
Configinfrastructure/gcp/cloudbuild.yaml
Current live tagv0.2.47 (commit 30a8c85)
Web revisionbilko-web-demo-00080-tq5
API revisionbilko-api-demo-00155-524
CIAM env vars in triggerNEXT\_PUBLIC\_ENTRA\_CLIENT\_ID, NEXT\_PUBLIC\_ENTRA\_AUTHORITY, NEXT\_PUBLIC\_ENTRA\_SCOPE, ENTRA\_EXTERNAL\_ID\_ISSUER, ENTRA\_EXTERNAL\_ID\_AUDIENCE (= c2902239), ENTRA\_EXTERNAL\_ID\_JWKS\_URL
**ZAKON PI2:** Do not run `cloudbuild.yaml` manually. Use `git tag + git push origin` only. The stage pipeline (`bilko-stage-auto-deploy`) fires on every push to main and is unrelated to the demo deploy. --- ## 6. Known Follow-Ups
IDPriorityDescription
H1 HIGH — must-fix before scale launch **Abuse gate (MC #103245):** JIT provisioning has no server-side rate gate on tenant creation. An attacker with many email inboxes can script CIAM sign-ups (each requires a real OTP but automation services exist). Fix: add a platform-level provision rate gate in `UserProvisioningService.provisionNewUserForEntra()` (max N JIT orgs per hour) + CIAM tenant configuration to block disposable email domains.
B3 MEDIUM **Migadu email OTP blocking:** Migadu (one.com), used for `@alai.no`, blocks Microsoft Azure CIAM OTP emails. Prospects with Gmail or Outlook receive OTP in ~6 seconds. Alai staff using `@alai.no` addresses cannot sign up. Fix: whitelist `accountprotection.microsoft.com` sender in Migadu SPF settings, or configure a custom CIAM email sender domain.
UX-1 LOW **Org display name:** JIT-provisioned orgs are named "unknown's Organization" (no display name collected at signup). The user flow only collects email. Fix: add displayName to the BilkoSignUpSignIn attribute collection (Azure config, no code change), or collect it on first post-login screen.
UX-2 LOW **Default country/currency:** JIT-provisioned org defaults to `country='BA'`, `currency='BAM'`. Prospects outside Bosnia must update via Settings. A country selection step at signup would improve the onboarding experience (follow-on, not a blocker).
M1 MEDIUM **INGRESS\_TRAFFIC\_ALL (MC #99924):** Direct `*.run.app` access bypasses GCLB, which degrades IP-based rate limiting to per-GFE-region keying. Pre-existing risk, not introduced by CIAM. Fix: lock ingress to internal-only when load balancer is provisioned.
M3 MEDIUM **No alert on rapid tenant creation:** Add a GCP Cloud Monitoring alert triggering when more than N organisations are JIT-provisioned per hour.
--- ## 7. Validation Evidence ### Proveo — 11/11 PASS (v0.2.47, 2026-06-09T02:55Z) Real Gmail sign-up (alembasic@gmail.com) end-to-end on `bilko-demo.alai.no`:
StepResultDetails
1PASSSelf-serve copy present; "Contact your administrator" absent
2PASS"Sign in with Microsoft" → ciamlogin.com (tenant 20bb17de) redirect
3PASSEmail entered on CIAM; OTP sent immediately
4PASSReturning user — OTP sent directly (no create-account needed)
5PASS8-digit OTP (17717965) received via Gmail UID:75644 in 7 seconds
6PASSRedirect back to bilko-demo.alai.no/dashboard
7PASSPOST /auth/entra/session → 200, Bilko HMAC JWT, org 4e96b6ff confirmed
8PASS/dashboard with trial UI ("Probno: 6 dana preostalo"), /auth/me → 200 + trialEndsAt 2026-06-15
9PASS/invoices via SPA nav — empty org (0 invoices), session alive
10PASS/invoices/new — invoice form visible, trial tenant usable
11PASSRegression clear — admin wall absent, self-serve copy confirmed
**Zero /auth/refresh calls** during SPA navigation after B1.3 fix (confirmed by network capture count=0). Cross-tenant RLS: org 4e96b6ff shows 0 invoices and 0 BAM balances (no data from other tenants). ### Securion — LAUNCH WITH CONDITIONS - CRITICAL: None found. - HIGH: H1 (JIT provisioning rate gate) — must fix before scale launch (MC #103245). - PASS areas: RS256 JWKS verification, issuer/audience pinning, OID as identity anchor, alg:none bypass blocked, org\_id derived from DB (not Entra token), RLS fail-closed, FORCE RLS on all 9 tenant tables, role=viewer hardcoded (no self-escalation), trial re-signup blocked, refresh token rotation (jti-based single-use), legacy auth endpoints retired (HTTP 410). --- ## 8. DEPLOY-MAP Reference The CIAM substitutions live in `infrastructure/gcp/cloudbuild.yaml` under the `bilko-main-deploy` trigger. The Cloudflare Turnstile entries in DEPLOY-MAP.md cover the marketing landing forms and are unrelated to the CIAM auth flow. No DEPLOY-MAP.md changes are required for the CIAM self-serve trial feature — the trigger substitutions are already updated. Do not add CIAM secrets to the DEPLOY-MAP secrets table — these are build-time substitutions injected directly from the trigger, not GCP Secret Manager secrets. --- ## 9. Environment Variables Reference
VariableServiceCorrect value note
NEXT\_PUBLIC\_ENTRA\_CLIENT\_IDbilko-web-demo (build-time)c2902239-ea63-41bd-8619-6cf096d7d45a (SPA app)
NEXT\_PUBLIC\_ENTRA\_AUTHORITYbilko-web-demo (build-time)https://\[tenant-id\].ciamlogin.com/\[tenant-id\]/v2.0 — no user flow suffix needed
NEXT\_PUBLIC\_ENTRA\_SCOPEbilko-web-demo (build-time)api://fe39e0f5.../access\_as\_user
ENTRA\_EXTERNAL\_ID\_ISSUERbilko-api-demohttps://\[tenant-id\].ciamlogin.com/\[tenant-id\]/v2.0
ENTRA\_EXTERNAL\_ID\_AUDIENCEbilko-api-demo**c2902239-ea63-41bd-8619-6cf096d7d45a** (SPA client ID — NOT the API resource ID)
ENTRA\_EXTERNAL\_ID\_JWKS\_URLbilko-api-demohttps://\[tenant-id\].ciamlogin.com/\[tenant-id\]/discovery/v2.0/keys
**Critical:** `ENTRA_EXTERNAL_ID_AUDIENCE` must be the SPA client ID (`c2902239`), not the API resource app ID. MSAL requests id\_tokens with the SPA client as audience. If set to the API app ID, the backend rejects every CIAM idToken with audience mismatch. --- *Page created by Skillforge (MC #103232 WS-D, 2026-06-09). Source evidence: /tmp/evidence-103232/. Validation: Proveo 11/11 PASS + Securion LAUNCH WITH CONDITIONS.* # AI Support Agent — bilko.cloud (HR) # AI Support Agent — bilko.cloud (HR) **Status:** Phase 1 operational (internal copilot); Phase 2 customer-facing widget HELD for Securion review **MC Task:** #104429 **Owner:** John → CodeCraft (Petter Graff lead) **Built:** 2026-06-28 ## 1. Purpose & Scope The **Bilko Cloud AI Support Agent** is a dedicated support system for the `bilko.cloud` (Croatia) jurisdiction of the Bilko SaaS platform. It handles **both technical problems** (login/Entra SSO, e-invoice/OIB failures, RLS, deploy errors) **and user/accounting questions** (PDV rates, HR-FISK/eRačun, invoices, bookkeeping, general ledger) — grounded in the Bilko knowledge base, validated by HR accounting domain experts, and gated by anti-hallucination verification. **Phased deployment:** - **Phase 1 — Internal copilot** (current): Assists ALAI/SnowIT support staff via ticketing workflow; human approves and sends answers. No direct customer exposure. - **Phase 2 — Customer-facing widget** (planned, HELD): In-app chat widget on `bilko.cloud` that auto-drafts answers in `triageJson` with guardrails (PII allowlist, prompt-injection guard, scope, escalation). Requires Securion security review before go-live. **Jurisdiction:** Croatia only. The agent reasons under **HR tax/accounting rules** and answers in **Croatian (hr-HR)**. **Cost target:** $0 per question (runs on local tier-2 models: Qwen 2.5 Coder 32B / MLX). ## 2. The Team — 5 Agents
RoleAgentRegistryJob
Lead architect**Petter Graff**`~/.claude/agents/petter-graff.md`Owns architecture, gates phases, integration design
Research (Phase 0)Datavera / Exploreephemeral dispatchesHR support taxonomy, competitor patterns, KB extraction (completed)
Support persona**bilko-support**`~/.claude/agents/bilko-support.md`Orchestrates answer pipeline, enforces anti-hallucination, escalation
HR accounting expert #1**bilko-racunovodstvo-hr**`~/.claude/agents/bilko-racunovodstvo-hr.md`Dvojno knjigovodstvo, RRiF chart of accounts, GL, expenses, financial statements (RDG/bilanca); KB author + validation gate
HR tax/fiscalization expert #2**bilko-porez-fiskalizacija-hr**`~/.claude/agents/bilko-porez-fiskalizacija-hr.md`PDV (25/13/5/0%), HR-FISK 2.0/eRačun (UBL 2.1/EN 16931), OIB validation, FINA, filing deadlines; KB author + validation gate
All three personas (bilko-support + 2 experts) registered in `~/system/agents/specialist-mapping.json`: - `bilko-support` → company `ALAI`, domain `product-support` - `bilko-racunovodstvo-hr` + `bilko-porez-fiskalizacija-hr` → company `Finverge`, domain `hr-accounting` ## 3. Architecture — Answer Pipeline **Orchestrator:** `~/system/tools/bilko-support-answer.js` (305 lines, CLI + module.exports). **Pipeline (8 steps, deterministic):** ``` question (+ contextBundle: errorCode, appRoute, country=HR, planTier, orgId…) ↓ [1] classify + route tier-router.js (local $0 model) ↓ [2] cache check rag-router.js (flywheel.db hit? early return) ⮑ if cached + confidence >= 0.70 (or not acct/tax/e-invoice) → DONE ⮑ if cached BUT classification ∈ {accounting, tax, e-invoice} AND confidence < 0.70 → escalate:true, return ↓ [3] retrieve context KB JSONL search (40 Q&A pairs) + LightRAG hybrid (knowledge.db) + HiveMind semantic (hivemind.db, fire-and-forget) ↓ [4] draft answer (Croatian) tier-2 local model (Qwen/MLX) ↓ [5] anti-hallucination gate mini-verifier.js ⮑ HALLUCINATION (cited file missing/empty) → escalate ⮑ DRIFT (file present but ambiguous/language mismatch) → reduce confidence ⮑ CONFIRMED (grounded) → boost confidence ⮑ SKIP (verifier offline) → neutral ↓ [6] accounting validation if classification ∈ {accounting, tax, e-invoice}: ⮑ re-verify vs domain-specific KB (hr-tax-fiscalization, hr-accounting sources) ⮑ if no domain KB → escalate ⮑ if HALLUCINATION or CONFIRMED < 0.70 → escalate ↓ [7] confidence floor gate belowAccountingFloor(cls, confidence) ⮑ if acct/tax/e-invoice AND confidence < 0.70 → escalate:true (same helper used on BOTH cache path [L139] and pipeline path [L258]) ↓ [8] cost log + return {answer, confidence, evidence_paths, classification, severity, escalate, source} ``` **Output schema:** ``` { "answer": "", "confidence": 0.0–1.0, "evidence_paths": [""], "classification": "technical | accounting | tax | e-invoice | billing | onboarding | other", "severity": "P1 | P2 | P3 | P4", "escalate": boolean, "source": "cached | local | escalated" } ``` ## 4. Escalation Policy **Hard rule (enforced in code):** `ACCOUNTING_CONF_FLOOR = 0.70` Any answer with classification ∈ `{accounting, tax, e-invoice}` AND confidence < 0.70 MUST escalate to a human specialist (or to `bilko-racunovodstvo-hr` / `bilko-porez-fiskalizacija-hr` personas in async workflow). **Escalation triggers:** - Verifier verdict = `HALLUCINATION` (fabricated citation) - Unknown question (no KB match, no LightRAG answer) - Accounting/tax claim: no domain-specific KB evidence OR domain-verified confidence < 0.70 - Confidence < 0.70 on cache hit for acct/tax/e-invoice (uses same `belowAccountingFloor()` helper as pipeline path) - Severity P1 (critical production blocker) **Single source of truth:** The `belowAccountingFloor(cls, confidence)` function (line 62) is called on BOTH the cache early-return path (line 139) and the post-step-6 gate (line 258) — guarantees no drift in threshold logic. ## 5. Knowledge Base — 40 Source-Cited Q&A Pairs **Storage (current):** JSONL files read directly by orchestrator; ingestion into `lightrag/knowledge.db` is a pending enhancement. - `~/system/reports/bilko-kb/hr-tax-fiscalization.jsonl` — 20 pairs (PDV rates/deadlines, HR-FISK 2.0/eRačun B2B mandatory 2026-01-01, OIB validation ISO 7064 MOD 11,10, FINA rejection reasons, B2G since 2019-07-01, UBL 2.1/EN 16931, EUR since 2023-01-01) - `~/system/reports/bilko-kb/hr-accounting.jsonl` — 20 pairs (RRiF chart classes 0-7, GL journal on invoice lifecycle sent→paid, expense approve→paid, storno/cancel logic, tečaj lock, RDG/bilanca/trial balance, fiscal year 1.1.–31.12., audit trail 7y retention) **Sources cited:** - `~/business/ALAI-Holding-AS/products/Bilko/docs/regulatory/CROATIA-ERACUN.md` (authoritative HR doc, HIGH confidence) - `~/business/ALAI-Holding-AS/products/Bilko/packages/domain-hr/src/tax/index.ts` - `~/business/ALAI-Holding-AS/products/Bilko/packages/domain-hr/src/chart/index.ts` (RRiF CoA implementation) - `~/business/ALAI-Holding-AS/products/Bilko/packages/domain-hr/src/fisk/index.ts` (OIB validateOIB) - `~/business/ALAI-Holding-AS/products/Bilko/packages/domain-hr/src/filing/index.ts` (eRačun UBL 2.1 generation) - `~/business/ALAI-Holding-AS/products/Bilko/docs/backend/BUSINESS-LOGIC.md` Each entry has: `{q, a, source, confidence: "HIGH" | "MEDIUM", domain: "hr-tax-fiscalization" | "hr-accounting"}`. **Confidence levels:** - **HIGH** — direct from CROATIA-ERACUN.md or implemented code (domain-hr packages) - **MEDIUM** — inferred deadlines or regulatory interpretations (recommend user confirm with Porezna uprava / FINA / certified accountant) ## 6. Integration with Bilko Backend **Existing infrastructure (reused, not built for this):** - `apps/api/src/routes/SupportTicketRoutes.kt` (437 lines) - `support_tickets` table (org\_id, subject, description, status open/in\_progress/resolved/closed, priority P1–P4, created\_at, updated\_at) - `POST /support/tickets` — idempotency key `(org_id, request_id)` - `GET /admin/support/tickets`, `PATCH /admin/support/tickets/:id` - PII-guarded `context_bundle` field (errorCode, appRoute, planTier, locale — allowlist enforced server-side) - **Reserved field:** `triageJson` (line 62 comment: "for AI assistant V2") — this is the Phase 2 hook **Phase 1 workflow:** 1. Staff create/triage ticket via `~/system/tools/support-ticket.js` (SLA P1–P4) 2. Call `node ~/system/tools/bilko-support-answer.js "" ''` 3. Agent returns JSON with answer + evidence + classification + escalate flag 4. Human reviews, approves, sends to customer (via email / admin panel) **Phase 2 workflow (planned, HELD):** 1. Customer opens in-app chat widget on `bilko.cloud` 2. Widget calls `POST /support/tickets` with `context_bundle` 3. Backend triggers `bilko-support-answer.js` (via internal job queue or sync call) 4. Agent output written to `triageJson` field: `{suggestedAnswer, classification, severity, escalate, confidence, evidencePaths}` 5. Render in UI: if `escalate:false` AND `confidence >= 0.70` → show AI answer with citation; else → "Eskaliran na podršku, očekujte odgovor u " 6. Guardrails: PII allowlist (already enforced), prompt-injection guard (add Securion layer), scope validation (no cross-org queries) **Security note:** Phase 2 requires Securion/Parisa Tabriz security review before live deployment (MC follow-up task). ## 7. Product Bugs Found by Experts (During KB Build) The 2 HR accounting experts found **8 Bilko product/documentation defects** while authoring the knowledge base:
MCSeverityIssue
\#104441P3Bilko MVP GL: only 1 D/P per transaction → PDV not split to konto 450 Obveze za PDV (tracking via reports only, not GL)
\#104446P3OIB validation: CROATIA-ERACUN.md missing ISO 7064 MOD 11,10 detail (in code, not doc)
\#104447P2CoA setup friction: not available in wizard, only post-onboarding in Settings (USER-ONBOARDING.md gap)
\#104442P3Storno logic: cannot cancel `paid` invoices (needs credit note, not auto-generated in MVP)
\#104448P4BUSINESS-LOGIC.md: HR PDV table lists only 25%/13%, omits 5%/0% (available via free input, just not in doc table)
*3 additional minor doc inconsistencies logged*
These are now tracked separately and do not block the support agent (KB answers work around them with "Bilko MVP limitation" disclaimers where needed). ## 8. Runbook — How to Invoke **CLI:** ``` node ~/system/tools/bilko-support-answer.js "" '' ``` **Example:** ``` node ~/system/tools/bilko-support-answer.js \ "Koja je stopa PDV-a na knjige u Hrvatskoj?" \ '{"country":"HR","planTier":"PRO","locale":"hr-HR"}' ``` **Output (JSON to stdout):** ``` { "answer": "Stopa PDV-a od 5% primjenjuje se na knjige...", "confidence": 0.78, "evidence_paths": ["/Users/makinja/.../CROATIA-ERACUN.md"], "classification": "tax", "severity": "P3", "escalate": false, "source": "local" } ``` **Module API:** ``` const { answer } = require('~/system/tools/bilko-support-answer'); const result = await answer(question, contextBundle); ``` **Cost tracking (automatic):** Each call logs to `~/system/tools/cost-tracker.js` with `{source: 'bilko-support-agent', backend: 'ollama', model: '...', cost_usd: 0, duration_ms, metadata}`. ## 9. Open Follow-Ups
MCTaskOwner
\#104432**Proveo UAT** — end-to-end verification: empty-KB degradation, offline-model fallback, severity classification coverage, schema validation, real ticket replayProveo / Angie Jones
\#104430**Phase 1 deployment** — staff onboarding, `support-ticket.js` workflow integration, SLA monitoringFlowForge / Kelsey Hightower
\#104431**Phase 2 customer-facing widget** — frontend component, POST hook, guardrails (HELD pending Securion)Vizu / Brad Frost + Securion / Parisa Tabriz
(backlog)KB ingestion into `lightrag/knowledge.db` (enhancement: replace JSONL direct-read with Neo4j-backed hybrid retrieval)AgentForge / Chip Huyen
(backlog)Securion review: confidence thresholds, cache-of-escalated-answers audit, PII leak surface, prompt-injection testsSecurion / Parisa Tabriz
## 10. Verification Evidence **MC #104429 verdict:** `PASS` (2026-06-28, john verified) **Method:** Company-Mesh (CodeCraft built, John verified via real CLI runs) **Evidence:** `~/system/evidence/104429/verdict.json` **Verified behaviors:** - Tax Q 'PDV na knjige' → 5% grounded (CROATIA-ERACUN.md + domain-hr/src/tax) - Unknown Q → `escalate:true`, `source:escalated` - Pipeline tax conf 0.62 → `escalate:true` - Cache tax conf 0.6547 → `escalate:true` (floor enforced on cache path) - Cache tax conf 1.0 → `escalate:false` (no over-escalation) - `belowAccountingFloor` defined once (L62), called L139 (cache) + L258 (pipeline) — no threshold drift **2 under-escalation defects caught & fixed:** Sub-0.70 tax answers on both pipeline AND cache paths were initially missing the confidence floor check; John's independent runs caught these, and CodeCraft fixed them via the shared `belowAccountingFloor()` helper. --- *This page is the deliverable for MC #104433 (ZAKON PLAN mandatory documentation task). Last updated: 2026-06-28.* # Bilko HR — Inbound e-Invoice Reject + Monthly Rejection eIzvještavanje (MC #106149 / #106146) *MC #106149 (reject action, M) + #106146 (monthly eIzvještavanje report, H, RED-ZONE HR tax/compliance). Coupled/parent #106145. Status as of 2026-07-21: built and tested in an isolated worktree, **NOT merged or pushed** — no PR opened yet. This page documents the built state for handoff / next-session continuation.* ## What was built - **Reject action** on `received_einvoice` (inbound/AP e-invoice): transitions `processing_status` and records a Bilko-internal rejection reason code, reject timestamp, and eIzvještavanje transmission tracking fields. - **`RejectionReportService`**: builds the monthly batch of rejected inbound e-invoices Bilko must report to Porezna uprava under čl.52 (rok: 20th of the month, for the prior calendar month — domain-gate CONFIRMED, web-verified via 6 convergent sources, distinct from the separate NN 151/2025 PDV-filing deadline change). ## IMPORTANT — N/U/O is Bilko's own taxonomy, NOT Porezna's The domain gate (agent `bilko-porez-fiskalizacija-hr`) caught and corrected a first-draft modeling error before this shipped: - Porezna's actual N/U/O are **three different eIzvještavanje REPORT TYPES**, not three rejection sub-reasons: - **N** = Naplata — issuer reports collection/payment of an issued e-invoice (unrelated to rejection) - **U** = Usluge/Isporuke — paper-fallback reporting when an e-invoice couldn't be issued (unrelated to rejection) - **O** = Odbijanje — recipient reports a REJECTED inbound e-invoice under čl.52. This is the only one relevant to Bilko's use case. - Every row Bilko reports to Porezna is type **O** — there is no per-rejection N/U/O choice on the Porezna side. - Fix applied: `received_einvoice.reason_code` is documented (Kotlin KDoc + V140 SQL comment) as **Bilko's own internal rejection-reason taxonomy** for the UI/audit trail (satisfying čl.52 st.1's "obrazloženo"/justified requirement), reusing the N/U/O letters only for DB/product convenience — **not** a claim of matching Porezna's N/U/O. - `RejectionReportService.RECORD_TYPE` is hardcoded to `"O"` and is **never** derived from `received_einvoice.reason_code`. Tested explicitly (`RejectionReportIntegrationTest` test 5: `recordType == "O"` while `bilkoReasonCode == "U"`, asserted as two independently-preserved fields). Full domain-gate detail: `~/system/evidence/106149/domain-gate-verdict.md` ## Schema
MigrationContents
`V140__received_einvoice_reject_reason.sql`Adds to `received_einvoice`: `reason_code CHAR(1) CHECK IN ('N','U','O')` (Bilko-internal taxonomy, see above), `rejected_at`, `report_transmission_status CHECK IN ('pending','sent')`, `report_transmitted_at`, `report_period`. Does not edit V139.
`V141__rejection_report_rls_bypass.sql`Two `bilko_auth` `SECURITY DEFINER` functions — `find_rejected_einvoices_for_period`, `mark_einvoice_report_transmission` — plus `GRANT SELECT, UPDATE ON TABLE public.received_einvoice TO bilko_admin`. Same ADR-017 Pattern B shape as V139's own `find_org_by_registration_number`.
## Lessons — RLS/SECURITY DEFINER pattern has now recurred 6x (V33/V39/V100/V111/V139/V141) Two real bugs were caught live by the Testcontainers integration test (real Postgres + full V1..V141 Flyway chain, no SchemaUtils/mocks) during this build — not assumed, not pre-empted from memory: 1. **Cross-org RLS blind spot.** `RejectionReportService`'s monthly batch query initially used a raw Exposed `transaction{}` against `received_einvoice` (FORCE ROW LEVEL SECURITY, V139) with no `app.current_org_id` set. This silently returned ZERO rows for every org, every time — not an error, because RLS here is fail-closed-permissive: the query "succeeds" with an empty result set. Fixed via V141 SECURITY DEFINER functions. 2. **SECURITY DEFINER without table GRANT.** After adding the SECURITY DEFINER functions, they still failed with "permission denied for table received\_einvoice" — `bilko_admin` has BYPASSRLS (V30\_1/V32) but is not superuser and never received an explicit GRANT on this specific table (V139 only granted `bilko_app`). Fixed by adding the GRANT in V141, following the exact precedent already set by V33/V39/V100/V111 for other tables `bilko_admin` needed to read via SECURITY DEFINER functions. **Callout for future FORCE-RLS table + batch/admin-query work:** any new table with FORCE ROW LEVEL SECURITY that needs a cross-org admin/batch read path will hit both of these unless it (a) goes through a SECURITY DEFINER function from the start, and (b) that function's owning role has an explicit table GRANT. This is now a 6-occurrence pattern — worth turning into a migration checklist item or lint rule rather than re-discovering it per-feature. ## What's explicitly NOT done - **Actual HTTP submission to Porezna is not implemented.** `transmitToPorezna()` is a clearly-marked TODO stub that always returns `false` (even with `SVERACUN_HR_LIVE=true`), with a loud `log.warn` explaining why. `submitMonthlyReport()` therefore never falsely claims "sent". - **Reason:** payload/schema for the real eIzvještavanje submission is not confirmed at field level. `https://porezna-uprava.gov.hr/fiskalizacija/api/dokumenti/157` returns HTTP 200 but serves a client-rendered SPA shell ("Naslovna"), not the raw document body — the literal field-level schema needs either human/browser (JS-rendering) access to that page, or the FINA/Porezna eIzvještavanje XSD. - **No cron wiring yet.** The `POST /internal/compliance/rejection-report` endpoint is not wired to an active ACA scheduled trigger in this task — same "safe to deploy inert" posture as the existing send-reminders sibling endpoint. FlowForge/John to wire per the KDoc go-live note. - **No UI.** API-only, M-tier task, out of scope per the original brief. ## Verification performed - `./gradlew compileKotlin compileTestKotlin` — clean. - `RejectionReportIntegrationTest` (new, Testcontainers postgres:16-alpine, real V1..V141 Flyway chain, no mocks): 8/8 passed. Covers reject persistence + status transition, no-op same-reason re-reject vs tracked different-reason correction, org isolation both directions, rejecting an already-accepted row throws, report payload recordType=O with correct bilkoReasonCode, non-rejected rows excluded, transmission state null→pending (never falsely 'sent'), report\_period stamping, and idempotency (a row already 'sent' for a period is not re-transmitted). - Regression: pre-existing `ReceivedEInvoiceIntegrationTest` (MC #106162) re-run after V140/V141/Tables.kt changes — still 0 failures. - Full suite: `./gradlew test` — 1808 tests, 25 failed, all 25 isolated to 3 unrelated pre-existing classes (root cause: `SVERACUN_SENDER_VAT not configured`, a local-env config gap in outbound sveRacun e-invoicing, grep-verified unrelated to ReceivedEInvoice\*/RejectionReport\*/ComplianceCron\*). ## Branch / merge status - Branch: `feat/task-106149-reject-report`, commit `faf3aa78`. - Based on: `feat/task-106162-inbound-einvoice-persist`, commit `06812347` (V139 `received_einvoice` table + persist). - **Neither branch is merged or pushed to azdo main. No PR opened yet.** - Built in isolated worktree `.claude/worktrees/codecraft-106149` — the main Bilko working tree was left untouched (it had unrelated in-flight work on `feat/task-106147`). ## Next steps 1. Human/browser session to pull field-level schema from `porezna-uprava.gov.hr/fiskalizacija/api/dokumenti/157` (or FINA XSD) before implementing real `transmitToPorezna()`. 2. Proveo end-to-end verification (reject → report, real evidence). 3. Open PR: `feat/task-106162-inbound-einvoice-persist` → main, then `feat/task-106149-reject-report` → main (or squash/rebase as one PR chain). 4. FlowForge: wire cron trigger for `POST /internal/compliance/rejection-report`. 5. `mc.js ready` for #106149/#106146 after Proveo pass. ## Source evidence - `~/system/evidence/106149/build-verdict.md` — full build verdict (CodeCraft, agent id `codecraft-106149`, PASS) - `~/system/evidence/106149/domain-gate-verdict.md` — domain/legal correction (agent `bilko-porez-fiskalizacija-hr`, CORRECTION NEEDED on Q1, applied) # MC #106259 — Bilko Admin Portal Contract Fix **MC #106259** — fix for 4 contract defects found by Angie Jones' platform\_admin UAT catalog (**MC #106258**). Backend DTOs, frontend types/guards, and one missing route were brought back in sync so the admin portal stops crashing and stops showing wrong data. ## Defects fixed
\#SeverityDefectFix
1H`GET /admin/dashboard` returned **404** — no handler existed anywhere server-side despite being called on first admin page load and documented in the OpenAPI spec. Likely the first thing CEO saw fail on `/admin`.Implemented in `AdminPortalRoutes.kt` (`get("/dashboard")` inside the existing `route("/admin")` block, same `requirePlatformAdmin()` gate as every other admin route). `AdminOrgService.getDashboardStats()` added with real DB aggregates: `totalOrgs` (COUNT non-deleted orgs), `activeTrials` (BASIC plan + trial not expired), `recentAudit` (audit\_log LEFT JOIN users, DESC limit 10), `mrr` (explicit `0.0`, see limitation below).
2H`/admin/orgs/{id}` detail page **crashed on every org**. Backend `OrgDetail` DTO never set `mrr`, so Jackson omitted the key entirely; frontend called `Intl.NumberFormat().format(org.mrr)` → `TypeError: Cannot convert undefined to a number`, tripping the global Next.js error boundary. This is almost certainly the "admin stranice puca" CEO reported.`OrgDetail` DTO gained `mrr: Double` (always explicit, never omitted), plus `vatMethod`/`trialStatus`. Frontend defense-in-depth: all three MRR render sites (`orgs/[id]/page.tsx`, `orgs/page.tsx`, admin dashboard `page.tsx`) now guard `== null` before formatting, not just the one crash site.
3M`OrgListItem` (the `/admin/orgs` list) was missing `vatMethod`, `trialStatus`, `userCount`, `mrr` even though the frontend TS interface declared them as required. Effect: VAT Method column always "—", Users column always blank, and every org — trial or paid — rendered with the green "paid" badge since `trialBadge(undefined)` silently fell through.`OrgListItem` gained all four fields. `trialStatus` derived via new `resolveTrialStatus(planTier, trialEndsAt)` (read-model projection only — does not touch `TrialGatePlugin`/`TrialService` enforcement). `userCount` is one batched query per page (grouped/counted in one round-trip), not N+1 per row.
4LPagination/total count silently broken. Backend has always returned nested `{data, meta:{total,page,perPage,totalPages}}`; the frontend `AdminOrgsListResponse`/`AdminOrgUsersResponse` TS types declared a **flat** shape (`{data,total,...}`). Result: header count never rendered, and pagination controls would silently never appear once org count exceeded the 50-per-page limit (untriggered today at 9 orgs, but a live landmine).Frontend types changed to nest under `meta: AdminOrgsPaginationMeta` (chosen over flattening the backend, to avoid touching other `PaginatedResponse` consumers). Call sites in `orgs/page.tsx` updated to read `data.meta.total` / `data.meta.totalPages`.
## Branch / commit - Repo: `Bilko` (canonical remote `azdo`) - Branch: `feat/106259-admin-contract-fix`, created off `azdo/main` at `cb3746d6` - Commit: `5513d0e6339864b31c2d3507ca0219ede5b052ba` — pushed to `azdo`, verified on remote via `git ls-remote` - 8 files changed: `AdminPortalRoutes.kt`, `AdminOrgService.kt`, `AdminPortalRoutesHttpIntegrationTest.kt` (new tests T16–T19b), `orgs/[id]/page.tsx`, `orgs/page.tsx`, admin dashboard `page.tsx`, `lib/api.ts`, and a new frontend test file `admin-contract-106259.test.tsx` ## Test results - **Backend**: `AdminPortalRoutesHttpIntegrationTest` — **23/23 passed** (9 new tests T16–T19b, one per fix + auth-gate coverage, plus 14 pre-existing T1–T15 unmodified, zero regressions). Sibling admin suites unmodified and green: `AdminPortalRoutesP2Test` 10/10, `AdminRoutesHttpIntegrationTest` 6/6. - **Frontend**: new `admin-contract-106259.test.tsx` — **9/9 passed** (React Testing Library, real rendered component tree — MRR undefined/null guards, real-number formatting, vatMethod/trialStatus/userCount render, nested `meta.total`/`meta.totalPages` reads, pagination-controls visibility). Full production `next build` succeeds (65/65 routes), `tsc --noEmit` clean, pre-push `turbo run type-check` across all 12 workspace packages green. - **Independent verification (Angie Jones / Proveo)** — read code directly in the isolated worktree at commit `5513d0e6` (did not trust the builder's self-report), re-ran backend integration tests and frontend Vitest herself, and diffed the commit against base to confirm scope boundaries. **Verdict: PASS** on all 4 items. Confirmed independently via her own grep that no aggregate MRR computation exists anywhere in the codebase, and via direct diff that zero auth files were touched. ## Known limitation `mrr` is returned as an explicit `0.0` everywhere (dashboard, org detail, org list) — **not fabricated, but not real**. There is no Stripe MRR aggregation anywhere in the Bilko codebase today: `stripeSubscriptionId` is stored per-org but only ever resolved for trial-gate checks and billing/webhook flows, never rolled up into an aggregate revenue figure. Wiring a real MRR source (either a live Stripe API call per org, or a synced `mrr_amount` column updated via webhook) is separate, larger follow-on work. Flagged in code comments on the 3 DTOs (`OrgDetail`, `OrgListItem`, dashboard stats) for whoever picks that up next. ## Deliberately not touched - `AdminAuthPlugin.kt`, `JwtService.kt`, `Authentication.kt`, and the `bilko-jwt` verifier — confirmed untouched by direct diff (`git diff cb3746d6 5513d0e6 --name-only`, zero overlap). Angie's original catalog established that the `/admin/orgs` 401 CEO/UAT saw was a stale/expired access-token test artefact, not a server-side auth defect — nothing in the auth stack needed fixing. - `/admin/users` 405 — by design, only a `POST` handler exists; no frontend page calls `GET /admin/users`. Not a bug. - "Report error" support-ticket button — confirmed working live during the original catalog investigation (real `POST /support/tickets` → 201). - Flyway V146 warning — not reproducible; DB and deployed image agreed on schema version at investigation time. ## Follow-on: deploy is separate This ticket covers **code + test correctness only** (worktree/local verification). PR → CI → merge to `azdo/main` → stage/demo promotion is a separate follow-on step, not yet done as of this page. Do not treat this fix as live on stage/demo until that pipeline runs and is verified (curl/browser check on the actual environment, per ZAKON PI2). ## Evidence - Defect catalog (spec): `~/system/evidence/106258/admin-defect-catalog.md` - Build evidence: `~/system/evidence/106259/build-evidence.md` - Independent verify (PASS): `~/system/evidence/106259/angie-verify-2026-07-24.md` # Deep-Link Redirects Survive Login — Mechanism, Consumers, Open Gaps (MC #106384) # Deep-Link Redirects Survive Login — Mechanism, Consumers, and Open Gaps **MC:** #106384 | **Status:** LIVE on azdo/main (merge commit `480d95ca`, PR 272) | **Verified against:** `azdo/main` @ `50e4223a` (2026-07-28) | **Independent peer-verify verdict:** PARTIAL (angie-106384-peer) | **Last updated:** 2026-07-28 **One-line summary:** a user hitting a private URL while logged out is now returned to that exact URL after signing in — except on one landing (an already-open bug, #106423) — where before this fix the `redirect` parameter was written by middleware and read by nothing, so every login silently discarded it. --- ## 1. The problem this replaced Before this fix there were two independent defects, both required to explain the reported symptom (CEO clicks an emailed link like `/expenses/new?type=purchase`, has to log in, lands on `/dashboard` instead): 1. **Half 1** — `middleware.ts` built the login-redirect URL from the request **pathname only**. The query string was silently dropped before the user ever saw the login screen. 2. **Half 2** — even where a `redirect` parameter did survive, **nothing in the app read it**. The login success handler hardcoded `router.replace('/dashboard')`. A parameter that is written and never read is a control that renders and does nothing — the same class of defect as the dead filters/dead locale switcher this audit program was raised to find. Fixing only those two would still not have worked: a real Entra sign-in does not return to the URL the user was on at all (see §2). The shipped fix (PR 272, two witness rounds + one independent post-merge peer-verify) addresses five loss points end to end. This page documents the mechanism as it exists in the code today, not as originally scoped. --- ## 2. End-to-end mechanism ``` GET /expenses/new?type=purchase (unauthenticated) → middleware.ts:93 builds /login?redirect=%2Fexpenses%2Fnew%3Ftype%3Dpurchase (carries PATHNAME + SEARCH — this is the Half-1 fix) → user clicks "Sign in with Microsoft" → use-entra-auth.ts:214 signInWithMicrosoft() reads the CURRENT ?redirect= param and stashes it in sessionStorage — the LAST moment it still exists → instance.loginRedirect() hands control to Entra → https:///authorize?...&redirect_uri=https://app.bilko.cloud&response_mode=fragment (bare origin, no path, no query — see §2.1) → back to https://app.bilko.cloud/#code=... window.location.search is EMPTY here — the query param is gone for good → use-entra-auth.ts:170 handleEntraLogin() calls resolvePostLoginPath(...), which falls through the (now-empty) query param to the STASH → router.replace('/expenses/new?type=purchase') ← the deep link, recovered ``` ### 2.1 Why the query param cannot survive the Entra round trip MSAL is configured (`msal-config.ts`) with `redirectUri` defaulting to the bare page origin, `navigateToLoginRequestUrl: false`, and CIAM returns the auth code in the URL **fragment** (`response_mode=fragment`), not the query. This was measured live, credential-free, against production: the authorize request the app actually sends to Entra carries no path and no query, and the browser lands back on `https://app.bilko.cloud/#code=...` with `window.location.search === ''`. Any code that reads only `window.location.search` on the way back — which is exactly what the first version of this fix did — will always fall through to the dashboard fallback, regardless of how carefully the query param was carried on the way *in*. This was the fifth loss point found in witness round 1 and is why the stash (§3) exists at all. --- ## 3. The stash — surviving the round trip `apps/web/lib/safe-redirect.ts` defines the mechanism:
PropertyValue
Storage key`bilko_post_login_redirect` (`STASH_KEY`, safe-redirect.ts:92)
Storage mechanism`sessionStorage`, not `localStorage` — survives a full-page redirect in the same tab, dies with the tab, matches MSAL's own `cacheLocation` (also sessionStorage, chosen for XSS reasons)
Written`stashRedirectTarget()` — one call site, `use-entra-auth.ts:214`, inside `signInWithMicrosoft()`, immediately before `loginRedirect()`
TTL10 minutes (`STASH_TTL_MS`, safe-redirect.ts:96) — long enough for a sign-in, short enough that a stale value cannot hijack an unrelated later login in the same tab
Sanitizedon write (invalid target is never stored) AND on read (a stored value is not trusted more than a URL param just because the app put it there)
### 3.1 Why the read is deliberately non-consuming `readStashedRedirectTarget()` (safe-redirect.ts:129) does **not** delete the key when it reads it. This is deliberate and load-bearing, not an oversight: there are two consumers that both run on the way back from Entra (`handleEntraLogin` and the `auth-provider.tsx` safety net, §4), and **their execution order is not guaranteed**. If the first reader to run cleared the stash, the second would find nothing, fall through to `/dashboard`, and could overwrite the correct navigation the first reader just made. Both readers see the same answer instead. The value is retired by three other means: the next sign-in click (which unconditionally overwrites or clears it before any navigation happens), logout (§5), and the 10-minute TTL. --- ## 4. Two consumers of `resolvePostLoginPath` — one fixed, one still open `resolvePostLoginPath(params)` = `readRedirectTarget(params) ?? readStashedRedirectTarget() ?? '/dashboard'` (param-first, see §5). There are exactly two call sites in the app that ever consulted the stash-fallback version. A third call site (`/demo`) was later re-scoped to **stop** using the fallback — see §4.1.
ConsumerFile:lineScoped to genuine post-Entra return?
`handleEntraLogin``lib/msal/use-entra-auth.ts:170`YES — this function only runs after MSAL fires `LOGIN_SUCCESS`
Authenticated-landing safety net`lib/auth-provider.tsx:109`**NO — see §4.2, this is the open defect**
### 4.1 `/demo` — re-scoped, does NOT use the stash **Correction to the originating tickets:** the instant-demo page lives at `apps/web/app/(auth)/demo/page.tsx`, not under a `(dashboard)` route group as earlier ticket text said. The code is the source of truth here. `demo/page.tsx` was the **sixth loss point**: it hardcoded `router.replace('/dashboard')`, so the journey *deep link → `/login?redirect=...` → instant sign-in → `/demo?...&redirect=...`* still landed on `/dashboard` even once the Entra path was fixed, because the cross-domain hop to `/demo` forwards the whole query string and the page just wasn't reading it. The fix (demo/page.tsx:190) is **not** `resolvePostLoginPath(searchParams)` — it is `readRedirectTarget(searchParams) ?? DEFAULT_POST_LOGIN_PATH`, i.e. it reads **only its own query params, never the stash**. This distinction was found the hard way: a first attempt used the stash-fallback version and a witness proved live that an abandoned sign-in leaves a target in the stash, and a later `/demo?country=HR` visit in the **same tab**, inside the 10-minute TTL, silently followed the old target instead of going to the demo the user just asked for — a journey where that version of the branch was worse than main. `/demo` has no Entra redirect of its own to survive, so it never needs the stash; it already carries the param whenever one exists. ### 4.2 OPEN DEFECT — the safety net was never re-scoped (MC #106423) The independent post-merge peer-verify (angie-106384-peer, verdict PARTIAL) found that `/demo` was fixed on the surface where the stash-leak bug was *found*, but `auth-provider.tsx:90-114` — the "authenticated user landing on `/` or `/login`" safety net — is the **other** caller of `resolvePostLoginPath` and was **not** given the same treatment. It still falls back to the stash for **any** authenticated landing on `/` or `/login`, not only a genuine post-Entra return. Proven by rendering the real `AuthProvider` component directly (not by reading the code): with an already-authenticated client state, a plain navigation to `/` with no query param, and a stash pre-seeded from an earlier sign-in, `router.replace` fired with the **stale stashed target** instead of leaving the user on `/`. **Reachability, honestly scoped narrower than the original N1 finding:** because the stash is non-consuming by design (§3.1), even a fully **successful** sign-in leaves the target sitting in `sessionStorage` for up to 10 more minutes. There is no in-app link to bare `/` from inside the authenticated dashboard shell, so this requires the user to navigate to the site root directly (URL bar, bookmark, external link) within that window while a stash from their own earlier sign-in — completed or abandoned — is still live. Real and user-visible, but a specific navigation habit rather than the default customer-facing path `/demo` is. **Why no test caught this:** no test in the entire suite renders `AuthProvider` or drives `handleEntraLogin` — flagged as a residual (R6) in the very first witness round and never closed. The fix that scoped `/demo` correctly (§4.1) left this sibling caller untouched because nothing exercises it. **Status: OPEN, tracked as MC #106423.** The prescribed fix is the same one-line treatment `/demo` got: this effect should read only whether it is landing here as a genuine post-Entra return (empty search, code in the fragment) versus any other authenticated landing on `/` or `/login`, and only consult the stash for the former — plus a test that actually renders `AuthProvider`, so this class of gap stops being invisible to the suite. --- ## 5. Why the cleanup lives in `authStore.logout()`, not `signOutFromEntra` **This is the single most useful fact on this page for whoever touches this code next.** `use-entra-auth.ts` defines and exports a function called `signOutFromEntra` (line 250) which does the "correct" full teardown: it calls the real logout, clears the marker cookie, clears the locale choice, calls `clearStashedRedirectTarget()` (line 271), and finally calls MSAL's `logoutRedirect` to end the Entra session itself. Reading that function in isolation, it looks like the obvious place the stash gets cleaned up. **It is not called anywhere.** Grepping `lib`, `app`, `components` for `signOutFromEntra` at `azdo/main` today returns exactly: the interface member declaration, the function definition, and the object literal that exports it from the hook. Zero call sites. The two logout paths a user can actually reach in this app are: - `components/top-bar.tsx:203` — `await useAuthStore.getState().logout()`, the user-menu "Log out" button - `components/DemoBannerWrapper.tsx` — "exit demo" also routes through the real `logout()` Neither of those goes anywhere near `signOutFromEntra`. So while this fix was being built, the first version of the cleanup was written correctly and placed in `signOutFromEntra` — and reproduced, inside its own fix, the **exact defect class the fix exists to kill**: a control that reads correctly and has no consumer. The original bug was a `redirect` query param nobody read; the accidental recreation was a cleanup function nobody called. **The actual fix:** `clearStashedRedirectTarget()` was moved into `lib/stores/auth-store.ts:233`, inside `logout()` itself — the one function both real logout paths in the app call through. That is confirmed reachable from both buttons. The lesson generalises past this one bug: **for any fix of this shape, enumerate every caller of the mechanism, including teardown** — not just the one the bug report happened to describe. **What this means for `signOutFromEntra` today:** it is dead code on a cleanup path, tracked separately as **MC #106421**, still open. That ticket deliberately does *not* conclude "delete it" — it asks whether Bilko's real logout is *supposed* to also end the user's Microsoft/Entra session (the way `signOutFromEntra`'s `logoutRedirect` call would do) and currently does not, because nothing calls the function that would do it. If that's the case, the actual bug is that `signOutFromEntra` is **not wired up** — a possible security-relevant gap (Entra SSO session surviving a Bilko logout on a shared machine), not simply dead code to delete. That question is still open. --- ## 6. Param-first on the return leg — the decision, and its residual `resolvePostLoginPath` checks the URL query param **before** the stash. This was deliberately re-examined (not just carried over) after a reviewer asked whether a fresh param should ever lose to an old stash, and the answer is: it depends which leg you're on. - **The true post-Entra return** (bare origin, code in the fragment) has **no query at all** — `window.location.search` is empty (§2.1). The stash wins here by default; param-vs-stash does not even arise. - **The contested case** is `/login?redirect=X` reached with a live `bilko_auth` cookie but no in-tab MSAL session — e.g. a link opened in a new tab, or a repeat visit later the same day. Here `X` was written seconds ago, by `middleware.ts:93` or `auth-provider.tsx:126`, from the path the user **just requested**. The stash, by construction, is older — written up to 10 minutes earlier, at the start of a *previous* sign-in. **Param-first was kept** on the reasoning that preferring a 10-minute-old stash over a just-expressed navigation would generalise the exact bug found in the `/demo` case (§4.1) rather than fix anything. **Residual, stated plainly:** this reasoning holds only while *every* writer of the `redirect` query param is writing genuine, current user intent. Today there are exactly two writers — `middleware.ts:93` and `auth-provider.tsx:126` — and both were re-checked and confirmed to derive the value from the path the user was actually just bounced from. If a future change adds a third writer of that param for some other purpose, or repurposes one of the two existing writers, param-first silently becomes the wrong rule on this leg. Re-verify this list before trusting the rule again. --- ## 7. What is NOT verified live **The real browser round-trip through Entra — redirect\_uri, the fragment-mode code return, and sessionStorage surviving the cross-origin navigation to the CIAM host and back — has never been observed by us with a real, credentialed sign-in.** There are no Entra credentials in the agent environment this work was built and reviewed in. What *was* observed live, credential-free, and should not be conflated with the above: - The authorize request the app sends to Entra (redirect\_uri = bare origin, response\_mode = fragment) — captured from a real headless click on the "Sign in with Microsoft" button, no password entered. - The mechanism the whole fix rests on — a value written to `sessionStorage` on `app.bilko.cloud`, invisible while the browser is on the CIAM host (that *is* the trap this fix exists to survive), then intact again back on `app.bilko.cloud` with an empty `window.location.search` — reproduced against production with a real navigation to the CIAM host and back. - The `/demo` journey end to end, including the open-redirect guard surviving a real navigation decision, on a production build. What remains genuinely unobserved: a **successfully authenticated** user's landing page after a real password/consent flow. That half of the original defect is verified in code and by component-level tests, not by watching it happen. Do not present this mechanism as fully live-verified — it is proven live up to the boundary Entra credentials impose, and proven in code beyond that boundary. --- ## 8. Related open tickets --- ## 9. Source Verified against `azdo/main` @ `50e4223a` (2026-07-28), which includes the merge commit `480d95ca` (PR 272, MC #106384). - `apps/web/middleware.ts` - `apps/web/lib/safe-redirect.ts` - `apps/web/lib/msal/use-entra-auth.ts` - `apps/web/lib/msal/msal-config.ts` - `apps/web/lib/auth-provider.tsx` - `apps/web/lib/stores/auth-store.ts` - `apps/web/app/(auth)/demo/page.tsx` - `apps/web/components/top-bar.tsx` Evidence: `~/system/evidence/106384/fix-verdict.md`, `witness-verdict.md` (two rounds), `peer-verify-verdict.md` (independent, post-merge, verdict PARTIAL). # Testing & QA # Test Plan # Bilko — Test Plan **Version:** 1.0 **Date:** 2026-02-23 **Project ID:** bbd77cc0 **Status:** Current — reflects actual codebase and target testing strategy as of 2026-02-23 --- ## Table of Contents 1. [Test Philosophy](#1-test-philosophy) 2. [Unit Test Strategy](#2-unit-test-strategy) 3. [Integration Test Strategy](#3-integration-test-strategy) 4. [End-to-End Test Strategy](#4-end-to-end-test-strategy) 5. [Accounting Scenario Tests](#5-accounting-scenario-tests) 6. [Regulatory Compliance Tests](#6-regulatory-compliance-tests) 7. [Performance Benchmarks](#7-performance-benchmarks) 8. [Security Tests](#8-security-tests) 9. [Test Infrastructure](#9-test-infrastructure) 10. [Test Coverage Targets](#10-test-coverage-targets) --- ## 1. Test Philosophy ### 1.1 Existing Tests The `@bilko/core` package has unit tests written with **Vitest**: | Test File | Coverage | |-----------|---------| | `packages/core/tests/accounting.test.ts` | `validateDoubleEntry`, `createJournalEntry`, `calculateTrialBalance` | | `packages/core/tests/tax.test.ts` | `calculateVAT`, `getDefaultVATRate`, `getVATRates`, `calculateNetFromGross`, `calculateCIT` | | `packages/core/tests/multi-currency.test.ts` | `convertCurrency`, `lockExchangeRate`, `calculateForexGainLoss` | | `packages/core/tests/invoicing.test.ts` | Invoice calculation helpers | | `packages/core/tests/chart-of-accounts.test.ts` | Chart structure validation | ### 1.2 Test Pyramid ``` ┌─────────┐ │ E2E │ ← Fewer, slower, critical user flows │ Tests │ └────┬────┘ ┌────┴────┐ │ Integ │ ← API endpoints with real test DB │ Tests │ └────┬────┘ ┌─────────┴──────────┐ │ Unit Tests │ ← Core engine, services, validators (fast, many) └────────────────────┘ ``` ```mermaid graph TD subgraph PYRAMID["Bilko Test Pyramid"] E2E["E2E Tests — 10%
Playwright
5 critical flows
Staging environment
~60s per test"] INT["Integration Tests — 30%
Supertest + Vitest
Real PostgreSQL
API endpoints
~5s per test"] UNIT["Unit Tests — 60%
Vitest
@bilko/core engine
Pure functions
~50ms per test"] end E2E --> INT INT --> UNIT UNIT --> U1["accounting.test.ts"] UNIT --> U2["tax.test.ts"] UNIT --> U3["multi-currency.test.ts"] UNIT --> U4["bank-import.test.ts"] UNIT --> U5["chart-of-accounts.test.ts"] INT --> I1["auth.test.ts"] INT --> I2["invoices.test.ts"] INT --> I3["expenses.test.ts"] INT --> I4["reports.test.ts"] INT --> I5["isolation.test.ts"] E2E --> E1["invoice-lifecycle.spec.ts"] E2E --> E2["expense-flow.spec.ts"] E2E --> E3["bank-reconciliation.spec.ts"] E2E --> E4["reports.spec.ts"] E2E --> E5["auth.spec.ts"] style PYRAMID fill:#f8f9fa,stroke:#dee2e6 style E2E fill:#dc3545,color:#fff,stroke:#c82333 style INT fill:#fd7e14,color:#fff,stroke:#e8690b style UNIT fill:#198754,color:#fff,stroke:#157347 ``` ### 1.3 Non-Negotiable Rules 1. **Money is never JavaScript `number`** — all monetary tests use `Decimal.js` or string assertions 2. **Double-entry always balanced** — every test that creates a financial transaction verifies debit = credit 3. **Organization isolation** — cross-org data access must be impossible (tested explicitly) 4. **Immutability** — locked transactions cannot be modified (must throw/fail) 5. **Audit trail** — mutations must create `LoggedAction` entries (tested in integration) --- ## 2. Unit Test Strategy **Framework:** Vitest (already configured in `packages/core/vitest.config.ts`) **Run:** `cd packages/core && npx vitest` ### 2.1 Core Accounting Engine (`@bilko/core`) #### `accounting/index.ts` — Double-Entry Engine **File:** `packages/core/tests/accounting.test.ts` (EXISTS) | Test Case | Assertion | |-----------|-----------| | Balanced entry: debit = credit | `validateDoubleEntry` returns `true` | | Unbalanced entry: debit ≠ credit | Returns `false` | | Less than 2 lines | Returns `false` | | Negative amounts | Returns `false` | | Zero amounts | Returns `false` | | Multiple lines summing to balanced | Returns `true` | | Decimal amounts with 4dp precision | Returns `true` | | `createJournalEntry` with valid data | Returns entry unchanged | | Missing description | Throws "must have a description" | | Missing date | Throws "must have a date" | | Unbalanced amounts in error message | Error shows actual debit/credit totals | | `calculateTrialBalance` from balanced entries | `isBalanced = true`, sums correct | | `calculateTrialBalance` groups by account number | Same account accumulated correctly | | `calculateTrialBalance` empty input | `isBalanced = true`, empty rows | | `calculateTrialBalance` sorts by account number | Rows sorted ascending | **Additional tests needed:** ```typescript describe('Immutable transaction locking', () => { it('locked transactions cannot have amount changed'); it('locked transactions cannot change debit/credit accounts'); it('locked = true after period close'); }); ``` --- #### `tax/index.ts` — VAT/CIT Calculator **File:** `packages/core/tests/tax.test.ts` (EXISTS) | Test Case | Assertion | |-----------|-----------| | Serbia PDV 20% on 1000 | base=1000, tax=200, total=1200 | | BiH PDV 17% on 1000 | base=1000, tax=170, total=1170 | | Croatia PDV 25% on 1000 | base=1000, tax=250, total=1250 | | Zero rate | tax=0, total=base | | Decimal base amounts (123.45 at 20%) | tax=24.69, total=148.14 | | Negative amount | Throws "non-negative" | | Negative rate | Throws "non-negative" | | Large amounts (999,999,999.9999) | No precision loss | | `Decimal` input accepted | Same result as string | | `getDefaultVATRate('RS')` | Returns 20 | | `getDefaultVATRate('BA')` | Returns 17 | | `getDefaultVATRate('HR')` | Returns 25 | | Unsupported country | Throws "Unsupported country" | | `getVATRates('RS')` | 3 rates: 20, 10, 0 | | `getVATRates('BA')` | 2 rates: 17, 0 | | `getVATRates('HR')` | 3 rates: 25, 13, 0 | | Returns copies (immutable) | Mutation doesn't affect originals | | Reverse VAT (BiH 1170 gross) | base≈1000, tax≈170 | | CIT at 15% | 100000 → 15000 | **Additional tests needed (country modules):** ```typescript // packages/country-rs/src/tax/index.ts describe('Serbian tax specifics', () => { it('calculateSerbianPDV standard 20%'); it('calculateSerbianPDV reduced 10%'); it('calculateSerbianPDV zero rate'); it('calculateSerbianCIT 15% flat'); it('qualifiesForPausalRegime: revenue < 6M RSD → true'); it('qualifiesForPausalRegime: revenue >= 6M RSD → false'); it('requiresVATRegistration: revenue >= 8M RSD → true'); it('requiresVATRegistration: revenue < 8M RSD → false'); }); // packages/country-ba/src/tax/index.ts describe('Bosnian tax specifics', () => { it('calculateBosnianPDV single 17% rate'); it('calculateCITFBiH 10%'); it('calculateCITRS 10%'); it('calculateDividendWHT FBiH: dividends 5%'); it('calculateDividendWHT RS: dividends 10%'); it('requiresVATRegistration: >= 100000 BAM → true'); }); // packages/country-hr/src/tax/index.ts describe('Croatian tax specifics', () => { it('calculateCroatianPDV standard 25%'); it('calculateCroatianPDV reduced 13%'); it('calculateCroatianPDV superReduced 5%'); it('calculateCroatianCIT: revenue < 1M EUR → 10%'); it('calculateCroatianCIT: revenue >= 1M EUR → 18%'); it('qualifiesForPausalni: revenue < 60000 EUR → true'); it('requiresVATRegistration: revenue >= 60000 EUR → true'); }); ``` --- #### `multi-currency/index.ts` — Currency Conversion **File:** `packages/core/tests/multi-currency.test.ts` (EXISTS) | Test Case | Assertion | |-----------|-----------| | Same currency | Rate = 1, no conversion | | RSD to EUR at rate 0.0086 | Correct base amount | | `lockExchangeRate` returns ExchangeRate object | Correct fields | | `lockExchangeRate` same currency | Throws error | | `lockExchangeRate` rate ≤ 0 | Throws "must be positive" | | `convertCurrency` with zero fromRate | Throws | | `calculateForexGainLoss` gain scenario | `gain > 0`, `loss = 0` | | `calculateForexGainLoss` loss scenario | `gain = 0`, `loss > 0` | | `isSupportedCurrency('EUR')` | `true` | | `isSupportedCurrency('XYZ')` | `false` | | Precision: toFixed(4) on result | 4 decimal places | --- #### `bank-import/index.ts` — CSV Parser **File:** `packages/core/tests/bank-import.test.ts` (MISSING — needs creation) ```typescript describe('parseCSV', () => { it('parses ISO date format YYYY-MM-DD'); it('parses Balkan dot format DD.MM.YYYY'); it('parses slash format DD/MM/YYYY'); it('skips header line'); it('skips empty lines'); it('returns empty array for empty string'); it('returns empty array for header-only CSV'); it('sets direction: inbound by default'); it('sets direction: outbound when field is "outbound"'); it('handles quoted fields with commas'); it('generates deterministic IDs for dedup'); }); describe('detectDuplicates', () => { it('detects exact duplicate by date+amount+currency+reference'); it('returns empty array when no duplicates'); it('returns empty array when either list is empty'); it('does NOT flag as duplicate if amount differs'); it('does NOT flag as duplicate if date differs'); it('does NOT flag as duplicate if reference differs (but amount/date same)'); }); ``` --- ### 2.2 Validator Unit Tests **Framework:** Vitest **Location:** `apps/api/src/validators/*.ts` ```typescript describe('Invoice validators (createInvoiceSchema)', () => { it('valid invoice passes'); it('missing customerId fails'); it('invalid date format fails'); it('negative unitPrice fails'); it('empty items array fails'); it('taxRate > 100 fails'); it('invalid currencyCode (5 chars) fails'); it('invalid UUID for customerId fails'); }); describe('Auth validators (registerSchema)', () => { it('valid registration passes'); it('invalid email fails'); it('password too short fails (< 8 chars)'); it('invalid country code (not RS/BA/HR) fails'); it('missing organizationName fails'); }); ``` --- ## Integration Test Architecture ```mermaid sequenceDiagram participant TC as Test Case participant ST as Supertest participant APP as Express App participant MID as Middleware
(Auth + RBAC) participant SVC as Service Layer participant PRI as Prisma ORM participant DB as Test PostgreSQL TC->>ST: HTTP request + Bearer token ST->>APP: Forward request APP->>MID: Authenticate JWT MID->>MID: Verify organizationId scope MID->>SVC: Authorized request SVC->>PRI: DB query (org-scoped) PRI->>DB: Parameterized SQL DB-->>PRI: Result rows PRI-->>SVC: Typed objects SVC-->>APP: Response data APP-->>ST: HTTP response ST-->>TC: Assert status + body Note over DB: beforeEach: seed
afterEach: truncate
(reverse FK order) ``` --- ## 3. Integration Test Strategy **Framework:** Supertest + Vitest (or Jest) **Database:** Test PostgreSQL instance (separate from dev/prod) **Setup:** Prisma migrations applied before tests; data seeded per test suite; truncated after each test ### 3.1 Test Database Setup ```typescript // test/setup.ts import { prisma } from '../src/lib/prisma'; import { execSync } from 'child_process'; beforeAll(async () => { // Apply migrations to test DB execSync('npx prisma migrate deploy', { env: { DATABASE_URL: process.env.TEST_DATABASE_URL } }); }); beforeEach(async () => { // Seed minimal data: 1 org, 1 owner user, default accounts await seedTestOrg(); }); afterEach(async () => { // Clean up in reverse FK order await prisma.loggedAction.deleteMany(); await prisma.bankTransaction.deleteMany(); await prisma.bankAccount.deleteMany(); await prisma.transaction.deleteMany(); await prisma.invoiceItem.deleteMany(); await prisma.invoice.deleteMany(); await prisma.expense.deleteMany(); await prisma.contact.deleteMany(); await prisma.account.deleteMany(); await prisma.user.deleteMany(); await prisma.organization.deleteMany(); }); ``` ### 3.2 Auth Endpoints ```typescript describe('POST /api/v1/auth/register', () => { it('creates org + owner user, returns tokens'); it('returns 409 for duplicate email'); it('returns 400 for missing required fields'); it('password is hashed (not stored plain)'); it('sets refreshToken httpOnly cookie'); it('org baseCurrency defaults to EUR'); }); describe('POST /api/v1/auth/login', () => { it('returns accessToken + sets cookie on valid credentials'); it('returns 401 for wrong password'); it('returns 401 for non-existent email'); it('updates lastLoginAt on success'); it('rememberMe=true extends cookie to 30 days'); }); describe('POST /api/v1/auth/refresh', () => { it('returns new accessToken from valid refresh cookie'); it('returns 401 when no cookie'); it('returns 401 for expired refresh token'); }); describe('POST /api/v1/auth/logout', () => { it('clears refreshToken cookie'); it('returns 204'); }); describe('GET /api/v1/auth/me', () => { it('returns user + org data for valid token'); it('returns 401 for missing token'); it('returns 401 for expired token'); }); ``` ### 3.3 Invoice Endpoints ```typescript describe('GET /api/v1/invoices', () => { it('returns paginated invoices for organization'); it('does NOT return invoices from other orgs'); it('filters by status'); it('filters by customerId'); it('filters by date range'); it('returns empty data array when no invoices'); it('returns 401 without auth'); }); describe('POST /api/v1/invoices', () => { it('creates invoice in draft status'); it('auto-generates invoice number INV-YYYY-001'); it('increments invoice number sequentially'); it('calculates subtotal correctly from line items'); it('calculates taxAmount at specified rate'); it('sets baseAmount = totalAmount when currency = baseCurrency'); it('locks exchange rate from ExchangeRate table'); it('returns 404 for non-existent customerId'); it('returns 400 for contact that is vendor only (not customer)'); }); describe('PATCH /api/v1/invoices/:id/status → send', () => { it('changes status from draft to sent'); it('creates Transaction: DR Receivable / CR Revenue'); it('transaction.amount = invoice.totalAmount'); it('transaction.referenceType = invoice, referenceId = invoice.id'); it('returns 400 if invoice already sent'); it('returns 400 if required accounts not in chart of accounts'); }); describe('PATCH /api/v1/invoices/:id/status → mark-paid', () => { it('changes status from sent to paid'); it('creates Transaction: DR Bank / CR Receivable'); it('sets paidAt to provided date'); it('returns 400 if invoice is still draft'); }); describe('DELETE /api/v1/invoices/:id', () => { it('deletes draft invoice'); it('returns 400 when trying to delete sent invoice'); it('returns 404 for non-existent invoice'); it('cannot delete invoice from another org'); }); ``` ### 3.4 Expense Endpoints ```typescript describe('POST /api/v1/expenses', () => { it('creates expense in pending status'); it('auto-generates expense number EXP-YYYY-001'); it('stores taxAmount separately'); it('locks exchange rate at expenseDate'); }); describe('PATCH /api/v1/expenses/:id/approve', () => { it('changes status from pending to approved'); it('creates Transaction: DR Expense / CR Payable'); it('returns 400 for non-pending expense'); }); describe('PATCH /api/v1/expenses/:id/pay', () => { it('changes status from approved to paid'); it('creates Transaction: DR Payable / CR Bank'); it('returns 400 for non-approved expense'); }); ``` ### 3.5 Transaction Endpoints ```typescript describe('POST /api/v1/transactions (manual journal)', () => { it('accountant can create manual transaction'); it('viewer cannot create manual transaction (403)'); it('debit and credit account must be different (422)'); it('debit account must belong to same org (404)'); it('credit account must belong to same org (404)'); it('creates transaction with correct amounts'); it('referenceType = manual'); }); describe('GET /api/v1/transactions', () => { it('filters by accountId (both debit and credit sides)'); it('filters by referenceType'); it('filters by date range'); it('does not return transactions from other orgs'); }); ``` ### 3.6 Report Endpoints ```typescript describe('GET /api/v1/reports/trial-balance', () => { it('returns balanced trial balance (totalDebits = totalCredits)'); it('returns balanced = true when no transactions'); it('includes all accounts with transactions'); it('debit-normal accounts: balance = debit - credit'); it('credit-normal accounts: balance = credit - debit'); }); describe('GET /api/v1/reports/profit-loss', () => { it('revenue accounts (type=4) in revenue section'); it('expense accounts (type=5) in expenses section'); it('netProfit = revenue - expenses'); it('respects date range filter'); }); describe('GET /api/v1/reports/vat', () => { it('outputVAT sum from invoice.taxAmount for sent/paid invoices'); it('inputVAT sum from expense.taxAmount for approved/paid expenses'); it('netVAT = outputVAT - inputVAT'); it('draft invoices excluded from output VAT'); it('pending expenses excluded from input VAT'); }); ``` ### 3.7 Multi-Tenancy Isolation Tests ```typescript describe('Organization isolation', () => { let org1Token: string; let org2Token: string; let org1InvoiceId: string; beforeEach(async () => { // Create two separate organizations org1Token = await registerAndLogin('org1@test.rs'); org2Token = await registerAndLogin('org2@test.rs'); // Create invoice in org1 const res = await createInvoice(org1Token, { ... }); org1InvoiceId = res.body.id; }); it('org2 cannot GET invoice from org1 (returns 404)'); it('org2 cannot PUT invoice from org1 (returns 404)'); it('org2 cannot DELETE invoice from org1 (returns 404 or 404)'); it('org2 list invoices does not include org1 invoices'); it('org2 cannot GET org1 contacts'); it('org2 cannot GET org1 transactions'); it('org2 cannot GET org1 bank accounts'); it('org2 trial balance does not include org1 accounts'); }); ``` --- ## Invoice Lifecycle — Integration Test Flow ```mermaid stateDiagram-v2 [*] --> Draft: POST /api/v1/invoices
(test: creates draft, generates INV-YYYY-NNN) Draft --> Sent: PATCH /status → send
(test: DR Receivable / CR Revenue) Draft --> Deleted: DELETE /invoices/:id
(test: draft can be deleted) Sent --> Paid: PATCH /status → mark-paid
(test: DR Bank / CR Receivable) Sent --> Deleted_ERR: DELETE attempt
(test: returns 400 — cannot delete sent) Paid --> [*]: Trial balance balanced
(test: Receivable = 0, balanced=true) state "Sent → mark-paid" as Paid { [*] --> TX_Created: Transaction created TX_Created --> GL_Updated: General Ledger updated GL_Updated --> Reconciled: BankTransaction matched } note right of Draft Auto-generates invoice number Locks exchange rate if foreign currency Validates customerId belongs to org end note note right of Sent Creates accounting transaction referenceType = invoice referenceId = invoice.id end note ``` --- ## 4. End-to-End Test Strategy **Framework:** Playwright **Target:** Critical business flows that span the full stack **Environment:** Staging environment with seeded data ### 4.1 User Registration and Setup ```typescript test('New user can register, set up org, and access dashboard', async ({ page }) => { // 1. Navigate to /register // 2. Fill in org name, country=RS, email, password // 3. Submit → redirected to dashboard // 4. Dashboard loads with zero-state (empty metrics) // 5. Logout → redirected to /login // 6. Login with same credentials → dashboard again }); ``` ### 4.2 Complete Invoice Flow ```typescript test('Create invoice → send → mark paid → check P&L', async ({ page }) => { // Step 1: Create contact (customer) await page.goto('/contacts/new'); await fillContactForm({ name: 'Test Customer', type: 'customer' }); await page.click('button[type=submit]'); // Step 2: Create invoice await page.goto('/invoices/new'); // Fill 6-step wizard: customer, date, items (1000 RSD + 20% PDV), review await completeInvoiceWizard({ customer: 'Test Customer', amount: 1000, taxRate: 20 }); // Verify: status = draft, total = 1200 RSD // Step 3: Send invoice await page.click('button:text("Send Invoice")'); // Verify: status = sent // Step 4: Mark paid await page.click('button:text("Mark as Paid")'); await page.fill('[name=paidAt]', '2026-02-20'); await page.click('button:text("Confirm")'); // Verify: status = paid, paidAt set // Step 5: Check P&L report await page.goto('/reports?from=2026-01-01&to=2026-12-31'); await expect(page.locator('[data-testid=revenue-total]')).toContainText('1,200.00'); // Step 6: Check trial balance (balanced) await page.goto('/reports/trial-balance'); await expect(page.locator('[data-testid=balanced-indicator]')).toBeVisible(); }); ``` ### 4.3 Expense Approval Flow ```typescript test('Create expense → approve → pay → check trial balance', async ({ page }) => { // Step 1: Create expense (office supplies, 5000 RSD, 17% PDV) // Step 2: Approve expense → DR Office Expense / CR Accounts Payable // Step 3: Pay expense → DR Accounts Payable / CR Bank // Step 4: Verify trial balance is still balanced // Step 5: Verify P&L shows expense in correct category }); ``` ### 4.4 Bank Reconciliation Flow ```typescript test('Import bank statement → reconcile with invoice payment', async ({ page }) => { // Pre-condition: Paid invoice exists (DR Bank / CR Receivable transaction) // Step 1: Go to Banking page // Step 2: Import CSV with matching payment entry // Step 3: Verify imported: 1, duplicates: 0 // Step 4: Match bank transaction to GL transaction // Step 5: Verify BankTransaction.reconciled = true // Step 6: Verify Transaction.reconciled = true }); ``` ### 4.5 VAT Report Generation ```typescript test('VAT report reflects invoices and expenses for period', async ({ page }) => { // Pre-condition: 3 sent invoices with 20% PDV, 2 approved expenses with PDV // Step 1: Navigate to Reports → VAT Report // Step 2: Set period to current month // Step 3: Verify: output VAT = sum of invoice tax amounts // Step 4: Verify: input VAT = sum of expense tax amounts // Step 5: Verify: net VAT = output - input // Step 6: Download/export VAT report (future feature) }); ``` --- ## E2E Test Flow — Complete Invoice Lifecycle ```mermaid flowchart TD START([Browser: /login]) --> LOGIN[Fill credentials
demo@bilko.io] LOGIN --> DASH[Dashboard loaded
assert: zero-state metrics] DASH --> NEW_CONTACT["/contacts/new
Create: Test Customer"] NEW_CONTACT --> NEW_INV["/invoices/new
6-step wizard"] NEW_INV --> W1["Step 1: Select Customer
assert: customer appears in dropdown"] W1 --> W2["Step 2: Set dates
invoiceDate, dueDate"] W2 --> W3["Step 3: Add line items
1000 RSD + 20% PDV = 1200 RSD total"] W3 --> W4["Step 4: Currency & exchange rate"] W4 --> W5["Step 5: Notes / payment terms"] W5 --> W6["Step 6: Review & Create
assert: subtotal=1000, tax=200, total=1200"] W6 --> INV_DETAIL["Invoice detail page
assert: status=draft, number=INV-YYYY-NNN"] INV_DETAIL --> SEND["Click: Send Invoice
assert: status=sent"] SEND --> PAY["Click: Mark as Paid
Enter paidAt date"] PAY --> PAID["assert: status=paid, paidAt set"] PAID --> PL["/reports?from=...&to=...
assert: revenue-total = 1,200.00"] PL --> TB["/reports/trial-balance
assert: balanced-indicator visible
assert: Receivable balance = 0"] style START fill:#198754,color:#fff style TB fill:#0d6efd,color:#fff style PAID fill:#198754,color:#fff ``` --- ## 5. Accounting Scenario Tests These tests verify correctness of the double-entry system under real-world accounting scenarios. ### 5.1 Invoice → Payment → Reconciliation **Scenario:** Company issues invoice, receives payment, reconciles bank statement ```typescript test('Full invoice lifecycle creates correct ledger entries', async () => { // 1. Create invoice: 100,000 RSD net + 20,000 RSD PDV = 120,000 RSD total // 2. Send invoice → Transaction: DR Receivable 120,000 / CR Revenue 120,000 // 3. Mark paid → Transaction: DR Bank 120,000 / CR Receivable 120,000 // 4. Trial balance: Bank +120,000 / Revenue +120,000 (balanced) // 5. Receivable account balance = 0 (opened and closed) // 6. General ledger shows both entries on Receivable account const trialBalance = await getTrialBalance(); expect(trialBalance.balanced).toBe(true); const receivable = trialBalance.accounts.find(a => a.code.startsWith('12')); expect(receivable.balance).toBe('0.0000'); }); ``` ### 5.2 Multi-Currency Invoice **Scenario:** RSD-based company invoices EUR customer ```typescript test('EUR invoice stored and reported in RSD base currency', async () => { // Exchange rate: 1 EUR = 117.25 RSD (locked at invoice date) // Invoice: 1,000 EUR + 200 EUR PDV = 1,200 EUR // Expected baseAmount: 1,200 × 117.25 = 140,700 RSD const invoice = await createInvoice({ currencyCode: 'EUR', items: [{ quantity: 1, unitPrice: 1000, taxRate: 20 }], invoiceDate: '2026-02-01' // rate exists for this date }); expect(invoice.currencyCode).toBe('EUR'); expect(invoice.totalAmount).toBe('1200.0000'); expect(invoice.exchangeRate).toBe('117.250000'); expect(invoice.baseAmount).toBe('140700.0000'); // When paid: DR Bank 140,700 RSD / CR Receivable 140,700 RSD await markPaid(invoice.id, '2026-02-15'); const transaction = await getTransactionForInvoice(invoice.id, 'payment'); expect(transaction.baseAmount).toBe('140700.0000'); }); ``` ### 5.3 VAT Calculation Accuracy ```typescript test('VAT calculated with Decimal precision, no float errors', async () => { // Known float trap: 0.1 + 0.2 ≠ 0.3 in JavaScript float // Test with amounts that expose float precision issues const result = calculateVAT('123.45', '20'); // Expected: tax = 123.45 × 0.20 = 24.69 (not 24.690000000000003) expect(result.tax.toString()).toBe('24.6900'); expect(result.total.toString()).toBe('148.1400'); // Large amount const large = calculateVAT('999999.9999', '17'); expect(large.tax.toString()).toBe('169999.9998'); // exact }); ``` ### 5.4 Trial Balance After Multiple Transactions ```typescript test('Trial balance remains balanced after 10 invoices and 5 expenses', async () => { // Create 10 invoices (all sent + paid) for (let i = 0; i < 10; i++) { const inv = await createAndSendInvoice(orgId, 10000 + i * 100); await markPaid(inv.id, today); } // Create 5 expenses (all approved + paid) for (let i = 0; i < 5; i++) { const exp = await createAndApproveExpense(orgId, 5000 + i * 50); await payExpense(exp.id); } const tb = await getTrialBalance(orgId); expect(tb.balanced).toBe(true); // Total debits must equal total credits expect(new Decimal(tb.totals.debit)).toEqual(new Decimal(tb.totals.credit)); }); ``` ### 5.5 Expense Approval Double-Entry ```typescript test('Expense approval creates correct DR Expense / CR Payable entry', async () => { const expense = await createExpense({ amount: 5000, taxRate: 17 }); // 850 PDV await approveExpense(expense.id); const transactions = await getTransactionsForExpense(expense.id); expect(transactions).toHaveLength(1); const tx = transactions[0]; // Verify debit is an expense account expect(tx.debitAccountCode).toMatch(/^5/); // Verify credit is payable expect(tx.creditAccountCode).toMatch(/^22/); // Amount matches expense amount expect(tx.amount).toBe('5000.0000'); }); ``` --- ## 6. Regulatory Compliance Tests ### 6.1 Serbia (RS) ```typescript describe('Serbia regulatory compliance', () => { it('PDV 20% standard rate applied to default supplies', async () => { const result = calculateSerbianPDV('10000', 'standard'); expect(result).toBe('2000.00'); }); it('PDV 10% reduced rate applied to food/medicine', async () => { const result = calculateSerbianPDV('10000', 'reduced'); expect(result).toBe('1000.00'); }); it('Business below 8M RSD threshold does not require VAT registration', () => { expect(requiresVATRegistration('7999999')).toBe(false); }); it('Business at 8M RSD threshold requires VAT registration', () => { expect(requiresVATRegistration('8000000')).toBe(true); }); it('Business below 6M RSD qualifies for pausal regime', () => { expect(qualifiesForPausalRegime('5999999')).toBe(true); }); it('CIT calculated at flat 15%', () => { const cit = calculateSerbianCIT('100000'); expect(cit).toBe('15000.00'); }); it('Invoice number follows Serbian format requirements', () => { // INV-YYYY-NNN format with sequential numbering expect(invoiceNumber).toMatch(/^INV-\d{4}-\d{3,}$/); }); it('VAT report groups output and input VAT separately', async () => { const report = await getVATReport(orgId, { from: '2026-01-01', to: '2026-01-31' }); expect(report).toHaveProperty('outputVAT'); expect(report).toHaveProperty('inputVAT'); expect(report).toHaveProperty('netVAT'); expect(new Decimal(report.netVAT)).toEqual( new Decimal(report.outputVAT.total).sub(new Decimal(report.inputVAT.total)) ); }); }); ``` ### 6.2 Bosnia & Herzegovina (BA) ```typescript describe('BiH regulatory compliance', () => { it('Single PDV rate of 17% applied uniformly', () => { const result = calculateBosnianPDV('10000'); expect(result).toBe('1700.00'); }); it('BiH has no reduced VAT rate (only standard and zero)', () => { const rates = Object.keys(bosnianVATRates); expect(rates).toEqual(['standard', 'zero']); }); it('VAT registration required at 100,000 BAM', () => { expect(requiresVATRegistration('99999')).toBe(false); expect(requiresVATRegistration('100000')).toBe(true); }); it('FBiH CIT at 10%', () => { expect(calculateCITFBiH('100000')).toBe('10000.00'); }); it('RS CIT at 10%', () => { expect(calculateCITRS('100000')).toBe('10000.00'); }); it('Dividend WHT: FBiH 5%, RS 10%', () => { expect(calculateDividendWHT('100000', 'fbih')).toBe('5000.00'); expect(calculateDividendWHT('100000', 'rs')).toBe('10000.00'); }); }); ``` ### 6.3 Croatia (HR) ```typescript describe('Croatia regulatory compliance', () => { it('Standard PDV rate is 25%', () => { const result = calculateCroatianPDV('10000', 'standard'); expect(result).toBe('2500.00'); }); it('Reduced PDV rate is 13% (food, accommodation)', () => { const result = calculateCroatianPDV('10000', 'reduced'); expect(result).toBe('1300.00'); }); it('Super-reduced PDV rate is 5% (books, medicines)', () => { const result = calculateCroatianPDV('10000', 'superReduced'); expect(result).toBe('500.00'); }); it('CIT 10% for small business (revenue < 1M EUR)', () => { const cit = calculateCroatianCIT('50000', '900000'); expect(cit).toBe('5000.00'); }); it('CIT 18% for large business (revenue >= 1M EUR)', () => { const cit = calculateCroatianCIT('50000', '1000000'); expect(cit).toBe('9000.00'); }); it('VAT registration threshold 60,000 EUR (EU 2025 aligned)', () => { expect(requiresVATRegistration('59999')).toBe(false); expect(requiresVATRegistration('60000')).toBe(true); }); }); ``` ### 6.4 Audit Trail Compliance ```typescript describe('Immutable audit trail', () => { it('LoggedAction created on invoice create', async () => { await createInvoice(orgId, ...); const logs = await prisma.loggedAction.findMany({ where: { tableName: 'invoices', action: 'INSERT' } }); expect(logs).toHaveLength(1); expect(logs[0].rowData).toBeTruthy(); }); it('LoggedAction created on invoice status change', async () => { await sendInvoice(invoiceId); const logs = await prisma.loggedAction.findMany({ where: { tableName: 'invoices', action: 'UPDATE' } }); expect(logs.length).toBeGreaterThan(0); expect(logs[0].changedFields).toHaveProperty('status'); }); it('LoggedAction cannot be deleted', async () => { // Attempt to delete a log entry — should fail (policy enforced at app or DB level) await expect(prisma.loggedAction.delete({ where: { eventId: logs[0].eventId } })) .rejects.toThrow(); }); it('locked transaction cannot be updated', async () => { await prisma.transaction.update({ where: { id: txId }, data: { locked: true } }); // Attempt to change amount of locked transaction via API const response = await request(app) .put(`/api/v1/transactions/${txId}`) .set('Authorization', `Bearer ${token}`) .send({ amount: 99999 }); expect(response.status).toBe(400); }); }); ``` ### 6.5 Record Retention ```typescript describe('Record retention requirements', () => { it('Deleted invoices remain in LoggedAction with full row data', async () => { const invoice = await createInvoice(orgId); const invoiceId = invoice.id; await deleteInvoice(invoiceId); // Invoice deleted from invoices table const inv = await prisma.invoice.findUnique({ where: { id: invoiceId } }); expect(inv).toBeNull(); // But audit log captures the full row const log = await prisma.loggedAction.findFirst({ where: { tableName: 'invoices', action: 'DELETE' } }); expect(log.rowData).toBeTruthy(); expect(JSON.parse(log.rowData).id).toBe(invoiceId); }); }); ``` --- ## 7. Performance Benchmarks **Tool:** k6 (load testing), Lighthouse (frontend) ### 7.1 API Response Time Targets | Endpoint | Target (P95) | Max Acceptable | |----------|-------------|----------------| | `GET /api/v1/health` | < 10ms | < 50ms | | `POST /api/v1/auth/login` | < 300ms | < 1s | | `GET /api/v1/invoices` (20 items) | < 200ms | < 500ms | | `POST /api/v1/invoices` | < 500ms | < 1s | | `GET /api/v1/reports/profit-loss` | < 500ms | < 2s | | `GET /api/v1/reports/trial-balance` | < 1s | < 3s | | `GET /api/v1/reports/general-ledger` | < 2s | < 5s | | `POST /api/v1/bank-accounts/:id/import` (100 rows) | < 1s | < 3s | ### 7.2 Load Test Scenarios ```javascript // k6 scenario: Normal business day load export const options = { scenarios: { normal_load: { executor: 'constant-vus', vus: 50, duration: '5m', }, spike: { executor: 'ramping-vus', startVUs: 0, stages: [ { duration: '30s', target: 200 }, { duration: '1m', target: 200 }, { duration: '30s', target: 0 }, ], } }, thresholds: { 'http_req_duration{type:api}': ['p(95)<500'], 'http_req_failed': ['rate<0.01'], // < 1% error rate } }; ``` ### 7.3 Database Performance | Operation | Target | |-----------|--------| | Invoice list query (org with 10K invoices) | < 100ms | | Trial balance (org with 1K accounts, 100K transactions) | < 2s | | Exchange rate lookup | < 10ms (covered by index) | | Audit log insert | < 5ms | ### 7.4 Frontend Performance (Lighthouse) | Metric | Target | |--------|--------| | First Contentful Paint (FCP) | < 1.5s | | Largest Contentful Paint (LCP) | < 2.5s | | Time to Interactive (TTI) | < 3.5s | | Cumulative Layout Shift (CLS) | < 0.1 | | Lighthouse Performance Score | > 90 | --- ## 8. Security Tests ### 8.1 Authentication Security ```typescript describe('Authentication security', () => { it('rejected with 401 for missing Authorization header'); it('rejected with 401 for malformed Bearer token'); it('rejected with 401 for expired access token'); it('rejected with 401 for tampered JWT signature'); it('rejected with 401 for wrong JWT_SECRET'); it('access token cannot be used as refresh token'); it('refresh token cannot be used as access token'); it('tokens have correct issuer and audience claims'); }); ``` ### 8.2 RBAC Authorization ```typescript describe('Role-based access control', () => { it('viewer cannot create invoices (403)'); it('viewer cannot create expenses (403)'); it('viewer cannot create manual transactions (403)'); it('accountant cannot change user roles (403)'); it('accountant cannot invite users (403)'); it('admin cannot change owner role (403)'); it('owner can change any role'); it('user cannot change their own role'); it('user cannot delete themselves'); }); ``` ### 8.3 SQL Injection ```typescript describe('SQL injection prevention', () => { it('invoice search with SQL payload returns 400 (Zod validation)', async () => { const res = await request(app) .get('/api/v1/invoices?customerId=\'; DROP TABLE invoices; --') .set('Authorization', `Bearer ${token}`); expect(res.status).toBe(400); // Zod rejects invalid UUID }); it('Prisma parameterizes all queries (no raw SQL in services)'); }); ``` ### 8.4 Cross-Site Scripting (XSS) ```typescript describe('XSS prevention', () => { it('contact name with script tag is stored as plain text', async () => { const name = ''; const contact = await createContact({ name }); expect(contact.name).toBe(name); // stored as-is // API response should not execute as HTML (verified by Content-Type: application/json) }); it('Content-Security-Policy header blocks inline scripts', async () => { const res = await request(app).get('/api/v1/health'); const csp = res.headers['content-security-policy']; expect(csp).toContain("script-src 'self'"); expect(csp).not.toContain("'unsafe-eval'"); }); }); ``` ### 8.5 Rate Limiting ```typescript describe('Rate limiting', () => { it('general API limit: 100 requests per 15 min per IP', async () => { // Make 101 requests from same IP const responses = await makeRequests(101, '/api/v1/health'); const lastResponse = responses[100]; expect(lastResponse.status).toBe(429); }); it('auth endpoints have stricter rate limit', async () => { // Make rapid login attempts — triggers auth rate limiter before general const responses = await makeLoginAttempts(20); expect(responses.some(r => r.status === 429)).toBe(true); }); }); ``` ### 8.6 Data Isolation / Multi-Tenant Security ```typescript describe('Tenant isolation security', () => { it('cannot access another org invoice by ID (returns 404, not 403)'); // Note: returning 404 instead of 403 prevents enumeration attacks it('cannot access another org transactions by reference ID'); it('cannot access another org users via /api/v1/users'); it('cannot access another org bank accounts'); it('PATCH invoice from another org returns 404'); it('DELETE invoice from another org returns 404'); }); ``` ### 8.7 CORS ```typescript describe('CORS policy', () => { it('requests from bilko.io are allowed'); it('requests from unknown origin are rejected with CORS error'); it('OPTIONS preflight returns correct headers'); it('credentials (cookies) allowed with CORS'); }); ``` ### 8.8 Security Headers ```typescript describe('Security headers', () => { it('X-Frame-Options: deny (clickjacking protection)'); it('X-Content-Type-Options: nosniff'); it('Strict-Transport-Security: maxAge=31536000; includeSubDomains; preload'); it('Content-Security-Policy present'); it('X-Powered-By header removed (helmet default)'); }); ``` --- ## CI/CD Test Pipeline ```mermaid flowchart TD PUSH["git push / PR opened"] --> CI["GitHub Actions triggered"] CI --> J1["Job: unit-tests
ubuntu-latest
No DB required"] CI --> J2["Job: integration-tests
ubuntu-latest
postgres:15 service"] CI --> J3["Job: e2e-tests
ubuntu-latest
Full stack startup"] J1 --> U1["npm ci"] U1 --> U2["cd packages/core && npx vitest run"] U2 --> U3{Coverage >= 80%?} U3 -->|Yes| U_OK["PASS"] U3 -->|No| U_FAIL["FAIL — block merge"] J2 --> I1["npm ci"] I1 --> I2["npx prisma migrate deploy
(TEST_DATABASE_URL)"] I2 --> I3["npm run test:integration
(apps/api)"] I3 --> I4{All assertions pass?} I4 -->|Yes| I_OK["PASS"] I4 -->|No| I_FAIL["FAIL — block merge"] J3 --> E1["npx playwright install --with-deps"] E1 --> E2["npm run dev (staging seed)"] E2 --> E3["npm run test:e2e"] E3 --> E4{All flows pass?} E4 -->|Yes| E_OK["PASS"] E4 -->|No| E_FAIL["FAIL — screenshot + video saved"] U_OK --> MERGE{All jobs passed?} I_OK --> MERGE E_OK --> MERGE MERGE -->|Yes| DEPLOY["Allow merge to main"] MERGE -->|No| BLOCK["Block PR merge"] style PUSH fill:#6c757d,color:#fff style DEPLOY fill:#198754,color:#fff style BLOCK fill:#dc3545,color:#fff style U_FAIL fill:#dc3545,color:#fff style I_FAIL fill:#dc3545,color:#fff style E_FAIL fill:#dc3545,color:#fff ``` --- ## 9. Test Infrastructure ### 9.1 Directory Structure ``` Bilko/ ├── packages/core/ │ ├── tests/ ← Unit tests (EXISTS) │ │ ├── accounting.test.ts │ │ ├── tax.test.ts │ │ ├── multi-currency.test.ts │ │ ├── invoicing.test.ts │ │ └── chart-of-accounts.test.ts │ └── vitest.config.ts ← Vitest config (EXISTS) │ ├── apps/api/ │ └── tests/ ← To be created │ ├── setup.ts ← DB setup/teardown │ ├── helpers/ │ │ ├── auth.helper.ts ← Login/register helpers │ │ └── factory.ts ← Test data factories │ ├── integration/ │ │ ├── auth.test.ts │ │ ├── invoices.test.ts │ │ ├── expenses.test.ts │ │ ├── contacts.test.ts │ │ ├── accounts.test.ts │ │ ├── transactions.test.ts │ │ ├── reports.test.ts │ │ ├── banking.test.ts │ │ ├── settings.test.ts │ │ └── isolation.test.ts │ └── security/ │ ├── auth-security.test.ts │ ├── rbac.test.ts │ ├── injection.test.ts │ └── headers.test.ts │ └── e2e/ ← To be created ├── playwright.config.ts ├── fixtures/ │ └── test-data.ts └── tests/ ├── auth.spec.ts ├── invoice-lifecycle.spec.ts ├── expense-flow.spec.ts ├── bank-reconciliation.spec.ts └── reports.spec.ts ``` ### 9.2 Environment Variables for Testing ```bash # Test environment TEST_DATABASE_URL="postgresql://bilko_test:password@localhost:5432/bilko_test" JWT_SECRET="test-jwt-secret-not-for-production" JWT_REFRESH_SECRET="test-refresh-secret-not-for-production" NODE_ENV="test" ``` ### 9.3 CI Pipeline Integration ```yaml # .github/workflows/test.yml (target) jobs: unit-tests: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 - run: npm ci - run: cd packages/core && npx vitest run integration-tests: runs-on: ubuntu-latest services: postgres: image: postgres:15 env: POSTGRES_DB: bilko_test POSTGRES_PASSWORD: password steps: - uses: actions/checkout@v4 - run: npm ci - run: npx prisma migrate deploy env: DATABASE_URL: ${{ env.TEST_DATABASE_URL }} - run: npm run test:integration working-directory: apps/api e2e-tests: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npx playwright install --with-deps - run: npm run test:e2e env: PLAYWRIGHT_BASE_URL: http://localhost:3000 ``` --- ## 10. Test Coverage Targets | Module | Unit Coverage | Integration Coverage | |--------|-------------|-------------------| | `@bilko/core` accounting | 95% (near complete) | N/A | | `@bilko/core` tax | 95% (near complete) | N/A | | `@bilko/core` multi-currency | 90% | N/A | | `@bilko/core` bank-import | 80% (tests missing) | N/A | | `@bilko/country-rs` tax | 0% (tests missing) | N/A | | `@bilko/country-ba` tax | 0% (tests missing) | N/A | | `@bilko/country-hr` tax | 0% (tests missing) | N/A | | API auth routes | N/A | 90% | | API invoice routes | N/A | 90% | | API expense routes | N/A | 85% | | API report routes | N/A | 80% | | API banking routes | N/A | 75% | | API settings routes | N/A | 80% | | Multi-tenancy isolation | N/A | 100% | | Security tests | N/A | 90% | **Overall target:** 80% line coverage across the codebase before production launch. # Testing Guide # Bilko — Testing Guide **Status:** NO TESTS EXIST YET — This document defines the testing strategy for implementation. --- ## Testing Philosophy Financial software has a higher correctness bar than typical web apps. Bilko's testing strategy prioritizes: 1. **Financial Logic Accuracy** — VAT calculations, double-entry bookkeeping, currency conversion 2. **Data Integrity** — No lost transactions, no balance discrepancies 3. **Regression Prevention** — Once fixed, bugs stay fixed 4. **Fast Feedback** — Tests run in <5 minutes locally --- ## Testing Pyramid ``` /\ /E2E\ ← 10% (Critical user flows) /------\ / Integ \ ← 30% (API endpoints, DB queries) /----------\ / Unit \ ← 60% (Business logic, utilities) /--------------\ ``` **Distribution:** - **60% Unit Tests** — Fast, isolated, test business logic - **30% Integration Tests** — Test API + database together - **10% E2E Tests** — Test full user flows (expensive, slow) ```mermaid graph TD subgraph STACK["Bilko Testing Stack"] direction TB subgraph E2E_LAYER["E2E Layer — 10% — Playwright"] PW1["invoice-flow.spec.ts
Create → Send → Paid"] PW2["expense-flow.spec.ts
Add → Approve → Pay"] PW3["report-flow.spec.ts
P&L → Export PDF"] PW4["auth-flow.spec.ts
Register → Login → Logout"] end subgraph INT_LAYER["Integration Layer — 30% — Supertest"] ST1["auth.routes.test.ts
register / login / refresh / logout"] ST2["invoices.routes.test.ts
CRUD + status transitions"] ST3["expenses.routes.test.ts
CRUD + approve/pay"] ST4["reports.routes.test.ts
P&L / trial-balance / VAT"] ST5["isolation.test.ts
Cross-org data access prevention"] end subgraph UNIT_LAYER["Unit Layer — 60% — Vitest"] VT1["accounting.test.ts
validateDoubleEntry, createJournalEntry
calculateTrialBalance"] VT2["tax.test.ts
calculateVAT: RS 20% / BA 17% / HR 25%
calculateCIT, getVATRates"] VT3["multi-currency.test.ts
convertCurrency, lockExchangeRate
calculateForexGainLoss"] VT4["bank-import.test.ts
parseCSV, detectDuplicates"] VT5["chart-of-accounts.test.ts
Structure validation"] end end E2E_LAYER --> INT_LAYER INT_LAYER --> UNIT_LAYER style E2E_LAYER fill:#ffc107,stroke:#e0a800 style INT_LAYER fill:#fd7e14,color:#fff,stroke:#e8690b style UNIT_LAYER fill:#198754,color:#fff,stroke:#157347 ``` --- ## Tech Stack | Test Type | Framework | Purpose | |-----------|-----------|---------| | **Unit** | Vitest | Business logic, utilities, components | | **Integration** | Supertest | API endpoint testing | | **E2E** | Playwright | Browser automation, user flows | | **Coverage** | c8 (built into Vitest) | Code coverage reporting | ### Why These Tools? #### Vitest (not Jest) - ✅ Faster (ESM native, Vite-based) - ✅ Compatible with Vite/Turborepo - ✅ Watch mode with HMR - ✅ Same API as Jest (easy migration if needed) #### Supertest (not Postman) - ✅ Programmatic API testing - ✅ Works with Express - ✅ Can test without starting server #### Playwright (not Cypress) - ✅ Multi-browser (Chromium, Firefox, WebKit) - ✅ Auto-wait (no flaky tests from race conditions) - ✅ Parallel execution - ✅ Video recording on failure --- ## Unit Tests (Vitest) ### Scope Test pure functions and business logic in isolation: - Invoice calculations (subtotal, tax, discount, total) - VAT calculations (Serbia 20%, BiH 17%, Croatia 25%) - Currency conversion (exchange rate locking) - Double-entry validation (debit = credit) - Date utilities (fiscal year, due date calculation) - Number formatting (currency display) ### File Structure ``` apps/api/src/ ├── services/ │ ├── invoice.service.ts │ └── invoice.service.test.ts ← Unit test ├── utils/ │ ├── vat.ts │ └── vat.test.ts ← Unit test ``` ### Example: VAT Calculation Test ```typescript // apps/api/src/utils/vat.test.ts import { describe, it, expect } from 'vitest'; import { calculateVAT } from './vat'; describe('calculateVAT', () => { it('calculates Serbia VAT (20%)', () => { const result = calculateVAT(100, 20); expect(result).toBe(20); }); it('calculates BiH VAT (17%)', () => { const result = calculateVAT(100, 17); expect(result).toBe(17); }); it('calculates Croatia VAT (25%)', () => { const result = calculateVAT(100, 25); expect(result).toBe(25); }); it('handles zero VAT', () => { const result = calculateVAT(100, 0); expect(result).toBe(0); }); it('handles decimal amounts', () => { const result = calculateVAT(123.45, 20); expect(result).toBe(24.69); }); it('rounds to 2 decimal places', () => { const result = calculateVAT(10.01, 20); expect(result).toBe(2.00); // Not 2.002 }); }); ``` ### Running Unit Tests ```bash # Run all unit tests npm run test:unit # Watch mode (re-run on file change) npm run test:unit -- --watch # Coverage report npm run test:unit -- --coverage # Specific file npm run test:unit -- vat.test.ts ``` ### Coverage Requirements | Category | Target | Rationale | |----------|--------|-----------| | **Financial logic** | >95% | Critical for correctness | | **Utilities** | >90% | Reused across codebase | | **Services** | >80% | Business logic layer | | **Controllers** | >60% | Thin layer (tested via integration) | | **Overall** | >80% | Industry standard | --- ## Integration Tests (Supertest) ### Scope Test API endpoints with real database: - Auth flow (register, login, refresh, logout) - CRUD operations (invoices, expenses, contacts) - Data validation (Zod schemas) - Error handling (400, 401, 403, 404, 500) - Database transactions - Organization scoping (can't access other org's data) ### File Structure ``` apps/api/src/ ├── routes/ │ ├── auth.routes.ts │ └── auth.routes.test.ts ← Integration test ├── routes/ │ ├── invoices.routes.ts │ └── invoices.routes.test.ts ← Integration test ``` ### Test Database Setup Use separate test database: ```bash # .env.test DATABASE_URL=postgresql://bilko_test:bilko_test@localhost:5432/bilko_test ``` Setup/teardown: ```typescript // apps/api/src/test/setup.ts import { PrismaClient } from '@prisma/client'; import { beforeAll, afterAll, beforeEach } from 'vitest'; const prisma = new PrismaClient(); beforeAll(async () => { // Run migrations on test DB await execSync('npx prisma migrate deploy'); }); beforeEach(async () => { // Clear all tables before each test await prisma.$transaction([ prisma.invoice.deleteMany(), prisma.expense.deleteMany(), prisma.contact.deleteMany(), prisma.user.deleteMany(), prisma.organization.deleteMany(), ]); }); afterAll(async () => { await prisma.$disconnect(); }); ``` ### Example: Invoice API Test ```typescript // apps/api/src/routes/invoices.routes.test.ts import { describe, it, expect, beforeEach } from 'vitest'; import request from 'supertest'; import { app } from '../app'; import { prisma } from '../lib/prisma'; describe('POST /api/v1/invoices', () => { let authToken: string; let organizationId: string; let customerId: string; beforeEach(async () => { // Create test organization const org = await prisma.organization.create({ data: { name: 'Test Company', baseCurrency: 'RSD', country: 'RS', }, }); organizationId = org.id; // Create test user const user = await prisma.user.create({ data: { organizationId, email: 'test@bilko.io', passwordHash: '$2b$12$...', // bcrypt hash fullName: 'Test User', role: 'admin', }, }); // Login to get token const loginRes = await request(app) .post('/api/v1/auth/login') .send({ email: 'test@bilko.io', password: 'test123' }); authToken = loginRes.body.accessToken; // Create test customer const customer = await prisma.contact.create({ data: { organizationId, type: 'customer', name: 'Test Customer', email: 'customer@example.com', }, }); customerId = customer.id; }); it('creates invoice with valid data', async () => { const res = await request(app) .post('/api/v1/invoices') .set('Authorization', `Bearer ${authToken}`) .send({ customerId, invoiceDate: '2026-02-20', dueDate: '2026-03-20', currencyCode: 'RSD', items: [ { description: 'Web Development', quantity: 10, unitPrice: 5000, taxRate: 20, }, ], }); expect(res.status).toBe(201); expect(res.body.invoiceNumber).toMatch(/^INV-\d+$/); expect(res.body.subtotal).toBe(50000); expect(res.body.taxAmount).toBe(10000); expect(res.body.totalAmount).toBe(60000); }); it('rejects invoice without auth', async () => { const res = await request(app) .post('/api/v1/invoices') .send({ customerId, items: [] }); expect(res.status).toBe(401); }); it('rejects invoice for customer in different org', async () => { // Create another org const otherOrg = await prisma.organization.create({ data: { name: 'Other Company', baseCurrency: 'EUR', country: 'RS' }, }); // Create customer in other org const otherCustomer = await prisma.contact.create({ data: { organizationId: otherOrg.id, type: 'customer', name: 'Other Customer', }, }); const res = await request(app) .post('/api/v1/invoices') .set('Authorization', `Bearer ${authToken}`) .send({ customerId: otherCustomer.id, items: [], }); expect(res.status).toBe(403); // Forbidden (can't access other org's data) }); }); ``` ### Running Integration Tests ```bash # Run all integration tests npm run test:integration # Specific file npm run test:integration -- invoices.routes.test.ts ``` --- ## E2E Tests (Playwright) ### Scope Test critical user flows from browser: - **Invoice Flow:** Create → Preview → Send → Mark Paid - **Expense Flow:** Add → Upload Receipt → Approve → Pay - **Report Flow:** Generate P&L → Export PDF - **Auth Flow:** Register → Login → 2FA → Logout ### File Structure ``` apps/e2e/ ├── tests/ │ ├── invoice-flow.spec.ts │ ├── expense-flow.spec.ts │ ├── report-flow.spec.ts │ └── auth-flow.spec.ts ├── fixtures/ │ └── test-data.ts └── playwright.config.ts ``` ### Configuration ```typescript // apps/e2e/playwright.config.ts import { defineConfig } from '@playwright/test'; export default defineConfig({ testDir: './tests', timeout: 60000, // 60s per test retries: 1, // Retry flaky tests once workers: 4, // Run 4 tests in parallel use: { baseURL: 'http://localhost:3000', screenshot: 'only-on-failure', video: 'retain-on-failure', }, projects: [ { name: 'chromium', use: { browserName: 'chromium' } }, { name: 'firefox', use: { browserName: 'firefox' } }, { name: 'webkit', use: { browserName: 'webkit' } }, ], }); ``` ### Example: Invoice E2E Test ```typescript // apps/e2e/tests/invoice-flow.spec.ts import { test, expect } from '@playwright/test'; test.describe('Invoice Flow', () => { test.beforeEach(async ({ page }) => { // Login await page.goto('/login'); await page.fill('input[name="email"]', 'demo@bilko.io'); await page.fill('input[name="password"]', 'demo123'); await page.click('button[type="submit"]'); await expect(page).toHaveURL('/dashboard'); }); test('create invoice and mark as paid', async ({ page }) => { // Navigate to invoices await page.click('a[href="/invoices"]'); await expect(page).toHaveURL('/invoices'); // Click "New Invoice" await page.click('button:has-text("New Invoice")'); await expect(page).toHaveURL('/invoices/new'); // Fill invoice form (6-step wizard) // Step 1: Customer await page.selectOption('select[name="customerId"]', { label: 'Acme Corp' }); await page.click('button:has-text("Next")'); // Step 2: Details await page.fill('input[name="invoiceDate"]', '2026-02-20'); await page.fill('input[name="dueDate"]', '2026-03-20'); await page.click('button:has-text("Next")'); // Step 3: Items await page.fill('input[name="items.0.description"]', 'Web Development'); await page.fill('input[name="items.0.quantity"]', '10'); await page.fill('input[name="items.0.unitPrice"]', '5000'); await page.selectOption('select[name="items.0.taxRate"]', '20'); await page.click('button:has-text("Next")'); // Step 4: Review await expect(page.locator('text=Subtotal')).toContainText('50,000.00 RSD'); await expect(page.locator('text=Tax')).toContainText('10,000.00 RSD'); await expect(page.locator('text=Total')).toContainText('60,000.00 RSD'); await page.click('button:has-text("Create Invoice")'); // Verify redirect to invoice detail await expect(page).toHaveURL(/\/invoices\/[a-f0-9-]+$/); await expect(page.locator('h1')).toContainText('INV-'); // Mark as paid await page.click('button:has-text("Mark as Paid")'); await page.click('button:has-text("Confirm")'); // Verify status changed await expect(page.locator('.status-badge')).toContainText('Paid'); }); test('validates required fields', async ({ page }) => { await page.goto('/invoices/new'); // Try to submit without customer await page.click('button:has-text("Next")'); // Verify error message await expect(page.locator('.error')).toContainText('Customer is required'); }); }); ``` ### Running E2E Tests ```bash # Start dev server first npm run dev # In another terminal: npm run test:e2e # Headless (CI mode) npm run test:e2e -- --headed # Debug mode (pause on failure) npm run test:e2e -- --debug # Specific browser npm run test:e2e -- --project=firefox ``` --- ## VAT Test Matrix — Country Coverage ```mermaid graph TD VAT["calculateVAT Tests
@bilko/core/tax"] VAT --> RS["Serbia RS
Standard: 20%
Reduced: 10%
Zero: 0% exports
CIT: 15% flat
Pausal: < 6M RSD
VAT reg: >= 8M RSD"] VAT --> BA["Bosnia BA
Standard: 17%
No reduced rate
Zero: 0% exports
FBiH CIT: 10%
RS CIT: 10%
WHT FBiH: 5% div
VAT reg: >= 100K BAM"] VAT --> HR["Croatia HR
Standard: 25%
Reduced: 13%
Super-red: 5%
CIT small: 10%
CIT large: 18%
VAT reg: >= 60K EUR"] RS --> RS_T["Test: calculateSerbianPDV
Test: qualifiesForPausalRegime
Test: requiresVATRegistration RS"] BA --> BA_T["Test: calculateBosnianPDV
Test: calculateCITFBiH / CITRS
Test: calculateDividendWHT"] HR --> HR_T["Test: calculateCroatianPDV
Test: calculateCroatianCIT
Test: requiresVATRegistration HR"] style VAT fill:#0d6efd,color:#fff style RS fill:#c0392b,color:#fff style BA fill:#2c3e50,color:#fff style HR fill:#e74c3c,color:#fff ``` ## Test Data Management ### Factories (Recommended) Create reusable test data generators: ```typescript // apps/api/src/test/factories/invoice.factory.ts import { faker } from '@faker-js/faker'; import { prisma } from '../../lib/prisma'; export async function createInvoice(overrides = {}) { return prisma.invoice.create({ data: { organizationId: faker.string.uuid(), customerId: faker.string.uuid(), invoiceNumber: `INV-${faker.number.int({ min: 1000, max: 9999 })}`, invoiceDate: faker.date.recent(), dueDate: faker.date.future(), currencyCode: 'RSD', subtotal: 50000, taxAmount: 10000, totalAmount: 60000, baseAmount: 60000, status: 'draft', ...overrides, }, }); } ``` Usage: ```typescript const invoice = await createInvoice({ status: 'paid' }); ``` --- ## Coverage Reporting ### Generate Coverage Report ```bash npm run test:unit -- --coverage ``` Output: ``` File | % Stmts | % Branch | % Funcs | % Lines -----------------|---------|----------|---------|-------- All files | 82.5 | 75.3 | 80.1 | 82.5 vat.ts | 95.0 | 90.0 | 100.0 | 95.0 invoice.ts | 88.2 | 80.5 | 85.0 | 88.2 currency.ts | 78.0 | 70.0 | 75.0 | 78.0 ``` ### Coverage Thresholds (CI) Fail build if coverage drops below threshold: ```json // vitest.config.ts export default defineConfig({ test: { coverage: { provider: 'c8', reporter: ['text', 'json', 'html'], statements: 80, branches: 75, functions: 80, lines: 80, }, }, }); ``` --- ## Testing Best Practices ### 1. Test Behavior, Not Implementation ❌ **Bad:** Test internal state ```typescript it('sets status to paid', () => { invoice.status = 'paid'; expect(invoice.status).toBe('paid'); }); ``` ✅ **Good:** Test observable behavior ```typescript it('marks invoice as paid', async () => { await invoiceService.markAsPaid(invoice.id); const updated = await prisma.invoice.findUnique({ where: { id: invoice.id } }); expect(updated.status).toBe('paid'); expect(updated.paidAt).toBeTruthy(); }); ``` --- ### 2. Use Descriptive Test Names ❌ **Bad:** Vague test name ```typescript it('works', () => { /* ... */ }); ``` ✅ **Good:** Descriptive test name ```typescript it('calculates Serbian VAT at 20% on €100 as €20', () => { /* ... */ }); ``` --- ### 3. Arrange-Act-Assert (AAA) ```typescript it('creates invoice with correct totals', async () => { // ARRANGE — Set up test data const customer = await createCustomer(); const invoiceData = { customerId: customer.id, items: [...] }; // ACT — Perform action const invoice = await invoiceService.create(invoiceData); // ASSERT — Verify outcome expect(invoice.subtotal).toBe(50000); expect(invoice.taxAmount).toBe(10000); expect(invoice.totalAmount).toBe(60000); }); ``` --- ### 4. Test Edge Cases Always test: - **Empty input** — `calculateVAT(0, 20)` - **Null/undefined** — `formatCurrency(null)` - **Negative numbers** — `calculateDiscount(100, -10)` - **Large numbers** — `convertCurrency(999999999999.9999, 1.2)` - **Boundary values** — Tax rate at 0%, 100% --- ### 5. Avoid Test Interdependence ❌ **Bad:** Tests depend on each other ```typescript let invoiceId; it('creates invoice', async () => { const invoice = await createInvoice(); invoiceId = invoice.id; // Shared state }); it('updates invoice', async () => { await updateInvoice(invoiceId); // Depends on previous test }); ``` ✅ **Good:** Tests are independent ```typescript it('creates invoice', async () => { const invoice = await createInvoice(); expect(invoice.id).toBeTruthy(); }); it('updates invoice', async () => { const invoice = await createInvoice(); // Create fresh data await updateInvoice(invoice.id); }); ``` --- ## CI/CD Integration Tests run automatically on every push (GitHub Actions): ```yaml # .github/workflows/main.yml jobs: test: runs-on: ubuntu-latest steps: - run: npm run test:unit -- --coverage - run: npm run test:integration - run: npm run test:e2e ``` ```mermaid flowchart LR GIT["git push"] --> GHA["GitHub Actions"] GHA --> PARALLEL["Parallel Jobs"] PARALLEL --> U["unit-tests
vitest run
@bilko/core
~30s"] PARALLEL --> I["integration-tests
supertest
postgres:15
~2min"] PARALLEL --> E["e2e-tests
playwright
all browsers
~5min"] U --> COV{"Coverage
>80%?"} I --> API{"All API
tests pass?"} E --> E2E{"All flows
pass?"} COV -->|Pass| GATE["Merge Gate"] API -->|Pass| GATE E2E -->|Pass| GATE COV -->|Fail| BLOCK1["Block PR"] API -->|Fail| BLOCK1 E2E -->|Fail| BLOCK1 GATE --> MAIN["Merge to main"] MAIN --> DEPLOY["Deploy to Staging"] style GIT fill:#6c757d,color:#fff style MAIN fill:#198754,color:#fff style BLOCK1 fill:#dc3545,color:#fff style DEPLOY fill:#0d6efd,color:#fff ``` See [CI-CD.md](/books/bilko-balkan-accounting-saas/page/cicd-pipeline) for full pipeline. --- ## Debugging Tests ### Unit/Integration Tests (Vitest) ```bash # Debug mode (pause on debugger statement) npm run test:unit -- --inspect-brk # VS Code launch.json: { "type": "node", "request": "launch", "name": "Debug Vitest", "runtimeExecutable": "npm", "runtimeArgs": ["run", "test:unit", "--", "--inspect-brk"], "console": "integratedTerminal" } ``` ### E2E Tests (Playwright) ```bash # Debug mode (opens inspector) npm run test:e2e -- --debug # Headed mode (see browser) npm run test:e2e -- --headed # Trace viewer (after failure) npx playwright show-trace trace.zip ``` --- ## Performance Testing (Future) ### Load Testing (k6) Test API under load: ```javascript // apps/e2e/load/invoices.js import http from 'k6/http'; import { check } from 'k6'; export let options = { vus: 100, // 100 virtual users duration: '30s', }; export default function () { const res = http.get('http://localhost:4000/api/v1/invoices'); check(res, { 'status is 200': (r) => r.status === 200 }); } ``` Run: ```bash k6 run apps/e2e/load/invoices.js ``` **Target:** API handles 1,000 requests/second with <200ms p95 latency. **Status:** PLANNED (Phase 2) --- ## Related Documents - CI/CD Pipeline: [../infrastructure/CI-CD.md](/books/bilko-balkan-accounting-saas/page/cicd-pipeline) - Test Inventory: [TEST-INVENTORY.md](/books/bilko-balkan-accounting-saas/page/test-inventory) - Security Testing: [../security/SECURITY-ARCHITECTURE.md](/books/bilko-balkan-accounting-saas/page/security-architecture) --- **Last Updated:** 2026-02-20 **Status:** NO TESTS EXIST YET — Implement tests during backend development **Coverage Target:** >80% overall, >95% for financial logic # Test Inventory # Bilko — Test Inventory **Status:** NO TESTS EXIST YET — This document tracks planned tests and implementation status. This inventory catalogs all tests planned for Bilko, organized by category and priority. --- ## Test Coverage Summary | Category | Total Planned | Implemented | Coverage Target | |----------|---------------|-------------|-----------------| | **Unit Tests** | 45 | 0 | >80% | | **Integration Tests** | 35 | 0 | >80% | | **E2E Tests** | 12 | 0 | Critical flows | | **TOTAL** | **92** | **0** | — | ```mermaid graph TD subgraph COVERAGE["Test Coverage Matrix — 92 Tests Planned"] subgraph UNIT["Unit Tests — 45"] FIN["Financial Calculations
12 tests — P0
VAT, invoice totals, precision"] DE["Double-Entry Validation
6 tests — P0
debit=credit enforcement"] CUR["Currency Conversion
8 tests — P0
exchange rate locking"] DATE["Date Utilities
6 tests — P1
due dates, fiscal year"] FMT["Number Formatting
5 tests — P1
RSD, EUR, BAM display"] AUTH_U["Authentication Utils
8 tests — P0
bcrypt, JWT, tokens"] end subgraph INTEG["Integration Tests — 35"] AUTH_API["Auth API
10 tests — P0
register/login/refresh/logout"] INV_API["Invoices API
10 tests — P0
CRUD + status + org-scope"] EXP_API["Expenses API
8 tests — P1
CRUD + approve/pay"] REP_API["Reports API
7 tests — P1
P&L / BS / VAT reports"] end subgraph E2E_["E2E Tests — 12"] INV_E2E["Invoice Flow
4 tests — P0
Create → Send → Paid"] EXP_E2E["Expense Flow
3 tests — P1
Add → Approve → Pay"] REP_E2E["Report Flow
2 tests — P1
Generate → Export PDF"] SET_E2E["Settings Flow
2 tests — P2
Org settings + Invite user"] AUTH_E2E["Auth Flow
1 test — P1
Register → Login → 2FA → Logout"] end end style FIN fill:#dc3545,color:#fff style DE fill:#dc3545,color:#fff style CUR fill:#dc3545,color:#fff style AUTH_U fill:#dc3545,color:#fff style AUTH_API fill:#dc3545,color:#fff style INV_API fill:#dc3545,color:#fff style INV_E2E fill:#dc3545,color:#fff style DATE fill:#fd7e14,color:#fff style FMT fill:#fd7e14,color:#fff style EXP_API fill:#fd7e14,color:#fff style REP_API fill:#fd7e14,color:#fff style EXP_E2E fill:#fd7e14,color:#fff style REP_E2E fill:#fd7e14,color:#fff style AUTH_E2E fill:#fd7e14,color:#fff style SET_E2E fill:#6c757d,color:#fff ``` --- ## Priority Legend - **P0** — Critical (MVP blocker, financial logic) - **P1** — High (core features, security) - **P2** — Medium (nice-to-have, edge cases) - **P3** — Low (future enhancements) --- ## Unit Tests (45 total) ### Financial Calculations (12 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `vat.test.ts` | `calculateVAT - Serbia 20%` | VAT calculation for Serbia | P0 | ❌ Not implemented | | `vat.test.ts` | `calculateVAT - BiH 17%` | VAT calculation for BiH | P0 | ❌ Not implemented | | `vat.test.ts` | `calculateVAT - Croatia 25%` | VAT calculation for Croatia | P0 | ❌ Not implemented | | `vat.test.ts` | `calculateVAT - zero rate` | VAT at 0% (exports) | P0 | ❌ Not implemented | | `vat.test.ts` | `calculateVAT - decimal amounts` | VAT on €123.45 | P0 | ❌ Not implemented | | `vat.test.ts` | `calculateVAT - rounding` | Rounds to 2 decimal places | P0 | ❌ Not implemented | | `invoice-calc.test.ts` | `calculateInvoiceTotal - subtotal` | Sum of line items | P0 | ❌ Not implemented | | `invoice-calc.test.ts` | `calculateInvoiceTotal - tax` | Sum of tax amounts | P0 | ❌ Not implemented | | `invoice-calc.test.ts` | `calculateInvoiceTotal - discount` | Subtract discount from subtotal | P0 | ❌ Not implemented | | `invoice-calc.test.ts` | `calculateInvoiceTotal - total` | Subtotal + tax - discount | P0 | ❌ Not implemented | | `invoice-calc.test.ts` | `calculateInvoiceTotal - multi-item` | Multiple line items with different tax rates | P0 | ❌ Not implemented | | `invoice-calc.test.ts` | `calculateInvoiceTotal - precision` | NUMERIC(19,4) precision maintained | P0 | ❌ Not implemented | --- ### Double-Entry Validation (6 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `double-entry.test.ts` | `validateTransaction - debit equals credit` | Debit amount = Credit amount | P0 | ❌ Not implemented | | `double-entry.test.ts` | `validateTransaction - rejects unbalanced` | Throws error if debit ≠ credit | P0 | ❌ Not implemented | | `double-entry.test.ts` | `validateTransaction - requires both accounts` | Throws if missing debit or credit account | P0 | ❌ Not implemented | | `double-entry.test.ts` | `validateTransaction - multi-currency` | Validates amounts in base currency | P0 | ❌ Not implemented | | `double-entry.test.ts` | `validateTransaction - precision` | NUMERIC precision preserved | P0 | ❌ Not implemented | | `double-entry.test.ts` | `validateTransaction - zero amount` | Rejects zero-amount transactions | P1 | ❌ Not implemented | --- ### Currency Conversion (8 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `currency.test.ts` | `convertCurrency - EUR to RSD` | Convert at locked exchange rate | P0 | ❌ Not implemented | | `currency.test.ts` | `convertCurrency - RSD to EUR` | Reverse conversion | P0 | ❌ Not implemented | | `currency.test.ts` | `convertCurrency - same currency` | Rate = 1.0 when currency matches | P0 | ❌ Not implemented | | `currency.test.ts` | `convertCurrency - precision` | NUMERIC(19,4) preserved | P0 | ❌ Not implemented | | `currency.test.ts` | `convertCurrency - large amounts` | €999,999,999.9999 | P0 | ❌ Not implemented | | `currency.test.ts` | `convertCurrency - rounding` | Rounds to 4 decimal places | P1 | ❌ Not implemented | | `currency.test.ts` | `lockExchangeRate - historical rate` | Uses rate from transaction date, not today | P0 | ❌ Not implemented | | `currency.test.ts` | `lockExchangeRate - missing rate` | Throws if no rate available for date | P1 | ❌ Not implemented | --- ### Date Utilities (6 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `date.test.ts` | `calculateDueDate - 30 days` | Invoice date + 30 days | P1 | ❌ Not implemented | | `date.test.ts` | `calculateDueDate - custom terms` | Invoice date + custom days | P1 | ❌ Not implemented | | `date.test.ts` | `isOverdue - past due date` | Returns true if today > due date | P1 | ❌ Not implemented | | `date.test.ts` | `isOverdue - not overdue` | Returns false if today <= due date | P1 | ❌ Not implemented | | `date.test.ts` | `getFiscalYear - starts Jan 1` | Fiscal year 2026 = Jan 1 - Dec 31 | P2 | ❌ Not implemented | | `date.test.ts` | `getFiscalYear - custom start` | Fiscal year starts on custom date | P2 | ❌ Not implemented | --- ### Number Formatting (5 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `format.test.ts` | `formatCurrency - RSD` | "50,000.00 RSD" format | P1 | ❌ Not implemented | | `format.test.ts` | `formatCurrency - EUR` | "€50,000.00" format | P1 | ❌ Not implemented | | `format.test.ts` | `formatCurrency - BAM` | "50,000.00 BAM" format | P1 | ❌ Not implemented | | `format.test.ts` | `formatCurrency - decimal places` | Respects currency decimal places (0-4) | P1 | ❌ Not implemented | | `format.test.ts` | `formatCurrency - null` | Returns "-" for null/undefined | P2 | ❌ Not implemented | --- ### Authentication (8 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `auth.test.ts` | `hashPassword - bcrypt 12 rounds` | Password hashed with bcrypt | P0 | ❌ Not implemented | | `auth.test.ts` | `hashPassword - unique salt` | Each hash is different | P0 | ❌ Not implemented | | `auth.test.ts` | `verifyPassword - correct password` | Returns true for correct password | P0 | ❌ Not implemented | | `auth.test.ts` | `verifyPassword - incorrect password` | Returns false for wrong password | P0 | ❌ Not implemented | | `auth.test.ts` | `generateJWT - valid payload` | JWT contains user ID, org ID, role | P0 | ❌ Not implemented | | `auth.test.ts` | `generateJWT - expiry 15 min` | Access token expires in 15 min | P0 | ❌ Not implemented | | `auth.test.ts` | `generateRefreshToken - expiry 7 days` | Refresh token expires in 7 days | P0 | ❌ Not implemented | | `auth.test.ts` | `verifyJWT - expired token` | Throws error if token expired | P1 | ❌ Not implemented | --- ## Integration Tests (35 total) ### Auth API (10 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `auth-api.test.ts` | `POST /auth/register - success` | Creates user, returns 201 | P0 | ❌ Not implemented | | `auth-api.test.ts` | `POST /auth/register - duplicate email` | Returns 400 if email exists | P0 | ❌ Not implemented | | `auth-api.test.ts` | `POST /auth/register - weak password` | Returns 400 if password < 8 chars | P0 | ❌ Not implemented | | `auth-api.test.ts` | `POST /auth/login - success` | Returns access + refresh tokens | P0 | ❌ Not implemented | | `auth-api.test.ts` | `POST /auth/login - wrong password` | Returns 401 | P0 | ❌ Not implemented | | `auth-api.test.ts` | `POST /auth/login - non-existent user` | Returns 401 | P0 | ❌ Not implemented | | `auth-api.test.ts` | `POST /auth/refresh - success` | Returns new access token | P0 | ❌ Not implemented | | `auth-api.test.ts` | `POST /auth/refresh - expired token` | Returns 401 | P1 | ❌ Not implemented | | `auth-api.test.ts` | `POST /auth/logout - success` | Deletes refresh token from DB | P1 | ❌ Not implemented | | `auth-api.test.ts` | `POST /auth/logout - already logged out` | Returns 204 (idempotent) | P2 | ❌ Not implemented | --- ### Invoices API (10 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `invoices-api.test.ts` | `POST /invoices - success` | Creates invoice, returns 201 | P0 | ❌ Not implemented | | `invoices-api.test.ts` | `POST /invoices - validates required fields` | Returns 400 if missing customer | P0 | ❌ Not implemented | | `invoices-api.test.ts` | `POST /invoices - validates currency` | Returns 400 if invalid currency code | P0 | ❌ Not implemented | | `invoices-api.test.ts` | `POST /invoices - org scoping` | Returns 403 if customer in different org | P0 | ❌ Not implemented | | `invoices-api.test.ts` | `GET /invoices - list` | Returns paginated invoices | P0 | ❌ Not implemented | | `invoices-api.test.ts` | `GET /invoices - filter by status` | Returns only "paid" invoices | P1 | ❌ Not implemented | | `invoices-api.test.ts` | `GET /invoices/:id - success` | Returns invoice by ID | P0 | ❌ Not implemented | | `invoices-api.test.ts` | `GET /invoices/:id - not found` | Returns 404 if ID doesn't exist | P1 | ❌ Not implemented | | `invoices-api.test.ts` | `PATCH /invoices/:id - update status` | Changes status to "sent" | P0 | ❌ Not implemented | | `invoices-api.test.ts` | `DELETE /invoices/:id - soft delete` | Marks as deleted (not hard delete) | P1 | ❌ Not implemented | --- ### Expenses API (8 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `expenses-api.test.ts` | `POST /expenses - success` | Creates expense, returns 201 | P0 | ❌ Not implemented | | `expenses-api.test.ts` | `POST /expenses - validates required fields` | Returns 400 if missing amount | P0 | ❌ Not implemented | | `expenses-api.test.ts` | `POST /expenses - org scoping` | Returns 403 if vendor in different org | P0 | ❌ Not implemented | | `expenses-api.test.ts` | `GET /expenses - list` | Returns paginated expenses | P0 | ❌ Not implemented | | `expenses-api.test.ts` | `PATCH /expenses/:id/approve - success` | Changes status to "approved" | P1 | ❌ Not implemented | | `expenses-api.test.ts` | `PATCH /expenses/:id/approve - requires admin` | Returns 403 if user is viewer | P1 | ❌ Not implemented | | `expenses-api.test.ts` | `PATCH /expenses/:id/reject - success` | Changes status to "rejected" | P1 | ❌ Not implemented | | `expenses-api.test.ts` | `DELETE /expenses/:id - soft delete` | Marks as deleted | P1 | ❌ Not implemented | --- ### Reports API (7 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `reports-api.test.ts` | `GET /reports/profit-loss - success` | Returns P&L with revenue, expenses, net | P1 | ❌ Not implemented | | `reports-api.test.ts` | `GET /reports/profit-loss - date range` | Filters by start/end date | P1 | ❌ Not implemented | | `reports-api.test.ts` | `GET /reports/balance-sheet - success` | Returns assets, liabilities, equity | P1 | ❌ Not implemented | | `reports-api.test.ts` | `GET /reports/cash-flow - success` | Returns operating, investing, financing | P1 | ❌ Not implemented | | `reports-api.test.ts` | `GET /reports/vat - success` | Returns sales VAT, purchase VAT, net VAT | P1 | ❌ Not implemented | | `reports-api.test.ts` | `GET /reports/vat - Serbia 20%` | Calculates Serbian VAT correctly | P1 | ❌ Not implemented | | `reports-api.test.ts` | `GET /reports/vat - export PDF` | Returns PDF file | P2 | ❌ Not implemented | --- ## E2E Tests (12 total) ### Invoice Flow (4 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `invoice-flow.spec.ts` | `Create invoice via 6-step wizard` | Full invoice creation flow | P0 | ❌ Not implemented | | `invoice-flow.spec.ts` | `Preview invoice before sending` | Preview modal shows correct totals | P0 | ❌ Not implemented | | `invoice-flow.spec.ts` | `Send invoice to customer` | Email sent, status changed to "sent" | P0 | ❌ Not implemented | | `invoice-flow.spec.ts` | `Mark invoice as paid` | Status changed to "paid", paidAt timestamp | P0 | ❌ Not implemented | --- ### Expense Flow (3 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `expense-flow.spec.ts` | `Add expense with receipt upload` | Create expense, upload JPG | P1 | ❌ Not implemented | | `expense-flow.spec.ts` | `Approve expense` | Admin approves, status changed | P1 | ❌ Not implemented | | `expense-flow.spec.ts` | `Mark expense as paid` | Status changed to "paid" | P1 | ❌ Not implemented | --- ### Report Flow (2 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `report-flow.spec.ts` | `Generate P&L report` | Select date range, view report | P1 | ❌ Not implemented | | `report-flow.spec.ts` | `Export P&L to PDF` | Download PDF file | P1 | ❌ Not implemented | --- ### Settings Flow (2 tests) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `settings-flow.spec.ts` | `Update organization settings` | Change org name, tax settings | P2 | ❌ Not implemented | | `settings-flow.spec.ts` | `Invite user to organization` | Send invite email, user accepts | P2 | ❌ Not implemented | --- ### Auth Flow (1 test) | Test File | Test Name | What It Tests | Priority | Status | |-----------|-----------|---------------|----------|--------| | `auth-flow.spec.ts` | `Register → Login → 2FA → Logout` | Full auth flow with 2FA | P1 | ❌ Not implemented | --- ## Critical Path Testing Flow ```mermaid flowchart TD START(["Start: No Tests"]) --> P1 subgraph P1["Phase 1 — MVP Critical (25 tests)"] P1_FIN["Financial Calculations
12 unit tests
VAT RS/BA/HR, invoice totals"] P1_DE["Double-Entry Validation
6 unit tests
debit=credit, balanced=true"] P1_AUTH["Auth API
7 integration tests
register, login, refresh"] P1_FIN --> P1_DE --> P1_AUTH end P1 --> P1_GATE{"Coverage
>=50%?"} P1_GATE -->|Yes| P2 P1_GATE -->|No| P1 subgraph P2["Phase 2 — Core Features (35 tests)"] P2_CUR["Currency Conversion
8 unit tests"] P2_INV["Invoices API
10 integration tests"] P2_E2E["Invoice + Auth + Expense E2E
8 E2E tests"] P2_REP["Reports API
7 integration tests"] P2_CUR --> P2_INV --> P2_E2E --> P2_REP end P2 --> P2_GATE{"Coverage
>=70%?"} P2_GATE -->|Yes| P3 P2_GATE -->|No| P2 subgraph P3["Phase 3 — Polish (32 tests)"] P3_DATE["Date + Formatting
11 unit tests"] P3_EXP["Expenses API
8 integration tests"] P3_EDGE["Edge cases
8 tests"] P3_SET["Settings flow
5 tests"] P3_DATE --> P3_EXP --> P3_EDGE --> P3_SET end P3 --> DONE(["Production Ready
>80% coverage
All critical paths tested"]) style START fill:#6c757d,color:#fff style DONE fill:#198754,color:#fff style P1_GATE fill:#ffc107,stroke:#e0a800 style P2_GATE fill:#ffc107,stroke:#e0a800 ``` ## Test Implementation Roadmap ### Phase 1 (MVP Critical) — 25 tests - ✅ **Financial calculations** (12 unit tests) - ✅ **Double-entry validation** (6 unit tests) - ✅ **Auth API** (7 integration tests: register, login, refresh) **Target:** Before backend MVP launch --- ### Phase 2 (Core Features) — 35 tests - ✅ **Currency conversion** (8 unit tests) - ✅ **Invoices API** (10 integration tests) - ✅ **Invoice E2E flow** (4 E2E tests) - ✅ **Auth E2E flow** (1 E2E test) - ✅ **Expense flow** (3 E2E tests) - ✅ **Reports API** (7 integration tests) - ✅ **Report E2E flow** (2 E2E tests) **Target:** 1 month after MVP launch --- ### Phase 3 (Polish) — 32 tests - ✅ **Date utilities** (6 unit tests) - ✅ **Number formatting** (5 unit tests) - ✅ **Expenses API** (8 integration tests) - ✅ **Settings flow** (2 E2E tests) - ✅ **Remaining auth tests** (3 integration tests) - ✅ **Edge cases** (8 tests across categories) **Target:** 3 months after MVP launch --- ## Test Execution Commands ### Run All Tests ```bash npm run test # All tests (unit + integration + E2E) ``` ### Run by Category ```bash npm run test:unit # Unit tests only npm run test:integration # Integration tests only npm run test:e2e # E2E tests only ``` ### Run Specific Test File ```bash npm run test:unit -- vat.test.ts npm run test:integration -- invoices-api.test.ts npm run test:e2e -- invoice-flow.spec.ts ``` ### Run with Coverage ```bash npm run test:unit -- --coverage ``` ### Watch Mode ```bash npm run test:unit -- --watch ``` --- ## Coverage Tracking ### Current Coverage (as of 2026-02-20) | Category | Coverage | Target | Status | |----------|----------|--------|--------| | **Financial Logic** | 0% | >95% | ❌ Not started | | **API Endpoints** | 0% | >80% | ❌ Not started | | **Utilities** | 0% | >90% | ❌ Not started | | **Overall** | 0% | >80% | ❌ Not started | **Next Milestone:** 50% coverage (25 critical tests) --- ## Related Documents - Testing Guide: [TESTING-GUIDE.md](/books/bilko-balkan-accounting-saas/page/testing-guide) - CI/CD Pipeline: [../infrastructure/CI-CD.md](/books/bilko-balkan-accounting-saas/page/cicd-pipeline) - Security Testing: [../security/SECURITY-ARCHITECTURE.md](/books/bilko-balkan-accounting-saas/page/security-architecture) --- **Last Updated:** 2026-02-20 **Status:** NO TESTS IMPLEMENTED YET **Total Tests Planned:** 92 (45 unit + 35 integration + 12 E2E) **Next Action:** Implement Phase 1 financial calculation tests (12 tests) # Infrastructure & DevOps # Deployment Guide # Bilko Deployment Guide **Last Updated:** 2026-04-16 **Current State:** Stable Cloud Run deployment with custom domain provisioning ## GCP Project Configuration - **Project ID:** `tribal-sign-487920-k0` - **Region:** `europe-north1` (Stockholm) - **Services:** - `bilko-api` → https://bilko-api-dh4m46blja-lz.a.run.app (revision 00037) - `bilko-web` → https://bilko-web-dh4m46blja-lz.a.run.app ## Secret Manager
Secret NameVersionPurpose
`bilko-cors-origins`v2Comma-separated list of allowed CORS origins
`bilko-database-url`latestCloud SQL connection string (password reset 2026-04-16)
`bilko-jwt-refresh-secret`latestJWT refresh token secret
**CORS Parsing:** Secret `bilko-cors-origins` is parsed by comma in `apps/api/src/app.ts:61` ## Environment Variables ### bilko-web - `NEXT_PUBLIC_API_URL=https://bilko-api-dh4m46blja-lz.a.run.app` ### bilko-api - `CORS_ORIGINS` → pulled from `bilko-cors-origins:latest` - `SESSION_COOKIE_SECURE=true` - `NODE_ENV=production` - `DATABASE_URL` → pulled from `bilko-database-url:latest` ## Custom Domain Setup ### Current Domain - **Host:** `bilko-demo.alai.no` - **Mapped to:** `bilko-web` Cloud Run service - **DNS Provider:** one.com - **DNS Record:** `CNAME bilko-demo.alai.no → ghs.googlehosted.com.` - **TLS Cert:** Let's Encrypt (managed by GCP, auto-renews) - **Provisioning Time:** 15-30 minutes after DNS propagation ### Domain Verification Constraint **Critical:** Only `alai.no` is verified in GCP Search Console (via dev@alai.no). `basicconsulting.no` is NOT verified. All custom domains MUST use `*.alai.no` subdomains until `basicconsulting.no` is verified. ## Custom Domain Runbook ### Prerequisites 1. Domain must be verified in Google Search Console by the GCP account owner 2. DNS provider access (one.com for `alai.no`, Vercel for `basicconsulting.no`) 3. `gcloud` CLI authenticated: `gcloud auth login` ### Step-by-Step #### 1. Create Domain Mapping ``` gcloud beta run domain-mappings create \ --service=bilko-web \ --domain=bilko-demo.alai.no \ --region=europe-north1 \ --project=tribal-sign-487920-k0 ``` #### 2. Configure DNS Add CNAME record at DNS provider: ``` Type: CNAME Host: bilko-demo Value: ghs.googlehosted.com. TTL: 3600 ``` #### 3. Wait for Certificate Provisioning ``` gcloud beta run domain-mappings describe bilko-demo.alai.no \ --region=europe-north1 \ --project=tribal-sign-487920-k0 ``` Look for `status.conditions → CertificateProvisioned: True` #### 4. Update CORS Allowed Origins ``` # Get current value gcloud secrets versions access latest --secret=bilko-cors-origins # Add new domain echo "https://bilko-demo.alai.no,https://bilko-web-dh4m46blja-lz.a.run.app" | \ gcloud secrets versions add bilko-cors-origins --data-file=- ``` #### 5. Deploy New Revision ``` gcloud run services update-traffic bilko-api \ --to-latest \ --region=europe-north1 \ --project=tribal-sign-487920-k0 ``` #### 6. Verify CORS Preflight ``` curl -sSI -X OPTIONS \ https://bilko-api-dh4m46blja-lz.a.run.app/api/v1/auth/login \ -H "Origin: https://bilko-demo.alai.no" \ -H "Access-Control-Request-Method: POST" ``` **Expected:** HTTP 204 with `Access-Control-Allow-Origin: https://bilko-demo.alai.no` ## GitHub Actions CI/CD - **Workflow:** `.github/workflows/deploy-production.yml` - **Auth:** Workload Identity Federation (WIF) - **Service Account:** `github-actions@tribal-sign-487920-k0.iam.gserviceaccount.com` - **IAM Roles:** `roles/run.admin`, `roles/iam.serviceAccountUser` ### Deployment Steps 1. Authenticate via WIF 2. Build Docker images (api + web) 3. Push to Google Container Registry 4. Deploy to Cloud Run (europe-north1) 5. Run smoke tests (Playwright E2E) ## Testing ### Backend Tests - **Framework:** Vitest - **Location:** `apps/api/src/**/*.test.ts` - **Command:** `pnpm test` (from `apps/api/`) ### End-to-End Tests - **Framework:** Playwright - **Location:** `apps/e2e/tests/` - **Command:** `pnpm test` (from `apps/e2e/`) - **Runs in CI:** Yes (on every deploy) ## Recent Fixes (2026-04-16) ### Commits - `a62b7f6` — Cloud Run service names align: `bilko-staging-*` → `bilko-*` - `9b1ced1` — Backend: added `currency` field to invoice list, added `/api/v1/settings/profile` endpoint - `73693d4` — Frontend: avatar initials fallback, invoice step indicator, chat widget ARIA labels ### Key Changes 1. **Service Naming:** Production services now named `bilko-api` and `bilko-web` (no `-staging` suffix) 2. **API Enhancements:** Invoice list now includes currency, new profile settings endpoint 3. **Frontend Fixes:** Accessibility improvements (ARIA), avatar initials when no image, visual polish ## Rollback Procedure ### Rollback to Previous Revision ``` # List revisions gcloud run revisions list --service=bilko-api --region=europe-north1 # Rollback gcloud run services update-traffic bilko-api \ --to-revisions=bilko-api-00036=100 \ --region=europe-north1 ``` ### Rollback via GitHub Actions ``` git revert HEAD git push origin main # Triggers deploy workflow ``` ## Troubleshooting ### Issue: CORS errors in browser **Cause:** Custom domain not in `bilko-cors-origins` secret **Fix:** Update secret (see step 4 in Custom Domain Runbook), deploy new revision ### Issue: 502 Bad Gateway **Cause:** Service unhealthy or startup timeout **Fix:** Check Cloud Run logs: `gcloud run services logs read bilko-api --region=europe-north1 --limit=50` ### Issue: Database connection timeout **Cause:** Cloud SQL Proxy misconfiguration or secret outdated **Fix:** Verify `bilko-database-url` secret, check Cloud SQL instance status ### Issue: Custom domain SSL pending **Cause:** DNS not propagated or domain not verified in Search Console **Fix:** Wait 15-30 min after DNS change, verify domain ownership in Search Console ## Architecture Diagram ``` ┌─────────────────┐ │ one.com DNS │ │ bilko-demo. │ │ alai.no │ └────────┬────────┘ │ CNAME ▼ ┌─────────────────────────────┐ │ ghs.googlehosted.com │ │ (Google Cloud Load Balancer)│ └────────┬────────────────────┘ │ ▼ ┌─────────────────────────────┐ ┌──────────────────┐ │ bilko-web (Cloud Run) │──────▶│ bilko-api │ │ Next.js 15 + React 19 │ HTTP │ Express + TS │ │ europe-north1 │ │ europe-north1 │ └─────────────────────────────┘ └────────┬─────────┘ │ ▼ ┌─────────────────┐ │ Cloud SQL │ │ PostgreSQL 16 │ │ europe-north1 │ └─────────────────┘ ``` # CI/CD Pipeline # Bilko — CI/CD Pipeline **Status:** PLANNED (GitHub Actions workflows not yet configured) This document describes the target continuous integration and deployment pipeline for Bilko. --- ## Overview Bilko uses **GitHub Actions** for CI/CD automation: - **Trigger:** Every push to `main` and on pull requests - **Stages:** Lint → Type Check → Unit Tests → Integration Tests → Build → E2E Tests → Deploy - **Duration Target:** <10 minutes from commit to production **Why GitHub Actions?** - Free for public repos - Native GitHub integration - Easy to configure (YAML) - Matrix builds for parallel testing - Secret management built-in ### Pipeline Overview ```mermaid flowchart TD PUSH(["git push / PR opened"]) TRIGGER{{"Branch?"}} subgraph PARALLEL["Stage 1 — Parallel Quality Checks"] LINT["Lint\nESLint + Prettier\n<2 min"] TC["Type Check\nTypeScript strict\n<2 min"] UT["Unit Tests\nVitest + coverage\n<3 min"] IT["Integration Tests\nSupertest + real PG\n<5 min"] end BUILD["Build (Turborepo)\napps/web → .next\napps/api → dist\n<4 min"] subgraph E2E_BLOCK["Stage 3 — E2E Tests"] VP["Wait for Vercel\nPreview URL"] E2E["Playwright E2E\nChromium + Firefox + WebKit\n<8 min"] end subgraph DEPLOY["Stage 4 — Deploy (main only)"] DF["Deploy Frontend\nVercel Production\nbilko.io"] DB["Deploy Backend\nRailway Production\napi.bilko.io"] MIGRATE["DB Migrations\nnpx prisma migrate deploy"] end NOTIFY["Slack Notification\n#bilko-deploys"] PUSH --> TRIGGER TRIGGER -->|"PR"| PARALLEL TRIGGER -->|"main"| PARALLEL PARALLEL --> BUILD BUILD --> E2E_BLOCK VP --> E2E E2E_BLOCK --> DEPLOY DEPLOY --> NOTIFY LINT & TC & UT & IT -->|"All pass"| BUILD ``` --- ## Pipeline Stages ### 1. Code Quality (Parallel) #### ESLint + Prettier ```yaml - name: Lint run: npm run lint ``` **Checks:** - ESLint rules for TypeScript - Prettier formatting - Import order - Unused variables **Fail Conditions:** - Any ESLint errors - Prettier format violations --- #### TypeScript Type Check ```yaml - name: Type Check run: npm run type-check ``` **Checks:** - TypeScript strict mode compliance - No `any` types without justification - Correct Prisma types - React prop types **Fail Conditions:** - Any TypeScript errors - Type inference failures --- ### 2. Unit Tests (Vitest) ```yaml - name: Unit Tests run: npm run test:unit ``` **Coverage Requirements:** - Overall: >80% - Financial logic (invoices, VAT, double-entry): >95% - Utility functions: >90% **Test Types:** - Business logic (invoice calculations, VAT rates) - Currency conversion - Double-entry validation - Date utilities - Number formatting **Fail Conditions:** - Any test failures - Coverage below threshold - Test timeout (>30s per test) --- ### 3. Integration Tests (Supertest) ```yaml - name: Integration Tests run: npm run test:integration env: DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }} ``` **Setup:** - Provision test PostgreSQL database - Run migrations: `npx prisma migrate deploy` - Seed test data - Run tests against real database - Cleanup after tests **Test Types:** - API endpoint tests (all routes) - Auth flow (register, login, refresh, logout) - CRUD operations (invoices, expenses, contacts) - Database transactions - Error handling **Fail Conditions:** - Any test failures - Database connection errors - Memory leaks (heap growth >100MB) --- ### Job Dependency Graph ```mermaid graph LR LINT["lint"] TC["type-check"] UT["unit-tests"] IT["integration-tests"] BUILD["build\nneeds: lint, type-check,\nunit-tests, integration-tests"] E2E["e2e-tests\nneeds: build"] DF["deploy-frontend\nneeds: build, e2e-tests\nif: main branch"] DB_JOB["deploy-backend\nneeds: build, e2e-tests\nif: main branch"] LINT --> BUILD TC --> BUILD UT --> BUILD IT --> BUILD BUILD --> E2E E2E --> DF E2E --> DB_JOB ``` ### 4. Build (Turborepo) ```yaml - name: Build run: npm run build ``` **Build Targets:** - `apps/web` — Next.js production build - `apps/api` — TypeScript compilation to `dist/` - `packages/database` — Prisma Client generation **Fail Conditions:** - Build errors - TypeScript compilation errors - Missing environment variables (fail-fast) **Artifacts:** - `apps/web/.next/` — Next.js build output - `apps/api/dist/` — Compiled JavaScript - Build logs for debugging --- ### 5. E2E Tests (Playwright) ```yaml - name: E2E Tests run: npm run test:e2e env: PLAYWRIGHT_BASE_URL: ${{ env.PREVIEW_URL }} ``` **Setup:** - Wait for Vercel preview deployment (for PRs) - Install Playwright browsers - Run tests against preview URL **Test Scenarios:** - **Invoice Flow:** Create → Preview → Send → Mark Paid - **Expense Flow:** Add → Upload Receipt → Approve → Pay - **Report Flow:** Generate P&L → Export PDF - **Auth Flow:** Register → Login → 2FA → Logout **Browsers:** - Chromium (primary) - Firefox (secondary) - Safari/WebKit (mobile) **Fail Conditions:** - Any test failures - Screenshot diffs (visual regression) - Timeout (>60s per test) --- ### 6. Deploy #### Frontend (Vercel) ```yaml - name: Deploy Frontend uses: vercel/action@v1 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} production: ${{ github.ref == 'refs/heads/main' }} ``` **Deployment Strategy:** - **PR:** Deploy to preview URL (automatic) - **main branch:** Deploy to production (automatic) **Rollback:** - Automatic if deployment fails health check - Manual via Vercel Dashboard --- #### Backend (Railway) ```yaml - name: Deploy Backend uses: railway-app/action@v1 with: railway-token: ${{ secrets.RAILWAY_TOKEN }} service: api environment: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }} ``` **Pre-Deploy:** 1. Run database migrations: `npx prisma migrate deploy` 2. Health check on current deployment **Deployment Strategy:** - **PR:** Deploy to staging Railway environment - **main branch:** Deploy to production Railway environment **Rollback:** - Railway keeps last 10 deployments - Rollback via Railway Dashboard or CLI --- ## Workflow Files ### Main Workflow (.github/workflows/main.yml) ```yaml name: CI/CD Pipeline on: push: branches: [main] pull_request: branches: [main] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 cache: npm - run: npm ci - run: npm run lint type-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 cache: npm - run: npm ci - run: npm run type-check unit-tests: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 cache: npm - run: npm ci - run: npm run test:unit -- --coverage - uses: codecov/codecov-action@v3 with: files: ./coverage/coverage-final.json integration-tests: runs-on: ubuntu-latest services: postgres: image: postgres:15 env: POSTGRES_USER: bilko_test POSTGRES_PASSWORD: bilko_test POSTGRES_DB: bilko_test options: >- --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5 ports: - 5432:5432 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 cache: npm - run: npm ci - run: npx prisma migrate deploy env: DATABASE_URL: postgresql://bilko_test:bilko_test@localhost:5432/bilko_test - run: npm run test:integration env: DATABASE_URL: postgresql://bilko_test:bilko_test@localhost:5432/bilko_test build: needs: [lint, type-check, unit-tests, integration-tests] runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 cache: npm - run: npm ci - run: npm run build - uses: actions/upload-artifact@v3 with: name: build-artifacts path: | apps/web/.next apps/api/dist e2e-tests: needs: build runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 cache: npm - run: npm ci - run: npx playwright install --with-deps - name: Wait for Vercel Preview uses: patrickedqvist/wait-for-vercel-preview@v1.3.1 id: vercel-preview with: token: ${{ secrets.GITHUB_TOKEN }} max_timeout: 300 - run: npm run test:e2e env: PLAYWRIGHT_BASE_URL: ${{ steps.vercel-preview.outputs.url }} - uses: actions/upload-artifact@v3 if: failure() with: name: playwright-screenshots path: test-results/ deploy-frontend: needs: [build, e2e-tests] if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: vercel/action@v1 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} production: true deploy-backend: needs: [build, e2e-tests] if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: railway-app/action@v1 with: railway-token: ${{ secrets.RAILWAY_TOKEN }} service: api environment: production ``` --- ### Hotfix Workflow (.github/workflows/hotfix.yml) Fast-track workflow for urgent production fixes (bypasses full pipeline): ```yaml name: Hotfix Deploy on: workflow_dispatch: inputs: reason: description: 'Reason for hotfix' required: true jobs: hotfix: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 cache: npm - run: npm ci - run: npm run lint - run: npm run type-check - run: npm run build - uses: vercel/action@v1 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} production: true - uses: railway-app/action@v1 with: railway-token: ${{ secrets.RAILWAY_TOKEN }} service: api environment: production - name: Notify Team uses: slackapi/slack-github-action@v1.24.0 with: webhook-url: ${{ secrets.SLACK_WEBHOOK }} payload: | { "text": "🚨 Hotfix deployed: ${{ github.event.inputs.reason }}" } ``` --- ## Secrets Configuration GitHub repository secrets (Settings → Secrets and variables → Actions): | Secret Name | Description | How to Generate | |-------------|-------------|-----------------| | `VERCEL_TOKEN` | Vercel deployment token | Vercel Dashboard → Settings → Tokens | | `VERCEL_PROJECT_ID` | Vercel project ID | `vercel link` output | | `VERCEL_ORG_ID` | Vercel organization ID | `vercel link` output | | `RAILWAY_TOKEN` | Railway deployment token | Railway Dashboard → Settings → Tokens | | `TEST_DATABASE_URL` | PostgreSQL test DB URL | Use GitHub Actions service | | `SLACK_WEBHOOK` | Slack notification webhook | Slack → Apps → Incoming Webhooks | --- ## Branch Protection Rules Configure on GitHub (Settings → Branches → Branch protection rules for `main`): - ✅ Require status checks to pass before merging - `lint` - `type-check` - `unit-tests` - `integration-tests` - `build` - `e2e-tests` - ✅ Require branches to be up to date before merging - ✅ Require pull request reviews (1 approver minimum) - ✅ Dismiss stale pull request approvals when new commits are pushed - ✅ Require linear history (no merge commits, rebase/squash only) - ❌ Do NOT allow force pushes (protect history) --- ## Performance Targets ### Pipeline Duration - **Lint + Type Check:** <2 minutes - **Unit Tests:** <3 minutes - **Integration Tests:** <5 minutes - **Build:** <4 minutes - **E2E Tests:** <8 minutes - **Deploy:** <3 minutes - **TOTAL:** <10 minutes ### Optimization Strategies - Parallel jobs where possible - Cache `node_modules` (GitHub Actions cache) - Matrix builds for multi-browser E2E tests - Incremental builds with Turborepo --- ## Failure Handling ### Failure & Rollback Flow ```mermaid flowchart TD FAIL(["Pipeline Failure"]) WHERE{{"Failed\nStage?"}} BLOCK_PR["PR Blocked\nLogs in GitHub Actions UI\nArtifacts uploaded"] FIX_CODE["Fix code\nPush new commit"] HEALTH{{"Health check\npasses?"}} AUTO_ROLL["Automatic Rollback\nPrevious deployment promoted"] SLACK_ALERT["Slack Alert\n#bilko-deploys"] MANUAL["Manual Investigation\nRailway / Vercel logs"] FLAKY{{"Flaky\nE2E test?"}} RETRY["Playwright retry\n(retries: 1)"] CRITICAL["Mark critical\nCreate GitHub issue"] FAIL --> WHERE WHERE -->|"Quality / Tests"| BLOCK_PR --> FIX_CODE WHERE -->|"Deploy"| HEALTH WHERE -->|"E2E"| FLAKY HEALTH -->|No| AUTO_ROLL --> SLACK_ALERT HEALTH -->|Yes| MANUAL FLAKY -->|Yes| RETRY RETRY -->|Still fails| CRITICAL FLAKY -->|No| BLOCK_PR ``` ### Test Failures 1. Pipeline stops immediately (fail-fast) 2. Logs available in GitHub Actions UI 3. Artifacts uploaded (screenshots, coverage reports) 4. PR blocked until fixed ### Deployment Failures 1. Automatic rollback to previous version 2. Slack notification to team 3. Health check endpoint monitored 4. Manual intervention if health check fails ### Flaky Tests - Retry failed E2E tests once (Playwright config: `retries: 1`) - If still fails, mark as critical and investigate - Track flaky tests in issue tracker --- ## Monitoring & Notifications ### Slack Notifications Notify on: - Production deployment success/failure - Critical test failures (E2E) - Hotfix deployments - Security vulnerabilities detected ### Email Notifications GitHub Actions built-in: - Pipeline failures (to commit author) - Deploy status (to repository admins) --- ## Local Testing Developers can run the full pipeline locally before pushing: ```bash # Lint npm run lint # Type check npm run type-check # Unit tests with coverage npm run test:unit -- --coverage # Integration tests (requires local PostgreSQL) npm run test:integration # Build npm run build # E2E tests (requires build) npm run test:e2e ``` **Pre-commit Hook (Recommended):** Install Husky to run lint + type-check before every commit: ```bash npx husky install npx husky add .husky/pre-commit "npm run lint && npm run type-check" ``` --- ## Future Enhancements ### Security Scanning - **Snyk:** Dependency vulnerability scanning - **SonarQube:** Code quality and security analysis - **OWASP Dependency-Check:** Known vulnerabilities ### Performance Testing - **Lighthouse CI:** Core Web Vitals on every PR - **k6:** Load testing API endpoints (1K concurrent users) ### Database Migration Testing - Test migrations on copy of production database - Validate data integrity post-migration - Measure migration duration --- ## Related Documents - Deployment Guide: [DEPLOYMENT.md](/books/bilko-balkan-accounting-saas/page/deployment-guide) - Environment Setup: [ENVIRONMENT.md](/books/bilko-balkan-accounting-saas/page/environment-configuration) - Testing Guide: [../testing/TESTING-GUIDE.md](/books/bilko-balkan-accounting-saas/page/testing-guide) --- **Last Updated:** 2026-02-20 **Status:** PLANNED — No GitHub Actions workflows configured yet **Next Steps:** Create `.github/workflows/main.yml`, configure secrets, test on staging branch MC #900159 (2026-08-23): Deploy_Landing_HR post-deploy health check — backport curl -L obrasca (io/ba već imaju); /terms.html i /privacy.html na bilko.cloud 308-uju na čiste URL-ove (izmjereno). Token dio riješen kroz MC #900080 (build 1288 'Deployment complete'). # Environment Configuration # Bilko — Development Environment Setup This guide walks through setting up a local development environment for Bilko. --- ## Environment Configuration Overview ```mermaid graph TD subgraph DEV["Development Environment"] D_ENV["apps/api/.env\napps/web/.env.local"] D_PG["PostgreSQL 15\nlocalhost:5432\nbilko_dev"] D_WEB["Next.js\nlocalhost:3000"] D_API["Express\nlocalhost:4000"] D_PRISMA["Prisma Studio\nlocalhost:5555"] end subgraph STAGING["Staging / Preview"] S_SECRETS["Railway Dashboard Env Vars\n(staging environment)"] S_VERCEL["Vercel Preview\nbilko-pr-{n}.vercel.app"] S_RAIL["Railway Staging\nbilko-api-staging"] S_PG["Railway PostgreSQL\nbilko_staging"] end subgraph PROD["Production"] P_SECRETS["Railway + Vercel\nDashboard Secrets"] P_WEB["Vercel Production\nbilko.io"] P_API["Railway Production\napi.bilko.io"] P_PG["Railway PostgreSQL\nbilko_prod"] P_R2["Cloudflare R2\nbilko-receipts"] end D_ENV --> D_API --> D_PG D_ENV --> D_WEB D_API --> D_PRISMA S_SECRETS --> S_RAIL --> S_PG S_SECRETS --> S_VERCEL P_SECRETS --> P_API --> P_PG P_SECRETS --> P_WEB P_API --> P_R2 ``` ## Prerequisites ### Required Software | Software | Version | Check Command | Install | |----------|---------|---------------|---------| | **Node.js** | 18+ | `node --version` | https://nodejs.org | | **npm** | 9+ | `npm --version` | Included with Node.js | | **PostgreSQL** | 15+ | `psql --version` | https://postgresql.org/download | | **Git** | Latest | `git --version` | https://git-scm.com | ### Optional Tools | Tool | Purpose | Install | |------|---------|---------| | **Prisma Studio** | Database GUI | `npx prisma studio` | | **Postman** | API testing | https://postman.com | | **VS Code** | Recommended IDE | https://code.visualstudio.com | --- ## Installation Steps ### 1. Clone Repository ```bash git clone https://github.com/your-org/bilko.git cd bilko ``` ### 2. Install Dependencies ```bash # Install all workspace dependencies npm install ``` This installs dependencies for: - Root workspace (Turborepo) - `apps/web` (Next.js frontend) - `apps/api` (Express backend) - `packages/database` (Prisma) - `packages/ui` (shared UI components) ### Local Setup Flow ```mermaid flowchart TD CLONE["git clone bilko"] INSTALL["npm install\n(Turborepo workspace)"] PG{{"PostgreSQL\navailable?"}} LOCAL_PG["Create local DB\npsql -U postgres\nCREATE DATABASE bilko_dev"] DOCKER_PG["Docker PostgreSQL\npostgres:15\nport 5432"] ENV["Configure .env files\napps/api/.env\napps/web/.env.local"] MIGRATE["npx prisma migrate dev\n(applies 15 table schema)"] GENERATE["npx prisma generate\n(Prisma Client)"] SEED["npx prisma db seed\n(demo org + user) — optional"] DEV["npm run dev\nlocalhost:3000 + 4000"] CLONE --> INSTALL --> PG PG -->|"Local install"| LOCAL_PG --> ENV PG -->|"Docker"| DOCKER_PG --> ENV ENV --> MIGRATE --> GENERATE --> SEED --> DEV ``` ### 3. Set Up PostgreSQL Database #### Option A: Local PostgreSQL Installation Create database and user: ```bash psql -U postgres ``` ```sql CREATE DATABASE bilko_dev; CREATE USER bilko WITH PASSWORD 'bilko'; GRANT ALL PRIVILEGES ON DATABASE bilko_dev TO bilko; \q ``` #### Option B: Docker PostgreSQL ```bash docker run --name bilko-postgres \ -e POSTGRES_USER=bilko \ -e POSTGRES_PASSWORD=bilko \ -e POSTGRES_DB=bilko_dev \ -p 5432:5432 \ -d postgres:15 ``` ### 4. Configure Environment Variables #### apps/api/.env Create `.env` file in `apps/api/` directory: ```env # Database DATABASE_URL=postgresql://bilko:bilko@localhost:5432/bilko_dev # JWT Secrets (use `openssl rand -base64 32` to generate) JWT_SECRET=your-secret-here-change-in-production JWT_REFRESH_SECRET=your-refresh-secret-here-change-in-production # Email (optional for local dev, required for staging/production) SENDGRID_API_KEY= # File Storage (optional for local dev) R2_ACCESS_KEY_ID= R2_SECRET_ACCESS_KEY= R2_BUCKET_NAME=bilko-receipts-dev R2_ENDPOINT= # App Config PORT=4000 NODE_ENV=development ALLOWED_ORIGINS=http://localhost:3000 ``` #### apps/web/.env.local Create `.env.local` file in `apps/web/` directory: ```env # API URL (backend) NEXT_PUBLIC_API_URL=http://localhost:4000 # App Environment NEXT_PUBLIC_APP_ENV=development ``` ### 5. Run Database Migrations ```bash cd packages/database npx prisma migrate dev npx prisma generate ``` This will: 1. Apply all migrations to `bilko_dev` database 2. Create 15 tables from `schema.prisma` 3. Generate Prisma Client ### 6. Seed Database (Optional) Create seed script: `packages/database/prisma/seed.ts` ```typescript import { PrismaClient } from '@prisma/client'; const prisma = new PrismaClient(); async function main() { // Create demo organization const org = await prisma.organization.create({ data: { name: 'Demo Company d.o.o.', registrationNumber: '12345678', vatNumber: 'RS123456789', baseCurrency: 'RSD', country: 'RS', language: 'sr', }, }); // Create demo user await prisma.user.create({ data: { organizationId: org.id, email: 'demo@bilko.io', passwordHash: '$2b$12$...', // bcrypt hash of "demo123" fullName: 'Demo User', role: 'owner', }, }); console.log('✅ Seed data created'); } main() .catch((e) => { console.error(e); process.exit(1); }) .finally(async () => { await prisma.$disconnect(); }); ``` Run seed: ```bash npx prisma db seed ``` --- ## Running the Application ### Start All Services (Recommended) From root directory: ```bash npm run dev ``` Turborepo starts: - **Frontend:** http://localhost:3000 (Next.js) - **Backend:** http://localhost:4000 (Express) ### Start Individual Services #### Frontend Only ```bash cd apps/web npm run dev ``` #### Backend Only ```bash cd apps/api npm run dev ``` --- ## Development Tools ### Prisma Studio (Database GUI) ```bash cd packages/database npx prisma studio ``` Opens at http://localhost:5555 Features: - Browse all tables - Edit records - Run queries - View relations ### Hot Reload Both frontend and backend support hot reload: - **Frontend:** File changes trigger automatic browser refresh - **Backend:** `nodemon` restarts server on `.ts` file changes --- ## Tech Stack Overview ### Frontend (apps/web/) | Technology | Version | Purpose | |------------|---------|---------| | **Next.js** | 15.0.0 | React framework with SSR | | **React** | 19.0.0 | UI library | | **TypeScript** | 5.3.0 | Type safety | | **Tailwind CSS** | 4.0.0 | Styling | | **shadcn/ui** | Latest | Component library (Radix UI + Tailwind) | | **Zustand** | 4.5.0 | State management | | **Recharts** | 2.15.0 | Charts (revenue, expenses) | | **Lucide React** | Latest | Icons | ### Backend (apps/api/) | Technology | Version | Purpose | |------------|---------|---------| | **Express** | TBD | Web framework | | **TypeScript** | 5.3.0 | Type safety | | **Prisma** | Latest | ORM + migrations | | **PostgreSQL** | 15+ | Database | | **Passport.js** | TBD | Authentication | | **Zod** | TBD | Validation | | **Helmet** | TBD | Security headers | | **bcrypt** | TBD | Password hashing | | **jsonwebtoken** | TBD | JWT tokens | ### Database (packages/database/) | Feature | Implementation | |---------|----------------| | **ORM** | Prisma | | **Database** | PostgreSQL 15 | | **Models** | 15 (see schema.prisma) | | **Migrations** | Prisma Migrate | | **Seeding** | prisma/seed.ts | --- ## Common Tasks ### Create Database Migration After modifying `schema.prisma`: ```bash cd packages/database npx prisma migrate dev --name describe_your_changes ``` ### Reset Database (DEV ONLY) **WARNING:** Deletes all data. ```bash cd packages/database npx prisma migrate reset ``` ### Generate Prisma Client After pulling new migrations: ```bash cd packages/database npx prisma generate ``` ### Run Linter ```bash npm run lint ``` Runs ESLint + Prettier on all workspaces. ### Run Type Check ```bash npm run type-check ``` Runs TypeScript compiler in `--noEmit` mode (checks types without building). ### Build for Production ```bash npm run build ``` Builds: - `apps/web/.next/` — Next.js production build - `apps/api/dist/` — Compiled TypeScript --- ## Troubleshooting ### Database Connection Errors **Error:** `Can't reach database server at localhost:5432` **Solutions:** 1. Check PostgreSQL is running: `pg_isready` 2. Verify credentials in `.env` 3. Check port 5432 is not blocked --- ### Port Already in Use **Error:** `Port 3000 is already in use` **Solutions:** 1. Kill process using port: `lsof -ti:3000 | xargs kill` 2. Change port: `PORT=3001 npm run dev` --- ### Prisma Client Not Generated **Error:** `@prisma/client` not found **Solution:** ```bash cd packages/database npx prisma generate ``` --- ### TypeScript Errors After Pulling Changes **Solution:** ```bash npm install npx prisma generate npm run type-check ``` --- ### Hot Reload Not Working **Solution:** 1. Restart dev server 2. Clear Next.js cache: `rm -rf apps/web/.next` 3. Check file watcher limits (Linux): `sysctl fs.inotify.max_user_watches` --- ## VS Code Configuration ### Recommended Extensions Create `.vscode/extensions.json`: ```json { "recommendations": [ "dbaeumer.vscode-eslint", "esbenp.prettier-vscode", "bradlc.vscode-tailwindcss", "prisma.prisma", "ms-vscode.vscode-typescript-next" ] } ``` ### Settings Create `.vscode/settings.json`: ```json { "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.codeActionsOnSave": { "source.fixAll.eslint": true }, "typescript.tsdk": "node_modules/typescript/lib", "tailwindCSS.experimental.classRegex": [ ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"] ] } ``` --- ## Secrets Management ```mermaid flowchart LR DEV_SECRET["Developer\n.env file\n(gitignored)"] GH_SECRET["GitHub Secrets\nActions → Settings\nVERCEL_TOKEN\nRAILWAY_TOKEN\nTEST_DATABASE_URL\nSLACK_WEBHOOK"] VERCEL_ENV["Vercel Dashboard\nEnvironment Variables\nNEXT_PUBLIC_API_URL\nNEXT_PUBLIC_APP_ENV"] RAILWAY_ENV["Railway Dashboard\nEnvironment Variables\nDATABASE_URL (auto)\nJWT_SECRET\nJWT_REFRESH_SECRET\nSENDGRID_API_KEY\nR2_ACCESS_KEY_ID\nR2_SECRET_ACCESS_KEY"] subgraph NEVERCOMMIT["NEVER commit to git"] SECRET_FILE[".env files\nAPI keys\nJWT secrets\nDB passwords"] end DEV_SECRET -->|"local only"| NEVERCOMMIT GH_SECRET -->|"CI/CD pipeline"| VERCEL_ENV GH_SECRET -->|"CI/CD pipeline"| RAILWAY_ENV ``` ## Environment Variables Reference ### apps/api/.env | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `DATABASE_URL` | Yes | — | PostgreSQL connection string | | `JWT_SECRET` | Yes | — | Access token secret (32+ chars) | | `JWT_REFRESH_SECRET` | Yes | — | Refresh token secret (32+ chars) | | `SENDGRID_API_KEY` | No | — | SendGrid API key (emails) | | `R2_ACCESS_KEY_ID` | No | — | Cloudflare R2 access key | | `R2_SECRET_ACCESS_KEY` | No | — | Cloudflare R2 secret key | | `R2_BUCKET_NAME` | No | — | R2 bucket name | | `R2_ENDPOINT` | No | — | R2 endpoint URL | | `PORT` | No | 4000 | API server port | | `NODE_ENV` | No | development | Environment (development/production) | | `ALLOWED_ORIGINS` | No | * | CORS allowed origins (comma-separated) | ### apps/web/.env.local | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `NEXT_PUBLIC_API_URL` | Yes | — | Backend API URL | | `NEXT_PUBLIC_APP_ENV` | No | development | Environment name | --- ## Testing Locally ### Unit Tests ```bash npm run test:unit ``` ### Integration Tests Requires test database: ```bash # Create test database createdb bilko_test # Run tests npm run test:integration ``` ### E2E Tests Requires both frontend and backend running: ```bash # Terminal 1: Start dev servers npm run dev # Terminal 2: Run E2E tests npm run test:e2e ``` --- ## Next Steps After setting up your environment: 1. **Read the docs:** - [Backend API Reference](/books/bilko-balkan-accounting-saas/page/api-reference) - [Frontend Component Guide](/books/bilko-balkan-accounting-saas/page/component-inventory) - [Database Schema](/books/bilko-balkan-accounting-saas/page/database-schema) 2. **Create your first feature:** - Pick a task from the backlog - Create feature branch: `git checkout -b feature/your-feature` - Make changes, test locally - Submit PR 3. **Join the team:** - Slack: #bilko-dev - Weekly sync: Fridays 10:00 CET - Documentation: Bilko Wiki --- ## Related Documents - Deployment Guide: [DEPLOYMENT.md](/books/bilko-balkan-accounting-saas/page/deployment-guide) - CI/CD Pipeline: [CI-CD.md](/books/bilko-balkan-accounting-saas/page/cicd-pipeline) - Security Architecture: [../security/SECURITY-ARCHITECTURE.md](/books/bilko-balkan-accounting-saas/page/security-architecture) --- **Last Updated:** 2026-02-20 **Status:** CURRENT — Reflects actual setup as of this date **Maintainer:** John (AI Director) # Bilko Stage Environment — Cloud SQL & IAM (Phase 1) ## Summary MC #10177 Phase 1 (FlowForge, 2026-04-29): `bilko-staging-db` Cloud SQL instance brought under Flyway management. Pre-existing instance (2026-04-15, Prisma-managed). V1+V2+V4+V5 baselined, V3 actually executed. IAM SA created. Phase 2 (Cloud Run) pending. ## Instance Details
FieldValue
Instance name`bilko-staging-db`
Connection name`tribal-sign-487920-k0:europe-north1:bilko-staging-db`
IP35.228.33.112
Tierdb-g1-small
VersionPOSTGRES\_16
StateRUNNABLE (pre-existing since 2026-04-15; reused)
Database`bilko`
App user`bilko`
Migration admin`migration_admin`
Secret`bilko-staging-db-password` (Secret Manager, 2026-04-15)
IAM SA`bilko-api-stage-sa@tribal-sign-487920-k0.iam.gserviceaccount.com`
IAM SA rolesroles/cloudsql.client + roles/secretmanager.secretAccessor
Total tables24 (public schema)
## Flyway State (2026-04-29)
VersionScriptStatus
V1V1\_\_initial\_schema.sqlBaselined (DDL existed via Prisma)
V2V2\_\_add\_missing\_prisma\_columns.sqlBaselined (DDL existed via Prisma)
V3V3\_\_add\_jmbg\_oib\_encryption.sql**EXECUTED LIVE** — jmbg/jmbg\_hash/oib/oib\_hash + 2 indexes added to contacts (ADR-014)
V4V4\_\_add\_supplementary\_tables.sqlBaselined (DDL existed via Prisma)
V5V5\_\_add\_logo\_url\_to\_organizations.sqlBaselined (DDL existed via Prisma)
## Open Risks - **V3 prod gap:** Prisma migrations never included V3. Production DB may be missing jmbg/oib columns on contacts. Audit required before Kotlin cutover (separate MC pending). - **Prod topology unknown:** bilko-staging-db is the only documented Cloud SQL instance. Whether a separate prod instance exists is unconfirmed. Audit required before Phase 2 prod deploy. - **MC #10187:** gradle flywayMigrate broken (Flyway plugin 10.22.0 + Gradle 9.3.1 incompatibility). Workaround: psql sequential apply. ## Phase Status - Phase 1 (Cloud SQL + IAM + Flyway baseline): COMPLETE - Phase 1.5 (Proveo validation): pending - Phase 2 (Cloud Run bilko-api-stage + bilko-web-stage): Mehanik gate next ## References - MC #10177 (parent), MC #10183 (Flyway verify), MC #10187 (gradle fix) - ADR-014 (field encryption), ADR-021 (blueprint reorg) - DEPLOY-MAP.md — Cloud SQL Instances section - RUNBOOK.md — Section 7g - Evidence: /tmp/bilko-stage-phase1-evidence.json (FlowForge) # Bilko Stage Environment — Cloud Run Services (Phase 2) # Overview **MC:** #10177 Phase 2 | **Deployed:** 2026-04-30 | **Git SHA:** `1f48fdc` | **Status:** LIVE, healthy **GCP Project:** tribal-sign-487920-k0 | **Region:** europe-north1 > **WARNING — TD-3 PROD CUTOVER BLOCKER (MC #10241):** `bilko-staging-db` uses public IP (0.0.0.0/0 authorized network, requireSsl=false). Acceptable for stage only. MUST NOT be replicated to production. Production deploy is blocked until Cloud SQL private IP + VPC connector is configured. ## Live Services
ServiceURLImageMin/MaxMemoryStatus
`bilko-api-stage`[bilko-api-stage](https://bilko-api-stage-dh4m46blja-lz.a.run.app)`bilko/api:stage-1f48fdc`0/2512Mi, CPU 1LIVE
`bilko-web-stage`[bilko-web-stage](https://bilko-web-stage-dh4m46blja-lz.a.run.app)`bilko/web:stage-1f48fdc`0/2512Mi, CPU 1LIVE
Full Artifact Registry prefix: `europe-north1-docker.pkg.dev/tribal-sign-487920-k0/` ## bilko-api-stage Detail
FieldValue
Dockerfile`Dockerfile.api-kotlin` (Kotlin/Ktor, port 4001)
JAVA\_OPTSHikariCP connection pool tuned
Cloud SQL`tribal-sign-487920-k0:europe-north1:bilko-staging-db` via direct TCP 35.228.33.112:5432 (TD-2 + TD-3)
Secrets`bilko-staging-db-password`, `bilko-jwt-secret`, `bilko-jwt-refresh-secret`, `bilko-staging-field-encryption-key` (NEW, ADR-014), `bilko-staging-field-hmac-key` (NEW, ADR-014)
SA`bilko-api-stage-sa@tribal-sign-487920-k0.iam.gserviceaccount.com`
SA roles`cloudsql.client`, `secretmanager.secretAccessor`
Smoke`GET /api/v1/health` → 200 `{"status":"ok","service":"bilko-api","version":"1.0.0"}`
Revision`bilko-api-stage-00001-5x8` (100% traffic)
## bilko-web-stage Detail
FieldValue
Dockerfile`apps/web/Dockerfile` (Next.js 15)
NEXT\_PUBLIC\_API\_URL`https://bilko-api-stage-dh4m46blja-lz.a.run.app/api/v1`
NEXT\_PUBLIC\_APP\_ENV`stage`
Smoke`GET /` → 200 (HTML, lang=sr-Latn)
Revision`bilko-web-stage-00001-c45` (100% traffic)
Build noteFresh npm install (no lockfile) — workaround TD-1 MC #10239
## Smoke Test Commands ``` # API health (expected: {"status":"ok","service":"bilko-api","version":"1.0.0"}) curl -s https://bilko-api-stage-dh4m46blja-lz.a.run.app/api/v1/health # Web root (expected: HTTP 200) curl -s -o /dev/null -w "HTTP %{http_code}" https://bilko-web-stage-dh4m46blja-lz.a.run.app ``` ## Stage Rollback ``` # List revisions gcloud run revisions list --service bilko-api-stage --project=tribal-sign-487920-k0 --region=europe-north1 # Route to prior revision gcloud run services update-traffic bilko-api-stage --project=tribal-sign-487920-k0 --region=europe-north1 --to-revisions=REVISION_NAME=100 ``` ## Stage Redeploy (image update only) ``` gcloud run services update bilko-api-stage --project=tribal-sign-487920-k0 --region=europe-north1 --image=europe-north1-docker.pkg.dev/tribal-sign-487920-k0/bilko/api:NEW_TAG gcloud run services update bilko-web-stage --project=tribal-sign-487920-k0 --region=europe-north1 --image=europe-north1-docker.pkg.dev/tribal-sign-487920-k0/bilko/web:NEW_TAG ``` ## Phase 2 Tech Debt Tracker
IDMCDescriptionSeverityBlocks
TD-1\#10239package-lock.json macOS arm64 missing linux-x64 native bins — fresh npm install workaroundMediumClean stage re-deploys
TD-2\#10240postgres-socket-factory not in build.gradle.kts — Kotlin API uses direct TCP public IPMediumSecure DB connectivity
**TD-3****\#10241****bilko-staging-db: 0.0.0.0/0 + requireSsl=false — STAGE ONLY, NEVER replicate to prod****BLOCKER****PROD CUTOVER Phase 5**
## Key Learnings 1. Lockfile drift macOS/linux: fresh npm install required per build until TD-1 fixed 2. Kotlin Cloud SQL TCP via public IP works for stage, NOT prod (TD-2 + TD-3) 3. --no-traffic flag invalid on new service creation — route 100% on first deploy 4. Field encryption/HMAC keys are random per env (stage isolated from prod — ADR-014) 5. HikariCP socketPath URL param silently ignored — always use explicit host:port for direct TCP ## References - Phase 1 Cloud SQL: Bilko Stage Environment — Cloud SQL & IAM (Phase 1) - MC #10177 (parent), #10239 / #10240 / #10241 (TD items) - ADR-014 (field encryption), ADR-021 (blueprint Section 15) - DEPLOY-MAP.md section: Cloud Run Stage Services - RUNBOOK.md section: 7a Stage Cloud Run Services Access # Bilko demo — receipt upload/download fix (GCS shared storage) — MC #103095 (2026-06-07) ## 1. Symptom CEO reported that receipt upload (PNG, PDF, JPG) was not working — a central part of the app. Investigation showed upload itself succeeded (HTTP 201) but **viewing/downloading the receipt returned intermittent HTTP 404 approximately 60% of the time**. From the user seat, intermittent 404 on download reads as a broken upload. The UI button "Priloženi dokumenti" -> "Preuzmi" triggered the failing request. ## 2. Root Cause The demo API had no shared object storage configured. It used `BILKO_LOCAL_UPLOAD_DIR=/tmp/bilko-uploads` — per-instance ephemeral local disk, routed through `ReceiptService.kt persistLocalIfEnabled`, storing files as `local://` URLs. Cloud Run (bilko-api-demo) runs up to 5 instances with `concurrency=1` (set during the earlier MC #103057 hang mitigation). An upload landing on instance A wrote the file to that instance's `/tmp`; a subsequent download request routed to instance B, which had no copy of the file, returning 404. Files were also permanently lost on any instance restart or recycle. A secondary symptom was occasional 15-second frontend timeouts on the expense detail page: the several parallel API calls the page makes on load were serialised by `concurrency=1`. Contributing config drift: the active deploy step in `infrastructure/gcp/cloudbuild.yaml` (deploy-api-demo) used `--set-env-vars` which replaces the entire env set, making a separate `cloudbuild-demo-api.yaml` with `BILKO_LOCAL_UPLOAD_DIR` ineffective. ## 3. Fix Applied by FlowForge (Kelsey Hightower). No application code changes were required — `ReceiptService.kt` is unchanged and uses a transparent filesystem abstraction.
ChangeDetail
GCS bucket provisioned`gs://bilko-receipts-demo`, region europe-north1, uniform bucket-level access, IAM: bilko-api-stage-sa = roles/storage.objectAdmin
Cloud Run exec environmentUpgraded to `gen2` (required for gcsfuse volume mounts)
Volume mount added`--add-volume=name=receipts,type=cloud-storage,bucket=bilko-receipts-demo`
Mount path`--add-volume-mount=volume=receipts,mount-path=/mnt/bilko-uploads`
Env var updated`BILKO_LOCAL_UPLOAD_DIR`: `/tmp/bilko-uploads` -> `/mnt/bilko-uploads`
Config persistedAll changes committed to `infrastructure/gcp/cloudbuild.yaml` (deploy-api-demo step)
**Deployed:** tag v0.2.30, commit 642bbc0cefdc63777d8c12d61aa61a8257716290, revision bilko-api-demo-00135-rmv, 100% traffic on new revision. Cloud Build ID: 793f929b-f41a-49e9-afa9-65b54d3972ff. Note: Cloud Build reported FAILURE due to a pre-existing flaky test timeout in coverage artifact upload (expenses-ux-102887). This is unrelated to the GCS change. All 8 deploy gates (lint, typecheck, unit, coverage, trivy, gitleaks, semgrep, npm-audit) PASSED; build, push, trivy, migrate, deploy, promote, smoke-test, and verify-sha steps all succeeded. ## 4. Validation **Validated by Proveo (Angie Jones) — GLOBAL VERDICT: PASS.**
TestResult
PDF upload + 10x download10/10 HTTP 200 (was intermittent 404)
PNG upload + 10x download10/10 HTTP 200
JPEG upload + 10x download10/10 HTTP 200
GCS persistence (15 total calls)15/15 HTTP 200 — confirmed shared across instances
UI: Priloženi dokumenti sectionVisible; download icon -> /content HTTP 200
Health checkhttps://bilko-demo-api.alai.no/api/v1/health -> 200 {"status":"ok"}
Company Mesh: `mesh-thr-03f166bb-f001-4293-b9ec-db245e5790b3` — PASS. **Open item (non-blocker):** 1 pre-fix orphan document (uploaded 07:58 before GCS deploy at 08:30) returns 404 as expected — the file lived in ephemeral /tmp on a recycled instance. Not a regression. ## 5. Known Follow-Up Tasks
MCDescription
\#103102Graceful 404 handling for missing documents in UI; fix misleading BILKO-INV-001 error code returned on expense document content misses
\#103103Flaky coverage test (expenses-ux-102887 dialog upload test) blocking clean Cloud Build artifact upload — unrelated to this fix
\#103104Invoice-receipt download gap: POST /invoices/{id}/receipts returns 201 but no download endpoint exists and receiptUrl stays null in invoice record
## 6. Operational Notes — Demo Deploy Pipeline - **Demo deploys** via semver tag (e.g. v0.2.30) pushed to the Bilko repo, which triggers the `bilko-main-deploy` Cloud Build trigger, which runs `infrastructure/gcp/cloudbuild.yaml`. This deploys `bilko-api-demo` + `bilko-web-demo` and migrates `bilko-demo-db`. - **Do NOT push directly to `main`** — pushing to main auto-triggers the stage deploy (bilko-stage-auto-deploy), not the demo deploy. - **Stage vs demo separation:** Stage uses `bilko-api-stage` (no GCS mount, different SA). Demo uses `bilko-api-demo` with `gs://bilko-receipts-demo` via gcsfuse. RLS bugs and storage configuration differ between the two environments — always verify fixes on demo, not only stage. - GCS FUSE driver: `gcsfuse.run.googleapis.com`, requires Cloud Run gen2 execution environment. # Bilko Azure Observability + MS for Startups Credit Setup (2026-06-15) ## Purpose Cross $100/month in foundational Azure spend to automatically unlock the Microsoft for Startups $25K credit tier. The model is **usage-triggered, not referral-gated**: once cumulative Azure spend reaches the threshold, the Founders Hub dashboard upgrades the credit allocation automatically. This work establishes the baseline infrastructure telemetry and security services that generate billable spend from day one. ## What Was Done (MC #103599, 2026-06-15) ### Application Insights Wiring - Resource: `appi-bilko` - Resource group: `rg-bilko-demo` - Region: `swedencentral` - Workspace-linked to: `workspace-rgbilkodemo6lnV` (Log Analytics, PerGB2018 billing tier) - Wired into Bilko Container Apps via `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable on both services. ### Container App Revisions (state at time of work)
ServiceActive RevisionStatusTrafficHTTP Check
`bilko-api-demo` `bilko-api-demo--0000003` Running / Healthy 100% HTTP 404 on root (Ktor baseline — app live, no root handler)
`bilko-web-demo` `bilko-web-demo--0000002` Running / Healthy 100% HTTP 200 (Next.js)
**Note (Proveo-corrected):** `bilko-web-demo--0000001` carries 0% traffic; a second deploy superseded it. Do not confuse with the active revision when diagnosing issues. ### Microsoft Defender for Containers - Tier: Standard, enabled on subscription `5b0b4d9b` - Enablement timestamp: `2026-06-15T06:37:35Z` - **FREE TRIAL: 29-day trial applies.** Billable Defender spend begins approximately **2026-07-14**. - Role: deferred backstop for ongoing security spend. Immediate spend for credit threshold comes from App Insights + Log Analytics ingest. ### Spend Mechanics - **Immediate (day 1):** App Insights data ingest + Log Analytics PerGB2018 billing begins as soon as telemetry flows. - **Deferred (~2026-07-14):** Defender for Containers billable after free trial expires. - **Credit unlock:** Watch Founders Hub dashboard for $25K tier upgrade within 30 days of crossing $100/month cumulative spend. ## Verification Independently verified by Proveo (Angie Jones). Verdict: **PARTIAL**— only a revision-name reporting discrepancy found (--0000001 vs --0000002 for bilko-web-demo), no functional defect. - Evidence: `/tmp/evidence-103599-proveo/verification.md` - Evidence: `/tmp/evidence-103599/verification.md` ## Telemetry Status Wired and operational. First metrics pending ingestion delay of approximately 10–15 minutes from fresh deploy (normal behaviour for App Insights cold start). ## Open Items (flagged, out of scope for MC #103599) - **GCP-vs-Azure canonical demo routing:** Bilko CF Worker still routes brand domains toward a dead GCP endpoint. Azure is the active demo environment but is not yet the canonical DNS target. - **UNLEASH\_URL env drift:** `UNLEASH_URL` environment variable on `bilko-api-demo` may be stale/incorrect. - **Unleash plaintext credentials in ACA:** Unleash credentials stored in plain ACA env vars. Securion review recommended — migrate to Azure Key Vault references. ## How to Verify ``` # Confirm App Insights resource is healthy az monitor app-insights component show --app appi-bilko -g rg-bilko-demo # Check Defender pricing tier az security pricing show --name Containers # Check Container App active revision az containerapp revision list -n bilko-api-demo -g rg-bilko-demo --query "[].{name:name,traffic:properties.trafficWeight,state:properties.runningState}" # Monitor spend trajectory toward $100/month threshold # Azure Portal: Cost Management > bilko subscription > cost analysis ``` Watch the **Microsoft Founders Hub dashboard** for automatic $25K credit tier upgrade once monthly spend crosses $100. ## References - MC #103599 — Bilko Azure Observability + MS for Startups Credit Setup - Memory: `project_microsoft_startups_azure_credits_2026-06-15` - Subscription: `5b0b4d9b` (Bilko demo Azure subscription) - Resource group: `rg-bilko-demo` (swedencentral) # Bilko ACA Telemetry & Observability Wiring (Azure) ## Context GCP Cloud Monitoring dashboard (070613fa) was decommissioned 2026-06-23 after migration to Azure (MC #104228 closed). This page documents the ACA→Log Analytics + App Insights telemetry wiring done as follow-on MC #104266. ## Resources - **Container App Environment:** `bilko-demo-env` (NOTE: `purplebeach-f004d490` is only the default-domain suffix in app URLs, not the env name). - **Log Analytics workspace:** `workspace-rgbilkodemo6lnV`, customerId `71443731-9feb-41b1-9e27-fff4e4ebf098`. - **App Insights:** `appi-bilko`, appId `69e12981-9ebb-47ef-9dbd-5cf69fa87c40`. - **Workbook:** `dcaef4e3-9bc7-48ae-8e1b-bd382a73889e` "Bilko Observability — Prod+Stage (Azure)". - **4 ACA apps:** bilko-api-demo, bilko-web-demo, bilko-api-stage, bilko-web-stage. ## Root cause that was fixed ACA env `appLogsConfiguration.destination` was not effectively set → ContainerApp logs not reaching the workspace. Fixed via: ``` az containerapp env update -n bilko-demo-env -g rg-bilko-demo --logs-destination log-analytics --logs-workspace-id 71443731-... --logs-workspace-key ``` **Result:** ContainerAppSystemLogs\_CL now flows (tool-verified 54 rows/15m, sustained). ## App Insights instrumentation Each ACA app needs env var `APPLICATIONINSIGHTS_CONNECTION_STRING` (from `az monitor app-insights component show -g rg-bilko-demo -n appi-bilko --query connectionString -o tsv`), set via `az containerapp update -n -g rg-bilko-demo --set-env-vars APPLICATIONINSIGHTS_CONNECTION_STRING=`. All 4 apps confirmed set. ## MC #104268 — SDK Initialization Fix (2026-06-28) ✅ The "KNOWN REMAINING GAP" documented below has been **RESOLVED**. Setting `APPLICATIONINSIGHTS_CONNECTION_STRING` env var alone was insufficient — the application runtime must initialize the App Insights SDK/agent. ### Solution — Both Services Now Emitting Telemetry #### 1. bilko-api-demo (Kotlin/Ktor) — Java Agent - **Method:** Application Insights Java Agent 3.6.2 auto-instrumentation - **Implementation:** - Downloaded agent JAR to `/app/applicationinsights-agent.jar` during Docker build (SHA256-pinned: `e81ef99f...`) - Entrypoint: `java -javaagent:/app/applicationinsights-agent.jar -jar /app/bilko-api.jar` - Config file: `apps/api/applicationinsights.json` with **Ktor preview instrumentation enabled**: ``` { "preview": { "instrumentation": { "ktor": { "enabled": true } } } } ``` - Env vars: `APPLICATIONINSIGHTS_CONNECTION_STRING` + `APPLICATIONINSIGHTS_ROLE_NAME=bilko-api` - **Critical discovery:** Ktor instrumentation is a PREVIEW feature in the Java agent. Without the explicit config file enabling it, the agent starts but does NOT instrument Ktor routes. - **Evidence:** 15+ requests visible in App Insights `requests` table with `cloud_RoleName=bilko-api` #### 2. bilko-web-demo (Next.js) — Azure Monitor OpenTelemetry - **Method:** Azure Monitor OpenTelemetry SDK - **Implementation:** `@azure/monitor-opentelemetry` (^1.18.1) initialized in `instrumentation.ts` - **Evidence:** 36+ requests visible in App Insights - **Service Name:** `unknown_service:node` (default, can be customized) ### Validation Result — Complete Success ✅ **Baseline before fix:** `requests` table = 0 rows in last 30 minutes **After fix:** 144+ requests in 15 minutes from BOTH services ``` requests | where timestamp > ago(15m) | summarize count() by cloud_RoleName Result: - bilko-web: 36+ requests - bilko-api: 15+ requests - Total: 144+ requests ``` ### Deployed Revisions (Final) - **bilko-api-demo:** revision `--0000036`, image `demo-9658388f-ai2` - **bilko-web-demo:** revision `--0000024`, image `demo-9658388f` - **Merge commit:** `f15deb8a` (PR #27) ### Files Modified 1. `apps/api/Dockerfile` — Java agent download + config file copy + javaagent entrypoint 2. `apps/api/applicationinsights.json` — NEW: Agent config with Ktor preview instrumentation 3. `apps/web/instrumentation.ts` — Azure Monitor OpenTelemetry initialization 4. `apps/web/package.json` — @azure/monitor-opentelemetry dependency ### Accepted Risk `@azure/monitor-opentelemetry` package has GHSA-8988-4f7v-96qf (documented in `DEPLOY-MAP.md`) ### Evidence Files Evidence stored in repo: `/docs/evidence/104268/{SUCCESS-FINAL.md, telemetry-validation.md, sdk-changes.md, deploy-revisions.md, final-status.md}` --- ## KNOWN REMAINING GAP (important for runbook) — RESOLVED 2026-06-28 *This section is retained for historical context. The gap was resolved by MC #104268 (see section above).* Setting the env var ALONE does not produce App Insights request/dependency telemetry — `requests` table = 0. The app code must initialize the App Insights SDK (Node: `applicationinsights` package; Spring Boot: azure-monitor starter). Until then, App-Insights-request-based workbook panels stay empty. The KQL log panel (ContainerAppSystemLogs\_CL) and ACA platform-metric panels work regardless. Track app-code SDK init as a separate CodeCraft task if request tracing is needed. ## Troubleshooting note `az monitor log-analytics query` returns a FLAT array `[{col:val}]` — do NOT filter with `--query "tables[0].rows"` (returns empty falsely). `az monitor app-insights query` uses `{tables:[{rows}]}` shape. ## Verification queries (runbook) - **Logs:** `ContainerAppSystemLogs_CL | where TimeGenerated > ago(20m) | count` (workspace 71443731) — expect >0. - **Env vars:** `az containerapp show -g rg-bilko-demo -n --query "properties.template.containers[0].env[?name=='APPLICATIONINSIGHTS_CONNECTION_STRING']"`. - **Availability:** availabilityResults pass rate on appi-bilko. ## Related - MC #104268 (completed 2026-06-28) — SDK initialization fix - MC #104266 (completed 2026-06-23) — Env var wiring - MC #104228 (GCP decommission, closed) - Azure subscription: 5b0b4d9b-e677-464e-abf0-5170cbce3b8e - Resource group: rg-bilko-demo (swedencentral) # MC #104332 — Bilko URA LocalDate ISO deploy evidence # MC #104332 / URA3 LocalDate + UI polish deploy evidence (2026-06-25) - Commit: `ea423587 fix: serialize accounting dates as ISO` - Branch: `feat/bilko-payroll-104318` - Images built/pushed linux/amd64: - `bilkodemo.azurecr.io/bilko-api:demo-104332ura3` digest `sha256:2093e32933d107c6b0fedf727c5eb03b199a6ad137283491f9042c28cdb5e728` - `bilkodemo.azurecr.io/bilko-web:demo-104332ura3` digest `sha256:5fac3ee12bb2616dbde9d1e1bd78824b7af84e130aa75d95fc22f7989126473f` ## What changed - Backend Jackson now registers `JavaTimeModule()` and disables `WRITE_DATES_AS_TIMESTAMPS`. - Added `jackson-datatype-jsr310` dependency. - Added regression test `SerializationLocalDateTest` proving `LocalDate` emits `"2026-04-02"`, not `[2026,4,2]`. - URA list/detail/new pages now tolerate ISO strings, legacy Jackson arrays, and comma-joined legacy strings; visible accounting dates use `dd.mm.gggg`. ## Validation evidence - API targeted regression: `docs/evidence/104332/api-serialization-localdate-test-2026-06-25.log` → BUILD SUCCESSFUL. - Web type-check: `docs/evidence/104332/web-type-check-2026-06-25.log` → `tsc --noEmit` exit 0. - Web Docker/Next production build completed during linux/amd64 image build with required `NEXT_PUBLIC_ENTRA_*` args. - Full API test caveat: existing unrelated SveRačun sender-VAT env/config inverse expectation prevents full-suite PASS; targeted regression passes. ## Demo deployment Name Image Latest Ready Running Traffic -------------- ---------------------------------------------- ------------------------ ------------------------ --------- --------- bilko-api-demo bilkodemo.azurecr.io/bilko-api:demo-104332ura3 bilko-api-demo--ura3-api bilko-api-demo--ura3-api Running 100 bilko-web-demo bilkodemo.azurecr.io/bilko-web:demo-104332ura3 bilko-web-demo--ura3-web bilko-web-demo--ura3-web Running 100 Health probes: - `https://app-api.bilko.cloud/api/v1/health` → 200 `{"status":"ok","service":"bilko-api","version":"1.0.0"}` - `https://app.bilko.cloud/login` → 200 and login page rendered. ## Live UAT evidence - Targeted deployed URA/LocalDate verification: `docs/evidence/104332/ura3-demo-get-verify-2026-06-25.log` → 20/20 PASS. - API list/detail: `accountingDate` serialized as ISO string `"2026-04-02"`. - API list/detail: no legacy Jackson LocalDate arrays. - UI `/accounting/ulazni-racuni`, `/accounting/ulazni-racuni/{id}`, `/accounting/ulazni-racuni/novi`: authenticated render, no legacy arrays, `02.04.2026` visible on list/detail. - JSON: `docs/evidence/104332/ura3-demo-get-verify-1782424811784.json`. - Screenshots: `docs/evidence/104332/ura3-demo-list-1782424811784.png`, `docs/evidence/104332/ura3-demo-detail-1782424811784.png`, `docs/evidence/104332/ura3-demo-new-1782424811784.png`. - Master live route walk rerun: `docs/evidence/104332/master-live-uat-ura3-rerun-2026-06-25.log` → 42/42 PASS, 0 FAIL. - Full owner live mutation UAT: `docs/evidence/104332/full-owner-uat-ura3-2026-06-26.log` → 129/129 PASS, 0 FAIL. - Created/verified real contact, invoice draft→sent→paid, expense, employee/payslip, invite create→validate→revoke, notifications, billing plan change, multi-org, and browser owner route walk. - Screenshots copied to `docs/evidence/104332/full-owner-uat-screenshots-2026-06-26/`. - Earlier master run had demo-session bounce flakiness (17 route bounces), superseded by clean rerun plus targeted URA verification. ## Azure DevOps merge evidence - PR #22 `Fix URA LocalDate ISO serialization`: completed 2026-06-26. - PR validation pipeline run #100: succeeded; blocking policy `Bilko-CI-CD PR Validation` approved. - `azdo/main` now at `7c340a11 Merge pull request 22 from feat/bilko-payroll-104318 into main`. - `azdo/main` contains `ea423587 fix: serialize accounting dates as ISO`. ## Status - Demo deploy and UAT: PASS (`42/42` master + `129/129` full owner + `20/20` targeted URA). - Re-merge main: PASS. --- Local evidence directory: `/Users/makinja/business/ALAI-Holding-AS/products/Bilko/docs/evidence/104332` # MC #105767 — Bilko Demo CORS/DNS Fix (OCD-11 Resolved) # MC #105767 — Bilko Demo Env CORS/API-host + DNS Retirement (OCD-11 closed) **Date:** 2026-07-15 | **Agent:** CodeCraft | **Status:** RESOLVED ## Root cause The original UAT finding (MC #105765) conflated two separate, non-overlapping facts as one "CORS bug": 1. The Ktor API's `CORS_ORIGINS` allowlist (`azure-pipelines.yml:889`) is deliberately scoped to the customer brand domains only (`app.bilko.cloud`, `app.bilko.io`, `app.bilko.company`, `localhost`). It correctly rejects unrecognized origins — the raw ACA FQDN and `bilko-demo.alai.no` — with a 403 `BILKO-AUTH-003`. **This is intended access control, not a defect.** 2. `bilko-demo.alai.no` and `bilko-demo-api.alai.no` were dead Cloudflare CNAME records pointing at `ghs.googlehosted.com` (GCP era, dead since the 2026-06-15 Azure cutover). This was already tracked as `DEPLOY-MAP.md` OCD-11 and already declared "dead/retired for customer handoff" in the canonical `docs/operations/DEMO-ACCESS.md` (verified 2026-07-12). The canonical customer/sales demo entry point, `https://app.bilko.cloud/demo?country=HR`, was **never broken**. Confirmed live before and after this change: HTTP 200, correct `access-control-allow-origin` header, zero console errors, zero network errors (Playwright chromium, screenshot in evidence). ## Action taken - Deleted 2 dead DNS records from the `alai.no` Cloudflare zone: `bilko-demo.alai.no` and `bilko-demo-api.alai.no` (both CNAME → `ghs.googlehosted.com`). - No code, pipeline, ACA container app, revision, or `CORS_ORIGINS` config was changed. - No production traffic was touched — `app.bilko.cloud/.io/.company` and `api.bilko.cloud/.io/.company` all confirmed 200 before and after. - Updated `DEPLOY-MAP.md`: OCD-11 marked RESOLVED; 2 stale references to the retired hostnames corrected to point at the canonical demo URL. ## Why repoint-through-Worker was rejected Both DNS records were `proxied=false` (grey-clouded), so they could never reach the `bilko-edge-proxy` Cloudflare Worker's Host/SNI rewrite mechanism. The Worker's `wrangler.toml` routes are scoped to the `bilko.io` / `bilko.cloud` / `bilko.company` zones only — not `alai.no`. Extending that would require a code change, an azdo pipeline deploy, and a Workers-scoped Cloudflare API token (only a DNS/zone-scoped token was available at triage time). Disproportionate for a dead legacy alias already declared retired in canonical docs. ## Verification - **P2P pre-verifier (Company Mesh):** thread `mesh-thr-f05cd82e-5678-4178-bc2d-b5a678686c76`, Proveo peer end-state PASS. - **Live Playwright browser check** on `https://app.bilko.cloud/demo?country=HR`: HTTP 200, 0 console errors, 0 network errors, screenshot captured. - **DNS retirement confirmed** via Cloudflare API (record count 0) and authoritative nameserver `dig` (empty answer) for both retired hostnames. - **Prod safety confirmed:** all 6 brand domain + health-check endpoints returned 200 post-change. ## Evidence `~/system/evidence/105767/` — DNS before/after snapshots, Playwright result JSON + screenshot, direct-probe log, sha256-verified evidence manifest (`evidence-105767.json`). ## References - MC #105765 (UAT synthesis that surfaced this) · MC #105767 (this task) - `Bilko/DEPLOY-MAP.md` OCD-11 · `Bilko/docs/operations/DEMO-ACCESS.md` # Bilko Landing Lead-Capture Chain — Mechanism, the Two-Month Outage, and the Traps # Bilko Landing Lead-Capture Chain — Mechanism, the Two-Month Outage, and the Traps **MCs covered:** #106193 (bilko.cloud KV, genesis), #106358 (bilko.io / bilko.company KV), #106359 (preview namespace isolation), #106405 (dead Turnstile widgets), #106408 (correction to a false "fixed" report), #106413 (HR cookie-banner click interception, OPEN), #106418 (CF Pages drift, structural root cause, OPEN), #106403 (was anything lost before today, OPEN) | **Status:** all three landings proven capturing leads end-to-end as of 2026-07-28 | **Verified against:** `azdo/main` @ `50e4223a` (2026-07-28) + live Cloudflare state read at deploy time | **Last updated:** 2026-07-28 **One-line summary:** a single 2026-06-17 session broke the storage layer and the anti-spam widget on two of three landing sites at once, in a way that produced no error a human would see for the next six weeks; `bilko.company` did not capture a single lead in its entire existence until it was fixed today. --- ## 1. The full path a lead takes Three separate Cloudflare Pages projects, one per market, each a static HTML form (Next.js-exported for two of them) with its own Pages Function:
MarketApp directoryDomainCF Pages project
io (Serbia, primary)`apps/landing-io/`bilko.io`bilko-io`
hr (Croatia)`apps/landing-hr/`bilko.cloud`bilko-cloud`
ba (Bosnia)`apps/landing-ba/`bilko.company`bilko-company`
``` Visitor fills the form → Turnstile (invisible widget, static