Tips for Reading Key Source Files in a New Project: Navigating the JFrame Go Framework

Start with main.go to find the Cobra CLI entry point, trace the server boot sequence through cmd/server/server.go, and study core/kernel/kernel.go to understand how JFrame orchestrates module lifecycles with dependency injection.

Reading key source files in a new project can feel overwhelming when facing a modular Go framework like JFrame. This guide breaks down the exact files you should read first and the order in which to read them, mapping the bootstrapping flow from CLI invocation to kernel initialization. By following these tips, you will understand how JFrame uses Cobra, Viper, and a custom dependency-injection kernel to manage modular applications.

JFrame Architecture at a Glance

JFrame is a modular Go framework that delegates control from a minimal entry point to a Cobra-based command-line interface. When you run jframe server, the framework executes a strict initialization sequence:

1. Configuration loading via Viper in conf/config.go.
2. Optional dependency setup (e.g., Sentry error tracking).
3. Kernel creation in core/kernel/kernel.go—the central lifecycle manager.
4. Module registration and startup using the slice defined in cmd/server/modList/list.go.

Essential Source Files for Understanding the Framework

main.go — The Entry Point

File: [main/main.go](https://github.com/juanjitech/jframe/blob/main/main/main.go)

This file contains the smallest possible main() function. It delegates immediately to cmd.Execute(), launching the Cobra command tree. Reading this file first confirms that the framework uses a command-pattern architecture and tells you where to find the actual command definitions.

cmd/server/server.go — The Server Command

File: [cmd/server/server.go](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go)

This is the most important command implementation. It parses CLI flags (such as -c for config path), initializes the Viper configuration, sets up Sentry if enabled, and constructs the kernel. The file demonstrates how the framework wires external libraries into the internal lifecycle.

conf/config.go — Configuration Management

File: [conf/config.go](https://github.com/juanjitech/jframe/blob/main/conf/config.go)

This file implements the Viper-based configuration system. It handles YAML file loading, environment-variable overrides (converting ORIGIN_VALUE to Origin.Value), and live reloads via viper.WatchConfig(). The global accessor conf.Get() returns the unmarshaled GlobalConfig struct defined in conf/vars.go.

core/kernel/kernel.go — The Application Kernel

File: [core/kernel/kernel.go](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go)

The kernel is the heart of JFrame. It manages the complete module lifecycle:

• RegMod – Registers module instances in an internal map.
• Init – Creates a root context and initializes the dependency injector using github.com/juanjiTech/inject/v2.
• StartModule – Executes five phases for each module: PreInit → Init → PostInit → Load → Start. Each phase runs in its own goroutine.
• Serve – Blocks until shutdown signals arrive.
• Stop – Waits for all modules to finish using a sync.WaitGroup.

Between lines 60 and 86, the kernel dynamically builds a Viper struct for each module’s configuration, enabling per-module config isolation without boilerplate.

core/kernel/module.go — The Module Interface

File: [core/kernel/module.go](https://github.com/juanjitech/jframe/blob/main/core/kernel/module.go)

This file defines the Module interface and the UnimplementedModule struct. The latter provides no-op defaults for all lifecycle hooks, allowing developers to embed it and override only the methods they need. The Hub struct passed to each hook contains the Injector (for dependency injection) and a namespaced Log (Zap logger).

core/logx/logger.go — Structured Logging

File: [core/logx/logger.go](https://github.com/juanjitech/jframe/blob/main/core/logx/logger.go)

logx abstracts Zap initialization to provide framework-wide logging. Key features include:

• NameSpace(name) – Returns a logger prefixed with the module or package name.
• PreInit() – Sets up a simple console logger for early boot stages before full configuration is loaded.
• Init(level) – Builds a production-grade logger that can write to rotating files and Tencent Cloud CLS when configured.

Understanding the Kernel Lifecycle

When tracing the boot sequence, look for this high-level flow in core/kernel/kernel.go:

RegMod → Init → StartModule → Serve → Stop

1. Registration – Modules are added to the kernel via RegMod before initialization begins.
2. Initialization – Init creates the root context and dependency injector.
3. Module Startup – StartModule runs each module through five phases (PreInit, Init, PostInit, Load, Start), with Start executing in its own goroutine.
4. Serving – The kernel blocks on Serve, waiting for OS signals.
5. Shutdown – Stop triggers graceful shutdown, waiting for all goroutines to exit via sync.WaitGroup.

Configuration Patterns and Live Reloading

JFrame uses Viper for configuration management with several advanced patterns:

• Environment Variable Mapping – Viper automatically maps environment variables like DATABASE_HOST to config keys like database.host.
• Live Reloading – viper.WatchConfig() monitors the YAML file for changes and reloads values without restarting the process.
• Per-Module Structs – The kernel dynamically constructs configuration structs for each module (lines 60-86 in kernel.go), allowing isolated configuration blocks under a single YAML file.

Access the global configuration anywhere using:

cfg := conf.Get()

Practical Examples for Exploring the Codebase

Starting the Server from the CLI

# Run the server with a specific configuration file

jframe server -c ./config.yaml

This command triggers the full initialization chain: configuration loading, kernel creation, and module startup.

Creating a Custom Module

Create a new file at mod/hello/mod.go:

package hello

import (
    "github.com/juanjiTech/jframe/core/kernel"
    "go.uber.org/zap"
)

type HelloModule struct {
    kernel.UnimplementedModule // Provides no-op defaults
}

// Name identifies the module for configuration and logging.
func (m *HelloModule) Name() string { return "hello" }

// Config returns a struct pointer for Viper to populate.
func (m *HelloModule) Config() any {
    return &Config{}
}

type Config struct {
    Greeting string `mapstructure:"greeting"` // e.g., "Hello, world!"
}

// Init runs after configuration is unmarshaled and injected.
func (m *HelloModule) Init(h *kernel.Hub) error {
    cfg := h.Injector.Get((*Config)(nil)).(*Config)
    h.Log.Infow("initializing", "greeting", cfg.Greeting)
    return nil
}

// Start runs asynchronously in its own goroutine.
func (m *HelloModule) Start(h *kernel.Hub) error {
    h.Log.Info("hello module started")
    return nil
}

Register the module in cmd/server/modList/list.go:

var ModList = []kernel.Module{
    // existing modules...
    &hello.HelloModule{},
}

Using the Namespaced Logger

import "github.com/juanjiTech/jframe/core/logx"

func ProcessData() {
    log := logx.NameSpace("dataProcessor")
    log.Info("processing started")
    
    // Later...
    log.Errorf("processing failed: %v", err)
}

Accessing Configuration Values

import "github.com/juanjiTech/jframe/conf"

func ConnectDatabase() {
    cfg := conf.Get()
    // Access fields defined in GlobalConfig
    fmt.Printf("Connecting to database at %s\n", cfg.Database.Host)
}

Summary

• Start at the entry point: main/main.go delegates to the Cobra CLI, making it the logical first file to read when exploring the codebase.
• Trace the server command: cmd/server/server.go demonstrates how JFrame wires together configuration, error tracking, and the kernel.
• Understand the kernel: core/kernel/kernel.go contains the lifecycle orchestration (RegMod → Init → StartModule → Serve → Stop) and dependency injection setup.
• Study the module interface: core/kernel/module.go defines the contract for extending JFrame via the UnimplementedModule embed pattern.
• Check configuration and logging: conf/config.go and core/logx/logger.go show how to access global state and structured logging throughout the application.

Frequently Asked Questions

What is the first file I should open when exploring the JFrame repository?

Start with main/main.go. This file contains the application entry point that immediately delegates to cmd.Execute(), launching the Cobra command tree. Reading this file first confirms the CLI-driven architecture and points you toward the command definitions in the cmd/ directory.

How does JFrame handle module initialization and dependency injection?

The kernel in core/kernel/kernel.go manages initialization through a five-phase lifecycle (PreInit, Init, PostInit, Load, Start) defined in StartModule. It uses github.com/juanjiTech/inject/v2 to create a dependency injection container during the Init phase, which is then passed to each module via the Hub struct. Modules retrieve dependencies through h.Injector.Get() and access configuration through their Config() method.

Where is configuration loaded and how can I access it in my code?

Configuration is loaded in conf/config.go using Viper, which reads YAML files and watches for live reloads. The package exposes a global accessor function conf.Get() that returns the unmarshaled GlobalConfig struct. You can call this function from any package after the kernel has initialized to access configuration values such as database connection strings or server ports.

What is the purpose of the UnimplementedModule struct?

UnimplementedModule, defined in core/kernel/module.go, provides no-op implementations for all optional lifecycle hooks in the Module interface. By embedding this struct in your custom module, you only need to override the specific methods you care about (such as Init or Start), reducing boilerplate and ensuring forward compatibility if new hooks are added to the interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}