MAVULA Finance Platform

Infrastructure for the next generation of finance.

MAVULA is a configurable financial infrastructure platform for institutions that need ledger, lending, payments, workflow automation and operational controls behind explicit contracts.

Primary domain: mavula.io

Developer and open source domain: mavula.dev

Repository Model

This repository is the main MAVULA engineering workspace. It uses professional module names and keeps brand ownership separate from code licensing.

finance-platform/
├── contracts/                 Versioned cross-module domain contracts
├── docs/architecture/          Context map, invariants and ADRs
├── packages/
│   ├── ledger-core/            Financial source of truth
│   ├── identity-access/        Institutional identity and authorization server
│   ├── workbench/              Durable worker runtime and status API
│   ├── settlements/            Payment process and reconciliation foundation
│   ├── developer-docs/         Public integration guides and API reference
│   ├── legacy-connectors/      COBOL and fixed-width interoperability contracts
│   └── operations/             Docker, Kubernetes, Terraform and runbooks
├── LICENSE_POLICY.md           Open core policy
├── TRADEMARKS.md               MAVULA mark usage
├── BRAND.md                    Brand asset usage
└── CONTRIBUTING.md             Contribution rules

developer-docs publishes the approved Identity Access, Ledger Core and Workbench OpenAPI v1 contracts, operational guides and reproducible examples at mavulahq.github.io/developer-docs. legacy-connectors owns durable receipts, fixed-width generation and validation-only imports under RFC-0002.

Licensing

MAVULA follows an open core model.

• identity-access, ledger-core, workbench, settlements, developer-docs, legacy-connectors, contracts and root code: AGPL-3.0-only.
• operations: Apache-2.0.
• MAVULA names, logos, domains and product marks remain reserved.
• Enterprise hosting, proprietary integrations, compliance packs and managed services may be licensed separately.

See LICENSE_POLICY.md, TRADEMARKS.md and BRAND.md.

Modules

Module	Package	Responsibility
Identity Access	@mavula/identity-access	Institutions, branches, operators, credentials, memberships, roles, OIDC artifacts and access policy.
Ledger Core	@mavula/ledger-core	Product configuration, accounts, ledger, lending, audit, outbox/inbox and read projections.
Workbench	@mavula/workbench	BullMQ workers, schedules, retries, payment publishing, legacy batch orchestration and platform status.
Settlements	@mavula/settlements	Payment process state, webhook dedupe, reconciliation candidates and guarded settlement outbox.
Developer Docs	@mavula/developer-docs	Versioned integration guides, examples and public OpenAPI reference with owner contract provenance.
Legacy Connectors	@mavula/legacy-connectors	COBOL copybooks, fixed-width generation, validation-only imports and durable batch receipts.
Operations	@mavula/operations	Local services, Docker, Kubernetes, Minikube, monitoring, secrets and Terraform starters.

Legacy names remain as compatibility aliases where needed:

• fengine -> ledger-core
• fwk -> workbench
• fpay -> settlements
• finfra -> operations

Architecture Contracts

RFC-0001 defines the current module boundaries, CQRS posture and domain event catalog. RFC-0002 defines the ledger-core production closeout for API security, tenant isolation, controlled financial operations, idempotency, audit trail and versioned HTTP contracts. The active event flow uses Transactional Outbox/Inbox, not full Event Sourcing.

Active events:

• products.configuration_published
• ledger.journal_posted
• lending.loan_disbursed
• lending.payment_posted
• payments.settlement_completed

payments.settlement_completed is owned by Settlements and delivered through Workbench to Ledger Core as an idempotent Inbox event. Ledger Core records the event and does not mutate ledger or lending state directly from the payment event.

Validate contracts with:

pnpm contracts:check

Local Development

Required tools:

• Node 22.22.3
• pnpm 10.33.0
• Docker 24+
• Kubernetes CLI 1.28+
• Minikube for the local cluster path

Install:

pnpm submodules:init
pnpm install --frozen-lockfile
pnpm git:hooks:install

Build and test:

pnpm --filter @mavula/identity-access build
pnpm --filter @mavula/identity-access test
pnpm --filter @mavula/ledger-core build
pnpm --filter @mavula/ledger-core test:all
pnpm --filter @mavula/settlements test
pnpm --filter @mavula/workbench test:all
pnpm contracts:check
pnpm -r build

Docker Compose:

docker compose up -d postgres redis identity-access ledger-core workbench
docker compose ps
docker compose logs -f identity-access ledger-core workbench
docker compose down

Minikube:

MINIKUBE_PROFILE=<existing-profile> pnpm --filter @mavula/operations minikube:deploy
pnpm --filter @mavula/operations minikube:status
pnpm --filter @mavula/operations minikube:stop

Environment

.env.example is intentionally a placeholder. Local secrets and runtime configuration belong in .env, which must not be committed.

Minikube reuses mavula/*:<tag> images by default. Set MINIKUBE_REBUILD_IMAGES=true only when a deliberate local rebuild is required.

New environment names are preferred:

• LEDGER_CORE_URL
• WORKBENCH_QUEUE_BACKEND
• WORKBENCH_WORKER_ENABLED
• WORKBENCH_SCHEDULER_ENABLED
• SETTLEMENTS_OUTBOX_ENABLED
• SETTLEMENTS_OUTBOX_PUBLISHER_ENABLED

Legacy FENGINE_*, FWK_* and FPAY_* variables remain supported during the transition.

Governance

All changes to main must pass through a pull request. Contributions must follow CONTRIBUTING.md and may require CLA.md confirmation.

Security reports should go to security@mavula.io. Legal and trademark questions should go to legal@mavula.io.

Documentation

• ROADMAP.md
• CI-CD.md
• docs/architecture/context-map.md
• docs/architecture/domain-events.md
• docs/architecture/rfc-0001-phase-3-4-impact.md
• docs/architecture/rfc-0002-ledger-core-closeout.md