# 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/\`