From 2f2a14f2c5b18516085da2b3747c399952cb969e Mon Sep 17 00:00:00 2001 From: 0x1d Date: Thu, 6 Nov 2025 20:49:19 +0100 Subject: [PATCH] docs: Update README.md with current implementation and quick start - 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 --- README.md | 244 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 202 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 3dcfb3f..8bb0692 100644 --- a/README.md +++ b/README.md @@ -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