Skip to content

README.md

Latest commit

 

History

History
238 lines (189 loc) · 9.92 KB

README.md

File metadata and controls

238 lines (189 loc) · 9.92 KB

Kovra Documentation

This directory contains all technical documentation for the Kovra B2B cross-border payment platform.

Documentation Philosophy

Orthogonal Thinking + Unix Philosophy:

  • Modularity: Each document focuses on one concern
  • Independence: Documents can be updated independently
  • Composition: Cross-references link related concepts
  • Clarity: No god documents; each has a single responsibility

Quick Start

New to Kovra? Start here:

  1. 00_OVERVIEW.md - Project vision, target market, quick links
  2. 01_ARCHITECTURE.md - High-level system design

Looking for specific info?

Folder Structure

docs/
├── 00_OVERVIEW.md                          # Central index
├── 01_ARCHITECTURE.md                      # High-level system design
├── 02_COMPONENTS.md                        # State machines, ledger, services
├── 03_COMPLIANCE.md                        # KYC/AML: 90% OxCaml + 10% Python ⭐
├── 04_DEPLOYMENT.md                        # Infrastructure, observability
├── README.md                               # This file
├── INTEGRATION.md                          # External adapters
├── SECURITY.md                             # Auth, encryption
├── TIMELINE.md                             # Roadmap
├── account/                                # Account-specific docs
│   └── FBO_NASTRO.md                       # FBO/Nostro structures
├── archive/                                # Legacy docs
│   ├── ARCHITECTURE.md.legacy              # Old god document (820 lines)
│   ├── ARCHITECTURE_REFACTOR_ANALYSIS.md   # Refactor analysis
│   └── DATABASE.md.legacy                  # Old god database doc (1015 lines)
├── compliance/                             # KYC/AML documentation (consolidated)
│   ├── README.md                           # Navigation guide
│   └── archive/                            # Old compliance docs (reference only)
├── database/                               # Database schemas (orthogonal)
│   ├── README.md                           # DB overview
│   ├── CORE.md                             # Payment tables
│   ├── COMPLIANCE.md                       # KYC/AML tables
│   ├── LEDGER.md                           # TigerBeetle schema
│   └── OPERATIONS.md                       # Jobs, config, cache
├── fix/                                    # Design fixes
│   ├── 001-fx-transfer-chain-redesign.md
│   └── 002-why-atomic-settlement-doesnt-fit-fx.md
└── explanation/                            # Technical decisions
    └── why-uint128-to-uint64.md

Document Index

Core Architecture (Start Here)

Document Purpose Lines
00_OVERVIEW.md Central index, quick navigation ~100
01_ARCHITECTURE.md High-level system design, service topology ~200
02_COMPONENTS.md State machines, ledger, detailed service specs ~400

Domain-Specific

Document Purpose Lines
03_COMPLIANCE.md KYC/AML Compliance: 90% OxCaml + 10% Python ⭐ ~1200
04_DEPLOYMENT.md Infrastructure, observability, operations ~400

Compliance Archive

Document Purpose Status
compliance/archive/03_COMPLIANCE_LEGACY.md Legacy Python/Mojo compliance Archived
compliance/archive/03A_COMPLIANCE_TECH_STACK.md Initial OxCaml proposal Superseded
compliance/archive/ROADMAP_OXCAMl.md 24-month roadmap Merged into 03_COMPLIANCE
compliance/archive/INTEGRATION_GUIDE.md Integration guide Merged into 03_COMPLIANCE

Technical Specifications

Document Purpose
INTEGRATION.md BI-FAST, SEPA, FPS adapter specifications
SECURITY.md Authentication, encryption, audit
TIMELINE.md Development roadmap

Database Schemas (Orthogonal)

Document Purpose Lines
database/README.md Database overview & principles ~200
database/CORE.md Payment domain tables ~400
database/COMPLIANCE.md KYC/AML tables ~500
database/LEDGER.md TigerBeetle schema ~300
database/OPERATIONS.md Jobs, config, cache ~300

Implementation Details

Document Purpose
account/FBO_NASTRO.md Account structure details
archive/ARCHITECTURE_REFACTOR_ANALYSIS.md Why we split the docs

Fixes & Explanations

