123 lines
8.3 KiB
Markdown
123 lines
8.3 KiB
Markdown
# 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`–`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.
|
||
|
||
### Final refactoring completion state (2026-09-01)
|
||
|
||
`F001`–`F005` are complete and the authoritative tracker has no actionable remaining task. `SHARED-TYPES-EVALUATION.md` records why Wallet scale-7 money, GL scale-18 money, legacy numeric IDs, Auth identifiers, and opaque GL IDs remain bounded-context types. `FINAL-MIGRATION-REPORT.md` records the final architecture, verification matrix, deployment configuration, known external conditions, and handoff.
|
||
|
||
Final verification regenerated every active consumer and found two missing checked-in consumers plus one race-test synchronization issue. API `0074e91`, Auth `2c8a0b1`, and Wallet `3b898e1` contain those corrections. Proto lint/build/breaking, all active Go normal/race/vet/build gates, Wallet's focused 20-run race test, AdminPanel's 13 focused tests/checks/compilation, and reproducible generation pass.
|
||
|
||
### 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.
|