# Project Overview

# Documentation Index

# Drop Documentation Index

> Last updated: 2026-02-17 | Validated: 20/20 PASS after doc alignment audit

## Backend

| Document | Description |
|----------|-------------|
| [API Reference](backend/API-REFERENCE.md) | All 26 API endpoints — method, path, request/response, auth, rate limits |
| [Database Schema](backend/DATABASE-SCHEMA.md) | All 19 tables (12 core + 7 compliance) — columns, types, constraints, indexes |
| [Authentication](backend/AUTHENTICATION.md) | JWT auth flow — register, login, refresh, logout, middleware |
| [Services](backend/SERVICES.md) | External integrations — Sumsub (KYC) `[PRODUCTION]`, Stripe (Cards) `[MOCK]`, Swan `[DEPRECATED]` |
| [Middleware](backend/MIDDLEWARE.md) | Auth, validation, rate limiting, CSRF, error handling |
| [Feature Flags](backend/FEATURE-FLAGS.md) | 8 feature flags, 16 tracked features, server/client APIs |

## Frontend

| Document | Description |
|----------|-------------|
| [Component Inventory](frontend/COMPONENT-INVENTORY.md) | All components — custom, icons, shadcn/ui primitives |
| [Pages](frontend/PAGES.md) | All 20 routes — auth, components, data fetching, compliance pages |
| [Design System](frontend/DESIGN-SYSTEM.md) | Colors, typography (Fraunces/DM Sans/Geist Mono), spacing, patterns |
| [State Management](frontend/STATE-MANAGEMENT.md) | useAuth hook, feature flags, data fetching patterns |
| [Landing Pages](frontend/LANDING-PAGES.md) | Marketing site — 9 sections, 12 sub-pages, waitlist API |

## Mobile

| Document | Description |
|----------|-------------|
| [Mobile App](mobile/MOBILE-APP.md) | Expo Router architecture, 8 screens, API client, theme |

## Infrastructure

| Document | Description |
|----------|-------------|
| [Deployment](infrastructure/DEPLOYMENT.md) | Docker, Fly.io, 3 deployment configs (MVP/Production/Staging) |
| [CI/CD](infrastructure/CI-CD.md) | GitHub Actions pipeline — lint, test, build, e2e, docker (5 jobs) |
| [Monitoring](infrastructure/MONITORING.md) | Health checks, container monitoring, gaps identified |
| [Environment](infrastructure/ENVIRONMENT.md) | Tech stack, npm scripts, Next.js config, env modes |

## Security

| Document | Description |
|----------|-------------|
| [Security Architecture](security/SECURITY-ARCHITECTURE.md) | JWT, cookies, bcrypt, CSRF, rate limiting, input validation |
| [Compliance](security/COMPLIANCE.md) | PSD2, AML, GDPR, DORA readiness — 8/100 overall, remediation plan |

## Testing

| Document | Description |
|----------|-------------|
| [Testing Guide](testing/TESTING-GUIDE.md) | Vitest + Playwright, running tests, mocking, patterns |
| [Test Inventory](testing/TEST-INVENTORY.md) | All 14 test files — unit, integration, e2e, regression, performance |

## Quality Assurance

| Document | Description |
|----------|-------------|
| [Validation Report](VALIDATION-REPORT.md) | Cross-reference audit of all docs against source code |

# Business Case (ZiCA v2)

# Drop — Business Case v2 (Remittance + QR Payments)

> **Note:** Originally titled "Drop — Business Case v2". Product has been rebranded to **Drop**. Target audience broadened from diaspora-only to ALL residents in Norway/Scandinavia. Business model updated to pass-through PSD2 (PISP/AISP) — Drop NEVER holds customer money. See [Drop CLAUDE.md](/ALAI/products/Drop/CLAUDE.md) for current spec.

**Date:** 2026-02-08 (updated 2026-02-14)
**Version:** 2.1
**Compiled by:** John (AI Director)
**Sources:** 8 AI agents — 2 runde analize
**Pivotni insight:** Alem

---

## Executive Summary

