Darano project memory

Updated: 2026-08-29

Product and domain

Darano is a real-world-asset tokenization platform. Bank Mellat is the main customer context and real estate is the primary asset class. User flows include wallets and locked balances, transaction history, bank accounts, referrals, legal agreements/contracts, maker/taker trading, ICO purchases, bank and Kuknos deposit identification, IPG deposits, IRT withdrawals, third-party collateral locks, and optional SMS/TOTP/email 2FA.

User transaction requests are event-driven. No automatic transaction-acceptance policy exists yet.

Sources of truth and availability

The append-only General Ledger (GL) is the primary source of truth.
Kuknos (Stellar 18+ compatible) is the secondary source of truth.
A normal financial transaction requires both GL and Kuknos.
If GL is unavailable, all financial transactions halt. Health becomes critical and the incident is emitted through structured/OTel-compatible logs.
Kuknos failure also halts transactions while enabled. An administrator may explicitly disable Kuknos by admin toggle or configuration; this is never an automatic failover.
The local Docker stack uses the explicit DARANO_KUKNOS_ENABLED=false configuration because the test Horizon endpoint returns 403/timeouts. GL remains mandatory.

Implemented architecture

Wallet contains a financial availability gate covering GL and Kuknos.
Transaction event outbox/inbox/deadbox processing is present for event-driven requests.
GL writes are append-only and wallet financial work fails closed when GL is unavailable.
API / health reports the financial component and returns HTTP 503 with critical status when unavailable.
Kuknos streaming pauses when the manual Kuknos switch is disabled.
Concurrent wallet-role database migrations are serialized with a PostgreSQL transaction advisory lock.
API configuration loading now accepts absolute paths.

Local Docker Desktop stack

Definition: DevOps/local/compose.yml

Use Docker Desktop, not OrbStack.

docker compose -f DevOps/local/compose.yml build
docker compose -f DevOps/local/compose.yml up -d --no-build
docker compose -f DevOps/local/compose.yml ps -a

Local endpoints:

API: http://localhost:3000
UI: http://localhost:3001
AdminPanel: http://localhost:8080
Auth: localhost:8100
Wallet: localhost:8200
Market: localhost:8300
Alert: localhost:8400
Internal wallet: localhost:8500
GL: localhost:8600
PostgreSQL: localhost:5432
Redis: localhost:6379
RabbitMQ: localhost:5672, management localhost:15672

The UI uses http://api:3000 for server-side container requests and http://localhost:3000 for browser requests.

Package registries

Go: https://go.reg.darano.ir
Python: https://pypi.reg.darano.ir/simple/

Dockerfiles were updated to use these defaults. AdminPanel retains one lockfile-pinned Kavenegar Git dependency from GitHub. UI npm packages still use the public npm registry.

Validation performed

GL, API, auth, wallet, AdminPanel, and UI Docker images built successfully on Docker Desktop ARM64.
API absolute config-path test passes.
Wallet infrastructure config and PostgreSQL repository tests pass.
Concurrent wallet roles remained running after the migration serialization fix.
With Kuknos enabled and unavailable, GL stayed ready while readiness became critical, HTTP health returned 503, logs recorded the reason, and event delivery halted as designed.

Known frontend warnings

ui/.eslintrc.json is malformed/empty, so the production build reports an ESLint configuration warning.
next.config.mjs passes obsolete fileExtensions to next-images.
Buf reports duplicate generated TypeScript filenames but completes the UI build.

Repository rule

All changed project repositories are kept on feat/refactor-v1. Clean auxiliary repositories that already use another branch were not modified.

3.9 KiB Raw Blame History