feat: microservice architecture

docs/content/architecture.md

@@ -13,7 +13,12 @@ This document provides a comprehensive overview of the Go Platform architecture,
 
 ## High-Level Architecture
 
-The Go Platform follows a **modular monolith** architecture that can evolve into microservices. The platform consists of a core kernel and pluggable feature modules.
+The Go Platform follows a **microservices architecture** where each module is an independent service:
+- **Core Services**: Authentication, Identity, Authorization, Audit, etc.
+- **Feature Services**: Blog, Billing, Analytics, etc. (modules)
+- **Infrastructure Services**: Cache, Event Bus, Scheduler, etc.
+
+All services communicate via gRPC (primary) or HTTP (fallback), with service discovery via a service registry. Services share infrastructure (PostgreSQL, Redis, Kafka) but are independently deployable and scalable.
 
 ```mermaid
 graph TB
@@ -581,10 +586,168 @@ graph TB
     style Module fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
 ```
 
+## Microservices Architecture
+
+The platform is designed as **microservices from day one**, with each module being an independent service.
+
+### Service Architecture
+
+```mermaid
+graph TB
+    subgraph "API Gateway"
+        Gateway[API Gateway<br/>Routing & Auth]
+    end
+    
+    subgraph "Core Services"
+        AuthSvc[Auth Service<br/>:8081]
+        IdentitySvc[Identity Service<br/>:8082]
+        AuthzSvc[Authz Service<br/>:8083]
+        AuditSvc[Audit Service<br/>:8084]
+    end
+    
+    subgraph "Feature Services"
+        BlogSvc[Blog Service<br/>:8091]
+        BillingSvc[Billing Service<br/>:8092]
+        AnalyticsSvc[Analytics Service<br/>:8093]
+    end
+    
+    subgraph "Infrastructure"
+        DB[(PostgreSQL)]
+        Cache[(Redis)]
+        Queue[Kafka]
+        Registry[Service Registry]
+    end
+    
+    Gateway --> AuthSvc
+    Gateway --> IdentitySvc
+    Gateway --> BlogSvc
+    Gateway --> BillingSvc
+    
+    AuthSvc --> IdentitySvc
+    AuthSvc --> Registry
+    BlogSvc --> AuthzSvc
+    BlogSvc --> IdentitySvc
+    BlogSvc --> Registry
+    BillingSvc --> IdentitySvc
+    BillingSvc --> Registry
+    
+    AuthSvc --> DB
+    IdentitySvc --> DB
+    BlogSvc --> DB
+    BillingSvc --> DB
+    
+    AuthSvc --> Cache
+    BlogSvc --> Cache
+    BillingSvc --> Cache
+    
+    BlogSvc --> Queue
+    BillingSvc --> Queue
+    AnalyticsSvc --> Queue
+    
+    style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Registry fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+```
+
+### Service Communication
+
+All inter-service communication uses service client interfaces:
+
+```mermaid
+graph TB
+    subgraph "Service Client Interface"
+        Interface[Service Interface<br/>pkg/services/]
+    end
+    
+    subgraph "Implementations"
+        GRPC[gRPC Client<br/>Primary]
+        HTTP[HTTP Client<br/>Fallback]
+    end
+    
+    subgraph "Service Registry"
+        Registry[Service Registry<br/>Discovery & Resolution]
+    end
+    
+    Interface --> GRPC
+    Interface --> HTTP
+    
+    Registry --> GRPC
+    Registry --> HTTP
+    
+    style Interface fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Registry fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+```
+
+### Service Communication Patterns
+
+The platform uses three communication patterns:
+
+1. **Synchronous Service Calls** (via Service Clients):
+   - gRPC calls (primary) - type-safe, efficient
+   - HTTP/REST calls (fallback) - for external integration
+   - All calls go through service client interfaces
+   - Service discovery via registry
+
+2. **Asynchronous Events** (via Event Bus):
+   - Distributed via Kafka
+   - Preferred for cross-service communication
+   - Event-driven architecture for loose coupling
+
+3. **Shared Infrastructure** (For state):
+   - Redis for cache and distributed state
+   - PostgreSQL for persistent data
+   - Kafka for events
+
+### Service Registry
+
+The service registry enables service discovery and resolution:
+
+```mermaid
+graph TB
+    subgraph "Service Registry"
+        Registry[Service Registry Interface]
+        Consul[Consul Registry]
+        K8s[K8s Service Discovery]
+        Etcd[etcd Registry]
+    end
+    
+    subgraph "Services"
+        AuthSvc[Auth Service]
+        IdentitySvc[Identity Service]
+        BlogSvc[Blog Service]
+    end
+    
+    Registry --> Consul
+    Registry --> K8s
+    Registry --> Etcd
+    
+    Consul --> AuthSvc
+    K8s --> IdentitySvc
+    Etcd --> BlogSvc
+    
+    style Registry fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+```
+
+### Scaling Strategy
+
+#### Independent Service Scaling
+- Scale individual services based on load
+- Independent resource allocation
+- Independent deployment
+- Better resource utilization
+- Team autonomy
+
+#### Development Mode
+- For local development, multiple services can run in the same process
+- Services still communicate via gRPC/HTTP (no direct calls)
+- Docker Compose for easy local setup
+- Maintains microservices architecture even in development
+
 ## Next Steps
 
 - [Module Architecture](./architecture-modules.md) - Detailed module architecture and design
 - [Module Requirements](./module-requirements.md) - Requirements for each module
 - [Component Relationships](./component-relationships.md) - Detailed component interactions
 - [ADRs](../adr/README.md) - Architecture Decision Records
+- [ADR-0029: Microservices Architecture](../adr/0029-microservices-architecture.md) - Microservices strategy
+- [ADR-0030: Service Communication](../adr/0030-service-communication-strategy.md) - Communication patterns