Track 2: Full Framework Examples

Use Lokstra as a complete application framework (like NestJS, Spring Boot)
Time: 6-10 hours • Level: Intermediate to Advanced

📚 What You’ll Learn

This track covers the complete Lokstra framework with dependency injection, auto-generated routers, and deployment patterns:

✅ Annotation-based service development (@RouterService, @Inject, @Route)
✅ Auto-generated REST routers from service methods
✅ Type-safe dependency injection (eager loading)
✅ Configuration-driven deployment (YAML or Code)
✅ Monolith → Microservices migration (zero code changes)
✅ External service integration
✅ Production-ready patterns

Full enterprise features - Annotations, DI, auto-router, multi-deployment!

🎯 Learning Path

01 - Enterprise Router Service (Annotations) ⏱️ 2-3 hours ⭐⭐⭐

START HERE - RECOMMENDED: Annotation-driven router services with auto-generated code.

// Write this:
// @RouterService name="user-service", prefix="/api"
type UserServiceImpl struct {
    // @Inject "user-repository"
    UserRepo domain.UserRepository
}

// @Route "GET /users/{id}"
func (s *UserServiceImpl) GetByID(p *GetUserRequest) (*User, error) {
    return s.UserRepo.GetByID(p.ID)
}

// Get this auto-generated:
// ✅ Service factory with eager dependency injection
// ✅ Remote HTTP proxy for microservices
// ✅ Router registration with path conventions
// ✅ Direct dependency access (no wrappers)

What you’ll learn:

Lokstra Annotations - @RouterService, @Inject, @Route
Auto-code generation with lokstra.Bootstrap()
Zero boilerplate router services
Hot reload in dev mode (auto-regenerates on changes)
Type-safe eager dependency injection
Microservice-ready architecture

Why this is the best starting point:

✅ 83% less code - No manual factory/proxy/registration
✅ Type-safe - Compiler-enforced correctness
✅ Fast development - Add method → auto-registered
✅ Production-ready - Zero runtime overhead
✅ Refactoring-friendly - Change once, update everywhere
✅ Modern Go - Embraces code generation best practices

Perfect for: Enterprise apps, microservices, teams wanting rapid development

02 - Multi-Deployment (YAML Config) ⏱️ 2-3 hours ⭐

One binary, multiple deployment topologies with YAML configuration.

# config.yaml
service-definitions:
  user-service:
    type: user-service-factory
    depends-on: [database]

deployments:
  monolith:
    servers:
      api-server:
        addr: ":8080"
        published-services: [user-service, order-service]
  
  microservices:
    servers:
      user-server:
        addr: ":8001"
        published-services: [user-service]
      order-server:
        addr: ":8002"
        published-services: [order-service]

# Same code, different deployment!
go run . -server=monolith.api-server
go run . -server=microservices.user-server

What you’ll learn:

YAML-based configuration
Auto-router generation from services
Service interfaces (local vs remote)
Proxy pattern for remote calls
Monolith vs microservices topology

🔍 Framework Comparison:
Lokstra vs NestJS vs Spring Boot - See how the same microservice application would be implemented in different frameworks with detailed code examples and trade-offs.

03 - Multi-Deployment (Pure Code) ⏱️ 30 min

Same as Example 02, but 100% code-based (no YAML).

// Type-safe configuration in Go
lokstra_registry.RegisterLazyService("user-service", "user-service-factory",
    map[string]any{"depends-on": []string{"database"}})

lokstra_registry.RegisterDeployment("monolith", &lokstra_registry.DeploymentConfig{
    Servers: map[string]*lokstra_registry.ServerConfig{
        "api-server": {
            Addr: ":8080",
            PublishedServices: []string{"user-service", "order-service"},
        },
    },
})

What you’ll learn:

Code-based configuration (vs YAML)
Type safety and IDE autocomplete
Dynamic configuration (conditionals, loops)
When to use code vs YAML

Benefits:

✅ Compile-time type checking
✅ IDE autocomplete
✅ Refactoring-friendly
✅ Single language (no YAML)

04 - External Services ⏱️ 1-2 hours ⭐

Integrate third-party APIs (payment gateways, email, etc.) as Lokstra services.

// Clean service wrapper
type PaymentServiceRemote struct {
    proxyService *proxy.Service
}

func (s *PaymentServiceRemote) CreatePayment(p *CreatePaymentParams) (*Payment, error) {
    return proxy.CallWithData[*Payment](s.proxyService, "CreatePayment", p)
}

