docs: Align documentation with true microservices architecture

Transform all documentation from modular monolith to true microservices
architecture where core services are independently deployable.

Key Changes:
- Core Kernel: Infrastructure only (no business logic)
- Core Services: Auth, Identity, Authz, Audit as separate microservices
  - Each service has own entry point (cmd/{service}/)
  - Each service has own gRPC server and database schema
  - Services register with Consul for service discovery
- API Gateway: Moved from Epic 8 to Epic 1 as core infrastructure
  - Single entry point for all external traffic
  - Handles routing, JWT validation, rate limiting, CORS
- Service Discovery: Consul as primary mechanism (ADR-0033)
- Database Pattern: Per-service connections with schema isolation

Documentation Updates:
- Updated all 9 architecture documents
- Updated 4 ADRs and created 2 new ADRs (API Gateway, Service Discovery)
- Rewrote Epic 1: Core Kernel & Infrastructure (infrastructure only)
- Rewrote Epic 2: Core Services (Auth, Identity, Authz, Audit as services)
- Updated Epic 3-8 stories for service architecture
- Updated plan.md, playbook.md, requirements.md, index.md
- Updated all epic READMEs and story files

New ADRs:
- ADR-0032: API Gateway Strategy
- ADR-0033: Service Discovery Implementation (Consul)

New Stories:
- Epic 1.7: Service Client Interfaces
- Epic 1.8: API Gateway Implementation

docs/content/adr/0029-microservices-architecture.md

@@ -9,31 +9,49 @@ The platform needs to scale independently, support team autonomy, and enable fle
 ## Decision
 Design the platform as **microservices architecture from day one**:
 
-1. **Service-Based Architecture**: All modules are independent services:
-   - Each module is a separate service with its own process
+1. **Core Services**: Core business services are separate microservices:
+   - **Auth Service** (`cmd/auth-service/`): JWT token generation/validation
+   - **Identity Service** (`cmd/identity-service/`): User CRUD, password management
+   - **Authz Service** (`cmd/authz-service/`): Permission resolution, authorization
+   - **Audit Service** (`cmd/audit-service/`): Audit logging
+   - Each service has its own process, database connection, and deployment
+
+2. **API Gateway**: Core infrastructure component (implemented in Epic 1):
+   - Single entry point for all external traffic
+   - Routes requests to backend services via service discovery
+   - Handles authentication, rate limiting, CORS at the edge
+   - Not optional - required for microservices architecture
+
+3. **Service-Based Architecture**: All modules are independent services:
+   - Each module/service is a separate service with its own process
    - Services communicate via gRPC (primary) or HTTP (fallback)
    - Service client interfaces for all inter-service communication
    - No direct in-process calls between services
 
-2. **Service Registry**: Central registry for service discovery:
+4. **Service Registry**: Central registry for service discovery:
    - All services register on startup
    - Service discovery via registry
    - Health checking and automatic deregistration
    - Support for Consul, etcd, or Kubernetes service discovery
 
-3. **Communication Patterns**:
+5. **Communication Patterns**:
    - **Synchronous**: gRPC service calls (primary), HTTP/REST (fallback)
    - **Asynchronous**: Event bus via Kafka
-   - **Shared State**: Cache (Redis) and Database (PostgreSQL)
+   - **Shared Infrastructure**: Cache (Redis) and Database (PostgreSQL instance)
+   - **Database Access**: Each service has its own connection pool and schema
 
-4. **Service Boundaries**: Each module is an independent service:
+6. **Service Boundaries**: Each service is independent:
    - Independent Go modules (`go.mod`)
-   - Own database schema (via Ent)
-   - Own API routes
+   - Own database schema (via Ent) - schema isolation
+   - Own API routes (gRPC/HTTP)
    - Own process and deployment
    - Can be scaled independently
 
-5. **Development Simplification**: For local development, multiple services can run in the same process, but they still communicate via service clients (no direct calls)
+7. **Development Mode**: For local development, services run in the same repository:
+   - Each service has its own entry point and process
+   - Services still communicate via service clients (gRPC/HTTP)
+   - No direct in-process calls
+   - Docker Compose for easy local setup
 
 ## Consequences
 
@@ -55,29 +73,36 @@ Design the platform as **microservices architecture from day one**:
 - **Development Setup**: More complex local development (multiple services)
 
 ### Mitigations
-- **Service Mesh**: Use service mesh (Istio, Linkerd) for advanced microservices features
-- **API Gateway**: Central gateway for routing and cross-cutting concerns
+- **API Gateway**: Implemented in Epic 1 as core infrastructure - handles routing, authentication, rate limiting
+- **Service Mesh**: Use service mesh (Istio, Linkerd) for advanced microservices features (optional)
 - **Event Sourcing**: Use events for eventual consistency
 - **Circuit Breakers**: Implement circuit breakers for resilience
 - **Comprehensive Observability**: OpenTelemetry, metrics, logging essential
 - **Docker Compose**: Simplify local development with docker-compose
-- **Development Mode**: Run multiple services in same process for local dev (still use service clients)
+- **Service Clients**: All inter-service communication via service clients (gRPC/HTTP)
 
 ## Implementation Strategy
 
-### Epic 1: Service Client Interfaces (Epic 1)
-- Define service client interfaces for all core services
-- All inter-service communication goes through interfaces
+### Epic 1: Core Kernel & Infrastructure
+- Core kernel (infrastructure only): config, logger, DI, health, metrics, observability
+- API Gateway implementation (core infrastructure component)
+- Service client interfaces for all core services
+- Service registry interface and basic implementation
 
-### Epic 2: Service Registry (Epic 3)
-- Create service registry interface
-- Implement service discovery
-- Support for Consul, Kubernetes service discovery
+### Epic 2: Core Services Separation
+- Separate Auth, Identity, Authz, Audit into independent services
+- Each service: own entry point (`cmd/{service}/`), gRPC server, database connection
+- Service client implementations (gRPC/HTTP)
+- Service registration with registry
 
-### Epic 3: gRPC Services (Epic 5)
-- Implement gRPC service definitions
-- Create gRPC servers for all services
-- Create gRPC clients for service communication
+### Epic 3: Service Registry & Discovery (Epic 3)
+- Complete service registry implementation
+- Service discovery (Consul, Kubernetes)
+- Service health checking and deregistration
+
+### Epic 5: gRPC Services (Epic 5)
+- Complete gRPC service definitions for all services
+- gRPC clients for service communication
 - HTTP clients as fallback option
 
 ## References