Proposal: Migrate to `uber-go/fx` for Dependency Injection

[diyor28]

Refactoring IOTA SDK to Uber‑FX

1. Background

Today the IOTA SDK hand‑wires constructors, context providers, and HTTP handlers via reflection (pkg/di, H/Invoke, composables). As modules grow (core, CRM, finance, warehouse, …) this “glue” becomes unwieldy:

• Every binary (server, migrate, seed, etc.) repeats plumbing.
• Dependencies aren’t explicit in function signatures.
• Lifecycle (start/stop hooks) is custom and ad hoc.

---

2. Why Uber‑FX?

fx (built on dig) offers:

• Automatic wiring of constructors (fx.Provide)
• Module grouping (fx.Options) per bounded context
• Lifecycle hooks (fx.Lifecycle for OnStart/OnStop)
• Explicit dependencies in each constructor’s signature
• Built‑in introspection of your dependency graph
• Strong type‑safety and better testability

---

3. Key Benefits for IOTA SDK

1. Modular initialization
   • Each domain (core, CRM, finance, warehouse, website, …) becomes an fx.Option you can register independently.
2. Minimal boilerplate
   • One fx.New(...) per binary—no more manual builder code.
3. Clear lifecycles
   • Attach Postgres pool shutdown, WebSocket broker stop, HTTP server start/stop via fx.Lifecycle.
4. Easier testing
   • Swap out individual constructors (fx.Testing) or provide mocks via fx.Provide.
5. DDD‑friendly
   • Your domain constructors remain pure (func NewOrderService(repo OrderRepo) *OrderService), but now wired automatically.

---

4. Proposed Architecture

4.1. Core Binary (cmd/server/main.go)

package main

import (
  "context"
  "log"

  "go.uber.org/fx"

  "github.com/iota-uz/iota-sdk/internal/assets"
  "github.com/iota-uz/iota-sdk/internal/server"
  "github.com/iota-uz/iota-sdk/modules"
  "github.com/iota-uz/iota-sdk/pkg/application"
  "github.com/iota-uz/iota-sdk/pkg/configuration"
  "github.com/iota-uz/iota-sdk/pkg/eventbus"
  "github.com/iota-uz/iota-sdk/pkg/logging"

  corefx "github.com/iota-uz/iota-sdk/fxmodules/core"
  crmfx "github.com/iota-uz/iota-sdk/fxmodules/crm"
  financefx "github.com/iota-uz/iota-sdk/fxmodules/finance"
  warehousefx "github.com/iota-uz/iota-sdk/fxmodules/warehouse"
  serverfx "github.com/iota-uz/iota-sdk/fxmodules/server"
)

func main() {
  app := fx.New(
    // —— Global Providers ——
    fx.Provide(
      configuration.New,            // *Configuration, error
      logging.NewLogger,            // *logrus.Entry
      func(cfg *configuration.Configuration) (*pgxpool.Pool, error) {
        return pgxpool.New(context.Background(), cfg.Database.Opts)
      },
      eventbus.NewPublisher,        // *eventbus.Publisher
      application.New,              // *application.Application
    ),

    // —— Domain Modules ——
    corefx.Module(),
    crmfx.Module(),
    financefx.Module(),
    warehousefx.Module(),

    // —— HTTP Server & Static Assets ——
    serverfx.Module(),

    // —— Application Initialization ——
    fx.Invoke(func(app *application.Application) error {
      // Load/Deregister built-in modules, register nav links & HashFS assets
      if err := modules.Load(app, modules.BuiltInModules...); err != nil {
        return err
      }
      app.RegisterNavItems(modules.NavLinks...)
      app.RegisterHashFsAssets(assets.HashFS)
      return nil
    }),
  )

  app.Run() // Blocks until shutdown
}

4.2. Example fx.Module (e.g. CRM)

// fxmodules/crm/module.go
package crmfx

import "go.uber.org/fx"

