feat: implement Epic 0 - Project Setup & Foundation
Implemented all 5 stories from Epic 0: Story 0.1: Project Initialization - Initialize Go module with path git.dcentral.systems/toolz/goplt - Create complete directory structure (cmd/, internal/, pkg/, modules/, config/, etc.) - Add comprehensive .gitignore for Go projects - Create README.md with project overview and setup instructions Story 0.2: Configuration Management System - Define ConfigProvider interface in pkg/config - Implement Viper-based configuration in internal/config - Create configuration loader with environment support - Add default, development, and production YAML config files Story 0.3: Structured Logging System - Define Logger interface in pkg/logger - Implement Zap-based logger in internal/logger - Add request ID middleware for Gin - Create global logger export with convenience functions - Support context-aware logging with request/user ID extraction Story 0.4: CI/CD Pipeline - Create GitHub Actions workflow for CI (test, lint, build, fmt) - Add comprehensive Makefile with development commands - Configure golangci-lint with reasonable defaults Story 0.5: Dependency Injection and Bootstrap - Create FX-based DI container in internal/di - Implement provider functions for Config and Logger - Create application entry point in cmd/platform/main.go - Add lifecycle management with graceful shutdown All acceptance criteria met: - go build ./cmd/platform succeeds - go test ./... runs successfully - go mod verify passes - Config loads from config/default.yaml - Logger can be injected and used - Application starts and shuts down gracefully
This commit is contained in:
260
README.md
Normal file
260
README.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# 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.
|
||||
|
||||
---
|
||||
|
||||
**Built with ❤️ using Go**
|
||||
Reference in New Issue
Block a user