109 lines
5.4 KiB
Markdown
109 lines
5.4 KiB
Markdown
# Darano refactoring final migration report
|
|
|
|
Date: 2026-09-01
|
|
Branch: `feat/refactor-v1`
|
|
Authoritative tracker: `REFACTORING-TODO.md`
|
|
|
|
## Outcome
|
|
|
|
The planned refactoring is complete. There are no `TODO`, `STARTED`, or `FAILED`
|
|
tasks in the actionable tracker. Historical `CHANGED` entries preserve explicit
|
|
scope decisions and completed task splits.
|
|
|
|
Active repositories are API, Auth, Wallet, AdminPanel, Proto, and GL. UI, Docs,
|
|
and DevOps were excluded from the architecture refactor by scope decision and were
|
|
not modified during the final phase.
|
|
|
|
## Delivered architecture
|
|
|
|
- API owns the public HTTP boundary under `interface/http`, depends on an
|
|
application upstream port, and uses explicitly composed lazy gRPC clients.
|
|
- Auth configuration is injected; domain/application boundaries cover OTP,
|
|
session/JWT, identity, periodic identity validation, and permissions; persistence
|
|
and provider implementations are infrastructure-owned.
|
|
- Wallet uses exact scale-7 domain money, application-owned wallet/transaction,
|
|
market, alert, stream, locking, and asset-administration workflows, explicit
|
|
process composition, durable transaction/ledger outboxes, and interface-owned
|
|
adapters.
|
|
- GL is an independent immutable double-entry service with scale-18 audit amounts,
|
|
idempotent append/reversal, reconciliation, recovery, explorer, and load coverage.
|
|
- Publisher-backed ICO settlement and all transaction-type event routes use the
|
|
owning Wallet/Market workflows with durable, idempotent delivery.
|
|
- Federation coupling and wallet creation by federation were removed; ownership is
|
|
`user_id -> identity_id -> wallet_id`, with wallets remaining asset-scoped.
|
|
- AdminPanel retains direct SQL reads for projections. Unmanaged projections fail
|
|
closed for writes; Assets alone use authenticated typed Wallet upsert/deactivate
|
|
commands. Duplicate Django wallet policy and secondary persistence signals are gone.
|
|
- Proto changes are additive where compatibility was required, and active generated
|
|
consumers are committed and reproducible.
|
|
|
|
## Shared-type decision
|
|
|
|
`SHARED-TYPES-EVALUATION.md` concludes that no new shared source package is safe:
|
|
|
|
- Wallet uses scale 7 with Stellar and `numeric(23,7)` semantics.
|
|
- GL uses precision 38/scale 18 with canonical immutable-journal semantics.
|
|
- deployed IDs mix signed database keys, unsigned legacy contract fields, Auth-owned
|
|
regulated identifiers, and opaque GL strings.
|
|
|
|
The approved boundary remains canonical base-10 decimal strings plus explicit
|
|
adapter conversions. Services do not import another service's domain package.
|
|
|
|
## Final corrections found by verification
|
|
|
|
- API commit `0074e91` regenerates its Wallet contract consumer.
|
|
- Auth commit `2c8a0b1` regenerates its Wallet contract consumer.
|
|
- Wallet commit `3b898e1` makes the duplicate-event integration assertion wait for
|
|
the first inbox success transition. The previous test could publish its duplicate
|
|
before the first handler completed; 20 race-enabled repetitions and the full race
|
|
suite pass after the correction.
|
|
|
|
These changes are scoped to generated outputs or test synchronization. No unrelated
|
|
working-tree changes were absorbed.
|
|
|
|
## Final verification
|
|
|
|
| Repository | Verification |
|
|
|---|---|
|
|
| Proto | Buf lint, build, and breaking check against the prior commit pass. |
|
|
| API | Proto and Swagger generation; `go test ./...`; race tests; vet; build; whitespace checks pass. |
|
|
| Auth | Proto generation; `go test ./...`; race tests; vet; build; whitespace checks pass. |
|
|
| Wallet | Proto generation; normal and race tests; vet; build; focused duplicate-event race test repeated 20 times; whitespace checks pass. |
|
|
| GL | Templ/proto generation; normal and race tests; vet; build pass. The localhost `httptest` case required normal socket permission rather than the restricted sandbox. |
|
|
| AdminPanel | Local BetterProto generation; 13 focused boundary tests; Django system checks; Python compilation; whitespace checks pass. |
|
|
|
|
API/Auth/Wallet/GL/AdminPanel/Proto are clean on `feat/refactor-v1` after their final
|
|
commits. The coordination repository contains only this final documentation change
|
|
until its handoff commit is created.
|
|
|
|
## Required deployment configuration
|
|
|
|
Asset administration is fail-closed. Configure matching secrets:
|
|
|
|
- AdminPanel: `WALLET_ADMIN_GRPC_TOKEN`
|
|
- Internal Wallet: `[admin-assets].token`
|
|
|
|
Optional AdminPanel settings:
|
|
|
|
- `WALLET_ADMIN_GRPC_ADDRESS` (default `127.0.0.1:8500`)
|
|
- `WALLET_ADMIN_GRPC_TIMEOUT` (default 5 seconds)
|
|
|
|
The internal Wallet schedule/config files remain environment-owned and ignored where
|
|
previously established; deploy secrets through the existing configuration mechanism.
|
|
|
|
## Known external/baseline conditions
|
|
|
|
- The Darano Go proxy previously returned long `504` responses during cold Docker
|
|
dependency downloads for API/Auth/Wallet. Native generation, tests, vet, and builds
|
|
pass; the final phase did not alter registry policy or add a public fallback.
|
|
- Django deploy checks still depend on production-provided secret, TLS redirect,
|
|
secure cookie, CSRF, HSTS, and DEBUG settings. Normal system checks pass.
|
|
- Legacy public Wallet/Market protobuf money remains `double` for compatibility.
|
|
New exact internal financial boundaries must use canonical decimal strings.
|
|
|
|
## Handoff
|
|
|
|
Use `REFACTORING-TODO.md`, `REFACTORING-AUDIT.md`, this report, and `MEMORY.md` as
|
|
the continuation sources. All implementation tasks are complete; future work should
|
|
be opened as a new scoped task rather than reopening the finished migration tracker.
|