# Key Source Files in JFrame: A Complete Guide to the Go Framework Architecture

> Explore the key source files in jframe, the Go framework. Understand the entry point, server command, configuration, kernel, and logging for efficient development.

- Repository: [卷鸡科技/jframe](https://github.com/juanjitech/jframe)
- Tags: architecture
- Published: 2026-03-05

---

**The key source files in jframe are organized into six main areas: entry point ([`main.go`](https://github.com/juanjitech/jframe/blob/main/main.go)), server command ([`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go)), configuration ([`conf/config.go`](https://github.com/juanjitech/jframe/blob/main/conf/config.go)), kernel ([`core/kernel/kernel.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go)), logging ([`core/logx/logger.go`](https://github.com/juanjitech/jframe/blob/main/core/logx/logger.go)), and modules (`mod/` directory), forming a modular Go framework for building services.**

JFrame is a lightweight **Go** framework designed for building services through a command-line entry point and modular architecture. Understanding the key source files in jframe is essential for developers who want to extend the framework, debug issues, or implement custom modules. This guide breaks down the critical files that handle everything from CLI parsing to module lifecycle management.

## Entry Point and CLI Structure

### main.go - The Application Entry Point

The journey begins in **[`main.go`](https://github.com/juanjitech/jframe/blob/main/main.go)** at the repository root. This file serves as the minimal entry point that immediately delegates to the Cobra-based command system.

```go
// main.go
package main

import "github.com/juanjitech/jframe/cmd"

func main() {
    cmd.Execute()
}

```

This delegation pattern keeps the root [`main.go`](https://github.com/juanjitech/jframe/blob/main/main.go) clean while allowing the `cmd/` package to handle all CLI logic.

### cmd/server/server.go - Server Command Implementation

The **[`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go)** file contains the primary `server` command implementation. This is where the framework boots up and orchestrates all components.

Key responsibilities of this file include:
- Loading configuration via `conf.LoadConfig()`
- Initializing optional dependencies like Sentry error tracking
- Creating a TCP listener and **cmux** multiplexer for protocol routing
- Constructing the **kernel** instance
- Registering modules from `modList.ModList`
- Starting the server loop via `kernel.StartModule()`

## Configuration Management

### conf/config.go - Viper-Based Configuration Loading

Configuration in jframe is handled by **Viper** through **[`conf/config.go`](https://github.com/juanjitech/jframe/blob/main/conf/config.go)**. This file defines the `GlobalConfig` struct and provides the `LoadConfig()` function.

The configuration system:
- Reads from [`config.yaml`](https://github.com/juanjitech/jframe/blob/main/config.yaml) (or a custom file specified via `-c` flag)
- Watches for file changes at runtime
- Unmarshals data into the global configuration accessible via `conf.Get()`

```go
// Example configuration access
config := conf.Get()
port := config.Server.Port

```

## Core Kernel Architecture

### core/kernel/kernel.go - The Framework Heart

The **[`core/kernel/kernel.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go)** file implements the **kernel**, which is the central orchestrator of the jframe framework. This is arguably the most critical source file in jframe.

The kernel manages:
- **Context management**: Creates a cancellable root context for graceful shutdowns
- **Dependency injection**: Uses `github.com/juanjiTech/inject/v2` to map objects like the TCP listener and cmux multiplexer
- **Module lifecycle**: Orchestrates the execution of lifecycle hooks in strict order
- **Dynamic configuration**: Unmarshals module-specific configuration sections using `mapstructure` tags

The kernel stores registered modules in a thread-safe map and exposes `RegMod()` for registration.

### core/kernel/module.go - Module Interface Definition

The **[`core/kernel/module.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/module.go)** file defines the `Module` interface that all jframe modules must implement. This interface establishes the contract for the lifecycle hooks:

- `Name() string` - Returns the module identifier
- `Config() interface{}` - Returns a pointer to the module's configuration struct
- `PreInit(*hub.Hub) error` - Early initialization before dependencies are ready
- `Init(*hub.Hub) error` - Main initialization with access to injected dependencies
- `PostInit(*hub.Hub) error` - Post-initialization cleanup
- `Load(*hub.Hub) error` - Loading phase for data preparation
- `Start(*hub.Hub) error` - Starts the module's background operations
- `Stop(*sync.WaitGroup, context.Context) error` - Graceful shutdown handling

## Logging Infrastructure

### core/logx/logger.go - Centralized Logging with Zap

The **[`core/logx/logger.go`](https://github.com/juanjitech/jframe/blob/main/core/logx/logger.go)** file provides the centralized logging abstraction built on **Zap**. This utility ensures consistent logging across all modules.

Key features:
- `PreInit()` configures a simple console logger for early boot messages
- `Init(level)` builds the production logger with optional file rotation via **lumberjack** and Tencent Cloud CLS integration
- `NameSpace(name)` returns a Zap SugaredLogger scoped to a specific module, creating prefixed log lines like `module.myservice`

```go
// Usage inside a module
log := logx.NameSpace("module.myservice")
log.Infow("initialising", "config", cfg)

```

## Module System and Examples

### mod/example/mod.go - Reference Module Implementation

The **[`mod/example/mod.go`](https://github.com/juanjitech/jframe/blob/main/mod/example/mod.go)** file serves as the canonical reference for implementing jframe modules. It demonstrates the proper structure including:

- Implementing the `Module` interface
- Defining configuration structs
- Creating service layers, models, and DAOs
- Proper lifecycle method implementations

Developers should study this file when creating custom modules to ensure compliance with jframe conventions.

### cmd/server/modList/list.go - Module Registry

The **[`cmd/server/modList/list.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/modList/list.go)** file acts as the central registry for all active modules. It contains the `ModList` slice that the server command iterates over during kernel initialization.

To activate a new module, developers simply append their module instance to this list:

```go
var ModList = []kernel.Module{
    &example.Example{},
    &myservice.MyService{}, // Add your module here
}

```

## Utility Packages

### pkg/utils/ and pkg/ip/ - Helper Functions

The **`pkg/utils/`** directory contains generic helper functions including HTTP client wrappers, pagination utilities, cryptography helpers, and random ID generators.

The **[`pkg/ip/ip.go`](https://github.com/juanjitech/jframe/blob/main/pkg/ip/ip.go)** file specifically handles local network interface discovery, helping the framework display accessible server addresses on startup.

These utility packages are designed to be lightweight with no external side effects, making them safe to import from any module without creating circular dependencies.

## Summary

- **[`main.go`](https://github.com/juanjitech/jframe/blob/main/main.go)** delegates to the Cobra CLI, keeping the entry point minimal and clean.
- **[`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go)** orchestrates the entire boot process, from config loading to kernel initialization.
- **[`conf/config.go`](https://github.com/juanjitech/jframe/blob/main/conf/config.go)** manages Viper-based configuration with hot-reload capabilities.
- **[`core/kernel/kernel.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go)** serves as the framework heart, managing dependency injection and module lifecycles.
- **[`core/kernel/module.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/module.go)** defines the interface contract that all modules must implement.
- **[`core/logx/logger.go`](https://github.com/juanjitech/jframe/blob/main/core/logx/logger.go)** provides centralized Zap-based logging with namespace scoping.
- **[`mod/example/mod.go`](https://github.com/juanjitech/jframe/blob/main/mod/example/mod.go)** offers a reference implementation for custom modules.
- **[`cmd/server/modList/list.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/modList/list.go)** acts as the central registry for active modules.

## Frequently Asked Questions

### What is the purpose of the kernel in jframe?

The kernel in [`core/kernel/kernel.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go) serves as the central orchestrator that manages the entire application lifecycle. It handles dependency injection using `github.com/juanjiTech/inject/v2`, maintains a cancellable root context for graceful shutdowns, and executes module lifecycle hooks in strict order from `PreInit` through `Stop`.

### How does jframe handle configuration changes at runtime?

JFrame uses Viper through [`conf/config.go`](https://github.com/juanjitech/jframe/blob/main/conf/config.go) to watch configuration files for changes. The `LoadConfig()` function sets up file watchers on [`config.yaml`](https://github.com/juanjitech/jframe/blob/main/config.yaml) (or custom specified files), allowing the framework to unmarshal updated values into the global `GlobalConfig` struct without requiring a server restart.

### Where should I register a new module in jframe?

New modules must be registered in [`cmd/server/modList/list.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/modList/list.go) by appending an instance of your module to the `ModList` slice. This central registry is iterated by the server command during kernel initialization in [`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go), ensuring your module receives all lifecycle callbacks.

### What logging library does jframe use?

JFrame uses **Uber Zap** for structured logging, abstracted through [`core/logx/logger.go`](https://github.com/juanjitech/jframe/blob/main/core/logx/logger.go). The framework provides namespace scoping via `logx.NameSpace()`, which returns a Zap SugaredLogger prefixed with the module name, enabling easy log filtering and optional integration with Tencent Cloud CLS and file rotation via lumberjack.