dev-procfile/MEMORY.md

Darano project memory

Updated: 2026-08-30

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.

Cross-machine continuation handoff (2026-08-30)

All committed work was pushed. api, auth, wallet, proto, and dev-procfile are clean on feat/refactor-v1 and synchronized with origin. API's branch diverged from the remote and was safely merged in 32c3953; the refactored configuration layout was retained, obsolete legacy config/ and Dockerfile conflict artifacts stayed removed, and go test ./... passes.

Recently completed

• Federation was removed from Wallet/Auth/API and the shared wallet protobuf. The intended ownership remains user_id → identity_id → wallet_id, with wallets asset-scoped. Deployed databases still need their separate legacy federation column/table migration.
• Auth refactoring tasks A001–A009 are complete, including configurable periodic identity validation.
• Wallet W001–W004 and W013 are complete. W005–W012 are started and have substantial application-boundary extraction.
• Recent Wallet commits: 5f37e56 configurable cron schedule; ba14ce1 no nil cron errors; 0920702 explicit lock/release success responses; 36b4d67 lock request validation; 66d271e safe unsupported transaction processing; f9a0262 propagate wallet-init commit failures; dc0bdf4 central agreement-ID policy; ab4091e central rounding policy.
• Recent coordination docs commit: 478d23a.

Wallet work still open

Use REFACTORING-TODO.md and REFACTORING-AUDIT.md as the authoritative detailed tracker. Remaining started Wallet items are:

• W005: complete initialization/trustline orchestration extraction and integration coverage.
• W006: finish balance coordination and business failure/refund orchestration. Refund remains constrained by the current PSP provider interface.
• W007: extract market lifecycle, settlement, contract generation, and adapters.
• W008: extract alert delivery/retry/persistence and adapters.
• W009: move remaining internal-wallet transaction, ledger, persistence, and RPC boundary work.
• W010: finish cron/stream process composition separation.
• W011: replace remaining shared bootstrap internals with explicit dependency composition.
• W012: remove remaining superseded core implementations and compatibility adapters.

Commands and cautions

• Prefix shell commands with rtk as required by /home/navid/.codex/RTK.md.
• Use rtk env GOCACHE=/tmp/darano-wallet-go-cache go test ./... from wallet/; the default Go build cache is not writable in this environment.
• Use rtk env GOCACHE=/tmp/darano-api-go-cache go test ./... from api/.
• Use apply_patch for edits. Do not hand-edit generated protobuf stubs; regenerate through the service build/proto workflow.
• Preserve unrelated worktree changes. Do not force-push.