Skip to main content

Bilko — Project Handbook

Bilko — Balkan Accounting SaaS

BookStack — Provjeri PRVO

Prije traženja bilo čega — provjeri BookStack (https://docs.basicconsulting.alai.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/`
Back to top