Creating Your First Module

Build a complete business module in under 50 lines of scaffolding code.

Overview

A platformkit module is a self-contained business capability. Each module has:

• Entities — database-backed data models
• Features — grouped functionality with routes and services
• Admin UI — automatically generated management pages
• MCP metadata — AI-discoverable descriptions

Step 1: Define the Entity

// features/tasks/entity.go
package tasks

import "github.com/septagon-dev/platformkit-backend-kit/core/entity/providers/base"

type Task struct {
    base.BaseEntity[Task] `gorm:"embedded"`
    Title       string `gorm:"type:varchar(255);not null" json:"title"`
    Description string `gorm:"type:text" json:"description"`
    Status      string `gorm:"type:varchar(50);default:'todo'" json:"status"`
    Priority    int    `gorm:"default:0" json:"priority"`
}

func (Task) TableName() string { return "tasks" }

Step 2: Create the Feature

// features/tasks/feature.go
package tasks

import (
    "github.com/septagon-dev/platformkit-backend-kit/app/module"
    "github.com/septagon-dev/platformkit-backend-kit/app/module/helpers"
)

func NewFeature() module.Feature {
    b := helpers.NewFeatureBuilder("task_management", module.FeatureMetadata{
        ID:      "tasks",
        Name:    "Tasks",
        Enabled: true,
    })
    helpers.RegisterEntity[*Task](b, helpers.EntityConfig{
        Name:      "Task",
        EnableMCP: true,
    })
    return b.Build()
}

Step 3: Wire the Module

// module.go
package task_management

import (
    "github.com/septagon-dev/platformkit-backend-kit/app/module"
    "github.com/septagon-dev/platformkit-backend-kit/app/module/providers/standard"
)

func createModule() *TaskModule {
    return &TaskModule{
        ModuleComposer: standard.NewComposer(
            module.ModuleMetadata{
                Name:     "task_management",
                Category: "productivity",
            },
            standard.WithFeatures(tasks.NewFeature()),
        ),
    }
}

Step 4: Add to Your App

modules := platformmodules.NewModuleSet().
    WithCoreVertical().
    WithModule(task_management.NewModule())

What You Get Automatically

With these ~50 lines, platformkit generates:

Next Steps

• Add a custom handler for domain-specific routes
• Implement MCP custom actions for Publish/Archive workflows
• Create E2E tests using the flow framework