func Module() fx.Option {
  return fx.Options(
    // Service + repo constructors
    fx.Provide(
      crmPersistence.NewClientRepository,   // func NewClientRepository(...) ClientRepo
      crmService.NewClientService,          // func NewClientService(repo ClientRepo) *ClientService
      presentation.NewClientController,     // func NewClientController(svc *ClientService) *ClientController
    ),

    // Register HTTP routes / GraphQL
    fx.Invoke(presentation.RegisterClientRoutes),
  )
}

4.3. HTTP Server Module

// fxmodules/server/module.go
package serverfx

import (
  "context"
  "log"

  "go.uber.org/fx"
  "github.com/iota-uz/iota-sdk/internal/server"
  "github.com/iota-uz/iota-sdk/pkg/configuration"
)

func Module() fx.Option {
  return fx.Options(
    fx.Provide(
      server.NewDefault, // func NewDefault(opts *server.Options) (*server.Server, error)
    ),
    fx.Invoke(func(lc fx.Lifecycle, srv *server.Server, cfg *configuration.Configuration) {
      lc.Append(fx.Hook{
        OnStart: func(ctx context.Context) error {
          log.Printf(">> Listening on %s", cfg.Address())
          return srv.Start(cfg.SocketAddress)
        },
        OnStop: srv.Stop,
      })
    }),
  )
}

---

5. Migration Roadmap

1. Extract Core Constructors
   • Move NewConfig, NewLogger, NewPostgresDB, NewEventPublisher, application.New into fx.Provide‑compatible functions.
2. Bootstrap cmd/server
   • Replace hand‑wired main.go with the fx-based pattern above.
3. Gradual Module Migration
   • For each domain (core, CRM, finance, warehouse, website…):
     • Create fxmodules/<domain>/Module()
     • Move all NewXxx constructors and RegisterRoutes into it.
4. Additional Binaries
   • Apply same pattern to cmd/migrate, cmd/seed, cmd/document, cmd/collect‑logs, wiring only the providers they need.
5. Sunset pkg/di
   • Once all constructors live under fx, remove pkg/di and H/Invoke.
6. CI & Testing
   • Leverage fx.Testing to inject mocks.
   • Retain existing NewXxx() constructors for backward compatibility in unit tests.

---

6. Risks & Mitigations

• Startup‑time errors: missing providers surface at runtime.
  Mitigation: enable fx’s graph printing (fx.New(fx.PrintDeps())) in dev.
• Learning curve for contributors.
  Mitigation: provide a “Getting Started” doc + examples.
• Longer build times when adding many constructors.
  Mitigation: group into coarse‑grained modules; merge related constructors.

---

7. Next Steps

• Prototype cmd/server migration in a feature branch.
• Update documentation and developer onboarding.
• Review and merge core infra changes.
• Roll out domain modules incrementally, validating with smoke tests.

By following this plan, IOTA SDK will gain a scalable, maintainable bootstrap system, clearer lifecycles, and faster developer onboarding—while preserving our DDD boundaries and testability.

[diyor28]

@mmirolim @jcbbb @bektosh-iota

[mirolimsgd]

@diyor28 I would suggest against using uber-go/fx if without going into details. It is complex, based on reflection, hard to debug, complex testing, possible runtime errors in case of missing deps and slowness in initiation and overkill if move to modules as microservices.
I still think manual dependency management will be much easier to test, easy to debug, explicit initiation and no initiation lag but more wiring code need to be written (boilerplate code) in app.
If you still want some library to handle that then I would recommend to check https://github.com/google/wire similar to fx library but use code gen which better on my view as it is more explicit, no runtime errors on missing deps (compile time detection) and easier to debug then reflection based approach. Testing is easier and more explicit.

[diyor28]

@diyor28 I would suggest against using uber-go/fx if without going into details. It is complex, based on reflection, hard to debug, complex testing, possible runtime errors in case of missing deps and slowness in initiation and overkill if move to modules as microservices. I still think manual dependency management will be much easier to test, easy to debug, explicit initiation and no initiation lag but more wiring code need to be written (boilerplate code) in app. If you still want some library to handle that then I would recommend to check https://github.com/google/wire similar to fx library but use code gen which better on my view as it is more explicit, no runtime errors on missing deps (compile time detection) and easier to debug then reflection based approach. Testing is easier and more explicit.