Drop je fintech app za sve stanovnike Norveške/Skandinavije sa dva revenue streama:
1. **Remittance** — pošalji novac u inostranstvo jeftinije (primatelj NE treba app)
2. **QR Merchant Payments** — plaćaj u dućanu skeniranjem QR koda (kao UPI u Indiji)

Isti korisnik, dva use-case-a, pass-through PSD2 model (Drop NIKAD ne drži novac korisnika). Ovo stvara flywheel efekat.

---

## 1. Vizija

```
┌─────────────────────────────────────────────────────────┐
│                     DROP ECOSYSTEM                       │
│                                                          │
│   POŠILJALAC (Norveška)          PRIMATELJ (inostranstvo)│
│   ┌──────────┐                   ┌──────────┐           │
│   │ Drop App │─── remittance ──▶│ Bank/Cash │           │
│   │ (PISP)   │   via Open Banking│ (no app!) │           │
│   └────┬─────┘                   └──────────┘           │
│        │                                                 │
│        │ QR scan                                         │
│        ▼                                                 │
│   ┌──────────┐                                          │
│   │ Merchant │ ← lokalni biznisi u Norveškoj            │
│   │ QR Code  │ ← jeftiniji od Vipps (1% vs 1.75-2.75%) │
│   └──────────┘                                          │
│                                                          │
│   FLYWHEEL:                                              │
│   Više korisnika → više merchanta → više korisnika       │
│   DROP NIKAD NE DRŽI NOVAC — pass-through PSD2 model    │
└─────────────────────────────────────────────────────────┘
```

---

## 2. Tržište (data-engineer agent)

| Podatak | Vrijednost | Izvor |
|---------|-----------|-------|
| Imigranti u Norveškoj | ~1,000,000 | SSB |
| Remittance iz Norveške godišnje | **5.7 mlrd NOK** | World Bank |
| Prosječna remittance tx | ~1,000 NOK | World Bank |
| SME u Norveškoj | ~195,000 | SSB |
| Top remittance korridori | Srbija, Poljska, Pakistan, Iran, Turska | SSB |
| Lokalni biznisi (procjena) | 30,000-50,000 | SSB estimate |

---

## 3. Dva Revenue Streama

### Stream 1: Remittance

| Aspekt | Detalj |
|--------|--------|
| **Šta** | Slanje novca iz Norveške u Balkan, Pakistan, Tursku, itd. |
| **Kako** | Drop app → PISP (Open Banking) via bank partner → bank transfer/cash pickup |
| **Primatelj** | NE treba app — prima na račun ili cash |
| **Fee** | 0.5% (vs Wise 0.7-1.5%, vs WU 5-10%) |
| **Corridors** | NOK→RSD, NOK→BAM, NOK→PKR, NOK→TRY, NOK→PLN, NOK→EUR |

### Stream 2: QR Merchant Payments

| Aspekt | Detalj |
|--------|--------|
| **Šta** | Plaćanje u dućanu skeniranjem QR koda |
| **Kako** | Merchant prikaže QR → customer skenira → instant transfer |
| **Merchant** | Lokalni biznisi (kebab, kiosk, pekara, restoran, frizer) |
| **Fee** | 1% (vs Vipps 1.75-2.75%) |
| **Settlement** | Daily batch payout na merchant bank račun |
| **Tech** | qrcode.js (generisanje) + html5-qrcode (skeniranje) |

### Flywheel

```
Korisnik šalje remittance → navikne na Drop → plaća u lokalnom dućanu QR-om
Merchant prihvati QR → preporuči Drop → korisnik šalje i remittance
→ REPEAT
```

---

## 4. User Journeys

### Journey A: Remittance

1. Amir otvori Drop, tap "Pošalji novac"
2. Odabere: Srbija, mama Jasmina, njen broj računa
3. Unese 2,000 NOK → vidi: primatelj dobije 23,400 RSD, fee 10 NOK (0.5%)
4. Potvrdi, plati sa norveške kartice
5. Mama dobije SMS: "Primili ste 23,400 RSD od Amira"
6. Novac na računu za 1-2 radna dana

### Journey B: QR Payment

