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](https://golang.org/doc/install)
- **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**
   ```bash
   git clone git.dcentral.systems/toolz/goplt.git
   cd goplt
   ```

2. **Set up development environment** (NixOS users)
   ```bash
   # If using direnv, it will auto-activate
   # Otherwise, activate manually:
   nix-shell
   ```

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

4. **Generate code** (protobuf, Ent schemas)
   ```bash
   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:

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

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

```bash
# 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](docs/content/stories/epic2/SUMMARY.md) 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:
```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 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

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

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

### 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](docs/content/stories/epic2/) for detailed implementation.

### 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 (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](docs/content/plan.md) for details.

## Links

- [Architecture Documentation](docs/content/architecture/)
- [ADRs](docs/content/adr/)
- [Implementation Plan](docs/content/plan.md)
- [Playbook](docs/content/playbook.md)
- [Epic 2 Summary](docs/content/stories/epic2/SUMMARY.md) - Core Services implementation details

## Support

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