# How to Explore the jframe Repository Structure: A Developer's Guide

> Explore the jframe repository structure by examining core kernel lifecycle, bootstrap logic, and module implementations. Understand how the dependency-injection container orchestrates your application.

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

---

**You explore the jframe repository structure by examining the kernel lifecycle in `core/kernel/`, the bootstrap logic in `cmd/server/`, and the module implementations in `mod/` to understand how the dependency-injection container orchestrates application modules.**

The **jframe** repository is a Go-based application framework built around modular architecture and dependency injection. To effectively explore the jframe repository structure, you must understand how the kernel engine manages module lifecycles and how the CLI bootstraps the application. This guide walks through the key directories and source files that define the framework's architecture.

## Architecture Overview

The repository organizes code around three core concepts: the kernel engine, the CLI bootstrapper, and pluggable modules.

### The Kernel and Engine

The heart of the framework lives in [`core/kernel/kernel.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go) and [`core/kernel/module.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/module.go). The `Engine` struct holds the dependency-injection container, configuration management, and lifecycle control. It maintains a registry of **Module** implementations that follow a strict interface contract.

The `Module` interface defines lifecycle hooks including `PreInit`, `Init`, `PostInit`, `Load`, `Start`, and `Stop`. A default `UnimplementedModule` provides empty implementations for convenience when creating new modules.

### Server Bootstrap Entry Point

The [`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go) file serves as the primary entry point for the `jframe server` command. This file orchestrates the initialization sequence: it loads configuration via `conf.LoadConfig`, initializes optional services like Sentry, creates the kernel using `kernel.New`, registers modules from `modList.ModList`, and starts the kernel.

### Module System

Concrete implementations of the `kernel.Module` interface reside under `mod/`. The [`mod/example/mod.go`](https://github.com/juanjitech/jframe/blob/main/mod/example/mod.go) file demonstrates how to register dependencies using `h.Map`, retrieve them via `h.Value`, `h.Invoke`, or `h.Load`, and expose HTTP routes through the embedded **jin** engine. Real applications extend this pattern by adding custom modules to the `modList.ModList` registry.

## Bootstrap Flow and Lifecycle

Understanding the execution flow helps you navigate the codebase effectively:

1. **Command execution** – [`main.go`](https://github.com/juanjitech/jframe/blob/main/main.go) calls `cmd.Execute()`, which routes to the `server` sub-command in [`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go).

2. **Configuration loading** – `conf.LoadConfig` reads YAML files or environment variables via **Viper** and populates the global configuration accessible through `conf.Get()`.

3. **Kernel creation** – `kernel.New` instantiates an `Engine` containing the DI container. The kernel receives shared resources including `conn` and `tcpMux`.

4. **Module registration** – `k.RegMod(modList.ModList...)` stores each module by name in the `Engine.modules` map.

5. **Lifecycle execution** – `k.StartModule()` iterates through registered modules, performing config unmarshalling and executing hooks in sequence: `PreInit` → `Init` → `PostInit` → `Load` → `Start`. Each phase runs in its own goroutine where appropriate.

6. **Graceful shutdown** – On SIGINT or SIGTERM signals, `k.Stop()` invokes each module's `Stop` method and waits for all goroutines to finish.

## Navigating the Source Code

When you explore the jframe repository structure, use these targeted approaches to locate specific functionality:

