goplt/README.md

Go Platform

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 Hexagonal Architecture principles with clear separation between:

• Core Kernel: Foundation services (configuration, logging, observability, dependency injection)
• Core Services: Independent microservices (Auth, Identity, Authz, Audit) with gRPC APIs
• 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
• Microservices: Each service is independently deployable with its own database schema

Directory Structure

goplt/
├── cmd/                   # Service entry points
│   ├── platform/         # Main platform entry point
│   ├── auth-service/     # Auth Service (JWT authentication)
│   ├── identity-service/ # Identity Service (user management)
│   ├── authz-service/    # Authz Service (authorization & RBAC)
│   └── audit-service/    # Audit Service (audit logging)
├── 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
│   └── client/           # Service clients (gRPC)
│       └── grpc/         # gRPC client implementations
├── pkg/                  # Public interfaces (exported)
│   ├── config/           # ConfigProvider interface
│   ├── logger/           # Logger interface
│   ├── module/           # IModule interface
│   ├── services/         # Service client interfaces
│   ├── auth/             # Auth interfaces
│   ├── perm/             # Permission DSL
│   └── infra/            # Infrastructure interfaces
├── services/             # Service-specific implementations
│   └── identity/         # Identity service internals
│       └── internal/
│           └── password/ # Password hashing (argon2id)
├── modules/              # Feature modules
│   └── blog/             # Sample Blog module (Epic 4)
├── api/                  # API definitions
│   └── proto/            # gRPC protobuf definitions
├── config/               # Configuration files
│   ├── default.yaml
│   ├── development.yaml
│   └── production.yaml
├── docker-compose.yml     # Full deployment (all services)
├── docker-compose.dev.yml # Development (infrastructure only)
├── scripts/              # Build/test scripts
├── docs/                 # Documentation
├── ops/                  # Operations (Grafana dashboards, etc.)
└── .github/
    └── workflows/
        └── ci.yml

Quick Start

Prerequisites

• Go 1.25.3+: Install Go
• Make: For using development commands
• Docker & Docker Compose: For infrastructure services
• PostgreSQL 16+: Database (or use Docker Compose)
• Consul: Service registry (or use Docker Compose)
• NixOS (optional): For development environment (shell.nix provided)

Installation

1. Clone the repository

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

2. Set up development environment (NixOS users)

   # If using direnv, it will auto-activate
   # Otherwise, activate manually:
   nix-shell
   

3. Install dependencies

   go mod download
   

4. Generate code (protobuf, Ent schemas)

   make generate-proto
   make generate-ent
   

Running Services

Option 1: Development Mode (Recommended for Development)

Start infrastructure services (PostgreSQL + Consul) in Docker, run services locally:

# Start infrastructure
docker-compose -f docker-compose.dev.yml up -d

# Verify infrastructure is running
docker-compose -f docker-compose.dev.yml ps

# Start services locally (in separate terminals)
go run ./cmd/auth-service/*.go      # Port 8081
go run ./cmd/identity-service/*.go  # Port 8082
go run ./cmd/authz-service/*.go     # Port 8083
go run ./cmd/audit-service/*.go     # Port 8084

Option 2: Full Docker Deployment

Run everything in Docker:

# Build and start all services
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Service Endpoints

Once services are running:

• Auth Service: localhost:8081 (gRPC)
• Identity Service: localhost:8082 (gRPC)
• Authz Service: localhost:8083 (gRPC)
• Audit Service: localhost:8084 (gRPC)
• Consul UI: http://localhost:8500/ui
• PostgreSQL: localhost:5432

Testing Services

Use grpcurl to test gRPC endpoints:

# List available services
grpcurl -plaintext localhost:8081 list

# Example: Create a user
grpcurl -plaintext -d '{
  "email": "user@example.com",
  "password": "securepassword123",
  "username": "testuser"
}' localhost:8082 identity.v1.IdentityService/CreateUser

# Example: Login
grpcurl -plaintext -d '{
  "email": "user@example.com",
  "password": "securepassword123"
}' localhost:8081 auth.v1.AuthService/Login

See Epic 2 Summary for detailed testing instructions.

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 generate-proto # Generate gRPC code from protobuf
make generate-ent  # Generate Ent ORM code
make clean         # Clean build artifacts
make docker-build  # Build Docker image
make docker-run    # Run Docker container
make verify        # Verify code (fmt, lint, test)

Building Services

# Build individual services
go build ./cmd/auth-service
go build ./cmd/identity-service
go build ./cmd/authz-service
go build ./cmd/audit-service

# Or use make (if targets are defined)
make build-services

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

Core Services (Epic 2 - ✅ Complete)

Four independent microservices provide authentication and authorization:

• Auth Service (cmd/auth-service/): JWT token generation, validation, refresh tokens
• Identity Service (cmd/identity-service/): User CRUD, password management, email verification
• Authz Service (cmd/authz-service/): RBAC/ABAC authorization, permission resolution
• Audit Service (cmd/audit-service/): Immutable audit logging with querying

Each service:

• Has its own gRPC API
• Uses its own database schema
• Registers with Consul service registry
• Can be deployed independently
• Communicates via gRPC clients

See Epic 2 Documentation for detailed implementation.

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 (Auth Service)
• User Management: Secure password hashing with Argon2id, email verification, password reset (Identity Service)
• Authorization: RBAC/ABAC authorization system with role and permission management (Authz Service)
• Audit Logging: Immutable audit trail for security-relevant actions (Audit Service)
• Rate Limiting: Configurable rate limiting per endpoint (planned)

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/gRPC server settings (port, host, timeouts)
• Database: Database connection settings (PostgreSQL with schema support)
• Logging: Log level, format, and output destination
• Authentication: JWT settings and token configuration
• Services: Service-specific ports and hosts
• Registry: Service registry settings (Consul)

Environment Variables

Services can be configured via environment variables:

• ENVIRONMENT: development or production
• DATABASE_DSN: PostgreSQL connection string
• REGISTRY_TYPE: Service registry type (default: consul)
• REGISTRY_CONSUL_ADDRESS: Consul address (default: localhost:8500)
• AUTH_JWT_SECRET: JWT signing secret (required for Auth Service)

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]

Implementation Status

✅ Completed

• Epic 0: Project Setup & Foundation
• Epic 1: Core Kernel & Infrastructure
• Epic 2: Core Services (Auth, Identity, Authz, Audit) - Complete
  • All four services implemented as independent microservices
  • gRPC APIs with service discovery
  • Database schemas and persistence
  • Docker support for all services

🚧 In Progress / Planned

• Epic 3: Module Framework
• Epic 4: Sample Feature Module (Blog)
• Epic 5: Infrastructure Adapters
• Epic 6: Observability & Production Readiness
• Epic 7: Testing, Documentation & CI/CD
• Epic 8: Advanced Features & Polish

See Implementation Plan for details.

Links

• Architecture Documentation
• ADRs
• Implementation Plan
• Playbook
• Epic 2 Summary - Core Services implementation details

Support

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