Document Purpose
fix/001-fx-transfer-chain-redesign.md FX implementation redesign
fix/002-why-atomic-settlement-doesnt-fit-fx.md Settlement design rationale
explanation/why-uint128-to-uint64.md Technical decision

Document Dependencies

00_OVERVIEW.md (no deps)
    │
    ├─► 01_ARCHITECTURE.md
    │       └─► 02_COMPONENTS.md
    │
    ├─► 03_COMPLIANCE.md (orthogonal - no deps)
    │
    ├─► 04_DEPLOYMENT.md
    │       └─► References all above
    │
    └─► INTEGRATION.md

Key Principle: No circular dependencies. Lower-numbered docs don't reference higher-numbered docs.

Orthogonal Domains

Payment Core (01_ARCHITECTURE.md, 02_COMPONENTS.md):

  • Money movement
  • FX conversion
  • Wallet management
  • State machines

Compliance Core (03_COMPLIANCE.md):

  • KYC/AML screening
  • Risk scoring
  • Audit trail
  • Regulatory reporting

Infrastructure (04_DEPLOYMENT.md):

  • Deployment
  • Monitoring
  • Backup/recovery
  • Security

These domains communicate via events, not direct coupling. Each can evolve independently.

Independence Principle

Kovra works 100% standalone (no external API dependencies):

  • Core functionality doesn't require third-party services
  • External integrations are optional enhancements
  • Can run air-gapped in standalone mode

See 03_COMPLIANCE.md section 0 for details.

Document Maintenance

Adding New Content

  1. Choose the right document: Follow single responsibility principle
  2. Add cross-references: Link to related docs
  3. Update this README: If adding new document types
  4. Keep docs orthogonal: Don't duplicate content

Updating Existing Content

  1. One concern per change: Don't mix compliance and deployment updates
  2. Update cross-references: Check if other docs need updating
  3. Maintain independence: Ensure orthogonal domains stay decoupled

Legacy Documents

Old, superseded documents are archived in:

  • archive/ - Previous versions, refactor analysis

Style Guide

Document Headers

# Title

One-line description.

For related info, see [OTHER_DOC.md](OTHER_DOC.md).

---

## Section 1

Cross-References

  • Use relative links: [doc](doc.md)
  • Add "See also" sections at end of major sections
  • Include "Prev/Next" navigation at document end

Code Blocks

  • Use fenced blocks with language tags
  • Include comments for complex logic
  • Show interface contracts for orthogonal boundaries

Diagrams

  • Use ASCII art for simple diagrams
  • Use Mermaid for complex sequences
  • Include text explanation alongside diagrams

Version History

Date Change
2026-02-17 SIMPLIFIED - Consolidated to single 03_COMPLIANCE.md (90% OxCaml + 10% Python), removed 03_COMPLIANCE_HYBRID.md
2026-02-17 ARCHIVED - Moved old compliance docs to compliance/archive/ (03_COMPLIANCE_LEGACY.md, 03A_COMPLIANCE_TECH_STACK.md, dll)
2026-02-17 NEW TECH STACK - Added OxCaml KYC/AML proposal (03A_COMPLIANCE_TECH_STACK.md)
2026-02-17 NEW FOLDER - Created compliance/ for KYC/AML-specific documentation
2026-02-17 NEW ROADMAP - Added ROADMAP_OXCAMl.md (24-month implementation plan)
2026-02-15 MAJOR REFACTOR - Split ARCHITECTURE.md into 5 focused docs (00-04)
2026-02-15 MAJOR REFACTOR - Split DATABASE.md (1015 lines) into 4 orthogonal schema docs
2026-02-15 Renamed COMPLIANCE.md → 03_COMPLIANCE.md for consistency
2026-02-15 Moved FBO_NASTRO_ACCOUNT.md → account/FBO_NASTRO.md
2026-02-15 Added comprehensive NOTES to INTEGRATION.md
2026-02-15 Added independence guarantee section to 03_COMPLIANCE.md
2026-02-15 Created orthogonal architecture documentation
2026-02-15 Established folder structure (account/, archive/, database/, fix/, explanation/)

Questions?

Last Updated: 2026-02-17 (Simplified: single 03_COMPLIANCE.md dengan Hybrid 90/10 approach)