Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/platforma-dev/platforma/llms.txt

Use this file to discover all available pages before exploring further.

The application package provides the core Application type that manages startup tasks, services, databases, and health checks throughout your application’s lifecycle.

​
Application Type

The Application type orchestrates the lifecycle of your application, managing startup tasks, services, databases, and health monitoring. 
type Application struct {
    // Contains startup tasks, services, healthcheckers, and databases
}

​
Constructor

​
New()
*Application
Creates and returns a new Application instance.
app := application.New()

​
Methods

​
RegisterService

​
RegisterService(serviceName string, service Runner)
void
Registers a named service with the application. Services are started concurrently when the application runs.
httpServer := httpserver.New("8080", 3*time.Second)
app.RegisterService("api", httpServer)

​
RegisterDatabase

​
RegisterDatabase(dbName string, db *database.Database)
void
Adds a database to the application for lifecycle management.
db, err := database.New(connStr)
if err != nil {
    log.Fatal(err)
}
app.RegisterDatabase("main", db)

​
RegisterRepository

​
RegisterRepository(dbName string, repoName string, repository any)
void
Registers a repository with a specific database. Repositories implementing the migrator interface will have their migrations applied.
userRepo := NewUserRepository(db.Connection())
app.RegisterRepository("main", "users", userRepo)

​
RegisterDomain

​
RegisterDomain(name, dbName string, domain Domain)
void
Registers a domain repository in the specified database. The domain must implement the Domain interface.
authDomain := auth.NewDomain(db.Connection())
app.RegisterDomain("auth", "main", authDomain)

​
OnStart

​
OnStart(task Runner, config StartupTaskConfig)
void
Registers a startup task that runs before services start.
app.OnStart(migrationTask, application.StartupTaskConfig{
    Name:         "database_migration",
    AbortOnError: true,
})

​
OnStartFunc

​
OnStartFunc(task RunnerFunc, config StartupTaskConfig)
void
Registers a startup task using a function.
app.OnStartFunc(func(ctx context.Context) error {
    log.InfoContext(ctx, "initializing application")
    return nil
}, application.StartupTaskConfig{
    Name:         "init",
    AbortOnError: false,
})

​
Health

​
Health(ctx context.Context)
*Health
Returns the current health status of the application and all registered services.
health := app.Health(ctx)
// Returns health status including service states

​
Run

​
Run(ctx context.Context)
error
Parses CLI arguments and executes the appropriate command.Supported commands:
  • run - Starts all registered services
  • migrate - Runs database migrations
  • --help, -h - Displays usage information
Returns ErrUnknownCommand if an unknown command is provided.
if err := app.Run(ctx); err != nil {
    log.ErrorContext(ctx, "app failed", "error", err)
}

​
Interfaces

​
Runner

The Runner interface defines tasks that can be executed with context. 
type Runner interface {
    Run(context.Context) error
}
​
Run
func(context.Context) error
Executes the task with the given context and returns an error if any.

​
RunnerFunc

A function type that implements the Runner interface. 
type RunnerFunc func(context.Context) error

func (rf RunnerFunc) Run(ctx context.Context) error {
    return rf(ctx)
}

​
Domain

The Domain interface describes a domain module that exposes its repository. 
type Domain interface {
    GetRepository() any
}
​
GetRepository
func() any
Returns the repository associated with this domain.

​
Healthchecker

Represents a service that can perform health checks. 
type Healthchecker interface {
    Healthcheck(context.Context) any
}
​
Healthcheck
func(context.Context) any
Returns the health status of the service. The returned value can be any serializable type.

​
Types

​
StartupTaskConfig

Configuration options for a startup task. 
type StartupTaskConfig struct {
    Name         string // Name of the startup task
    AbortOnError bool   // Whether to abort application startup if this task fails
}
​
Name
string
Name of the startup task for logging and identification.
​
AbortOnError
bool
If true, the application will terminate if this startup task fails. If false, the error is logged and execution continues.

​
Errors

​
ErrUnknownCommand

var ErrUnknownCommand = errors.New("unknown command")
Returned when an unknown CLI command is provided to Run().

​
ErrDatabaseMigrationFailed

type ErrDatabaseMigrationFailed struct {
    err error
}
Returned when database migration fails during the migrate command.

​
ErrStartupTaskFailed

type ErrStartupTaskFailed struct {
    err error
}
Returned when a startup task with AbortOnError: true fails.

​
Helpers

​
HealthCheckHandler

An HTTP handler that serves application health information as JSON. 
type HealthCheckHandler struct {
    app *Application
}
​
NewHealthCheckHandler(app)
*HealthCheckHandler
Creates a health check HTTP handler for the application.Parameters:
  • app (*Application): The application instance to check health for
app := application.New()
healthHandler := application.NewHealthCheckHandler(app)

api := httpserver.New("8080", 3*time.Second)
api.Handle("/health", healthHandler)
The handler returns a JSON response with:
  • Application start time
  • Service statuses (NOT_STARTED, STARTED, ERROR)
  • Service start/stop times
  • Error messages for failed services
  • Custom health data from Healthchecker implementations

​
Example Usage

package main

import (
    "context"
    "time"
    "github.com/platforma-dev/platforma/application"
    "github.com/platforma-dev/platforma/httpserver"
    "github.com/platforma-dev/platforma/log"
)

func main() {
    ctx := context.Background()
    
    // Create application
    app := application.New()
    
    // Create and register HTTP server
    api := httpserver.New("8080", 3*time.Second)
    api.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        health := app.Health(r.Context())
        json.NewEncoder(w).Encode(health)
    })
    app.RegisterService("api", api)
    
    // Add startup task
    app.OnStartFunc(func(ctx context.Context) error {
        log.InfoContext(ctx, "application initialized")
        return nil
    }, application.StartupTaskConfig{
        Name:         "init",
        AbortOnError: false,
    })
    
    // Run application (handles CLI commands)
    if err := app.Run(ctx); err != nil {
        log.ErrorContext(ctx, "app error", "error", err)
    }
}
CLI Usage: 
# Start the application
./myapp run

# Run database migrations
./myapp migrate

# Show help
./myapp --help

Build docs developers (and LLMs) love

Get started for freeTalk to us