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 — 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

  1. Start with API Reference — this is your implementation contract
  2. Read Database Schema — understand the data model
  3. Review Business Logic — learn accounting domain rules
  4. 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.

  • 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

No comments to display

Back to top