# 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.

```sh
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.