Sprint 3: Service Migration Strategy

Overview

Sprint 3 involves migrating services (llm-api, mcp-tools, media-api, response-api) to use the centralized configuration system in pkg/config.

Challenge: Module Dependencies

The jan-server project uses a workspace structure where each service is a separate Go module:

services/llm-api has its own go.mod
services/mcp-tools has its own go.mod
pkg/config is at the root workspace level

Problem: Services cannot directly import github.com/janhq/jan-server/pkg/config without either:

Restructuring into a monorepo with shared pkg/
Publishing pkg/config as a separate module
Using Go workspace features to share the package

Recommended Approach

Phase 1: Environment Variable Alignment (Immediate)

Goal: Ensure all services use the same environment variable names as defined in pkg/config/types.go

Tasks:

Audit each service's env tags against pkg/config/types.go
Update service env tags to match centralized naming
Update Docker Compose files to use new env var names
Test each service independently

Example:

// Before (llm-api):
HTTPPort int `env:"HTTP_PORT"`

// After (aligned with pkg/config/types.go):
HTTPPort int `env:"HTTP_PORT"` // OK Already matches!

// Before (llm-api):
DBPostgresqlWriteDSN string `env:"DB_POSTGRESQL_WRITE_DSN,notEmpty"`

// After (should use components):
// Build from POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, etc.

Phase 2: Configuration Bridge Pattern (Sprint 3-4)

Goal: Create bridge functions that convert centralized config to service-specific config

Implementation:

// In services/llm-api/internal/config/bridge.go

import centralconfig "github.com/janhq/jan-server/pkg/config"

// FromCentralConfig converts pkg/config.Config to llm-api Config
func FromCentralConfig(central *centralconfig.Config) *Config {
 return &Config{
 HTTPPort: central.Services.LLMAPI.HTTPPort,
 DatabaseURL: buildDatabaseURL(central.Infrastructure.Database.Postgres),
 //... map all fields
 }
}

Benefits:

Gradual migration (can still use env vars)
Backward compatibility
Clear mapping between old and new config

Phase 3: Direct Integration (Sprint 5+)

Goal: Services directly use pkg/config types

Requires:

Go workspace configuration or monorepo restructuring
Update Wire providers to inject centralconfig.Config
Remove service-specific Config structs
Update all service code to use central types

Current Status

Sprint 2 Complete OK

pkg/config foundation built
Precedence system (100-600) implemented
All tests passing
Documentation complete

Sprint 3 Next Steps

Option A: Environment Variable Alignment (Recommended for Sprint 3)

OK Low risk, immediate value
OK No code restructuring needed
OK Can be done per-service incrementally
Tasks:

Create env var mapping document
Update docker compose.yml environment sections
Update service env tags
Test each service

Option B: Module Restructuring (Deferred to Sprint 4-5)

WARNING Requires Go workspace setup or monorepo migration
WARNING Higher risk, more invasive
WARNING Blocks other development during migration
Tasks:

Set up Go workspace in root
Update all go.mod files
Implement bridge pattern
Migrate services one by one
Comprehensive integration testing

Decision: Sprint 3 Scope

RECOMMENDATION: Focus on Option A for Sprint 3

Rationale:

Immediate Value: Standardizing env vars provides immediate operational benefits
Low Risk: No code changes, only configuration alignment
Foundation for Phase 2: Makes bridge pattern easier in Sprint 4
Testable: Can validate each service independently

Deliverables for Sprint 3: