# 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)