> For the complete documentation index, see [llms.txt](https://0xgosu.gitbook.io/monolith-framework/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://0xgosu.gitbook.io/monolith-framework/examples/basic.md).

# Basic

This example demonstrates the basic usage of the Monolith-Framework with a simple "Hello World" module.

## Overview

This example shows:

* Framework initialization with default configuration
* Single module registration
* Module lifecycle (Start/Stop)
* Basic logging
* Graceful shutdown handling

## What You'll Learn

1. **Framework Creation**: Using `mono.NewMonoApplication()` with functional options
2. **Module Interface**: Implementing the core `Module` interface (Name, Start, Stop)
3. **Configuration**: Setting log level, format, and shutdown timeout
4. **Lifecycle Management**: Framework automatically manages module startup and shutdown
5. **Health Checks**: Querying framework and module health status
6. **Signal Handling**: Graceful shutdown on SIGINT/SIGTERM

## Code Structure

```
examples/basic/
├── main.go           # Application entry point, framework initialization
├── hello_module.go   # Simple "Hello World" module implementation
└── README.md         # This file
```

## Module Implementation

The `HelloModule` demonstrates the minimal module interface:

```go
type HelloModule struct {
    name string
}

// Name returns the module identifier
func (m *HelloModule) Name() string {
    return m.name
}

// Start initializes the module
func (m *HelloModule) Start(ctx context.Context) error {
    fmt.Println("  → Hello from HelloModule! Module is now running...")
    return nil
}

// Stop gracefully shuts down the module
func (m *HelloModule) Stop(ctx context.Context) error {
    fmt.Println("  → Goodbye from HelloModule!")
    return nil
}
```

Note: The framework automatically logs module lifecycle events (registration, start, stop), so modules don't need to implement their own logging for basic operations.

## Running the Example

```bash
# Navigate to the example directory
cd examples/basic

# Run the example
go run .

# Expected output:
# === Mono-Framework Basic Example ===
# Demonstrates: Framework initialization, module registration, and lifecycle management
#
# ✓ Framework created successfully
# ✓ Module registered successfully
# ✓ Framework started - module is running
#
# Framework Health: healthy=true, nats_healthy=true
# Registered modules: [hello-world]
#
# Press Ctrl+C to shutdown...
# [Log entries from the module...]
#
# Shutdown signal received...
# ✓ Framework stopped successfully
# Example completed!
```

## Key Concepts Demonstrated

### 1. App Configuration

```go
app, err := mono.NewMonoApplication(
    mono.WithLogLevel(mono.LogLevelInfo),
    mono.WithLogFormat(mono.LogFormatText),
    mono.WithShutdownTimeout(10*time.Second),
)
```

The app uses functional options for clean, composable configuration.

### 2. Module Registration

```go
helloModule := NewHelloModule()
err := app.Register(helloModule)
```

Modules must be registered before starting the app.

### 3. Lifecycle Management

```go
// Start all registered modules
app.Start(ctx)

// Stop all modules gracefully (in reverse order)
app.Stop(ctx)
```

The app manages the complete module lifecycle automatically.

### 4. Health Checks

```go
health := app.Health(ctx)
fmt.Printf("Healthy: %v, NATS: %v\n", health.Healthy, health.NATSHealthy)
```

Check the operational status of the app and all modules.

## Next Steps

After understanding this basic example, explore:

1. [**Multi-Module Example**](/monolith-framework/examples/multi-module.md) - Learn about:
   * Module dependencies
   * Inter-module communication
   * Request-reply patterns
   * Event-driven architecture
2. [**Channel Services Example**](https://github.com/go-monolith/mono/blob/main/examples/channel-services/README.md) - Learn about:
   * Channel-based services
   * Advanced service patterns
   * Custom message handlers

## See Also

* [Design Document](https://github.com/go-monolith/mono/blob/main/docs/spec/foundation.md)
* [Module Interface Documentation](https://github.com/go-monolith/mono/blob/main/pkg/types/module.go)
* [Framework API Documentation](https://github.com/go-monolith/mono/blob/main/pkg/types/framework.go)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://0xgosu.gitbook.io/monolith-framework/examples/basic.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.