- **Locate modules** – All modules live under `mod/`. Each subdirectory contains a [`mod.go`](https://github.com/juanjitech/jframe/blob/main/mod.go) file implementing `kernel.Module`. Use grep to find module definitions:
  
  ```bash
  grep -R "type .* struct" mod/*/mod.go
  ```

- **Trace dependency injection** – The framework uses **juanjiTech/inject/v2**. The kernel's `Hub` embeds an `inject.Injector`. Query the container with `h.Value`, `h.Invoke`, or `h.Load` to understand how components receive their dependencies.

- **Examine HTTP routing** – The default router is **jin** (`github.com/juanjiTech/jin`). Modules retrieve a `*jin.Engine` from the injector and register routes, as demonstrated in the example module.

## Practical Code Examples

### Listing Registered Modules at Runtime

Inspect the engine's module registry after initialization to verify active components:

```go
func ListModules(e *kernel.Engine) {
    for name := range e.modules {
        fmt.Println("registered module:", name)
    }
}

```

Call this after `k.RegMod(...)` to confirm which modules are loaded.

### Registering Dependencies in a Module

Provide shared resources to the DI container during the `Init` phase:

```go
func (m *MyMod) Init(h *kernel.Hub) error {
    db, err := sql.Open("postgres", conf.Get().PostgresDSN)
    if err != nil {
        return err
    }
    h.Map(db)
    return nil
}

```

### Retrieving Dependencies in Another Module

Consume shared resources during the `Load` phase:

```go
func (m *AnotherMod) Load(h *kernel.Hub) error {
    var db *sql.DB
    if err := h.Load(&db); err != nil {
        return err
    }
    return nil
}

```

### Adding HTTP Routes from a Module

Expose endpoints by interacting with the jin router:

```go
func (m *MyMod) Load(h *kernel.Hub) error {
    var router *jin.Engine
    if err := h.Load(&router); err != nil {
        return err
    }
    router.GET("/hello", func(c *jin.Context) {
        _, _ = c.Writer.WriteString("Hello from MyMod")
    })
    return nil
}

```

## Key Files Reference

These files provide the definitive map for exploring the codebase:

- **[`core/kernel/kernel.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go)** – Engine implementation and lifecycle orchestration
- **[`core/kernel/module.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/module.go)** – `Module` interface and `UnimplementedModule` base
- **[`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go)** – Server command, configuration loading, and kernel boot
- **[`conf/config.go`](https://github.com/juanjitech/jframe/blob/main/conf/config.go)** – Global configuration struct and defaults
- **[`mod/example/mod.go`](https://github.com/juanjitech/jframe/blob/main/mod/example/mod.go)** – Sample module demonstrating DI patterns and routing
- **[`mod/example/modList/list.go`](https://github.com/juanjitech/jframe/blob/main/mod/example/modList/list.go)** – Central registry where modules are listed for bootstrapping
- **[`pkg/sentry/sentry.go`](https://github.com/juanjitech/jframe/blob/main/pkg/sentry/sentry.go)** – Optional Sentry integration used by the server
- **[`pkg/ip/ip.go`](https://github.com/juanjitech/jframe/blob/main/pkg/ip/ip.go)** – Network interface utilities for UI output

## Summary

- **Start with `core/kernel/`** to understand the `Engine` struct and `Module` interface that govern the framework lifecycle
- **Study [`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go)** to see how the application bootstraps configuration, creates the kernel, and registers modules
- **Explore `mod/` directories** to find concrete module implementations showing dependency injection and HTTP routing patterns
- **Use the `Hub` methods** (`Map`, `Load`, `Invoke`) to trace how components interact through the **juanjiTech/inject/v2** container
- **Reference [`conf/config.go`](https://github.com/juanjitech/jframe/blob/main/conf/config.go)** to understand the configuration structure populated by **Viper**

## Frequently Asked Questions

### Where should I start when exploring the jframe repository structure?

Begin with [`core/kernel/kernel.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go) and [`core/kernel/module.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/module.go) to understand the foundational interfaces. Then examine [`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go) to see how the kernel initializes during application startup. This sequence provides the architectural context needed to understand specific modules in `mod/`.

### How does jframe handle dependency injection between modules?

The framework uses **juanjiTech/inject/v2** through the `kernel.Hub` type. Modules register dependencies using `h.Map()` during `Init`, and retrieve them using `h.Load()` or `h.Invoke()` during `Load` or `Start` phases. The `Engine` maintains a single injector instance shared across all modules.

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

The `modList` (typically found in [`mod/example/modList/list.go`](https://github.com/juanjitech/jframe/blob/main/mod/example/modList/list.go) or similar) serves as the central registry where developers list active modules. The server bootstrap code iterates over this list when calling `k.RegMod()`, determining which modules participate in the application lifecycle.

### How do I add a new module to the jframe repository?

Create a new subdirectory under `mod/` containing a [`mod.go`](https://github.com/juanjitech/jframe/blob/main/mod.go) file that implements the `kernel.Module` interface. Embed `kernel.UnimplementedModule` to satisfy the interface with minimal boilerplate, then override the lifecycle hooks you need (typically `Init` for dependency registration and `Load` for route setup). Finally, add your module to the `modList.ModList` in the list file to ensure the kernel loads it during startup.