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 
 
 Money = NUMERIC(19,4) — NEVER use float or number for currency 
 Double-entry always — Every financial event = debit + credit entries 
 Multi-currency locking — Exchange rate locked at transaction date 
 Immutable audit — LoggedAction is append-only, NEVER delete 
 Mock data replacement — Flag all mock data usage, replace with API calls 
 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)