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/
+├── cmd/                   # Service entry points
-│   └── platform/          # Main application entry point
+│   ├── platform/         # Main platform entry point
-├── internal/              # Private implementation code
+│   ├── auth-service/     # Auth Service (JWT authentication)
-│   ├── di/                # Dependency injection container
+│   ├── identity-service/ # Identity Service (user management)
-│   ├── registry/          # Module registry
+│   ├── authz-service/    # Authz Service (authorization & RBAC)
-│   ├── pluginloader/      # Plugin loader (optional)
+│   └── audit-service/    # Audit Service (audit logging)
-│   ├── config/            # Configuration implementation
+├── internal/             # Private implementation code
-│   ├── logger/            # Logger implementation
+│   ├── di/               # Dependency injection container
-│   ├── infra/             # Infrastructure adapters
+│   ├── registry/         # Module registry
-│   └── ent/               # Ent ORM schemas
+│   ├── pluginloader/     # Plugin loader (optional)
-├── pkg/                   # Public interfaces (exported)
+│   ├── config/           # Configuration implementation
-│   ├── config/            # ConfigProvider interface
+│   ├── logger/           # Logger implementation
-│   ├── logger/            # Logger interface
+│   ├── infra/            # Infrastructure adapters
-│   ├── module/            # IModule interface
+│   ├── ent/              # Ent ORM schemas
-│   ├── auth/              # Auth interfaces
+│   └── client/           # Service clients (gRPC)
-│   ├── perm/              # Permission DSL
+│       └── grpc/         # gRPC client implementations
-│   └── infra/             # Infrastructure interfaces
+├── pkg/                  # Public interfaces (exported)
-├── modules/               # Feature modules
+│   ├── config/           # ConfigProvider interface
-│   └── blog/              # Sample Blog module (Epic 4)
+│   ├── logger/           # Logger interface
-├── config/                # Configuration files
+│   ├── 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
+├── docker-compose.yml     # Full deployment (all services)
-├── scripts/               # Build/test scripts
+├── docker-compose.dev.yml # Development (infrastructure only)
-├── docs/                  # Documentation
+├── scripts/              # Build/test scripts
-├── ops/                   # Operations (Grafana dashboards, etc.)
+├── 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**
+### Running Services
-   ```bash
+
-   ./bin/platform
+#### Option 1: Development Mode (Recommended for Development)
-   # Or
+
-   go run cmd/platform/main.go
+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
+- **Authentication**: JWT-based authentication with access and refresh tokens (Auth Service)
-- **Authorization**: RBAC/ABAC authorization system
+- **User Management**: Secure password hashing with Argon2id, email verification, password reset (Identity Service)
-- **Audit Logging**: Immutable audit trail for security-relevant actions
+- **Authorization**: RBAC/ABAC authorization system with role and permission management (Authz Service)
-- **Rate Limiting**: Configurable rate limiting per endpoint
+- **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)
+- **Server**: HTTP/gRPC server settings (port, host, timeouts)
-- **Database**: Database connection settings
+- **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