1. Amir uđe u Ahmetov kebab shop u Oslu
2. Na kasi je Drop QR naljepnica
3. Amir otvori Drop, tap "Skeniraj"
4. Skenira QR → prikaže se: "Ahmetov Kebab, unesi iznos"
5. Unese 129 NOK, tap "Plati"
6. Ahmet dobije notifikaciju: "Primljeno 129 NOK od Amir"
7. Instant. Bez terminala. Fee 1.29 NOK umjesto 3.55 NOK (Vipps).

### Journey C: Killer Combo

1. Amir šalje 5,000 NOK mami — dobije 25 Drop bodova
2. Plaća kebab 129 NOK QR-om — dobije 1 bod
3. Na 50 bodova: besplatna remittance (no fee)
4. Ahmet (merchant) vidi: "Ove sedmice: 47 transakcija, 12,300 NOK, fee 123 NOK"
5. Ahmet preporuči Drop svim korisnicima → novi korisnici → više remittance

---

## 5. Merchant Onboarding (3 minuta)

1. Vlasnik skine Drop app
2. Tap "Registruj biznis" → unese: naziv, adresa, bank račun
3. KYC: lična karta + org.nummer
4. Dobije QR kod — printaj ili koristi na telefonu
5. Lijepi QR na kasu
6. Gotovo. Prima plaćanja odmah.

---

## 6. Finansijski Model (KORIGIRAN — realistične projekcije)

### Startup Costs

| Stavka | Iznos (NOK) |
|--------|-------------|
| Development (AI-first) | 10,000 |
| Open Banking integracija (PSD2) | 15,000 |
| Legal + compliance setup | 50,000 |
| Marketing launch | 100,000 |
| QR naljepnice + merchant kit | 20,000 |
| Buffer | 55,000 |
| **UKUPNO** | **250,000 NOK** |

### Revenue Projection (KONZERVATIVAN)

| Period | Remittance korisnici | Merchant-i | MRR Remittance | MRR Merchant | **Ukupni MRR** |
|--------|---------------------|-----------|---------------|-------------|---------------|
| Mj 1-3 | 200 | 20 | 2,000 | 10,000 | **12,000** |
| Mj 4-6 | 1,000 | 80 | 10,000 | 40,000 | **50,000** |
| Mj 7-12 | 3,000 | 200 | 30,000 | 100,000 | **130,000** |
| Year 1 avg | 3,000 | 200 | 30,000 | 100,000 | **130,000** |
| Year 2 avg | 8,000 | 500 | 80,000 | 250,000 | **330,000** |
| Year 3 avg | 15,000 | 1,000 | 150,000 | 500,000 | **650,000** |

**Napomena:** MRR Remittance = korisnici × 2 tx/mj × 1,000 NOK × 0.5%. MRR Merchant = merchanti × 50,000 NOK/mj promet × 1%.

### ARR Projection

| Godina | ARR (NOK) |
|--------|-----------|
| Year 1 | ~1,000,000 |
| Year 2 | ~4,000,000 |
| Year 3 | ~7,800,000 |

### Monthly Costs (post-launch)

| Stavka | NOK/mj |
|--------|--------|
| Bank partner fees | 10,000-20,000 |
| Hosting + infra | 2,000 |
| Claude Code (development) | 1,100 |
| Marketing (ongoing) | 30,000-50,000 |
| Support + compliance | 10,000 |
| **Mjesečni burn** | **~55,000-85,000** |

### Break-Even

| Scenarij | Break-even MRR | Kad? |
|----------|---------------|------|
| Optimistički | 85,000 NOK/mj | Mjesec 5-6 |
| Realistički | 85,000 NOK/mj | Mjesec 7-9 |
| Pesimistički | 85,000 NOK/mj | Mjesec 12-14 |

### Unit Economics

| Segment | CAC | LTV (24mj) | LTV:CAC |
|---------|-----|-----------|---------|
| Consumer (remittance) | 100 NOK | 2,400 NOK | **24:1** |
| Merchant (QR) | 500 NOK | 24,000 NOK | **48:1** |

Merchant LTV je IZUZETAN jer je recurring i visok volumen.

---

## 7. Competitive Landscape

