Bitkaya Compliance Management System (BCMS)

Technical Implementation Memorandum

Date: 2026-07-28 From: Operations Classification: Internal Audience: Technical Staff, Operations, Compliance

Purpose

This memorandum describes the technical architecture and implementation of Bitkaya’s Compliance Management System (“BCMS”). It is intended for staff who need to understand how the system is built, how data flows through it, and how artifacts are produced — without going into code-level detail.

System Overview

The BCMS is a file-based compliance management system built on structured markdown notes. Each compliance object — a policy, procedure, control, requirement, issue, or change request — is a standalone markdown file with standardized YAML frontmatter (machine-readable metadata) and a human-readable body. The files are organized in a numbered folder structure and version-controlled through Git, providing full history, branching, and traceability.

The system does not rely on a database, a web server, or a proprietary application. It can be read and edited in any text editor or note-taking application, while the structured frontmatter enables automation, validation, and artifact generation.

Architecture

Data Model

Every BCMS object follows the same pattern:

┌─────────────────────────────────────────┐
│  YAML Frontmatter (machine-readable)    │
│  - id: POL-AML-001                      │
│  - type: policy                         │
│  - status: implemented                  │
│  - relationships: procedures, controls  │
│  - approval: who, when, next review     │
├─────────────────────────────────────────┤
│  Markdown Body (human-readable)         │
│  - Purpose, scope, policy statement     │
│  - Full content from approved manual    │
│  - Implementing procedures and controls │
│  - Relationships, assurance, history     │
└─────────────────────────────────────────┘

The frontmatter is the backbone of the system. It contains:

Identity fields: id, type, title, status, classification, criticality
Ownership fields: business_owner, technical_owner, approver, reviewed_by, approved_by
Relationship arrays: sources, requirements, policies, processes, procedures, controls, systems, issues, publications, decisions
Lifecycle fields: created, approved, effective, last_reviewed, next_review, retired, implementation_state
Patterns: descriptive tags for categorization and search

The body contains the actual content — policy text, step-by-step procedures, control testing methods, impact assessments — formatted as readable markdown with headings, bullet lists, tables, and wikilinks ([[Note Name]]) that connect related objects.

Folder Structure

00 Governance         Constitutions, standards, ADRs, specifications
01 Sources            Regulatory sources (laws, guidelines, standards)
02 Requirements       Regulatory requirements decomposed from sources
03 Processes          High-level business process descriptions
04 Policies           Approved compliance manuals (21 domains)
05 Procedures         Step-by-step operational procedures (131 notes)
06 Controls           Control descriptions and testing methods (158 notes)
07 Systems            Systems and tools inventory
08.1 Change Requests  Formal change proposals with approval workflow
08.2 Issues           Open issues, gaps, and conflicts
09 Publications       Generated artifacts and approved PDFs
10 Review Packs       Periodic review packages
11 Dashboards         Monitoring and overview views
12 Glossary           Terms and definitions
90 Templates          Object templates for new notes
91 Scripts            Automation and generation scripts
99 Archive           Retired and superseded objects

Object Types and ID Convention

Each object type uses a prefix-based ID scheme:

Type	ID Pattern	Count	Example
Source	SRC-XXX-001	7	SRC-VASP-001
Requirement	REQ-XXX-001	68	REQ-FATF-004
Process	PRC-XXX-001	6	PRC-FCI-001
Policy	POL-XXX-001	21	POL-AML-001
Procedure	PROC-XXX-001	131	PROC-AML-002
Control	CTRL-XXX-001	158	CTRL-AML-002
System	SYS-XXX-001	7	SYS-ECM-001
Change Request	CHG-XXX-001	—	CHG-AML-001
Issue	ISS-XXX-001	14	ISS-AML-001
Publication	PUB-XXX-001	15	PUB-ECM-001

The middle segment (XXX) identifies the compliance domain (e.g., AML, ABC, ECM, OUT, KYC), enabling quick visual grouping and automated domain-based queries.

