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 Key Documents 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 All API endpoints — method, path, request/response, auth SPECIFICATION Database Schema All 15 models — columns, types, constraints, indexes IMPLEMENTED (Prisma) Authentication JWT auth flow, password hashing, 2FA, RBAC SPECIFICATION Business Logic Double-entry bookkeeping, VAT calculation, multi-currency, reconciliation SPECIFICATION Middleware Express middleware stack — security, auth, validation, error handling SPECIFICATION Services External service integrations — SendGrid, Cloudflare R2, exchange rates, PDF generation SPECIFICATION Frontend Documentation Document Description Status Pages All 10 implemented pages — routes, data requirements, mobile responsive IMPLEMENTED Component Inventory All 17 shadcn/ui components — usage, props, examples IMPLEMENTED Design System Colors, typography, spacing, shadows — 73 design tokens IMPLEMENTED State Management Zustand setup, stores, patterns SPECIFICATION Forms 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 Deployment strategy — Vercel (frontend), Railway (backend+DB), environments SPECIFICATION CI/CD GitHub Actions pipeline — lint, test, build, deploy SPECIFICATION Environment Environment variables, secrets management, config SPECIFICATION Security Documentation Document Description Status Security Architecture JWT auth, RBAC, encryption, rate limiting, OWASP Top 10 SPECIFICATION Compliance GDPR compliance, data retention, user rights, privacy policy SPECIFICATION Testing Documentation Document Description Status Testing Guide Testing philosophy, pyramid, tech stack (Vitest, Supertest, Playwright) SPECIFICATION Test Inventory Critical test scenarios, coverage requirements, quality gates SPECIFICATION Regulatory Documentation Document Description Status Serbia SEF SEF e-invoicing (UBL 2.1), 20% PDV, Kontni Okvir Chart of Accounts, e-Transport RESEARCH COMPLETE BiH PDV 17% PDV, UNO/ITA filing, e-invoicing draft law, FBiH (IFRS) + RS Chart of Accounts RESEARCH COMPLETE Croatia eRačun eRačun B2G (2019) + B2B (2026), 25% VAT, RRiF Chart of Accounts, Fiscalization 2.0 RESEARCH COMPLETE Chart of Accounts Serbia (Class 0-9), BiH (IFRS/RS), Croatia (RRiF) — account structures RESEARCH COMPLETE How to Use This Documentation For Backend Developers Start with API Reference — this is your implementation contract Read Database Schema — understand the data model Review Business Logic — learn accounting domain rules Implement endpoints following Middleware and Authentication 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: Add entry to this INDEX.md Follow existing document structure (Purpose → Spec → Examples) Mark implementation status (SPECIFICATION, IN PROGRESS, IMPLEMENTED) Update "Last updated" date in this file