| Konkurent | Remittance | QR Payments | Dijaspora focus | Fee |
|-----------|-----------|------------|----------------|-----|
| Vipps | ❌ Samo Norveška | ✅ Ali skupo za merchante | ❌ | 1.75-2.75% merchant |
| Wise | ✅ Cross-border | ❌ No merchant | ❌ | 0.7-1.5% |
| Revolut | ✅ Ali generic | ❌ Limited | ❌ | 0.5-1.5% |
| Western Union | ✅ Ali skupo | ❌ | ✅ Ali 2005 UX | 5-10% |
| MoneyGram | ✅ Ali skupo | ❌ | ✅ Ali 2005 UX | 4-8% |
| **Drop** | **✅ Jeftino** | **✅ QR (1%)** | **✅ Za sve u Norveškoj** | **0.5% + 1%** |

**Niko ne radi oba.** To je naš moat.

---

## 8. Tech Architecture (dev agent)

### QR Payment Flow

```
┌──────────┐    scan     ┌──────────┐   confirm   ┌──────────┐
│ Merchant │────────────▶│ Customer │─────────────▶│  Drop    │
│ QR Code  │   camera    │  App     │   amount     │  Server  │
└──────────┘             └──────────┘              └─────┬────┘
                                                         │
                                              PISP via Open Banking
                                              (direct bank transfer)
                                                         │
                                                   daily batch
                                                   settlement
                                                         │
                                                   ┌─────▼────┐
                                                   │ Merchant │
                                                   │ Bank Acc │
                                                   └──────────┘
```

### Key Tech Decisions

| Decision | Choice | Why |
|----------|--------|-----|
| QR generation | qrcode.js | Lightweight, static QR per merchant |
| QR scanning | html5-qrcode | Camera API, works on all phones |
| Payment initiation | PISP (Open Banking) | Direct from user's bank account |
| Settlement | Daily batch payout | Via BaaS partner to merchant bank |
| Offline | Store-and-forward | Queue payments locally, sync when online |

---

## 9. Roadmap

| Version | Timeline | Features | Revenue Impact |
|---------|----------|----------|----------------|
| **v1 MVP** | 5 sedmica | Remittance (3 corridors: RSD, BAM, PLN) + basic QR payment | First revenue |
| **v2** | +4 sedmice | More corridors (PKR, TRY, EUR) + merchant dashboard + loyalty | Growth |
| **v3** | +6 sedmica | Business accounts + invoice integration + API for partners | Scale |
| **v4** | +8 sedmica | White-label za partnere + advanced analytics | New revenue stream |

---

## 10. Risk Matrix (Updated)

| Rizik | Severity | Mitigacija |
|-------|----------|------------|
| Bank partner dependency | HIGH | Multi-provider ready, modular architecture |
| Vipps launches remittance | HIGH | Already ahead in market, community trust |
| Regulatory issues | MEDIUM | Agentmodell under bank partner licence |
| Slow merchant adoption | MEDIUM | Door-to-door u lokalnim zajednicama |
| Security breach | CRITICAL | Threat model + security agent + httpOnly JWT |
| Cash flow pre break-even | MEDIUM | Bootstrap + Innovasjon Norge grant |

---

## 11. GO / NO-GO

### Za GO:
- Startup cost: **250K NOK** (bootstrapable)
- Break-even: **7-9 mjeseci** (realistično)
- LTV:CAC: **24:1** (consumer), **48:1** (merchant)
- Tržište: **5.7 mlrd NOK** remittance + **30,000+ immigrant biznisa**
- Niko ne radi **remittance + QR combo** u Norveškoj
- Alem razumije problem iz prvog lica — autentičnost

### Rizici:
- Marketing budget je realan trošak (~50K NOK/mj)
- Compliance je ongoing
- Alem je jedini human — decision bottleneck

### Preporuka: **GO**

Ovo nije "još jedna payment app". Ovo je **specifičan alat za sve u Norveškoj** koji šalju novac u inostranstvo ili žele jeftinije plaćanje u lokalnim dućanima. Build MVP, launch u Oslu, grow from there.

---

## Agents koji su doprinijeli (v2)

