Skip to main content

Documentation Index

Bilko Documentation Index

Last updated: 2026-02-20 Project ID: bbd77cc0 Status: Backend SPECIFICATION (not implemented) Pipeline Status: 7/8 gates PASS — BalkanSee AccountingValidation SaaSReport

Key Documents

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

DocumentDescriptionStatus
API ReferenceAll API endpoints — method, path, request/response, authSPECIFICATION
Database SchemaAll 15 models — columns, types, constraints, indexesIMPLEMENTED (Prisma)
AuthenticationJWT auth flow, password hashing, 2FA, RBACSPECIFICATION
Business LogicDouble-entry bookkeeping, VAT calculation, multi-currency, reconciliationSPECIFICATION
MiddlewareExpress middleware stack — security, auth, validation, error handlingSPECIFICATION
ServicesExternal service integrations — SendGrid, Cloudflare R2, exchange rates, PDF generationSPECIFICATION

Frontend Documentation

DocumentDescriptionStatus
PagesAll 10 implemented pages — routes, data requirements, mobile responsiveIMPLEMENTED
Component InventoryAll 17 shadcn/ui components — usage, props, examplesIMPLEMENTED
Design SystemColors, typography, spacing, shadows — 73 design tokensIMPLEMENTED
State ManagementZustand setup, stores, patternsSPECIFICATION
FormsForm validation, error handling, submission patternsSPECIFICATION
Web App CLAUDE.mdNext.js 15 frontend overviewREFERENCE

Infrastructure Documentation

DocumentDescriptionStatus
DeploymentDeployment strategy — Vercel (frontend), Railway (backend+DB), environmentsSPECIFICATION
CI/CDGitHub Actions pipeline — lint, test, build, deploySPECIFICATION
EnvironmentEnvironment variables, secrets management, configSPECIFICATION

Security Documentation

DocumentDescriptionStatus
Security ArchitectureJWT auth, RBAC, encryption, rate limiting, OWASP Top 10SPECIFICATION
ComplianceGDPR compliance, data retention, user rights, privacy policySPECIFICATION

Testing Documentation

DocumentDescriptionStatus
Testing GuideTesting philosophy, pyramid, tech stack (Vitest, Supertest, Playwright)SPECIFICATION
Test InventoryCritical test scenarios, coverage requirements, quality gatesSPECIFICATION

Regulatory Documentation

DocumentDescriptionStatus
Serbia SEFSEF e-invoicing (UBL 2.1), 20% PDV, Kontni Okvir Chart of Accounts, e-TransportRESEARCH COMPLETE
BiH PDV17% PDV, UNO/ITA filing, e-invoicing draft law, FBiH (IFRS) + RS Chart of AccountsRESEARCH COMPLETE
Croatia eRačuneRačun B2G (2019) + B2B (2026), 25% VAT, RRiF Chart of Accounts, Fiscalization 2.0RESEARCH COMPLETE
Chart of AccountsSerbia (Class 0-9), BiH (IFRS/RS), Croatia (RRiF) — account structuresRESEARCH COMPLETE

How to Use This Documentation

QuickFor InfoBackend Developers

  • Start
  • Implement
    • MiddlewareAuthentication
    FieldValue
    ProductCloudwith API Reference — this is your implementation contract
  • Read Database Schema — understand the data model
  • Review Business Logic — learn accounting fordomain Balkanrules
    • SMBs
    MarketsSerbia,endpoints BiH,following Croatia
    InspirationFikenand (Norway)
    Domainsbilko.io (primary), bilko.rs (Serbia)
    Pipeline IDbbd77cc0
    Path/Users/makinja/ALAI/products/Bilko/

    TechFor StackFrontend Developers

    • Frontend:All Next.jsendpoints 15in +API ReactReference 19 +include TypeScript + Tailwind CSS 4 + shadcn/uiinterfaces
    • Backend:Replace Expressmock +data TypeScriptimports +with PostgreSQLAPI + Prisma (NOT BUILT YET)calls
    • State:Use Zustandthe (installed,request/response mostlytypes Reactfrom hooks)
      • API
    • Charts: Recharts
    • Icons: Lucide React
    • Monorepo: TurborepoReference

    BrandingFor QA Engineers

    • Name:API BilkoReference (fromincludes Serbianexample "bilans"requests/responses =for balanceall sheet)endpoints
    • PrimaryUse Color:these #00E5A0as (minttest green)cases
    • Font:Verify Inter
      • business
    • Logo:logic Sharprules Bfrom —Business MinimalistLogic Geometric (Figma Design #1)document

    Key Architectural Decisions

    Current1. StatusDouble-Entry Bookkeeping

      Every

    • Frontend:financial 8+event pagescreates implementeda Transaction with mockdebitAccount data
      • +
    • Backend:creditAccount. EmptyDebits —= ExpressCredits scaffold only
    • Database: 15 Prisma models fully defined
    • Design: Figma validated, sidebar fix applied 2026-02-21
    always.

    Key2. Decisions

    • Double-entry bookkeeping (debit/credit)
    • Multi-currencyCurrency with exchangeRate Locking

      Exchange rate locking

      • 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 monetaryMoney

      amounts

      NEVER use float or JavaScript number for currency. Precision is critical.

      Contributing

      When adding new documentation:

      1. Add entry to this INDEX.md
      2. RBAC:Follow owner,existing admin,document accountant,structure viewer(Purpose → Spec → Examples)
  • Mark implementation status (SPECIFICATION, IN PROGRESS, IMPLEMENTED)
  • Update "Last updated" date in this file
    • Back to top