// Metadata in registry (single source of truth)
lokstra_registry.RegisterServiceType(
    "payment-service-remote-factory",
    nil, PaymentServiceRemoteFactory,
    deploy.WithResource("payment", "payments"),
    deploy.WithRouteOverride("CreatePayment", "POST /payments"),
    deploy.WithRouteOverride("Refund", "POST /payments/{id}/refund"),
)

What you’ll learn:

External service integration
proxy.Service for structured APIs
Route overrides for custom endpoints
Service metadata patterns
Real-world API integration (Stripe, SendGrid, etc.)

05 - Remote Router ⏱️ 30 min

Quick API integration without service wrappers.

type WeatherService struct {
    weatherAPI *proxy.Router
}

func (s *WeatherService) GetWeather(city string) (*Weather, error) {
    var weather Weather
    err := s.weatherAPI.DoJSON("GET", fmt.Sprintf("/weather/%s", city), 
        nil, nil, &weather)
    return &weather, err
}

// Simple factory with URL
func WeatherServiceFactory(deps, cfg map[string]any) any {
    url := cfg["url"].(string)
    return &WeatherService{
        weatherAPI: proxy.NewRemoteRouter(url),
    }
}

What you’ll learn:

proxy.Router for simple HTTP calls
When to use Router vs Service
Quick API prototyping
Direct HTTP calls vs structured services

Use for: Weather APIs, currency converters, one-off integrations

🚀 Running Examples

cd 02-multi-deployment-yaml  # or 03

# Option 1: Monolith
go run . -server=monolith.api-server

# Option 2: Microservices (2 terminals)
go run . -server=microservices.user-server   # Terminal 1
go run . -server=microservices.order-server  # Terminal 2

External Service Examples (04):

cd 04-external-services

# Terminal 1: Mock gateway
cd mock-payment-gateway && go run main.go

# Terminal 2: Main app
cd .. && go run main.go

📊 Skills Progression

Example 01:  Service Architecture
    → Services, DI, factory pattern

Example 02:  YAML Configuration
    → Auto-router, multi-deployment, YAML config

Example 03:  Code Configuration
    → Pure code config, type safety

Example 04:  External Integration
    → proxy.Service, route overrides, real-world patterns

Example 05:  Quick Integration
    → proxy.Router, simple HTTP calls

Example 07:  Annotation-Driven (RECOMMENDED)
    → @RouterService, @Inject, @Route, auto-generation, zero boilerplate

🎯 After This Track

Continue Learning:

Framework Guide - Advanced DI patterns
Configuration Reference - Full YAML schema
Production Deployment - Microservices patterns

Build Real Projects:

Apply multi-deployment patterns
Integrate external services
Build microservices architectures
Use auto-router for rapid development

💡 When to Use Full Framework

Perfect for:

✅ Enterprise applications
✅ Microservices architectures
✅ Teams wanting DI and auto-router
✅ Configuration-driven deployment
✅ Scalable, maintainable codebases
✅ Rapid development with annotations

Framework advantages:

Type-safe dependency injection
Auto-generated REST routers
Zero-code deployment changes
Service abstraction (local/remote)
Production-ready patterns
83% less boilerplate with annotations

🔄 Comparison with Other Frameworks

Lokstra Framework is similar to:

NestJS (Node.js) - DI, decorators, modular architecture
Spring Boot (Java) - Enterprise DI, auto-configuration
Uber Fx (Go) - Dependency injection framework
Buffalo (Go) - Full-stack web framework

Lokstra advantages:

✅ Type-safe generics (no any)
✅ Auto-router from service methods
✅ Zero-code deployment topology changes
✅ Code or YAML configuration (your choice)
✅ Annotation-driven development (Example 01) - Like NestJS decorators, but with Go code generation

📖 Detailed Framework Comparisons:

Practical Example: Microservices in 3 Frameworks - Same app, different approaches
Lokstra vs NestJS - TypeScript framework comparison
Lokstra vs Spring Boot - Java framework comparison

💡 Which Example Should I Start With?

For Quick Start → Example 01 (01_enterprise_router_service) ⭐⭐⭐

STRONGLY RECOMMENDED for all developers - annotation-driven, minimal boilerplate

// @RouterService, @Inject, @Route - that's it!
// Everything auto-generated with lokstra.Bootstrap()

This is the modern way to build Lokstra apps!

For Configuration Deep Dive → Examples 02-03

After mastering annotations, explore YAML vs code configuration

For Real-World Integration → Examples 04-05

External APIs, payment gateways, third-party services

Ready to start? → 01 - Enterprise Router Service (Annotations) ⭐⭐⭐ START HERE

Coming from Router Track? Full Framework eliminates manual routing with @RouterService annotations!