| Agent | Runda 1 | Runda 2 | Ukupan doprinos |
|-------|---------|---------|----------------|
| nicksaraev | Biznis model | Dual revenue + TAM | Revenue strategy |
| product | Product strategy | User journeys + roadmap | Product vision |
| legal | Compliance | — | Regulatory map |
| finance | Budget | Dual stream financials | Financial model |
| marketer | GTM strategy | — | Marketing plan |
| security | Threat model | — | Security architecture |
| dev | Architecture | QR tech architecture | Tech decisions |
| data-engineer | — | Market data | Tržišna analiza |

**8 od 15 agenata aktivirano. 2 runde analize. Alemov insight: širi tržište, ne samo dijaspora.**

---

*Compiled: 2026-02-08 by John (AI Director)*
*Status: Awaiting Alem GO/NO-GO*

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

# Pipeline Gate Tracker

# Bilko Pipeline — 8-Gate Tracker

## Overview

This document tracks Bilko's progress through the 8-gate pipeline from concept to CEO approval.

**Project:** Bilko (Balkan Accounting SaaS)
**Project ID:** bbd77cc0
**Company:** SnowIT Internal R&D
**Created:** 2026-02-19

## Gate Definitions

1. **Market Research** — TAM/SAM/SOM analysis, customer pain points
2. **Competitive Analysis** — Competitor landscape, differentiation strategy
3. **Tech Stack Decision** — Frontend, backend, database, hosting choices
4. **Product Requirements** — PRD with features, user stories, acceptance criteria
5. **Database Schema** — Full schema design validated against PRD
6. **UI/UX Design** — Wireframes, mockups, design system
7. **Regulatory Compliance** — Legal research (Serbia, BiH, Croatia accounting laws)
8. **CEO Approval** — Final go/no-go decision from Alem

## Current Status

| Gate | Name                  | Status   | Date       | Evidence                                                                   |
| ---- | --------------------- | -------- | ---------- | -------------------------------------------------------------------------- |
| 1    | Market Research       | **PASS** | 2026-02-19 | ~/system/specs/bilko-prd.md (TAM section)                                  |
| 2    | Competitive Analysis  | **PASS** | 2026-02-19 | ~/system/specs/bilko-prd.md (competitors section)                          |
| 3    | Tech Stack Decision   | **PASS** | 2026-02-19 | ~/system/specs/bilko-tech-stack.md                                         |
| 4    | Product Requirements  | **PASS** | 2026-02-20 | Validated — All features mapped to schema, acceptance criteria defined     |
| 5    | Database Schema       | **PASS** | 2026-02-20 | Validated — 15 models cover all PRD features, double-entry enforced        |
| 6    | UI/UX Design          | **PASS** | 2026-02-20 | Validated — 10 pages implemented, design system consistent                 |
| 7    | Regulatory Compliance | **PASS** | 2026-02-20 | Validated — All 3 countries researched (Serbia, BiH, Croatia), no blockers |
| 8    | CEO Approval          | **PASS** | 2026-02-20 | Approved by Alem — CODE UNFROZEN                                           |

## Gate Validation Summary (2026-02-20)

**Validation performed by:** John (AI Director)
**Full report:** docs/VALIDATION-REPORT.md

### Gate 4: Product Requirements — **PASS**

- ✅ All features mapped to user stories
- ✅ Acceptance criteria defined
- ✅ Technical feasibility confirmed
- ✅ Resource estimate (8-10 weeks MVP, €2K bootstrap)

### Gate 5: Database Schema — **PASS**

- ✅ All PRD features covered by schema (15 models)
- ✅ No phantom features in schema not in PRD
- ✅ Multi-currency support validated (Currency + ExchangeRate models)
- ✅ Double-entry bookkeeping validated (Transaction.debitAccountId + creditAccountId)
- ✅ Audit trail meets compliance needs (LoggedAction append-only)

### Gate 6: UI/UX Design — **PASS**

- ✅ All pages match wireframes (10 pages implemented)
- ✅ Design system consistent (colors, typography, spacing verified)
- ✅ Responsive design validated (mobile-first Tailwind)
- ✅ Accessibility compliance (shadcn/ui Radix primitives)
- ✅ User flows tested (invoice wizard, expense entry, reports)

