toolz/goplt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update README.md with current implementation and quick start

Browse Source 
- Add Core Services section highlighting Epic 2 completion
- Update directory structure to include all service entry points
- Add comprehensive Quick Start guide with:
  - Prerequisites including NixOS support
  - Installation steps with code generation
  - Two deployment options (development vs full Docker)
  - Service endpoints and ports
  - Testing examples with grpcurl
- Update Architecture section with Core Services details
- Add Implementation Status section showing completed epics
- Update Configuration section with service-specific settings
- Add links to Epic 2 documentation
This commit is contained in:
0x1d
2025-11-06 20:49:19 +01:00
parent ff330e510d
commit 2f2a14f2c5
1 changed files with 202 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

244
README.md
View File

@@ -8,43 +8,59 @@ A modular, extensible platform built with Go that provides a solid foundation fo
Go Platform follows **Hexagonal Architecture** principles with clear separation between:
- **Core Kernel**: Foundation services (authentication, authorization, configuration, logging, observability)
- **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/
│ └── 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
├── 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
├── api/ # OpenAPI specs
├── scripts/ # Build/test scripts
├── docs/ # Documentation
├── ops/ # Operations (Grafana dashboards, etc.)
├── 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
@@ -54,9 +70,12 @@ goplt/
### Prerequisites
- **Go 1.24+**: [Install Go](https://golang.org/doc/install)
- **Go 1.25.3+**: [Install Go](https://golang.org/doc/install)
- **Make**: For using development commands
- **Docker** (optional): For containerized development
- **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
@@ -66,22 +85,93 @@ goplt/
cd goplt
```
2. **Install dependencies**
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
```
3. **Build the platform**
4. **Generate code** (protobuf, Ent schemas)
```bash
make build
make generate-proto
make generate-ent
```
4. **Run the platform**
```bash
./bin/platform
# Or
go run cmd/platform/main.go
```
### 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/main.go # Port 8081
go run ./cmd/identity-service/main.go # Port 8082
go run ./cmd/authz-service/main.go # Port 8083
go run ./cmd/audit-service/main.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
@@ -110,12 +200,27 @@ 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
@@ -175,6 +280,24 @@ The platform provides a core kernel with essential services:
- **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:
@@ -191,10 +314,11 @@ type IModule interface {
### 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
- **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
@@ -209,10 +333,22 @@ Configuration is managed through YAML files and environment variables. See `conf
Key configuration sections:
- **Server**: HTTP server settings (port, host, timeouts)
- **Database**: Database connection settings
- **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
@@ -226,12 +362,36 @@ Key configuration sections:
[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