# How Repository Structure Indicates Project Type: Inside the JFrame Go Backend Framework

> Discover how JFrame's repository structure reveals its nature as a production-ready modular Go backend framework for microservices. Explore its layered layout, kernel, and plugin system.

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

---

**The JFrame repository uses a layered directory layout with a central kernel, modular plugin system, and clear separation between core infrastructure and business logic, indicating it is a production-ready modular Go backend framework designed for microservices.**

The way a codebase organizes its files and directories reveals architectural intent before you read a single line of logic. In the `juanjitech/jframe` repository, the **repository structure indicates project type** through distinct layers for kernel management, configuration, CLI tooling, and pluggable modules. This layout reflects a Go-based backend framework built for scalability, observability, and clean separation of concerns.

## Core Architectural Layers

### Application Entry Point and Kernel

The [`main/main.go`](https://github.com/juanjitech/jframe/blob/main/main/main.go) file serves as the application entrypoint, bootstrapping the central `Kernel` object defined in [`core/kernel/kernel.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go). This kernel acts as the dependency injection container and lifecycle manager, registering modules via the `RegisterModule` method.

```go
// core/kernel/kernel.go – bootstrapping the kernel
func NewKernel(conf *config.Config) *Kernel {
    k := &Kernel{config: conf}
    // Load built‑in modules
    k.RegisterModule(uptrace.New())
    k.RegisterModule(pyroscope.New())
    // Load user‑defined modules from config
    for _, m := range conf.Modules {
        k.RegisterModule(m)
    }
    return k
}

```

The kernel accepts types implementing the `Module` interface from [`core/kernel/module.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/module.go), establishing a plugin-based architecture where functionality is composed at runtime rather than hard-coded.

### Configuration and Logging Infrastructure

Configuration management is isolated in the `conf/` directory, with [`conf/config.go`](https://github.com/juanjitech/jframe/blob/main/conf/config.go) loading YAML files and environment variables into a structured `Config` struct. Global defaults reside in [`conf/vars.go`](https://github.com/juanjitech/jframe/blob/main/conf/vars.go), ensuring centralized access to settings without scattering viper calls throughout the codebase.

Logging infrastructure in [`core/logx/logger.go`](https://github.com/juanjitech/jframe/blob/main/core/logx/logger.go) wraps the Zap logger, adding request-scoped fields and Sentry integration. This placement within `core/` signals that logging is treated as a framework-level concern, available to all modules through the kernel's dependency injection.

### Command-Line Interface Structure

The `cmd/` directory follows the standard Go CLI pattern, containing subdirectories for each command: `server`, `init`, `create`, and `config`. Each command is self-contained, with [`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go) handling the server startup workflow:

```go
// cmd/server/server.go – start the HTTP/gRPC server
func RunServer(cmd *cobra.Command, args []string) {
    cfg := conf.LoadConfig()
    k := kernel.NewKernel(cfg)
    if err := k.Start(); err != nil {
        log.Fatalf("failed to start kernel: %v", err)
    }
}

```

This structure indicates the project provides first-class CLI tooling for operational tasks, not just a library for import.

## Modular Plugin Architecture

### The Module Interface Pattern

The `mod/` directory is the clearest indicator that **repository structure indicates project type** as a modular framework. Each subdirectory represents an optional plugin implementing the `Module` interface. The kernel discovers and initializes these modules based on configuration, enabling features without recompilation.

```go
// mod/example/mod.go – registering a new module
func (e *ExampleModule) Register(k *kernel.Kernel) {
    // expose a gRPC service
    k.GrpcServer().RegisterService(&examplepb.ExampleService{})
    // add HTTP routes via the gateway
    k.Gateway().RegisterHandler(http.HandlerFunc(e.handleExample))
}

```

The `mod/grpcGateway/` directory provides a gRPC-to-REST gateway with authentication middleware, demonstrating how transport concerns are encapsulated within modules.

### Built-in Observability Modules

The framework includes dedicated observability modules in `mod/uptrace/`, `mod/pyroscope/`, and `mod/jinx/`. These provide distributed tracing, continuous profiling, and health checks respectively. Their isolation in `mod/` demonstrates the framework's commitment to **observability-first** architecture, where monitoring capabilities are pluggable rather than invasive.

### Example Module Implementation

The `mod/example/` directory serves as a reference implementation, containing `service/`, `model/`, `handler/`, `dao/`, and [`embed.go`](https://github.com/juanjitech/jframe/blob/main/embed.go). This mirrors the layered architecture expected of business logic modules, guiding developers on how to structure their own features within the framework while demonstrating proper separation between data access, business logic, and transport layers.

## Utility and Data Access Patterns

### Reusable Utilities in pkg/

The `pkg/` directory contains framework-agnostic utilities organized by function: `utils/` for HTTP helpers and pagination, `ip/` for address handling, `fsx/` for filesystem operations, `jsonx/` for JSON processing, and `randx/` for random generation. These packages have no external dependencies beyond the Go standard library, reducing supply-chain risk and upgrade complexity.

### Database Access Layer

Database interaction is standardized through `pkg/stdao/`, which provides [`model.go`](https://github.com/juanjitech/jframe/blob/main/model.go) and [`dao.go`](https://github.com/juanjitech/jframe/blob/main/dao.go) files. These define ORM-like structs and data-access helpers for relational databases. This offers a consistent pattern for modules that require persistence without mandating a specific database driver, keeping the framework agnostic to storage implementations.

## Deployment and DevOps Configuration

The presence of `Dockerfile`, [`docker-compose.yml`](https://github.com/juanjitech/jframe/blob/main/docker-compose.yml), and [`docker-compose-dev.yml`](https://github.com/juanjitech/jframe/blob/main/docker-compose-dev.yml) at the repository root indicates the framework is designed for containerized deployment. These files define production and development environments, suggesting the project targets cloud-native microservice architectures where container orchestration is standard.

## Summary

- The **repository structure indicates project type** through a layered architecture separating core kernel logic, configuration, CLI tooling, and pluggable modules.
- The `mod/` directory and `Module` interface pattern reveal a **modular plugin system** designed for extensibility without core modification.
- Isolation of utilities in `pkg/` and data access in `pkg/stdao/` demonstrates a **framework-agnostic approach** to common backend concerns.
- Built-in observability modules and containerization files confirm this is a **production-ready microservice framework** targeting cloud-native deployments.

## Frequently Asked Questions

### What makes JFrame a modular framework rather than a simple library?

The presence of the `core/kernel/` package with its `RegisterModule` method and the `mod/` directory containing independent plugin implementations distinguishes JFrame from a simple library. Each module in `mod/` implements the `Module` interface defined in [`core/kernel/module.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/module.go), allowing the kernel to discover and initialize features dynamically based on configuration, which is characteristic of modular frameworks rather than static libraries.

### How does the repository structure support microservice architecture?

The structure supports microservices through several design decisions: the [`cmd/server/server.go`](https://github.com/juanjitech/jframe/blob/main/cmd/server/server.go) entry point allows independent service startup, the `mod/` directory enables selective feature loading so services only include necessary components, and the Docker configuration files at the root facilitate containerized deployment. Additionally, the observability modules in `mod/uptrace/` and `mod/pyroscope/` provide distributed tracing and profiling essential for microservice monitoring.

### Why are utilities isolated in the pkg/ directory?

Utilities are isolated in `pkg/` to maintain a clear separation between framework-specific logic and generic, reusable code. This directory contains packages like `utils/`, `ip/`, `fsx/`, and `jsonx/` that have no dependencies on the JFrame kernel or configuration, allowing them to be imported by external projects or used across different modules without creating circular dependencies. This pattern follows Go community standards for library organization.

### What role does the kernel play in the project structure?

The kernel serves as the central dependency injection container and lifecycle manager, located in [`core/kernel/kernel.go`](https://github.com/juanjitech/jframe/blob/main/core/kernel/kernel.go). It implements the `RegisterModule` method that accepts types satisfying the `Module` interface, maintains references to the gRPC server, HTTP gateway, and configuration, and orchestrates the startup and shutdown sequences. This centralization allows modules in `mod/` to remain stateless and focused on business logic while relying on the kernel for infrastructure concerns.