Architecture

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

Component	Required	Purpose
Repository	Yes	Database operations, exposes migrations
Service	Yes	Business logic, orchestrates repository calls
HandlerGroup	No	HTTP API endpoints for the domain
Middleware	No	Request 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

Dependencies Flow Inward

Repositories depend only on the database. Services depend on repositories. Handlers depend on services. This creates a clean dependency graph.

Domains are Self-Contained

Each domain manages its own database schema, migrations, business rules, and API. Domains can depend on other domains via their service interfaces.

No Global State

Except for log.Logger, the framework avoids global state. All dependencies are explicitly passed through constructors.

Interface-Based Design

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:

Task	Location	Reference
Add new domain	`application/domain.go`	Implement `Domain` interface
Add HTTP routes	`httpserver/handlergroup.go`	Use `Handle("METHOD /path", handler)`
Add middleware	`httpserver/middleware.go`	Implement `Wrap(http.Handler) http.Handler`
Database migrations	Repository’s `Migrations()`	Returns `[]database.Migration`
Register with app	`application/application.go`	`RegisterDomain()`, `RegisterService()`
Background jobs	`queue/processor.go`	Implement `Handler[T]` interface
Scheduled tasks	`scheduler/scheduler.go`	Pass `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

Get Started

Core Concepts

Guides

Package Structure

application

httpserver

database

queue

scheduler

log

auth

session

Domain-Driven Design Pattern

Domain Interface

Component Responsibilities

Reference Implementation: Auth Domain

Package Organization

Architectural Principles

Quick Reference

Next Steps

Application Lifecycle

Domains

HTTP Routing

Middleware

​Package Structure

application

httpserver

database

queue

scheduler

log

auth

session

​Domain-Driven Design Pattern

​Domain Interface

​Component Responsibilities

​Reference Implementation: Auth Domain

​Package Organization

​Architectural Principles

​Quick Reference

​Next Steps

Application Lifecycle

Domains

HTTP Routing

Middleware

Package Structure

Domain-Driven Design Pattern

Domain Interface

Component Responsibilities

Reference Implementation: Auth Domain

Package Organization

Architectural Principles

Quick Reference

Next Steps