goplt/README.md

# 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](https://golang.org/doc/install)
- **Make**: For using development commands
- **Docker** (optional): For containerized development

### Installation

1. **Clone the repository**
   ```bash
   git clone git.dcentral.systems/toolz/goplt.git
   cd goplt
   ```

2. **Install dependencies**
   ```bash
   go mod download
   ```

3. **Build the platform**
   ```bash
   make build
   ```

4. **Run the platform**
   ```bash
   ./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:
```bash
export SERVER_PORT=8080
export DATABASE_DSN="postgres://user:pass@localhost/dbname"
export LOGGING_LEVEL=debug
```

## Development

### Make Commands

```bash
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

```bash
# 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:
```bash
make verify
```

## Documentation

Comprehensive documentation is available in the `docs/` directory:

- **[Architecture Documentation](docs/content/architecture/)**: System architecture and design patterns
- **[Architecture Decision Records (ADRs)](docs/content/adr/)**: Documented architectural decisions
- **[Implementation Stories](docs/content/stories/)**: Epic-based implementation tasks
- **[Playbook](docs/content/playbook.md)**: Detailed implementation guide and best practices

### View Documentation Locally

```bash
# 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:

```go
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](docs/content/architecture/)
- [ADRs](docs/content/adr/)
- [Implementation Plan](docs/content/plan.md)
- [Playbook](docs/content/playbook.md)

## 📞 Support

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