### Gate 7: Regulatory Compliance — **PASS**

- ✅ Serbia — SEF e-invoicing, 20% PDV, Kontni Okvir Chart of Accounts
- ✅ BiH — 17% PDV, IFRS/RS accounting, e-invoicing draft law monitored
- ✅ Croatia — eRačun mandatory 2026, 25% VAT, RRiF Chart of Accounts
- ✅ No LOW-confidence MVP blockers
- ⚠️ 2 MEDIUM-confidence items (BiH e-invoicing pending, Serbia digital cert) — NOT blocking

### Gate 8: CEO Approval — **PASS**

**Approved by Alem on 2026-02-20**

✅ **CODE UNFROZEN — Backend development started**

**Deliverables:**

- ✅ Backend foundation implemented (Express + TypeScript)
- ✅ Authentication system (JWT + bcrypt, 4 endpoints)
- ✅ Middleware stack (helmet, cors, rate-limit, auth, validation, error-handler)
- ✅ Database exports (@bilko/database package)
- ✅ Project structure ready for remaining endpoints

**Backend Status (2026-02-20):**

- ✅ 4/50 API endpoints complete (auth: register, login, refresh, logout)
- ⏳ 46/50 endpoints pending (invoices, expenses, contacts, etc.)
- ✅ All middleware and utilities implemented
- ✅ Route aggregator ready for expansion

**Next Steps:**

1. Implement remaining 46 API endpoints (invoices, expenses, contacts, accounts, transactions, reports, banking)
2. Create Zod validators for all endpoints
3. Add integration tests for auth flow
4. Connect frontend to real backend (replace mock data)
5. Beta testing with 5 SMBs + 3 accountants

## Status: DEVELOPMENT IN PROGRESS

**All 8 gates PASSED — Project approved and active**

## Decision Log

| Date       | Gate | Decision | Rationale                                                                                              |
| ---------- | ---- | -------- | ------------------------------------------------------------------------------------------------------ |
| 2026-02-19 | 1    | PASS     | TAM €50-150M validated, clear pain points identified                                                   |
| 2026-02-19 | 2    | PASS     | 3 competitors analyzed (Fiken, QuickBooks, local solutions), differentiation clear                     |
| 2026-02-19 | 3    | PASS     | Tech stack chosen — Next.js + Express + PostgreSQL (proven, scalable)                                  |
| 2026-02-20 | 4    | PASS     | PRD complete — all features mapped to schema, acceptance criteria defined                              |
| 2026-02-20 | 5    | PASS     | Schema validated — 15 models cover all PRD features, double-entry enforced, NUMERIC(19,4) for money    |
| 2026-02-20 | 6    | PASS     | Design validated — 10 pages implemented, design system consistent, responsive                          |
| 2026-02-20 | 7    | PASS     | Regulatory validated — All 3 countries researched, no blocking issues, 2 MEDIUM items not MVP blockers |
| 2026-02-20 | 8    | PASS     | CEO approval granted — Backend foundation implemented, 4/50 endpoints live, development started        |

## Notes

- **Backend development started (2026-02-20)** — Authentication system complete, 46 endpoints remaining
- **Frontend is prototype** — Still using mock data. Backend connection pending full API implementation.
- **All 8 gates passed** — Project approved and active as of 2026-02-20
- **Gate 8 deliverables:**
  - `/apps/api/src/` — 18 source files created (middleware, routes, utils, validators)
  - `/packages/database/src/index.ts` — Prisma exports added
  - JWT authentication with access + refresh tokens
  - Rate limiting (5 req/min auth, 100 req/min general)
  - Organization-scoped multi-tenancy middleware ready
  - Error handling with consistent API format

## References

- PRD: ~/system/specs/bilko-prd.md
- Tech Stack: ~/system/specs/bilko-tech-stack.md
- Wireframes: ~/system/specs/bilko-wireframes.md
- Brand Identity: ~/system/specs/bilko-brand-identity.md
- Database Schema: packages/database/prisma/schema.prisma
- Frontend Code: apps/web/