Version Control and Change Management

Git-Based Workflow

The entire vault is a Git repository hosted on GitHub (private). This provides:

Full history: every change is a commit with author, date, and message
Branching: changes are developed on feature branches before merging
Pull requests: human review before changes reach the authoritative branch
Diffing: any two versions of a document can be compared line by line
Audit trail: the commit log serves as an immutable record of who changed what and when

Change Request Workflow

Content changes to the vault follow a controlled workflow:

Change Request (CHG-XXX-001)
    │
    ├─ status: open          → Request created
    ├─ branch: chg/XXX-001   → Developer creates a branch
    ├─ status: review        → Changes implemented, awaiting review
    ├─ status: approved      → Human reviewer approves
    ├─ status: merged        → Branch merged to main
    ├─ implementation_status: staged    → In vault, not yet published
    ├─ implementation_status: published  → PDF artifact generated
    └─ status: closed        → Fully resolved

Key design principle: merging to main and publishing a new artifact are separate steps. A change can sit staged in the vault while multiple changes accumulate. The vault owner manually triggers artifact generation when ready, ensuring that published versions are deliberate, not accidental.

Relationship to Issues

Issues (08.2 Issues/) identify problems or gaps. When an issue’s resolution requires modifying policies, procedures, or controls, a change request is created and linked:

The issue’s frontmatter includes a change_requests: [] array listing the CHG objects that resolve it
The change request’s frontmatter includes a source_issue: field pointing back to the originating issue
This bidirectional link enables full traceability from problem identification through resolution

Artifact Generation

Pipeline

Approved PDF manuals are generated from the structured markdown content through an automated pipeline:

Markdown notes (vault)
    │
    ├─ Policy note (04 Policies/POL-XXX-001.md)     → full manual content
    ├─ Procedure notes (05 Procedures/PROC-XXX-*.md) → steps tables
    ├─ Control notes (06 Controls/CTRL-XXX-*.md)    → objectives, testing
    │
    ▼
Assembly (script reads all related notes)
    │
    ├─ Cover page (from POLICY_REGISTRY metadata)
    ├─ Table of contents (auto-generated from headings)
    ├─ Body content (from policy note)
    ├─ Procedures table (from procedure notes)
    ├─ Controls table (from control notes)
    ├─ Cross-references (from frontmatter relationship arrays)
    └─ Appendices (change history, cross-reference register)
    │
    ▼
Markdown assembly → HTML conversion (pandoc)
    │
    ▼
HTML + Brand CSS → PDF rendering (weasyprint)
    │
    ▼
Branded PDF artifact (09 Publications/Generated/)

Branding

Generated PDFs apply a consistent visual identity:

Cover page: Split-panel design with logo, title in light weight, metadata grid on a dark panel
Typography: Poppins font family in multiple weights (ExtraLight for titles, SemiBold for headings, Regular for body)
Color system: Brand colors applied as accents — cyan for section markers, coral for heading underlines, charcoal for footers and table headers
Page headers/footers: Three-column footer with document ID + version, page number, and company name
Tables: Minimal styling with subtle horizontal lines, alternating row tints, and no heavy borders
Callout boxes: Cyan-tinted blocks with a left accent bar for important statements

Reproducibility

Each generated PDF includes a source reference (Git commit hash) on the cover page, meaning any artifact can be traced back to the exact state of the vault when it was generated. Regenerating from the same commit produces a byte-identical artifact.

Cross-Referencing and Traceability

Wikilinks

Objects are connected through Obsidian-style wikilinks ([[Note Name]]). These links enable:

Navigation between related objects (e.g., from a policy to its implementing procedures)
Visual graph views of the compliance framework
Automated detection of broken or orphaned references

Frontmatter Relationship Arrays

In addition to wikilinks in the body text, each object’s frontmatter contains structured relationship arrays:

