Go Platform (goplt)

Plugin-friendly SaaS/Enterprise Platform – Go Edition

A modular, extensible platform built with Go that provides a solid foundation for building scalable, secure, and observable applications. The platform supports plugin-based architecture, enabling teams to build feature modules independently while sharing core services.

Architecture Overview

Go Platform follows Clean/Hexagonal Architecture principles with clear separation between:

• Core Kernel: Foundation services (authentication, authorization, configuration, logging, observability)
• Module Framework: Plugin system for extending functionality
• Infrastructure Adapters: Support for databases, caching, event buses, and job scheduling
• Security-by-Design: Built-in JWT authentication, RBAC/ABAC authorization, and audit logging
• Observability: OpenTelemetry integration for tracing, metrics, and logging

Key Principles

• Clean Architecture: Separation between pkg/ (interfaces) and internal/ (implementations)
• Dependency Injection: Using uber-go/fx for lifecycle management
• Microservices-Ready: Each module is an independent service from day one
• Plugin-First Design: Extensible architecture supporting static and dynamic module loading
• Security-by-Design: JWT authentication, RBAC/ABAC, and audit logging
• Observability: OpenTelemetry, structured logging, and Prometheus metrics

Directory Structure

goplt/
├── cmd/
│   └── platform/          # Main application entry point
├── internal/              # Private implementation code
│   ├── di/                # Dependency injection container
│   ├── registry/          # Module registry
│   ├── pluginloader/      # Plugin loader (optional)
│   ├── config/            # Configuration implementation
│   ├── logger/            # Logger implementation
│   ├── infra/             # Infrastructure adapters
│   └── ent/               # Ent ORM schemas
├── pkg/                   # Public interfaces (exported)
│   ├── config/            # ConfigProvider interface
│   ├── logger/            # Logger interface
│   ├── module/             # IModule interface
│   ├── auth/              # Auth interfaces
│   ├── perm/              # Permission DSL
│   └── infra/             # Infrastructure interfaces
├── modules/               # Feature modules
│   └── blog/              # Sample Blog module (Epic 4)
├── config/                # Configuration files
│   ├── default.yaml
│   ├── development.yaml
│   └── production.yaml
├── api/                   # OpenAPI specs
├── scripts/               # Build/test scripts
├── docs/                  # Documentation
├── ops/                   # Operations (Grafana dashboards, etc.)
└── .github/
    └── workflows/
        └── ci.yml

Quick Start

Prerequisites

• Go 1.24+: Install Go
• Make: For using development commands
• Docker (optional): For containerized development

Installation

1. Clone the repository

   git clone git.dcentral.systems/toolz/goplt.git
   cd goplt
   

2. Install dependencies

   go mod download
   

3. Build the platform

   make build
   

4. Run the platform

   ./bin/platform
   # Or
   go run cmd/platform/main.go
   

Configuration

The platform loads configuration from multiple sources with the following precedence:

1. Environment variables (highest priority)
2. Environment-specific YAML files (config/development.yaml, config/production.yaml)
3. Base configuration file (config/default.yaml)

Example environment variables:

export SERVER_PORT=8080
export DATABASE_DSN="postgres://user:pass@localhost/dbname"
export LOGGING_LEVEL=debug

Development

Make Commands

make help          # Show all available commands
make test          # Run all tests
make test-coverage # Run tests with coverage report
make lint          # Run linters
make fmt           # Format code
make fmt-check     # Check code formatting
make build         # Build platform binary
make clean         # Clean build artifacts
make docker-build  # Build Docker image
make docker-run    # Run Docker container
make verify        # Verify code (fmt, lint, test)

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run tests for a specific package
go test ./internal/config/...

Code Quality

The project uses:

• golangci-lint: For comprehensive linting
• gofmt: For code formatting
• go vet: For static analysis

Run all checks:

make verify

Documentation

Comprehensive documentation is available in the docs/ directory:

• Architecture Documentation: System architecture and design patterns
• Architecture Decision Records (ADRs): Documented architectural decisions
• Implementation Stories: Epic-based implementation tasks
• Playbook: Detailed implementation guide and best practices

View Documentation Locally

# Using MkDocs (requires Python)
make docs-install
make docs-serve

# Using Docker (no Python required)
make docs-docker

Documentation will be available at http://127.0.0.1:8000

Architecture

Core Kernel

The platform provides a core kernel with essential services:

• Configuration Management: Hierarchical configuration with YAML and environment variable support
• Structured Logging: JSON-formatted logs with request correlation
• Dependency Injection: FX-based DI container for service lifecycle management
• Health & Metrics: Health check endpoints and Prometheus metrics
• Error Handling: Centralized error handling with proper error wrapping

Module System

Modules extend the platform's functionality by implementing the IModule interface:

type IModule interface {
    Name() string
    Version() string
    Initialize(ctx context.Context, app *Application) error
    Routes() []Route
    Permissions() []Permission
}

Security

• Authentication: JWT-based authentication with access and refresh tokens
• Authorization: RBAC/ABAC authorization system
• Audit Logging: Immutable audit trail for security-relevant actions
• Rate Limiting: Configurable rate limiting per endpoint

Observability

• Distributed Tracing: OpenTelemetry integration for request tracing
• Metrics: Prometheus metrics for monitoring
• Structured Logging: JSON-formatted logs with correlation IDs
• Health Checks: Kubernetes-ready health and readiness endpoints

🔧 Configuration

Configuration is managed through YAML files and environment variables. See config/default.yaml for the base configuration structure.

Key configuration sections:

• Server: HTTP server settings (port, host, timeouts)
• Database: Database connection settings
• Logging: Log level, format, and output destination
• Authentication: JWT settings and token configuration

Testing

The project follows table-driven testing patterns and includes:

• Unit tests for all packages
• Integration tests for service interactions
• Mock generation for interfaces
• Test coverage reporting

Contributing

1. Create a feature branch: git checkout -b feature/my-feature
2. Make your changes following the project's architecture principles
3. Run tests and linting: make verify
4. Commit your changes with clear messages
5. Push to your branch and create a pull request

License

[Add license information here]

Links

• Architecture Documentation
• ADRs
• Implementation Plan
• Playbook

📞 Support

For questions and support, please refer to the documentation or create an issue in the repository.