dev-procfile/REFACTORING-PLAN.md

Darano Monorepo — DDD / Clean Architecture Refactoring Plan

Executive Summary

The five codebases (api/, auth/, wallet/, AdminPanel/, and proto/) share the same general idea of layering but diverge in naming, directory structure, config libraries, where business logic lives, and — critically for AdminPanel — how they access data. AdminPanel bypasses all Go backend services and writes directly to the core database, making it a parallel implementation of business logic. This plan defines a unified target architecture and a phased migration that preserves functionality at every step.

---

1. Current State Analysis

1.1 Naming & Structure Inconsistencies

Concern	api/	auth/	wallet/
Business logic layer	handler/ (HTTP-only)	usecase/	core/walletImp/
Business logic layer (2nd)	service/ (gRPC client)	(same as above)	core/marketImp/, core/alertImp/
Data access	No repo (gateway only)	repository/	repository/
Domain models	domain/stub/ only	domain/db/ + domain/dto/	domain/db/
Config library	knadh/koanf	kkyr/fig	kkyr/fig
Config global	config.Cfg	config.Cfg	config.Cfg
gRPC server impl	N/A (HTTP-only)	usecase/* implements gRPC server	core/*Imp/* implements gRPC server

Key observation: auth/ has the cleanest pattern (usecase/ for business logic), wallet/ is the most messy (core/ mixes gRPC server with business logic), and api/ is fine as an HTTP gateway.

1.2 AdminPanel Architecture — Direct DB Access, No Abstraction

AdminPanel has a fundamentally different problem: it bypasses all Go backend services and connects directly to the core database.

AdminPanel ──direct Postgres──→ core_db (same DB as Go services)
                              ──→ default_db (Django's own tables)
                              ──→ lite_db (SQLite, fallback)

Key problems:

1. managed = False GORM models copied manually: Every model in src/coreLogic/models.py has managed = False and db_table = "..." — they are manual replicas of the Go services' GORM models. Generated via inspectdb, never kept in sync. make proto generates betterproto stubs, but Django models are not auto-generated from those.

2. No service layer: The entire AdminPanel is a thin layer of Django admin widgets on top of raw SQL tables. Business logic is scattered across:

   • src/coreLogic/admin/asset.py — inline validation (check_token_policy, auto_gen) duplicating Go-side rules
   • src/coreLogic/acl.py — permission rules
   • src/usermapper/user_perm.py — asset access control
   • Inline admin methods (save_model) that bypass Go services' validation entirely

3. No gRPC integration: The AdminPanel reads/writes directly to core_db. No gRPC call to Go services. Means:

   • Admin edits to Assets bypass trustline updates
   • Admin edits to Transactions don't trigger blockchain operations
   • Admin edits to Wallets don't update Stellar balances
   • Race conditions between admin edits and Go service operations

4. Hardcoded business rules in Django: check_token_policy duplicates validation that should live in the wallet service. auto_gen generates metadata that should be produced by the wallet service.

5. Multi-database with fragile router: src/adminpanel/db/routers.py routes coreLogic models to core_db. If a new model is added to Go services but forgotten in Django admin, it silently fails.

6. Inline business logic in Django admin: MultiDBModelAdmin.save_model has asset-level access control. delete_model does soft deletes. Mixed with admin layer, not separated.

1.3 Config Library Mismatch

• api/ uses knadh/koanf/v2 with TOML parser. Tags are koanf:"field-name".
• auth/ and wallet/ use kkyr/fig. Tags are fig:"field-name".
• All three use a global singleton config.Cfg.
• api/ hardcodes defaults in ParseConfig; auth/ and wallet/ rely on struct defaults.
• AdminPanel uses django-environ (.env files). Different language/framework entirely.

1.4 Where Business Logic Lives

• auth/ usecase/ — Decent separation, but gRPC interfaces embedded directly in the struct. Validation, business rules, and gRPC response building mixed in the same methods.
• wallet/ core/walletImp/ — Problematic: 19 files implementing WalletServiceServer with business logic, validation, DB calls, and Stellar blockchain calls all in one method. Example: UserInitWallet does validation, DB transactions, key generation, trustline creation, and status response — all in one method.
• api/ handler/ — Acceptable: handlers call DaranoService (gRPC client). No business logic here. But service/ is a gRPC client aggregator with reflection-based URL lookup, not a traditional service layer.
• AdminPanel admin/ — Wrong layer: business validation, metadata generation, and policy checks live in Django admin classes, not in a service layer.

1.5 Domain Model vs Persistence Model Confusion

All Go services use GORM models (domain/db/) directly as domain objects. No separation between domain entities (rich business objects with behavior) and persistence models (plain structs with GORM tags).

AdminPanel uses Django models with managed = False — the same conflation, but in Python.

---

2. Target Architecture

2.1 Go Services — Unified Directory Structure

Each Go service should follow:

service/
├── cmd/                          # CLI entry points (Cobra)
├── domain/                       # Innermost layer — pure business logic
│   ├── entity/                   # Domain entities (rich, no persistence tags)
│   ├── valueobject/              # Immutable value objects (Money, AssetID, etc.)
│   ├── service/                  # Domain services (orchestrate entities)
│   ├── repository/               # Repository INTERFACES only (ports)
│   ├── error/                    # Domain-specific errors
│   ├── event/                    # Domain events
│   ├── dto/                      # Data transfer objects (gRPC/HTTP)
│   └── stub/                     # Generated protobuf code (never edit)
├── application/                  # Application layer — use cases
│   ├── usecase/                  # Business logic / use cases
│   └── service/                  # Application services
├── infrastructure/               # Infrastructure layer
│   ├── repository/               # Repository implementations (DB, Redis, Queue)
│   │   ├── db/                   # PostgreSQL, etc.
│   │   ├── redis/                # Redis
│   │   └── queue/                # RabbitMQ
│   ├── config/                   # Configuration loading
│   ├── grpc/                     # gRPC server setup & registration
│   ├── logger/                   # Logger initialization
│   └── crypto/                   # Cryptography utilities
├── interface/                    # Interface/Adapter layer
│   ├── http/                     # HTTP handlers (api gateway only)
│   ├── grpc/                     # gRPC server implementations
│   └── ws/                       # WebSocket handlers
├── util/                         # Cross-cutting utilities
├── go.mod
└── main.go

Dependency flow (points inward):

interface/ → application/ → domain/ ← infrastructure/

2.2 AdminPanel — Thin Admin Wrapper Around Go Services

AdminPanel needs a Django-native approach (no forced DDD naming), but the architectural principles are the same:

AdminPanel/src/
├── adminpanel/           # Django project config
├── coreLogic/
│   ├── domain/           # NEW: extracted business logic
│   │   ├── services/     # Validation, metadata generation (moved from admin/)
│   │   └── repositories/# Interfaces to backend
│   ├── application/      # NEW: use cases that delegate to gRPC
│   │   ├── asset_uc.py
│   │   ├── wallet_uc.py
│   │   └── market_uc.py
│   ├── infrastructure/   # NEW: gRPC client to Go services
│   │   └── grpc_client.py
│   ├── admin/            # Keep — now thin UI adapters only
│   ├── models.py         # Keep as legacy (read-only ORM, managed=False)
│   └── enums.py          # Keep
├── usermapper/           # Admin user management (keep as-is)
├── alerts/               # Notification system (keep as-is)
├── accounts/             # SMS accounts (keep as-is)
└── utils/                # Cross-cutting utilities

Key principle: AdminPanel should be a thin admin wrapper around the Go services, not a parallel implementation. Go services own all business logic. AdminPanel provides a human-friendly interface to view and (with validation) modify state.

2.3 AdminPanel Data Access Pattern

Read path:  AdminPanel ──SQL──→ core_db (fast, direct, for list/detail views)
Write path: AdminPanel ──gRPC──→ Go services (validate + execute business logic)

2.4 Config Standardization

All Go services → knadh/koanf/v2 with TOML. No global singletons — config passed via constructor injection.

---

3. Migration Plan — Phased Approach

Phase 0: Preparation (1 day)

No code changes. Document test coverage, verify all services build, create tracking doc.

Phase 1: Standardize Go Config (2-3 days)

Replace fig → koanf in auth/ and wallet/. Move config to infrastructure/config/config.go. Remove global config.Cfg.

Risk: Low. Config struct fields stay the same; only the loader changes.

Phase 2: Reorganize auth/ (3-4 days)

Rename layers, move interfaces to domain/, move GORM models to infrastructure/. auth/ already has the cleanest pattern — this validates the approach.

Risk: Low. Structure change, minimal logic changes.

Phase 3: Reorganize wallet/ (1-2 weeks)

Rename core/ → application/. Split walletImp/, marketImp/, alertImp/ into application/usecase/. Move GORM models and interfaces. Split gRPC server registration from use cases. Move port/stellar/ → infrastructure/.

Risk: Medium. Incremental: rename first, then split gRPC, then add entities.

Phase 4: Restructure api/ (3-4 days)

Rename handler/ → interface/http/, service/ → infrastructure/grpcclient/, move middlewares/ → interface/http/middleware/.

Risk: Medium. Gateway pattern is different from auth/wallet.

Phase 5: AdminPanel Service Layer (2-3 weeks)

1. Create infrastructure/grpc_client.py — reusable gRPC client to Go services
2. Extract business logic from admin classes to coreLogic/domain/services/
3. Create use case layer coreLogic/application/
4. Refactor admin classes to thin adapters (delegate to use cases)
5. Fix router typo (no_migartion → no_migration)
6. Add gRPC write hooks for save_model

Risk: Medium. Test every admin page after migration.

Phase 6: Shared Domain Types (3-5 days)

Extract WalletID, UserID, AssetID, Balance value objects into monorepo root shared/domain/. Import via each service's go.mod.

Risk: Medium. Affects all services on change.

Phase 7: Domain Events (2-3 days, optional)

Add domain/event/ to Go services for cross-domain communication.

---

4. Migration Order

Phase 0: Preparation
    ↓
Phase 1: Go config standardization
    ↓
Phase 2: Reorganize auth/  ──┐
                              ├──→ Phase 5: AdminPanel (parallel with 2-4)
Phase 3: Reorganize wallet/  ─┘
    ↓
Phase 4: Restructure api/
    ↓
Phase 6: Shared domain types
    ↓
Phase 7: Domain events (optional)

---

5. Before/After: AdminPanel Asset Management

Before — business logic in Django admin:

# src/coreLogic/admin/asset.py
@admin.register(Assets, site=admin_site)
class AssetAdmin(MultiDBModelAdmin):
    def save_model(self, request, obj, form, change):
        if user_perm.can_access_asset(request.user, obj):
            return super().save_model(request, obj, form, change)
        # Direct DB write — bypasses wallet service!

    def check_token_policy(self, request, obj: Assets) -> bool:
        # Validation duplicated from wallet service
        if obj.can_buy:
            p = AssetPrices.objects.filter(asset=obj).last()
            if not p or p.ico_price <= 0:
                errors.append("ico price must be > 0")

After — thin admin delegating to Go service:

# src/coreLogic/application/asset_uc.py
class AssetUseCase:
    def __init__(self, grpc_client: GRPCClient):
        self.grpc_client = grpc_client

    def update_asset(self, admin_user, asset_id, changes: dict) -> StatusRes:
        """Delegates all mutations to wallet service."""
        return self.grpc_client.wallet_service.InternalWalletUpdateAsset(
            AssetUpdateReq(id=asset_id, changes=changes)
        )

# src/coreLogic/admin/asset.py
@admin.register(Assets, site=admin_site)
class AssetAdmin(MultiDBModelAdmin):
    list_display = [...]
    # ... UI config only

    def save_model(self, request, obj, form, change):
        uc = AssetUseCase(self.grpc_client)
        uc.update_asset(request.user, obj.id, form.cleaned_data)

---

6. Risk Mitigation

Risk	Mitigation
Breaking CI/CD	Keep make build and make run working at every phase
Lost functionality during rename	Use git mv + sed for mass renames; commit each file move separately
gRPC contract breaks	Proto definitions are in proto/. We only change Go implementation
Config migration issues	Keep old config format identical; only change the loader
AdminPanel write conflicts	gRPC write path ensures Go services own all mutations
Django model drift	Document which models are read-only ORM vs which need gRPC sync
Multiple air instances conflict	The flock mechanism in wallet Makefile handles this

7. Non-Goals

• Changing protobuf definitions — .proto files stay as-is
• Adding new frameworks — no ORM replacement
• Rewriting the UI
• Complete test suite rewrite