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–W013 are complete. The final W005–W012 series ends at 240b8d0 on feat/refactor-v1.
• Recent Wallet completion commits include 03da6fd atomic trustline transaction persistence, c7f442a failed IPG fulfillment recording, ae0b185 canceled-maker balance release, ca2dc50 synchronous settlement, fbca6fa stream application service, 14c5d35 lock persistence workflow, 200d6d6 market lifecycle, d91d51b transaction balance processor, and 240b8d0 final interface boundaries.
• API G001–G008 are complete. The compatibility inventory begins at 95c4264; the final removal of superseded packages is 31e3043. Upstream clients live in infrastructure/grpcclient, HTTP adapters live in interface/http, and cmd/apiRuntime owns explicit composition.

Wallet completion state

Use REFACTORING-TODO.md and REFACTORING-AUDIT.md as the authoritative detailed tracker. No Wallet refactoring task remains open. The active Vandar PSP interface has verification/settlement but no refund/reversal operation; post-settlement fulfillment failures are persisted as failed transactions rather than calling a fabricated provider API.

Final Wallet verification on 2026-08-31: protobuf regeneration produced no diff; go test ./..., go test -race ./..., go vet ./..., and go build ./... all passed.

API completion state

No API refactoring task remains open. Final API verification on 2026-08-31: protobuf and Swagger regeneration produced no diff; go test ./..., go test -race ./..., go vet ./..., and go build ./... all passed. Swagger regeneration requires GOCACHE=/tmp/darano-api-go-cache in this environment.

AdminPanel/protobuf completion state

P001–P010 and R001–R003 are complete. AdminPanel still reads service-owned tables directly, but every unmanaged model is read-only unless explicitly service-backed. Assets write through authenticated Wallet gRPC upsert/deactivate commands; prices and every other legacy mutation/import/inline/bulk path are disabled. Configure matching WALLET_ADMIN_GRPC_TOKEN in AdminPanel and [admin-assets].token in the internal-wallet configuration, plus the optional WALLET_ADMIN_GRPC_ADDRESS and WALLET_ADMIN_GRPC_TIMEOUT values. AdminPanel protobuf generation now uses the adjacent local proto/ checkout and BetterProto 2.

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.