Bilko — Project Handbook

Bilko — Balkan Accounting SaaS

BookStack — Provjeri PRVO

Prije traženja bilo čega — provjeri BookStack (https://docs.basicconsulting.no). 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), bilko.cloud (Croatia / HR), bilko.company (Bosnia / BA)
• Landing pages: apps/landing-hr/ (bilko.cloud) + apps/landing-ba/ (bilko.company) — deployed to CF Pages

Branding

• Name: Bilko (from Serbian "bilans" = balance sheet)
• Primary Color: #8B6BBF (Plum)
• Secondary: #5B3E8A (Deep Plum)
• Accent: #F2C87A (Gold)
• Surface: #F9F7FC (Light Lavender)
• Text Dark: #231C33
• Font Heading: National Park
• Font Body: Work Sans
• Font Mono: DM Mono
• Grid: 8px spacing system
• Icons: Lucide React

Tech Stack (updated 2026-03-17)

• Frontend: Next.js 15 + React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui (ALAI standard ✓)
• Backend: Kotlin/Ktor + Exposed + Flyway (ALAI standard, sole canonical backend, ADR-020+ADR-021). CEO removed Express/api-express 2026-05-02 (MC #10493).
• 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/          # Kotlin/Ktor backend — canonical (ADR-020+ADR-021)
├── packages/
│   ├── database/     # Prisma schema — 15 models, FULLY DEFINED
│   ├── domain-rs/    # Serbia domain plugin
│   ├── domain-ba/    # Bosnia & Herzegovina domain plugin
│   ├── domain-ba-fed/# BiH Federation domain plugin
│   ├── domain-ba-rs/ # Republika Srpska domain plugin
│   ├── domain-hr/    # Croatia domain plugin
│   └── ui/           # Shared UI — empty scaffold
├── docs/             # Documents (see docs/INDEX.md)
├── infrastructure/   # Docker, GCP, terraform
├── tools/            # figma-plugin, ci-stubs
├── 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/)

CANONICAL. Kotlin/Ktor backend (ADR-020+ADR-021, 2026-04-29). Express/api-express deleted 2026-05-02 (MC #10493, CEO directive). Kotlin/Ktor backend: apps/api/CLAUDE.md. API contract: docs/backend/API-REFERENCE.md.

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)

Open Banking (Bank Feed)

Bilko uses Tok (~/ALAI/products/Tok/) for automatic bank feed via Open Banking (PSD2 AISP).

• Tok is the independent Open Banking platform — Bilko is a consumer of Tok API
• Integration spec: docs/INTEGRATION-WITH-TOK.md
• Tok docs: ~/ALAI/products/Tok/docs/
• Open Banking docs have been migrated to Tok — docs/open-banking/ no longer exists

Documentation

• Root index: docs/INDEX.md — documents (see INDEX.md for current count)
• Backend API: docs/backend/API-REFERENCE.md (contract for api/ implementation)
• Regulatory: docs/regulatory/ (Serbia/BiH/Croatia accounting laws)
• Legal: docs/legal/ (Privacy Policy, ToS, Data Retention)
• Security: docs/security/ (11 docs — GDPR, DPIA, encryption, pentest)
• Business: docs/business/ (GTM, pricing, beta testing, onboarding)
• Open Banking integration: docs/INTEGRATION-WITH-TOK.md

Shared Dev Configs

• TypeScript: `@alai/tsconfig` — `~/ALAI/internal/configs/packages/tsconfig/`
• ESLint: `@alai/eslint-config` — `~/ALAI/internal/configs/packages/eslint-config/`
• Prettier: `@alai/prettier-config` — `~/ALAI/internal/configs/packages/prettier-config/`