sources:
  - SRC-VASP-001
requirements:
  - REQ-FATF-004
policies:
  - POL-AML-001
procedures:
  - PROC-AML-002
controls:
  - CTRL-AML-002

These arrays enable automated validation:

Verify that every ID referenced in a frontmatter array corresponds to an existing file
Detect orphaned objects (procedures not referenced by any policy)
Generate cross-reference registers for artifacts
Map the full compliance graph from regulation to control

Validation

A validation script checks the integrity of the vault:

Frontmatter completeness and consistency across object types
Wikilink integrity (no broken references)
Cross-reference consistency (bidirectional links match)
Content coverage (policy word count vs. source PDF word count)
Orphan detection (objects not referenced by any parent)
Encoding issues (no corruption artifacts)

Automation

Script Inventory

The system includes several automation scripts:

Script	Purpose
`generate_premium_pdf.py`	Generate branded PDF artifacts from vault content
`validate_bcms.py`	Validate frontmatter, wikilinks, and cross-references
`extract_all_pdfs.py`	Extract text from existing PDF artifacts for comparison
`compare_policies.py`	Compare policy word counts against PDF artifacts
`compare_proc_ctrl.py`	Compare procedure/control coverage against PDFs

The PDF generator is parameterized — it can generate a single manual by policy ID, all 21 manuals in one run, or list available policies.

PDF Generation

# List available manuals
python generate_premium_pdf.py --list
 
# Generate a single manual
python generate_premium_pdf.py POL-AML-001
 
# Generate all 21 manuals
python generate_premium_pdf.py --all

Output is saved to 09 Publications/Generated/ with preview images of the first 6 pages.

Security and Access

Repository Access

The vault is stored in a private GitHub repository. Access is controlled through:

Deploy keys: SSH key-based access for the cloud instance
Branch protection: Changes require review before merging to main
Change request workflow: No content changes reach main without approval

Data Classification

Every BCMS object carries a classification field:

Classification	Meaning
`public`	May be shared externally
`internal`	Internal use only
`confidential`	Restricted to authorized personnel

Generated artifacts inherit the classification of their source policy.

Scalability

The system is designed to scale with Bitkaya’s growth:

New domains: Adding a new compliance domain (e.g., insurance, lending) requires creating a policy, procedures, and controls following the existing template patterns
New object types: The template-based architecture allows adding new object types without restructuring the system
Team growth: Multiple contributors can work on different branches simultaneously, with changes merged through the review workflow
Regulatory changes: The change request system handles regulatory updates with the same governance as internal improvements
Artifact volume: The PDF generator can produce all 21 manuals in a single run, and the parameterized design supports future additions

Maintenance

Routine Tasks

Task	Frequency	Owner
Vault validation (wikilinks, frontmatter, cross-refs)	Monthly	Operations
Policy review cycle	Annual per policy	Compliance
Control testing	Per risk tier	Compliance
Issue review and closure	Monthly	Compliance
Artifact regeneration	On demand, after approved changes	Operations
Backup verification	Monthly	Operations

Disaster Recovery

The vault is replicated across:

GitHub (primary remote) — full history, all branches
Cloud instance (working copy) — live copy for generation and automation
Local machines (developer copies) — via git pull

Any copy can restore the full vault including complete history.

Summary

The BCMS is a lightweight but rigorous compliance management system built on structured text files, version control, and automated artifact generation. It provides full traceability from regulatory sources through to approved PDF manuals, with a controlled change workflow that ensures every modification is deliberate and auditable. The system is designed to be maintained by compliance and operations staff without specialized software — only standard text editing and a Git client are required.

For technical questions about the BCMS implementation, contact Operations. For questions about compliance content, policies, or controls, contact Compliance.

Bitkaya B.V. · Julianaplein 36, Willemstad, Curaçao · Dutch Caribbean · www.bitkaya.io

BCMS

Explorer

BCMS Technical Implementation Memorandum