Skip to main content

Tonica Framework Documentation

Welcome to the Tonica framework documentation! Tonica is a modern, proto-first Go framework designed for building production-ready microservices with gRPC, REST APIs, workers, and message consumers.

Table of Contents​

Core Documentation​

  1. Getting Started - Quick setup and your first Tonica application
  2. CLI Reference - Tonica command-line tools and code generation
  3. Architecture Overview - Understanding how Tonica works
  4. Run Modes - AIO, Service, Worker, Consumer, and Gateway modes explained
  5. Configuration - All configuration options and environment variables
  6. Custom Routes - Adding custom HTTP routes with OpenAPI documentation
  7. Testing Guide - How to test your Tonica applications
  8. Best Practices - Patterns, anti-patterns, and recommendations

Additional Resources​

For New Users​

Start with Getting Started to build your first application in 5 minutes.

For Experienced Users​

What is Tonica?​

Tonica is a comprehensive Go framework that provides:

  • Proto-First Design: Define your APIs with Protocol Buffers
  • Auto-Generated OpenAPI: Swagger specs generated from your protos
  • Multiple Run Modes: Run as unified service (AIO), standalone service, worker, or consumer
  • Built-in Observability: OpenTelemetry tracing, Prometheus metrics, structured logging
  • Graceful Shutdown: Proper lifecycle management for all components
  • Database Support: PostgreSQL, MySQL, SQLite with Bun ORM
  • Redis Support: Connection pooling and caching
  • Temporal Integration: Built-in Temporal worker support
  • Message Consumers: Kafka/PubSub consumer support
  • API Documentation UI: Built-in Scalar UI for interactive API exploration

Key Features​

🚀 Proto-First Development​

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse) {
    option (google.api.http) = {
      get: "/api/v1/users/{id}"
    };
  }
}

🎯 Flexible Run Modes​

import (
    "github.com/tonica-go/tonica/pkg/tonica"
    "github.com/tonica-go/tonica/pkg/tonica/config"
)

// All-in-one mode: gRPC + REST + Workers + Consumers
app := tonica.NewApp(
    tonica.WithConfig(
        config.NewConfig(
            config.WithRunMode(config.ModeAIO),
        ),
    ),
)
err := app.Run()

// Service only: gRPC + REST
app := tonica.NewApp(
    tonica.WithConfig(
        config.NewConfig(
            config.WithRunMode(config.ModeService),
        ),
    ),
)
err := app.Run()

// Workers only: Temporal workers
app := tonica.NewApp(
    tonica.WithConfig(
        config.NewConfig(
            config.WithRunMode(config.ModeWorker),
        ),
    ),
)
err := app.Run()

// Consumers only: Message consumers
app := tonica.NewApp(
    tonica.WithConfig(
        config.NewConfig(
            config.WithRunMode(config.ModeConsumer),
        ),
    ),
)
err := app.Run()

🔌 Custom Routes​

tonica.NewRoute(app).
    GET("/health").
    Summary("Health check endpoint").
    Tags("Monitoring").
    Response(200, "Healthy", tonica.InlineObjectSchema(map[string]string{
        "status": "string",
    })).
    Handle(func(c *gin.Context) {
        c.JSON(200, gin.H{"status": "healthy"})
    })

📊 Built-in Observability​

import "log/slog"

// Metrics
app.GetMetricManager().NewCounter("requests_total", "Total requests")

// Tracing (automatic)
// Logging (structured with slog)
app.GetLogger().Info("Processing request", "user_id", userID)
// GetLogger() returns *slog.Logger

Architecture​

Tonica follows a modular architecture:

Community and Support​

License​

[Your License Here]

Contributing​

Contributions are welcome! Please check our GitHub repository for contribution guidelines.