> 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/getting-started/readme.md).

# Welcome

Welcome to the Mono Framework documentation—a Go framework for building **distributed modular monolith** applications powered by NATS.io.

{% hint style="info" %}
These docs are for the **Mono Framework**. [GitHub Repository](https://github.com/go-monolith/mono)
{% endhint %}

## What is Mono Framework?

Mono Framework enables building applications as a collection of loosely-coupled modules that communicate via NATS messaging. Start with a single binary monolith for simplicity, then scale horizontally to a distributed cluster when needed—**without changing your code**.

Powered by NATS.io's distributed architecture, your application can seamlessly evolve from a single instance to a highly scalable distributed system.

### Why Distributed Modular Monolith?

| Approach                         | Development | Deployment        | Scaling        |
| -------------------------------- | ----------- | ----------------- | -------------- |
| Traditional Monolith             | Simple      | Single binary     | Vertical only  |
| Microservices                    | Complex     | Many services     | Horizontal     |
| **Distributed Modular Monolith** | **Simple**  | **Single binary** | **Horizontal** |

* **Develop** like a monolith: single codebase, simple debugging, no network complexity during development
* **Deploy** like microservices: run multiple instances behind a load balancer, scale horizontally on demand
* **Communicate** through NATS: modules use messaging patterns that work identically whether running in one process or distributed across a cluster

### Key Features

* **Distributed Modular Monolith** - Start simple, scale horizontally without code changes
* **NATS.io Powered** - Built on NATS distributed messaging for high scalability and resilience
* **Embedded or External NATS** - Run embedded for development or single instance deployment, connect to production NATS clusters for HA deployments
* **Event-Driven Communication** - Publish/subscribe patterns for loose coupling
* **Five Service Patterns** - Channel, Request-Reply, Queue Group, Stream Consumer, and Cron services
* **JetStream Persistence** - Durable messaging with at-least-once delivery guarantees
* **Lifecycle Management** - Automatic dependency resolution and ordered startup/shutdown
* **Built-in Middleware** - Access logging, audit trails, and request ID injection
* **Plugin System** - Extensible architecture for custom functionality

## Quick Start

### Installation

```bash
go get github.com/go-monolith/mono
```

### Basic Example

```go
package main

import (
    "context"
    "log"
    "time"

    "github.com/go-monolith/mono"
)

type GreetingModule struct{}

func (m *GreetingModule) Name() string              { return "greeting" }
func (m *GreetingModule) Start(context.Context) error  { return nil }
func (m *GreetingModule) Stop(context.Context) error   { return nil }

func main() {
    app, err := mono.NewMonoApplication(
        mono.WithLogLevel(mono.LogLevelInfo),
        mono.WithShutdownTimeout(10*time.Second),
    )
    if err != nil {
        log.Fatal(err)
    }

    app.Register(&GreetingModule{})

    if err := app.Start(context.Background()); err != nil {
        log.Fatal(err)
    }

    // Application is running with embedded NATS server...

    app.Stop(context.Background())
}
```

## Next Steps

New to Mono Framework? Start here:

| If you want to...                    | Start here                                                                        |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| Set up the framework in your project | [📦 Installation](/monolith-framework/getting-started/installation.md)            |
| Build your first module quickly      | [⚡ Quick Start](/monolith-framework/getting-started/quickstart.md)                |
| Understand how to organize your app  | [📁 Project Structure](/monolith-framework/getting-started/project-structure.md)  |
| Learn the core concepts              | [🧠 Core Concepts](/monolith-framework/core-concepts/core-concepts.md)            |
| See working examples                 | [Examples](https://github.com/go-monolith/mono/blob/main/docs/examples/README.md) |
| Look up API details                  | [📚 API Reference](/monolith-framework/api-reference/api.md)                      |

## Core Concepts

Understand the architectural foundation:

* [Modules](/monolith-framework/core-concepts/modules.md) - How modules work and their lifecycle
* [Inter-Module Communication](/monolith-framework/core-concepts/inter-module-communication.md) - Service and Event communication patterns
* [Architecture](/monolith-framework/core-concepts/architecture.md) - Framework architecture and design

## Examples

Learn by example:

* [Basic](/monolith-framework/examples/basic.md) - Simple "Hello World" module
* [Multi-Module](/monolith-framework/examples/multi-module.md) - Order system with dependencies and service patterns
* [Analytics](/monolith-framework/examples/analytics.md) - Channel-based services for high-performance communication
* [Event Emitter](/monolith-framework/examples/event-emitter.md) - Event publishing and consumption patterns

## Explore More

* [API Reference](https://pkg.go.dev/github.com/go-monolith/mono) - Complete godoc documentation
* [GitHub Repository](https://github.com/go-monolith/mono) - Source code and issue tracking

## Help and Support

* Check our [examples](https://github.com/go-monolith/mono/blob/main/examples/README.md) directory for working code
* Review the [API documentation](https://pkg.go.dev/github.com/go-monolith/mono) for detailed information
* Visit the [GitHub repository](https://github.com/go-monolith/mono) for issues and discussions

***

Ready to get started? Head to [Installation](/monolith-framework/getting-started/installation.md).


---

# 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 dynamically 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/getting-started/readme.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 `build a script that syncs our docs to a CMS` 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.