Madra Finance

Locally robust, globally connected.

Built on Hedera.

Repository Structure

This is a Turbo monorepo managed with pnpm.

apps/
  api-specification/   # API schemas/specs and documentation
  dashboard/           # Internal/admin/merchant dashboard (Next.js)
  verification-app/    # KYC verification flow app (Next.js)
  web/                 # Marketing website / public web frontend (Next.js)

packages/
  db/                  # Database access, schema, migrations (Drizzle ORM)
  ui/                  # Shared UI components, hooks, styles
  eslint-config/       # Shared ESLint configurations
  typescript-config/   # Shared TS configs

pnpm-workspace.yaml
turbo.json

Core scripts (from package.json at repo root):

  • pnpm dev – runs Turbo dev across apps.

  • pnpm build – builds all packages and apps via Turbo.

  • pnpm lint – runs lint across the workspace.

  • pnpm format – formats files with Prettier.

  • Database helpers (via packages/db):

    • pnpm db:generate

    • pnpm db:migrate

    • pnpm db:push

    • pnpm db:studio

Requirements:

Getting Started

  1. Install prerequisites

  • Install Node.js >= 20.

  • Install pnpm: npm i -g pnpm.

  1. Clone and install

pnpm install

  1. Environment variables

Copy .env.example to .env.local (or relevant env file) and fill the values:

# API KEY FOR PLATFORM
MADRA_FINANCE_API_KEY=

# DATABASE
DATABASE_URL=

# URLs
NEXT_PUBLIC_API_URL=
NEXT_PUBLIC_FRONTEND_URL=
HEDERA_NETWORK=TESTNET
AUTH_BASE_URL=https://api.thirdweb.com

# DIDIT / USER VERIFICATION
DIDIT_KYC_API_KEY=
DIDIT_KYC_WEBHOOK_SECRET_KEY=
DIDIT_KYC_VERIFICATION_WORKFLOW_ID=

# Exchange rate and historic data
# https://app.exchangerate-api.com/dashboard/confirmed
FX_RATE_API=

# HEDERA
HEDERA_ACCOUNT_ID=
HEDERA_PRIVATE_KEY=
MADRA_KYC_NFT_SUPPLY_PRIVATE_KEY=
MADRA_KYC_TOKEN_ID=0.0.6908028

# THIRDWEB
THIRDWEB_BASE_URL=https://api.thirdweb.com/
THIRDWEB_CLIENT_ID=
THIRDWEB_CLIENT_SECRET=

# MARQETA
MARQETA_API_KEY=
MARQETA_ADMIN_ACCESS_TOKEN=
MARQETA_BASE_URL=https://sandbox-api.marqeta.com/v3/

# ALPACA
ALPACA_CLIENT_ID=
ALPACA_CLIENT_SECRET=

# PINATA_IPFS
PINATA_API_KEY=
PINATA_API_SECRET=
PINATA_JWT_SECRET=

Notes:

  • HEDERA_NETWORK defaults to TESTNET for development.

  • Ensure DATABASE_URL points to a reachable database instance.

  • Some integrations require accounts and API keys (Thirdweb, Marqeta, Alpaca, DIDIT, Pinata). Do not commit secrets.

  • Keep .env.example as a template only; use .env.local (or per-app env files) for actual secrets.

  1. Run the monorepo in dev mode

pnpm dev

This runs development servers for relevant apps via Turbo.

Run a single app (from repo root):

# Web (marketing site)
pnpm -C apps/web dev

# Dashboard (admin/merchant)
pnpm -C apps/dashboard dev

# Verification app (KYC flow)
pnpm -C apps/verification-app dev

  1. Database workflows

pnpm db:generate
pnpm db:migrate
pnpm db:push
pnpm db:studio

These commands proxy to packages/db using dotenv-cli. Ensure your .env.local is configured.

  1. Build and lint

pnpm build
pnpm lint
pnpm format

Application Overview

  • apps/web/

    • Public/marketing site built with Next.js.

    • Highlights: hero and feature components showcasing mobile app, developer-first API, and widgets.

  • apps/dashboard/

    • Next.js dashboard for internal/merchant/admin operations.

    • Uses shared UI from @workspace/ui and DB from @workspace/db.

  • apps/verification-app/

    • Next.js app focused on KYC/verification flows, integrates with Hedera and Thirdweb.

  • apps/api-specification/

    • Central place for API specs and documentation (schemas, contracts, docs).

  • packages/db/

    • Drizzle ORM schemas, migrations, and DB utilities. Exposes db:* scripts.

  • packages/ui/

    • Shared components, hooks, styles, and utilities exported for apps to consume.

  • packages/eslint-config/ and packages/typescript-config/

    • Shared lint and TypeScript configurations.

Security and Secrets

  • Never commit .env* files or credentials.

  • Rotate API keys regularly and use scoped credentials per environment.

  • Prefer secret managers in production (e.g., cloud KMS/secret stores).

Contributing

We welcome contributions. To propose changes:

  1. Fork the repo and create a feature branch.

  2. Ensure pnpm lint and pnpm build pass.

  3. Open a PR describing the motivation, changes, and testing steps.

Please keep commit messages clear and PRs focused.

Roadmap (High-Level)

  • Expand local provider coverage and cross-border corridors.

  • Deepen card issuing and on/off-ramp capabilities.

  • More embeddable widgets and SDKs for developers.

  • Richer consumer experiences in the super app.

  • Compliance tooling, risk controls, and observability.

License

TBD.

Contact

For product and partnership inquiries, please reach out to the maintainers.

Nextapps

Last updated