# Requirements Traceability Matrix (RTM)

# Requirements Traceability Matrix (RTM): Bilko

> **Project:** Bilko — Balkan Accounting SaaS
> **Version:** 0.1
> **Date:** 2026-02-23
> **Author:** John (AI Director)
> **Status:** Draft
> **Reviewers:** Alem Bašić (CEO)

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | 2026-02-23 | John (AI Director) | Initial draft — Phase 1 Serbia MVP |

---

## 1. Purpose of Traceability

The Requirements Traceability Matrix serves four functions for Bilko:

1. **Coverage Assurance** — Every business requirement (BR) has an implementation path (FR, US) and test cases (AC, TC)
2. **Change Impact** — When a regulatory requirement changes (e.g., SEF API update), quickly identify all affected code and tests
3. **Gap Detection** — Identify FRs with no tests (coverage gap) or tests with no requirement (potential scope creep)
4. **Compliance Audit** — Demonstrates to auditors that SEF, PDV, and accounting law requirements are implemented and verified

**Traceability Directions:**
- **Forward Traceability** — BR → FR → Code → Test (did we build what was required by law and stakeholders?)
- **Backward Traceability** — Test → Code → FR → BR (does everything we built have a legal or business justification?)

---

## 2. Document References

| Document | Location | Version | Last Updated |
|----------|----------|---------|-------------|
| Business Requirements Document (BRD) | [`BRD.md`](BRD.md) | 0.1 | 2026-02-23 |
| Functional Requirements Spec (FRS) | [`FUNCTIONAL-REQUIREMENTS.md`](FUNCTIONAL-REQUIREMENTS.md) | 0.1 | 2026-02-23 |
| Non-Functional Requirements | [`NON-FUNCTIONAL-REQUIREMENTS.md`](NON-FUNCTIONAL-REQUIREMENTS.md) | 0.1 | 2026-02-23 |
| User Stories | [`USER-STORIES.md`](USER-STORIES.md) | 0.1 | 2026-02-23 |
| Acceptance Criteria | [`ACCEPTANCE-CRITERIA.md`](ACCEPTANCE-CRITERIA.md) | 0.1 | 2026-02-23 |
| Risk Register | [`../governance/RISK-REGISTER.md`](../governance/RISK-REGISTER.md) | 0.1 | 2026-02-23 |
| Test Plan | [`../TEST-PLAN.md`](../TEST-PLAN.md) | 0.1 | 2026-02-23 |
| Database Schema | [`../../packages/database/prisma/schema.prisma`](../../packages/database/prisma/schema.prisma) | Current | 2026-02-20 |

---

## 3. Forward Traceability Matrix

### 3.1 Functional Requirements Traceability

