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)