I’m aware of google/wire and found uber/fx more suitable for our use case.

How do you avoid global singletons when you need to pass configuration or UI layouts at startup? Should you manually thread that configuration through every component instead?

[danil-bragin]

@diyor28, @mirolimsgd
At this point, I’m leaning toward using uber-go/fx in the IOTA SDK.

While fx is based on reflection and some errors may surface at runtime, I believe its benefits outweigh the downsides in the context of our architecture:

• We have a modular structure (core, CRM, warehouse, etc.), and fx makes it easy to initialize each module cleanly via fx.Options().
• We’re planning to introduce dynamic mechanisms (such as a CRUD builder), and in such scenarios, static dependency generation (like Wire) tends to be limiting rather than helpful.
• Manual DI results in boilerplate code and becomes hard to maintain. As the project grows, it quickly becomes a bottleneck that slows down development.
• Wiring issues can still be effectively caught using fx.PrintDeps(), fx.ErrorHook, and fx.WithLogger. In practice, most of the problems show up immediately during local development.
• Relying on external code generators (e.g., Wire) introduces a dependency on tools we don’t control. This can lead to surprises during upgrades or with edge-case structures. Runtime DI gives us more flexibility and predictability.

[mirolimsgd]

@diyor28 I am for explicit and simpler approach, load config during app initiation and pass relevant configs to module constructors then you don't need singleton.

// In main.go
globalConf := configuration.Use()
warehouseConf := warehouse.Config{
    DefaultStockLocation: globalConf.Warehouse.DefaultLocation,
    EnableAutoOrders:    globalConf.FeatureFlags.WarehouseAutoOrder,
}
// ... instantiate warehouse components, passing warehouseConf ...
whModule:= warehouse.New(whProductRepo, evtBus, warehouseConf)

I like Go's design philosophy which focus on simplicity and explicitness. I think we should not try replicate Django, Laravel, Nestjs frameworks in Go (people already tried). Of course if we were using Java, Python, Php, JS etc then I would suggest to use runtime/dynamic/reflection/decorator based libraries because it is common and idiomatic approach and how those languages work.

[diyor28]

@diyor28 I am for explicit and simpler approach, load config during app initiation and pass relevant configs to module constructors then you don't need singleton.

// In main.go
globalConf := configuration.Use()
warehouseConf := warehouse.Config{
    DefaultStockLocation: globalConf.Warehouse.DefaultLocation,
    EnableAutoOrders:    globalConf.FeatureFlags.WarehouseAutoOrder,
}
// ... instantiate warehouse components, passing warehouseConf ...
whModule:= warehouse.New(whProductRepo, evtBus, warehouseConf)

I like Go's design philosophy which focus on simplicity and explicitness. I think we should not try replicate Django, Laravel, Nestjs frameworks in Go (people already tried). Of course if we were using Java, Python, Php, JS etc then I would suggest to use runtime/dynamic/reflection/decorator based libraries because it is common and idiomatic approach and how those languages work.

I do agree, Go is a different beast. But as we build the SDK into something easily extensible and fast to build with, we can't escape things like reflection magic or runtime shenanigans.

You can clearly see that through the history of this project. I started with the simplest and idiomatic approach first and then went for some fancier abstractions later on.
Let me cook up a few hands on examples tomorrow to compare the manual wiring up approach with uber/fx.

I think I am doing a bad job conveying the use of SDK as an ERP builder, not just a stand alone product.

[mirolimsgd]

@diyor28 When I say explicit approach you should not think about that SWE manually will spend time to write boiler plate code. Actually simple, explicit approach with well defined interfaces and concreate types, most of boiler plate code (manual part) can be generated by AI. It can also generate tests and debug much easier for you when there is not much magic (many empty interfaces{}, reflection, runtime shenanigans) happens. I strongly think that SWE+AI could be more efficient with explicit approach then with "magical" one.

[diyor28]

@mirolimsgd let’s defer this for now. We’ll complete the critical SDK work first. Once Granite development starts, you can join and help drive the SDK improvements.
I think you might change your mind after using SDK as a dependency on a project