Skip to main content

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)
Back to top