| BR ID | Business Requirement | FR ID | Functional Requirement | US ID | DB Model | Code Module | Unit Test | Integration Test | AC ID | Status |
|-------|---------------------|-------|----------------------|-------|----------|-------------|-----------|-----------------|-------|--------|
| BR-001 | SEF e-invoice submission | FR-010 | Create Invoice | US-010 | Invoice, InvoiceItem | `apps/api/src/routes/invoices.ts` | ❌ | ❌ | AC-030 | ❌ Not Started |
| BR-001 | SEF e-invoice submission | FR-011 | SEF Submission | US-011 | Invoice (sef_status, sef_id) | `apps/api/src/services/sef.service.ts` | ❌ | ❌ | AC-050 | ❌ Not Started |
| BR-001 | SEF e-invoice submission | FR-012 | Invoice Status Tracking | US-012 | Invoice (status) | `apps/api/src/routes/invoices.ts` | ❌ | ❌ | AC-060 | ❌ Not Started |
| BR-002 | PDV auto-calculation | FR-010 | Create Invoice (PDV) | US-010 | InvoiceItem (vat_amount) | `apps/api/src/services/tax.service.ts` | ❌ | ❌ | AC-030, AC-038 | ❌ Not Started |
| BR-002 | PDV auto-calculation | FR-050 | PDV Report | US-050 | Invoice, Expense | `apps/api/src/routes/reports.ts` | ❌ | ❌ | AC-080, AC-083 | ❌ Not Started |
| BR-003 | Double-entry bookkeeping | FR-031 | Transaction Recording | US-031 | Transaction | `apps/api/src/services/accounting.service.ts` | ❌ | ❌ | NF-AC-030 | ❌ Not Started |
| BR-004 | Multi-currency | FR-070 | Exchange Rate Management | US-070 | Currency, ExchangeRate | `apps/api/src/services/currency.service.ts` | ❌ | ❌ | AC-032, NF-AC-032 | ❌ Not Started |
| BR-005 | Bank statement import | FR-040 | CSV Import | US-040 | BankTransaction | `apps/api/src/routes/banking.ts` | ❌ | ❌ | AC-070 (extended) | ❌ Not Started |
| BR-006 | Financial reports | FR-060 | P&L Statement | US-060 | Transaction, Account | `apps/api/src/routes/reports.ts` | ❌ | ❌ | — | ❌ Not Started |
| BR-006 | Financial reports | FR-061 | Balance Sheet | US-061 | Transaction, Account | `apps/api/src/routes/reports.ts` | ❌ | ❌ | NF-AC-030 | ❌ Not Started |
| BR-007 | Multi-user RBAC | FR-003 | Invite User | US-003, US-004 | User, Organization (RBAC) | `apps/api/src/middleware/auth.ts` | ❌ | ❌ | AC-001 (ext) | ❌ Not Started |
| BR-008 | PDF invoice + email | FR-010 | Invoice PDF delivery | US-010 | Invoice | `apps/api/src/services/email.service.ts` | ❌ | ❌ | INT-004 | ❌ Not Started |
| BR-009 | Expense tracking | FR-020 | Create Expense | US-020 | Expense | `apps/api/src/routes/expenses.ts` | ❌ | ❌ | AC-070 | ❌ Not Started |
| BR-010 | Chart of Accounts | FR-030 | Chart of Accounts | US-030 | Account, AccountType | `apps/api/src/services/accounts.service.ts` | ❌ | ❌ | AC-003, AC-039 | ❌ Not Started |
| BR-011 | Serbian language | N/A | i18n / l10n (frontend) | N/A | N/A | `apps/web/lib/i18n/` | ❌ | ❌ | — | ❌ Not Started |
| BR-012 | Immutable audit trail | FR-031 | LoggedAction (all mutations) | US-031 | LoggedAction | `apps/api/src/middleware/audit.ts` | ❌ | ❌ | — | ❌ Not Started |
| BR-013 | Data export (GDPR) | N/A | Export API endpoint | N/A | All models | `apps/api/src/routes/export.ts` | ❌ | ❌ | — | ❌ Not Started |
| BR-014 | Secure multi-tenancy | FR-001, FR-002 | Auth (register/login) | US-001, US-002 | User, Organization | `apps/api/src/routes/auth.ts` | ✅ | ✅ | AC-001, AC-020 | ✅ Complete |

> Note: BR-014 Auth endpoints are the only complete items — 4/50 auth endpoints built (2026-02-20).

### 3.2 Non-Functional Requirements Traceability

| NFR ID | Requirement | Target | Test Type | Test Case ID | Status |
|--------|------------|--------|-----------|-------------|--------|
| NFR-P01 | Dashboard load < 3s initial | < 3s (4G) | Performance | PERF-001 | ❌ Not Started |
| NFR-P02 | Dashboard < 1s subsequent | < 1s warm cache | Performance | PERF-002 | ❌ Not Started |
| NFR-P04 | API response < 300ms | p95 < 300ms | Performance | PERF-003 | ❌ Not Started |
| NFR-SEC01 | JWT authentication | 15min access + 30d refresh | Security | SEC-001 | ✅ Complete (auth built) |
| NFR-SEC06 | Input validation (Zod) | All inputs validated server-side | Security / SAST | SEC-010 | ⏳ In Progress |
| NFR-SEC10 | Org data isolation | No cross-tenant access | Security | SEC-020 | ⏳ In Progress (middleware built) |
| NFR-R02 | ACID compliance | 100% ACID transactions | Database | DB-001 | ⏳ In Progress (PostgreSQL + Prisma) |
| NFR-R03 | Double-entry balance | Debit = Credit always | Database / CI | DB-002 | ❌ Not Started |
| NFR-D01 | NUMERIC(19,4) monetary | No float for money | Database | DB-010 | ✅ Complete (schema enforced) |
| NFR-COMP01 | SEF e-invoicing compliance | 100% UBL 2.1 | Compliance | COMP-001 | ❌ Not Started |
| NFR-COMP02 | PDV compliance | Correct PDV rates | Compliance | COMP-002 | ❌ Not Started |
| NFR-COMP04 | GDPR compliance | Right to deletion; export | Compliance | COMP-010 | ❌ Not Started |
| NFR-U03 | WCAG 2.1 AA | Level AA | Accessibility | A11Y-001 | ❌ Not Started |
| NFR-A01 | Uptime ≥ 99.9% | 99.9% monthly | Operations | OPS-001 | N/A (pre-launch) |

