Introduction

Audience: the Dropout Capital engineering team building Vecnet greenfield. Status: v0.1 — finances module + system architecture. Owner: Yuyo (Tonder / Vecnet). Source of truth: the build spec supersedes verbal context. Where it conflicts with the architecture PDF or vecnet_citizen_flow.mmd, the spec wins.

Mission & context

Vecnet is an orchestration, reconciliation, and settlement layer that sits on top of two independent payment rails and presents a unified financial picture to the merchant and to Vecnet operations.

In the reference deployment (government collections / GovTech):

• A citizen (Ciudadano) pays either:
  • online through the government portal (Portal de Gobierno → Web/App), or
  • in person at a POS terminal (Terminal POS) in the collection office (Oficina de Recaudación).
• Online payments are processed through the Tonder rail (card-not-present).
• In-person payments are processed through the Menta rail (card-present / POS).
• Vecnet consolidates both rails: it listens to their transaction notifications, records them in its own books, runs fees / settlements / rolling reserve / daily ledger, and exposes dashboards and admin tooling.

The same engine generalizes beyond GovTech — the merchant (BUSINESS entity) can be any Vecnet client, and the rails (ACQUIRER entities) can be extended. See The two rails for acquirer-as-plugin.

Vecnet owns its finances module

It is not a thin client of Tonder's books. Vecnet keeps its own double-entry ledger and computes its own fees, settlements, reserves, and reports — modeled on the Tonder engine documented here, rebuilt on Supabase.

How to use these docs

This is the master spec, with the finances module as the technical centerpiece. Read in this order:

1. Architecture and The two rails — what Vecnet is and how it's shaped.
2. AWS/NoSQL → Supabase — the single most important section: how Tonder's AWS/NoSQL finances engine ports to Supabase/Postgres, and why the port simplifies it.
3. Tech stack, Domain model, and the Data model.
4. Finances flows — each rewritten for Supabase.
5. Surfaces — the merchant Dashboard, the Vecnet Admin operator platform, and the Hosted Checkout.
6. Rails integration, Security, Build phases, and the Tonder → Vecnet mapping appendix.

Hard constraint up front

Vecnet does not use MongoDB or DynamoDB. The entire data layer is Supabase (Postgres). Tonder's finances engine is the blueprint; the storage and eventing primitives are replaced. Do not port the workarounds — port the intent.