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.

Platforma follows a domain-driven design (DDD) pattern that organizes code around business domains rather than technical layers. Each domain encapsulates its own data access, business logic, HTTP handlers, and middleware.

​
Package Structure

The framework provides the following core packages:

application

Core lifecycle management: Application, Domain interface, Runner, startup tasks

httpserver

HTTP server with HTTPServer, HandlerGroup, and Middleware support

database

PostgreSQL integration with migrations using sqlx and lib/pq driver

queue

Background job processing with Processor[T] and Handler[T] interfaces

scheduler

Periodic task execution for cron-like functionality

log

Structured logging with context support

auth

Built-in authentication domain (reference implementation)

session

Session management domain

​
Domain-Driven Design Pattern

A domain represents a bounded context in your application. It aggregates all components needed for a specific business capability.
Each domain typically contains four components: 
type Domain struct {
    Repository  *Repository               // Database operations
    Service     *Service                  // Business logic
    HandleGroup *httpserver.HandlerGroup  // HTTP endpoints (optional)
    Middleware  httpserver.Middleware     // Request processing (optional)
}

​
Domain Interface

All domains must implement the application.Domain interface defined in application/domain.go:4: 
type Domain interface {
    GetRepository() any
}
This allows the application to register the domain’s repository for database migrations.

​
Component Responsibilities

ComponentRequiredPurpose
RepositoryYesDatabase operations, exposes migrations
ServiceYesBusiness logic, orchestrates repository calls
HandlerGroupNoHTTP API endpoints for the domain
MiddlewareNoRequest interceptors (auth, validation, etc.)

​
Reference Implementation: Auth Domain

The auth package provides a complete domain example. See auth/domain.go:7 for the full implementation: 
type Domain struct {
    Repository  *Repository
    Service     *Service
    HandleGroup *httpserver.HandlerGroup
    Middleware  httpserver.Middleware
}

func (d *Domain) GetRepository() any {
    return d.Repository
}
Use the auth domain as a template when creating new domains. It demonstrates all four components working together.

​
Package Organization

A typical domain package structure: 
auth/
├── domain.go       # Domain aggregate + constructor
├── model.go        # Data models (User, Status, etc.)
├── repository.go   # Database queries + migrations
├── service.go      # Business logic
├── middleware.go   # HTTP middleware
├── handler_*.go    # HTTP handlers
├── context.go      # Context helpers
└── errors.go       # Domain-specific errors

​
Architectural Principles

Repositories depend only on the database. Services depend on repositories. Handlers depend on services. This creates a clean dependency graph.
Each domain manages its own database schema, migrations, business rules, and API. Domains can depend on other domains via their service interfaces.
Except for log.Logger, the framework avoids global state. All dependencies are explicitly passed through constructors.
Components depend on interfaces, not concrete types. This enables testing with mocks and allows swapping implementations.

​
Quick Reference

For common tasks, refer to this mapping:
TaskLocationReference
Add new domainapplication/domain.goImplement Domain interface
Add HTTP routeshttpserver/handlergroup.goUse Handle("METHOD /path", handler)
Add middlewarehttpserver/middleware.goImplement Wrap(http.Handler) http.Handler
Database migrationsRepository’s Migrations()Returns []database.Migration
Register with appapplication/application.goRegisterDomain(), RegisterService()
Background jobsqueue/processor.goImplement Handler[T] interface
Scheduled tasksscheduler/scheduler.goPass Runner + duration

​
Next Steps

Application Lifecycle

Learn how to bootstrap and run your application

Domains

Deep dive into creating and registering domains

HTTP Routing

Set up HTTP endpoints and route groups

Middleware

Add request processing with middleware

Build docs developers (and LLMs) love

Get started for freeTalk to us