---

## 4. Backward Traceability Matrix

| Test Case ID | Test Description | AC ID | FR ID | BR ID | Has Requirement? |
|-------------|-----------------|-------|-------|-------|-----------------|
| TC-AUTH-001 | User registration flow | AC-001 | FR-001 | BR-014 | ✅ Yes |
| TC-AUTH-002 | Login with JWT | AC-020 | FR-002 | BR-014 | ✅ Yes |
| TC-AUTH-003 | Token refresh | AC-021 | FR-002 | BR-014 | ✅ Yes |
| TC-AUTH-004 | Account lockout (5 attempts) | AC-024 | FR-002 | BR-014 | ✅ Yes |
| TC-INV-001 | Invoice PDV 20% calculation | AC-030 | FR-010 | BR-002 | ✅ Yes |
| TC-INV-002 | Invoice PDV 10% calculation | AC-031 | FR-010 | BR-002 | ✅ Yes |
| TC-INV-003 | NUMERIC precision (no float) | AC-040, NF-AC-031 | FR-010 | BR-002 | ✅ Yes |
| TC-SEF-001 | SEF UBL 2.1 submission | AC-050 | FR-011 | BR-001 | ✅ Yes |
| TC-SEF-002 | SEF rejection handling | AC-052 | FR-011 | BR-001 | ✅ Yes |
| TC-SEF-003 | SEF unavailable — queue | AC-053 | FR-011 | BR-001 | ✅ Yes |
| TC-ACC-001 | Debit = Credit balance check | NF-AC-030 | FR-031 | BR-003 | ✅ Yes |
| TC-ACC-002 | Exchange rate immutability | NF-AC-032 | FR-070 | BR-004 | ✅ Yes |
| TC-PDV-001 | Monthly PDV report accuracy | AC-080, AC-083 | FR-050 | BR-002, BR-006 | ✅ Yes |
| TC-SEC-001 | Cross-tenant data isolation | NF-AC-020 | N/A | BR-014 | ✅ Yes |

---

## 5. Coverage Analysis

### 5.1 Requirement Coverage Summary

| Category | Total Count | Fully Covered | Partially Covered | Not Covered | Coverage % |
|----------|-------------|--------------|-------------------|-------------|-----------|
| Business Requirements (BR) | 14 | 1 (BR-014 auth) | 3 (schema, middleware) | 10 | 7% |
| Functional Requirements (FR) | 14 | 2 (FR-001, FR-002) | 2 (FR-003, FR-030) | 10 | 14% |
| Non-Functional Requirements (NFR) | 30 | 5 | 4 | 21 | 17% |
| User Stories (US) | 15 | 2 (US-001, US-002) | 0 | 13 | 13% |
| Acceptance Criteria (AC) | 40+ | 0 (all Draft) | 0 | 40 | 0% |

**Overall Requirement Coverage:** ~7% (project in early development phase — backend 4/50 endpoints complete)
**Target:** ≥ 95% before UAT (estimated Sprint 4); 100% before production release

> This is expected at current stage. Backend foundation complete (auth, middleware, DB schema). 46 API endpoints remaining.

### 5.2 Test Coverage Summary

