theplant.lifecycle-setup

Prompt file imported from theplant/speckit-starter-go (.windsurf/workflows/theplant.lifecycle-setup.md). Fill in {{arguments}} before use. Copyright stays with the author.

User Input

{{arguments}}

You MUST consider the user input before proceeding (if not empty).

Goal

Help project setup standardized service startup architecture with:

• Configuration management with confx (embedded defaults + file + env + flags)
• Lifecycle management with lifecycle (dependency injection, graceful shutdown)
• Provider pattern (each component as independent provider function)

This workflow focuses on framework and patterns, not specific business logic or directory structures.

Core Principles

1. Configuration First: All runtime configuration through confx, never scattered os.Getenv() calls
2. Provider Independence: Each component is a provider function with explicit dependencies
3. Lifecycle Managed: All long-running components managed by lifecycle
4. Flexible Structure: Directory structure adapts to project, not the other way around
5. Minimal Dependency: Only introduce dependencies that are actually used by other providers in the lifecycle

Execution Steps

Step 1: Analyze Current Project

1. Examine existing structure

   • Identify entry point(s) (main.go, cmd/*/main.go)
   • Find existing configuration patterns (env vars, config files, hardcoded values)
   • List components that should become providers (DB, services, servers, etc.)
   • Check for existing confx/lifecycle usage

2. Propose directory structure

   Based on analysis, propose a structure. Common patterns:

   Pattern	When to Use
   Single main.go with inline config/providers	Small demos, simple services
   cmd/main.go + pkg/app/config.go + pkg/app/provider.go	Medium services
   cmd/{service}/main.go + cmd/{service}/setup/ + pkg/app/	Multi-service projects

   Important: Each project should have a single centralized package (e.g., pkg/app/ or app/) that provides:

   • Config structs and InitializeXxxConfig functions
   • Provider functions
   • Embedded default YAML configuration files

   This package serves as the single source of truth for dependency injection, whether for the project's own service startup or when other projects depend on this project's services.

   Service Startup Principles:

   • cmd/ is responsible for service startup, defining a Setup that lists required providers
   • main.go creates a lifecycle, loads config from the centralized package, then invokes Setup
   • For single service: one lifecycle with providers from the centralized package
   • For multiple services in one cmd: define a parent lifecycle containing child lifecycles for each service. If service B depends on a value from service A after startup, use lc.Resolve() on service A's lifecycle to obtain it

   ASK USER to confirm the proposed structure before proceeding.

3. Identify configuration items

   Extract all configurable values:

   • Database connection strings
   • Server addresses/ports
   • External service credentials (OAuth, API keys)
   • Feature flags
   • Timeouts and limits

⛔ Step 1 Checkpoint - MANDATORY

You MUST complete the following before proceeding to Step 2:

1. Output your analysis to the user:

   ## Step 1 Analysis Results
   
   ### Existing Structure
   - Entry point(s): [list files]
   - Existing config patterns: [describe]
   - Components to become providers: [list]
   - confx/lifecycle usage: [yes/no, describe]
   
   ### Proposed Directory Structure
   - Pattern: [single main.go | cmd + pkg/app | multi-service]
   - Files to create/modify: [list]
   
   ### Configuration Items Identified
   - [list all configurable values]
   

2. If any issues found → Generate your proposed solution and include it in the output.

3. Continue to Step 2 immediately after outputting the analysis. Do NOT wait for user confirmation.

Step 2: Create Configuration Structure

1. Define Config struct

   type Config struct {
       // Infrastructure configs (use qor5/x types when available)
       Log      slogx.Config         `confx:"log"`
       Database gormx.DatabaseConfig `confx:"database"`
       HTTP     httpx.ServerConfig   `confx:"http"`
   
       // Business configs
       // ... project-specific configs
   }

   Rules:

   • Use confx:"fieldName" tag (camelCase)
   • Use usage:"description" tag for documentation
   • Use validate:"required" for mandatory fields
   • Group infrastructure configs first, then business configs

2. Create embedded default config

   Create embed/default.yaml (or similar path based on project structure):

   log:
     level: info
   database:
     host: localhost
     port: 5432
     # NO passwords or production values
   http:
     addr: ":8080"

   Rules:

   • Provide complete defaults for local development
   • NO sensitive information (passwords, API keys)
   • NO production addresses
   • Service should start with defaults alone (for local dev)

3. Implement config loader

   //go:embed embed/default.yaml
   var defaultConfigYAML string
   
   func InitializeConfig(opts ...confx.Option) (confx.Loader[*Config], error) {
       def, err := confx.Read[*Config]("yaml", strings.NewReader(defaultConfigYAML))
       if err != nil {
           return nil, errors.Wrap(err, "failed to load default config")
       }
       return confx.Initialize(def, opts...)
   }

⛔ Step 2 Checkpoint - MANDATORY

STOP. You MUST verify the following before proceeding to Step 3:

1. Config struct verification:

   • All fields use confx:"fieldName" tag (camelCase)
   • Required fields have validate:"required" tag
   • Infrastructure configs grouped before business configs

2. Default config verification:

   • embed/default.yaml exists (or equivalent path)
   • NO sensitive information (passwords, API keys)
   • NO production addresses
   • Service can start with defaults alone

3. Output to user:

   ## Step 2 Verification
   
   ### Config Struct
   - File: [path]
   - Fields: [list with tags]
   
   ### Default Config
   - File: [path]
   - Contains sensitive info: NO ✅ / YES ❌
   - Contains production addresses: NO ✅ / YES ❌
   

If any check fails → FIX before proceeding.

Step 3: Define Provider Functions

Each component should be a provider function following these rules:

1. Naming conventions:

   • Single-function provider: Setup{Component} - returns a single component
   • Multi-function provider: Setup{Component} - uses []any slice containing multiple related providers
   • Serving-related: Setup{Protocol}Serving - combines Listener + Server

2. Provider function signature single-function provider:

   // Dependencies as parameters, output as return value
   func SetupXXX(ctx context.Context, lc *lifecycle.Lifecycle, conf *Config, dep1 Type1, dep2 Type2) (*XXX, error)

   multiple-function provider: // use []any slice

   var SetupXXX = []any{
    func(conf *Config) *XXX { return &conf.XXX },
    SetupXXX,
   }

   Serving combination:

   // Serving combination
   var SetupXXXServing = []any{
       SetupXXXListener,
       SetupXXXServer,
   }

   Internal service provider (registers service to existing server):

   var SetupLedgerServices = []any{
       // Extract service config from main config
       func(conf *Config) *ledger.Config {
           return &conf.Ledger
       },
       // Construct internal service and register to server
       func(lc *lifecycle.Lifecycle, config *ledger.Config, grpcServer *grpc.Server) (*ledger.LedgerService, error) {
           service, err := ledger.NewService(config)
           if err != nil {
               return nil, err
           }
           ledgerv1.RegisterLedgerServiceServer(grpcServer, service)
           return service, nil
       },
   }

   • Input: Dependencies declared via function parameters
   • Output: Concrete type (NOT any), with optional error
   • Accept *lifecycle.Lifecycle if needs lifecycle hooks
   • Accept context.Context as first param if needed

3. Provider categories

   Category	Examples	Notes
   Infrastructure	Logger, ErrorNotifier	Usually no lifecycle hooks
   Data Layer	Database, Cache, MessageBus	Register cleanup in lifecycle
   External Clients	gRPC clients, HTTP clients	May need connection management
   Business Services	Domain services	Depend on data layer
   Servers	HTTP server, gRPC server	HaveListener, HaveServe, Have middleware
   One-time Tasks	Migrator, Seeder	Return marker type after completion

4. One-time task provider pattern (Migrate)

   type Migrator struct{}
   
   func Migrate(ctx context.Context, db *gorm.DB) (*Migrator, error) {
       if err := db.AutoMigrate(AllModels()...); err != nil {
           return nil, errors.Wrap(err, "failed to migrate")
       }
       return &Migrator{}, nil
   }

• Return a marker type (e.g., *Migrator) so other providers can depend on it
• Use dependency to enforce execution order (e.g., Seeder depends on Migrator)

5. Worker Service Rule

   For background workers and message consumers that need lifecycle management:

   var SetupWorkerService = []any{
       // Extract worker-specific config from main config
       func(conf *Config) *WorkerConfig {
           return &conf.Worker
       },
       // Create worker and register to lifecycle
       func(lc *lifecycle.Lifecycle, conf *WorkerConfig, db *gorm.DB, bus bus.Bus, conn ExternalConn) (*Worker, error) {
           // Create gRPC client inside provider when this is the terminal consumer
           client := externalv1.NewExternalServiceClient(conn)
   
           worker, err := NewWorker(conf, db, bus, client)
           if err != nil {
               return nil, err
           }
   
           // Register worker using goquex.NewWorkerService
           // For workers with Start(ctx) (WorkerController, error) signature
           lc.Add(goquex.NewWorkerService(worker.Start).WithName("worker-name"))
           return worker, nil
       },
   }

   Key points:

   • Use []any slice to group config extraction and worker creation
   • Create gRPC client inside provider when it's the terminal consumer
   • Use goquex.NewWorkerService for workers that return WorkerController
   • Use .WithName() to identify the worker in logs

6. gRPC Connection vs Client rule

   When a provider needs to call an external gRPC service:

   • Define typed Conn for each external service
   • Create SetupXxxClient provider ONLY when the client is shared by multiple providers
   • Create client inside provider when it's the terminal consumer

   ✅ Pattern A: Shared client (multiple consumers)

   When multiple providers need the same client:

   // Define typed connection
   type ConsentConn grpc.ClientConnInterface
   
   func SetupConsentConn(lc *lifecycle.Lifecycle, conf *Config) (ConsentConn, error) {
       return grpcx.SetupConnFactory("consent-conn")(lc, &conf.Consent)
   }
   
   // Create shared client provider - multiple providers depend on this
   func SetupConsentServiceClient(conn ConsentConn) consentv1.ConsentServiceClient {
       return consentv1.NewConsentServiceClient(conn)
   }
   
   // Multiple providers depend on the shared client
   func SetupServiceA(client consentv1.ConsentServiceClient) *ServiceA { ... }
   func SetupServiceB(client consentv1.ConsentServiceClient) *ServiceB { ... }

   ✅ Pattern B: Terminal consumer (single consumer)

   When only one provider needs the client, create it inside:

   var SetupConsumerService = []any{
       func(conf *Config) *ConsumerConfig { return &conf.Consumer },
       func(lc *lifecycle.Lifecycle, conf *ConsumerConfig, conn ExternalConn) (*Consumer, error) {
           // Create client inside - this is the only consumer
           client := externalv1.NewExternalServiceClient(conn)
           consumer, err := NewConsumer(conf, client)
           // ...
       },
   }

   ❌ Anti-pattern: Creating unused shared client

   // DON'T create SetupXxxClient if only one provider uses it
   func SetupExternalClient(conn ExternalConn) externalv1.Client { ... }
   
   // Only one consumer - should create client inside instead
   func SetupConsumer(client externalv1.Client) *Consumer { ... }

7. Verify provider dependencies (Minimal Dependency Principle)

   After creating a provider, verify that:

   • Every provider's return type is used by at least one other provider in the lifecycle, OR
   • The provider registers lifecycle hooks (OnStart/OnStop), OR
   • The provider performs a one-time task (like migration)

   If a provider's return type is not depended upon by any other provider and it doesn't register lifecycle hooks, it should NOT be added to the provider list.

   Verification checklist:

   For each new provider SetupXXX that returns *XXX:
   1. Search the codebase: Is *XXX used as a parameter in any other provider?
   2. Does SetupXXX call lc.Add() or lc.Append() to register lifecycle hooks?
   3. Is SetupXXX a one-time task (migration, seeding)?
   
   If ALL answers are NO → Do NOT add this provider to the lifecycle
   

   ✅ Valid reasons to add a provider:

   • Its return type is a dependency of another provider
   • It registers lifecycle hooks (starts a server, worker, etc.)
   • It performs a one-time initialization task

   ❌ Invalid reason:

   • "It might be useful later" - violates minimal dependency principle
   • "Other services might need it" - add it when actually needed

⛔ Step 3 Checkpoint - MANDATORY

STOP. You MUST complete the following verification for EACH provider before proceeding to Step 4:

## Step 3 Provider Verification

For each provider, verify ALL applicable rules:

| Provider | Returns | Format | gRPC Client | Lifecycle |
|----------|---------|--------|-------------|-----------|
| (name)   | (type)  | (A/B)  | (C/D/N/A)   | (E/F/N/A) |

### Format Check:
- **A**: Uses `var SetupXXX = []any{...}` for multi-function providers ✅
- **B**: Uses `func SetupXXX(...) (Type, error)` for single-function providers ✅

### gRPC Client Check (if calls external gRPC):
- **C**: Shared client - has `SetupXxxClient` provider, multiple consumers depend on it ✅
- **D**: Terminal consumer - creates client inside provider, no other consumer needs it ✅

### Lifecycle Check (if needs lifecycle management):
- **E**: Uses `lc.Add(goquex.NewWorkerService(...))` for workers ✅
- **F**: Uses `lc.Add()` with custom Actor/Service for other cases ✅

### Minimal Dependency Check:
- [ ] Return type is used by another provider, OR
- [ ] Registers lifecycle hooks via `lc.Add()`, OR
- [ ] Performs one-time task (migration, seeding)

If ANY check fails → FIX before proceeding.

Step 4: Assemble Providers

1. Create setup variable

   IMPORTANT: Setup MUST be a var of type []any, NOT a function.

   package setup
   
   import "github.com/yourproject/pkg/app"
   
   // Setup is a slice of providers - NOT a function
   var Setup = []any{
       // 1. Infrastructure
       app.SetupI18N,
       app.SetupLogger,
       app.SetupErrorNotifier,
   
       // 2. External connections
       app.SetupCIAMConn,
       app.SetupConsentConn,
       app.SetupConsentServiceClient,  // Shared client (multiple consumers)
   
       // 3. Servers
       app.SetupGRPCServing,
       app.SetupHTTPServing,
   
       // 4. Data layer
       app.SetupDatabase,
       app.SetupGoBus,
   
       // 5. Business services
       app.SetupLoyaltyServices,
       app.SetupLoyaltyServiceConn,
       app.SetupLoyaltyServiceClient,  // Shared client
   
       // 6. Workers
       app.SetupConsumerService,  // Terminal consumer, creates client inside
   }

   ❌ Incorrect pattern:

   // DON'T use function that calls lc.Provide manually
   func Setup(lc *lifecycle.Lifecycle, conf *Config) {
       lc.Provide(...)
   }

2. Provider ordering rules

   • Dependencies must come before dependents
   • Group by category for readability
   • One-time tasks before services that depend on migrated schema

⛔ Step 4 Checkpoint - MANDATORY

STOP. You MUST verify provider ordering and usage before proceeding to Step 5:

1. Dependency order check: For each provider, verify all its dependencies appear earlier in the list.

2. Unused provider check: Verify all provider functions defined in the package are included in the Setup slice. There should be NO unused provider functions.

3. Output to user:

   ## Step 4 Provider Order & Usage Verification
   
   | # | Provider | Dependencies | All deps appear earlier? | Included in Setup? |
   |---|----------|--------------|-------------------------|--------------------|
   | 1 | (name)   | (list)       | ✅/❌                    | ✅/❌               |
   | 2 | (name)   | (list)       | ✅/❌                    | ✅/❌               |
   ...
   
   ### Unused Provider Functions Check
   - All `Setup*` functions in package are used: ✅/❌
   - Unused functions found: [list or "None"]
   

If ANY row has ❌ → Fix before proceeding:

• Dependency order issue → Reorder providers
• Unused provider → Either add to Setup or remove the function

Step 5: Create Entry Point

confx.Initialize internally creates a pflag.FlagSet and registers a -c/--config flag automatically. You do NOT need to manually create a FlagSet or define a confPath variable.

1. Standard main.go pattern (for long-running services)

   package main
   
   import (
       "context"
       "log"
       "os"
   
       "github.com/qor5/confx"
       "github.com/theplant/inject/lifecycle"
   
       "github.com/yourproject/cmd/myservice/setup"
       "github.com/yourproject/pkg/app"
   )
   
   const envPrefix = "MYAPP_"
   
   func main() {
       confLoader, err := app.InitializeConfig(confx.WithEnvPrefix(envPrefix))
       if err != nil {
           log.Fatalf("Failed to initialize config: %v", err)
       }
   
       if err := lifecycle.Serve(context.Background(),
           lifecycle.SetupSignal,
           func(ctx context.Context) (*app.Config, error) {
               return confLoader(ctx, "")
           },
           setup.Setup,
       ); err != nil {
           log.Fatalf("Failed to serve: %v", err)
           os.Exit(1)
       }
   }

2. Separate command pattern (e.g., migrate-only, one-shot tasks)

   // cmd/migrate/main.go
   package main
   
   import (
       "context"
       "log"
       "log/slog"
   
       "github.com/qor5/confx"
       "github.com/qor5/x/v3/gormx"
   
       "github.com/yourproject/pkg/app"
   )
   
   const envPrefix = "MYAPP_"
   
   func main() {
       ctx := context.Background()
   
       confLoader, err := app.InitializeMigrateConfig(confx.WithEnvPrefix(envPrefix))
       if err != nil {
           log.Fatalf("Failed to initialize config: %v", err)
       }
   
       conf, err := confLoader(ctx, "")
       if err != nil {
           log.Fatalf("Failed to load config: %v", err)
       }
   
       db, closer, err := gormx.Open(ctx, &conf.Database)
       if err != nil {
           log.Fatalf("Failed to open database: %v", err)
       }
       defer func() {
           if err := closer.Close(); err != nil {
               slog.Error("Failed to close database connection", "error", err)
           }
       }()
   
       if _, err = app.Migrate(ctx, db, &conf.Ledger); err != nil {
           log.Fatalf("Failed to run migrations: %v", err)
       }
   
       slog.Info("Migrations completed successfully")
   }

⛔ Step 5 Checkpoint - MANDATORY

STOP. You MUST verify the entry point before proceeding to Step 6:

1. main.go verification:

   • Does NOT manually create pflag.FlagSet (confx handles this internally)
   • Does NOT call pflag.Parse() manually (confx handles this internally)
   • Does NOT define confPath variable (confx registers -c/--config automatically)
   • Passes empty string to confLoader: confLoader(ctx, "")
   • For services: includes lifecycle.SetupSignal for graceful shutdown
   • No business logic in main.go

2. Output to user:

   ## Step 5 Entry Point Verification
   
   - File: [path]
   - Manual pflag.FlagSet creation: NO ✅ / YES ❌
   - Manual pflag.Parse() call: NO ✅ / YES ❌
   - Manual confPath variable: NO ✅ / YES ❌
   - Passes empty string to confLoader: ✅/❌
   - Has lifecycle.SetupSignal (services only): ✅/❌/N/A
   - Business logic in main: NO ✅ / YES ❌
   

If ANY check fails → FIX before proceeding.

Step 6: Verify Setup

1. Build check // turbo

   go build ./...

2. Run with defaults

   ./cmd/myapp/myapp

3. Run with config file

   ./cmd/myapp/myapp -c config.yaml

⛔ Step 6 Checkpoint - MANDATORY

You MUST verify the build succeeds AND the service starts correctly:

1. Run build check: // turbo

   go build ./...

2. If build fails → Fix the errors immediately, then re-run build check.

3. Run service startup check:

   After successful build, start the service to verify it initializes correctly:

   # Run the service in background, wait for startup, then check if it's running
   timeout 10s ./cmd/myapp/myapp &
   sleep 3
   # Check if process is still running (not crashed)
   # If using HTTP server, can also curl health endpoint:
   # curl -f http://localhost:8080/healthz || echo "Health check failed"

   Verification criteria:

   • Service starts without immediate crash
   • No panic or fatal errors in startup logs
   • If HTTP server: health endpoint responds
   • If gRPC server: can establish connection

4. If startup fails → Analyze error logs, fix the issue, rebuild and re-test.

5. Output to user:

   ## Step 6 Final Verification
   
   - Build result: SUCCESS ✅ / FAILED ❌
   - Service startup: SUCCESS ✅ / FAILED ❌
   - Startup logs: [brief summary or "Clean startup"]
   - If failed initially, fixes applied: [describe fixes]
   

6. Continue to mark task complete after successful build AND startup. Do NOT wait for user confirmation.

Configuration Priority (Low to High)

1. Embedded defaults (embed/default.yaml)
2. Config file (-c/--config)
3. Environment variables ({PREFIX}_FIELD_NAME)
4. Command-line flags

AI Agent Requirements

MUST DO

• Analyze existing project structure before proposing changes
• ASK USER to confirm directory structure proposal
• Use confx for all configuration (no scattered os.Getenv())
• Each component as independent provider function
• Use lifecycle for dependency injection and lifecycle management
• Provider functions return concrete types with explicit dependencies
• One-time tasks (migrate/seed) return marker types for dependency ordering
• Include lifecycle.SetupSignal for graceful shutdown
• Setup must be var Setup = []any{...} - not a function
• Use goquex.NewWorkerService for workers that return WorkerController
• Verify minimal dependency principle - only add providers that are actually used

MUST NOT

• Assume fixed directory structure without analysis
• Use global variables in providers
• Include business logic in main.go
• Call pflag.Parse() manually (confx handles it)
• Hardcode configuration values that should be configurable
• Use func Setup(lc, conf) pattern - Setup must be var Setup = []any{...}
• Create custom Service wrapper types when goquex.NewWorkerService or similar utilities exist
• Create SetupXxxClient providers for terminal consumers - create client inside provider instead
• Add providers whose return type is not depended upon - unless they register lifecycle hooks or perform one-time tasks

Common Infrastructure Packages

Core Packages

Server & Network Packages

Data & Messaging Packages

Observability & Error Handling Packages

Request Processing Packages

Utility Packages