Common Source Files to Examine First in the jFrame Go Framework

Start with main.go, cmd/server/server.go, conf/config.go, and core/kernel/kernel.go to understand how the jFrame binary boots, loads configuration, and orchestrates the module lifecycle.

When exploring the juanjitech/jframe repository—a modular Go framework for building server applications—certain source files provide a complete mental map of the architecture. Examining these entry points, configuration handlers, and core engine files first reveals how the framework initializes dependency injection, registers modules, and manages the application lifecycle.

Application Entry Point

The journey begins at the root of the repository.

main.go

In main.go, the application delegates immediately to the Cobra command hierarchy:

package main

import (
	"github.com/juanjiTech/jframe/cmd"
)

func main() {
	// Cobra root command parses flags and executes sub-commands
	cmd.Execute()
}

This file confirms that jFrame uses the Cobra CLI framework. The actual command definitions live under the cmd/ directory, making main.go a thin wrapper that merely hands control to the subcommand implementations.

CLI Command Implementation

Understanding how the server boots requires examining the primary command definition.

cmd/server/server.go

This file implements the jframe server command, which is the standard entry point for running the framework. The Run function inside this file orchestrates the entire bootstrap sequence:

// Inside the Run function of the server command
log.Info("loading config...")
viper.SetOptions(viper.ExperimentalBindStruct())
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
viper.AutomaticEnv()
err := conf.LoadConfig(configPath)   // ← reads config.yaml or ENV vars
// ...
k := kernel.New(kernel.Config{})    // ← creates the core engine
k.Map(&conn, &tcpMux)               // registers low-level resources
k.RegMod(modList.ModList...)         // registers all enabled modules
k.Init()
k.StartModule()

This sequence reveals the framework's startup flow: load configuration → instantiate kernel → map dependencies → register modules → initialize and start. Understanding this file is essential for debugging startup failures or adding new CLI flags.

Configuration Management

Configuration parsing happens in a dedicated package that defines the schema for all runtime options.

conf/config.go

This file defines the GlobalConfig struct and the LoadConfig function that unmarshals YAML files and environment variables into Go structs:

type GlobalConfig struct {
	Port        string `mapstructure:"port"`
	SentryDsn   string `mapstructure:"sentry_dsn"`
	// … other fields …
}

func LoadConfig(configPath ...string) error {
	// Viper reads the file (or defaults) and unmarshals into GlobalConfig
	if err := viper.Unmarshal(serveConfig); err != nil {
		return errors.Wrap(err, "config unmarshal failed")
	}
}

The use of mapstructure tags indicates that jFrame uses the Viper configuration library. This file serves as the single source of truth for which configuration keys the framework recognizes, making it the first place to check when modifying runtime behavior.

Core Kernel and Lifecycle

The engine that manages dependency injection and module orchestration resides in the core package.

core/kernel/kernel.go

This file implements the Engine struct and its lifecycle methods. The StartModule method is particularly critical as it defines the exact sequence of hook calls during startup:

func (e *Engine) StartModule() error {
	// 1️⃣ Unmarshal each module’s config from Viper
	// 2️⃣ Call PreInit, Init, PostInit, Load, Start for every registered module
	// 3️⃣ Run each module’s Start in its own goroutine
}

Understanding this lifecycle order (PreInit → Init → PostInit → Load → Start) is essential for developers writing custom modules, as it determines when dependencies are available and when initialization logic should execute.

Module System and Utilities

After understanding the core, examine how modules plug into the system and what utilities support them.

mod/example/mod.go

This file provides a template for module registration. It demonstrates how individual modules implement the lifecycle hooks defined in the kernel and register themselves with the engine.

pkg/utils/http.go

This file contains utility helpers for URL manipulation, MIME detection, and other HTTP-related functions that modules commonly depend on. Examining this file reveals the shared library code available to all modules.

Project Metadata

Finally, review the module definition files to understand dependencies and versioning.

go.mod and go.sum

These files declare the module path (github.com/juanjiTech/jframe) and all external dependencies. Checking go.mod reveals which libraries the framework relies on (such as Cobra, Viper, and various middleware packages) and the minimum Go version required.

Summary

• Start at main.go to confirm the CLI framework and entry point delegation.
• Study cmd/server/server.go to understand the bootstrap sequence from configuration loading to kernel startup.
• Review conf/config.go to see the configuration schema and Viper integration.
• Analyze core/kernel/kernel.go to learn the module lifecycle and dependency injection mechanism.
• Check go.mod to identify external dependencies and Go version requirements.

Frequently Asked Questions

What is the first file to open when exploring jFrame?

Open main.go at the repository root. This file contains the main function that immediately delegates to cmd.Execute(), confirming that jFrame uses the Cobra CLI framework and directing you to the cmd/ directory for actual command implementations.

How does jFrame load configuration files?

jFrame uses the Viper configuration library. The conf/config.go file defines a GlobalConfig struct with mapstructure tags, and the LoadConfig function unmarshals YAML files or environment variables into this struct. Environment variables are automatically mapped by replacing dots with underscores.

What is the module lifecycle in jFrame?

According to core/kernel/kernel.go, modules follow a strict initialization sequence: PreInit, Init, PostInit, Load, and finally Start. The kernel executes each hook across all registered modules in order, with the final Start phase running in separate goroutines for concurrency.

Where are CLI commands defined in jFrame?

CLI commands reside in the cmd/ directory. The server command, which boots the framework, is implemented in cmd/server/server.go. This file contains the Cobra command definition and the Run function that orchestrates configuration loading, kernel instantiation, and module startup.

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