| Test Type | Total Tests | Passing | Failing | Skipped | Coverage |
|-----------|------------|---------|---------|---------|----------|
| Unit tests | 0 (not yet written) | 0 | 0 | 0 | 0% |
| Integration tests | 4 (auth endpoints) | 4 | 0 | 0 | auth only |
| E2E / UAT scenarios | 0 | 0 | 0 | 0 | 0% |
| Performance tests | 0 | — | — | — | 0% |
| Security tests | 0 | — | — | — | 0% |

> Test coverage target: ≥ 80% overall, ≥ 95% for financial logic (double-entry, PDV, SEF) before launch.

---

## 6. Gap Identification

### 6.1 Requirements Without Test Coverage (All Phase 1 Non-Auth)

| Requirement ID | Description | Gap Type | Action Required | Owner | Target Date |
|---------------|-------------|----------|----------------|-------|-------------|
| BR-001 | SEF e-invoicing | No tests for SEF integration | Create TC-SEF-001 through TC-SEF-003 | John | 2026-03-21 (SEF integration sprint) |
| BR-002 | PDV calculation | No tests for PDV accuracy | Create TC-INV-001 through TC-INV-003; verify against Zakon o PDV | John | 2026-03-14 |
| BR-003 | Double-entry | No tests for accounting balance | Create TC-ACC-001; CI balance check | John | 2026-03-07 |
| FR-050 | PDV Report | No implementation yet | Build + test in Sprint 3 | builder agent | 2026-03-21 |
| FR-060 | P&L Statement | No implementation yet | Build + test in Sprint 3 | builder agent | 2026-03-21 |
| NFR-D01 | NUMERIC precision | Schema enforced but no test | Add TC-INV-003 decimal precision test | John | 2026-03-07 |

### 6.2 Test Cases Without Requirements (Orphans)

| Test Case ID | Description | Status | Action |
|-------------|-------------|--------|--------|
| — | No orphaned tests at this stage | N/A | N/A |

### 6.3 Requirements Without Design Reference

| Requirement ID | Description | Action |
|---------------|-------------|--------|
| FR-011 | SEF Submission UI (status display) | Existing invoice detail page — update to show SEF status field |
| FR-040 | Bank CSV Import UI | New page `/banking` — existing placeholder page needs implementation |
| FR-050 | PDV Report page | Existing `/reports/vat` placeholder — needs full implementation |

---

## 7. Change Impact Tracking

| Change Request ID | Changed Requirement | Impact on FR | Impact on Code | Impact on Tests | Impact Assessment | CR Status |
|-----------------|--------------------|--------------|--------------|-----------------|--------------------|-----------|
| — | No change requests at this stage | — | — | — | — | — |

**Key anticipated change risk:**
If SEF API changes (Risk R-001 in risk register), the following would need updating:
- FR-011 (SEF submission logic)
- `apps/api/src/services/sef.service.ts`
- TC-SEF-001, TC-SEF-002, TC-SEF-003
- UBL 2.1 XML generation templates
- AC-050, AC-052, AC-054

---

## 8. Traceability Status Dashboard

**Last Updated:** 2026-02-23
**Updated By:** John (AI Director)

| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| Total Business Requirements | 14 | — | |
| BRs with FR coverage | 14 / 14 | 100% | ✅ All mapped |
| FRs with test coverage | 2 / 14 | 100% | ❌ In progress |
| Test cases passing | 4 / 4 (auth only) | 100% | ✅ (auth only) |
| Open gaps | 11 FRs untested | 0 at launch | ❌ Expected at this stage |
| Change requests open | 0 | ≤ 3 at a time | ✅ |
| UAT sign-off pending | 0 (pre-launch) | 0 at launch | N/A |

**Overall RTM Health:** AMBER — Expected for current development phase. All requirements defined and mapped to code modules. Test coverage to be built alongside each feature in Sprints 2-4.

---

## Approval

| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | John (AI Director) | 2026-02-23 | |
| Reviewer | | | |
| Business Analyst | John | 2026-02-23 | |
| QA Engineer | validator agent | | |
| Tech Lead | John | 2026-02-23 | |
| AI Director (John) | John | 2026-02-23 | |