pos-system/docs/en/templates/architecture.md

# [Architecture Name]

> Brief English description of this architectural component or system

## Overview Diagram

```mermaid
graph TD
    A[Component A] --> B[Component B]
    B --> C[Component C]
    C --> D[Component D]
    
    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#f0e1ff
    style D fill:#e1ffe1
```

## Architecture Description

Detailed English explanation of the architecture, including:
- Purpose and goals
- Key components
- Design decisions
- Technology choices
- Trade-offs and considerations

## System Context

```mermaid
C4Context
    title System Context Diagram for GoodGo Microservices Platform
    
    Person(user, "End User", "Platform users")
    Person(admin, "Administrator", "System administrators")
    
    System_Boundary(platform, "GoodGo Platform") {
        System(gateway, "Traefik Gateway", "API Gateway, routing, load balancing")
        System(services, "Microservices", "IAM, Storage, Chat, Membership, etc.")
        System(rabbitmq, "RabbitMQ", "Message broker for async events")
    }
    
    System_Ext(neon, "Neon PostgreSQL", "Serverless database")
    System_Ext(redis, "Redis", "Cache and session store")
    System_Ext(minio, "MinIO/Aliyun OSS", "Object storage")
    System_Ext(monitoring, "Observability Stack", "Prometheus + Grafana + Loki + Jaeger")
    
    Rel(user, gateway, "Uses", "HTTPS")
    Rel(admin, gateway, "Manages", "HTTPS")
    Rel(gateway, services, "Routes to", "HTTP")
    Rel(services, neon, "Stores data", "PostgreSQL")
    Rel(services, redis, "Caches data", "Redis Protocol")
    Rel(services, rabbitmq, "Pub/Sub events", "AMQP")
    Rel(services, minio, "Stores files", "S3 API")
    Rel(services, monitoring, "Sends telemetry", "HTTP/gRPC")
```

The GoodGo Platform uses microservices architecture where all client requests go through Traefik API Gateway. Services communicate synchronously via REST/HTTP and asynchronously via RabbitMQ events. Each service has its own database schema in Neon PostgreSQL and uses Redis for caching.

## Components

### Component A

Description of Component A, its responsibilities, and how it fits into the overall architecture.

**Key Features**:
- Feature 1
- Feature 2
- Feature 3

**Technologies Used**:
- Technology 1
- Technology 2

**Code Reference**:
```typescript
// Example code showing how this component is implemented
import { ComponentA } from './component-a';

const componentA = new ComponentA({
  config: appConfig,
});
```

**File Location**: [`component-a.ts`](file:///path/to/component-a.ts)

---

### Real-World Example: Storage Service

File storage management service supporting multiple cloud providers (MinIO, Aliyun OSS).

**Key Features**:
- Multi-provider pattern (MinIO/Aliyun OSS)
- Pre-signed URL generation for secure uploads/downloads
- User quota management
- File sharing with time-limited tokens
- Direct client upload pattern

**Technologies Used**:
- .NET 10, Entity Framework Core
- MinIO Client, Aliyun OSS SDK
- Redis (caching)
- PostgreSQL (Neon)

**Architecture Pattern**:
```csharp
// Provider abstraction
public interface IStorageProvider
{
    Task<string> UploadFileAsync(Stream fileStream, string fileName, CancellationToken ct);
    Task<string> GeneratePresignedUrlAsync(string objectKey, int expiryMinutes, CancellationToken ct);
}

// Concrete implementations
public class MinioStorageProvider : IStorageProvider { }
public class AliyunOssStorageProvider : IStorageProvider { }

// Factory pattern for provider selection
public class StorageProviderFactory
{
    public IStorageProvider CreateProvider(string providerName) { }
}
```

**File Location**: [`services/storage-service-net/`](file:///Users/velikho/Desktop/WORKING/Base/services/storage-service-net)

---

### Real-World Example: IAM Service

Identity and Access Management service handling authentication, authorization, and RBAC.

**Key Features**:
- JWT authentication (RS256)
- Role-Based Access Control (RBAC)
- MFA support (TOTP)
- Session management
- Permission caching

**Technologies Used**:
- .NET 10, Duende IdentityServer
- Entity Framework Core
- Redis (caching)
- PostgreSQL (Neon)

**File Location**: [`services/iam-service-net/`](file:///Users/velikho/Desktop/WORKING/Base/services/iam-service-net)

## Data Flow

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Service
    participant Database
    
    Client->>API: Request
    API->>Service: Process
    Service->>Database: Query
    Database-->>Service: Result
    Service-->>API: Response
    API-->>Client: JSON
```

Detailed explanation of the data flow:
1. Step 1: Description
2. Step 2: Description
3. Step 3: Description

## Database Architecture

```mermaid
erDiagram
    Entity1 ||--o{ Entity2 : has
    Entity2 ||--o{ Entity3 : contains
    
    Entity1 {
        string id PK
        string name
        datetime createdAt
    }
    
    Entity2 {
        string id PK
        string entity1Id FK
        string description
    }
```

Database schema description, relationships, and design decisions.

## Design Decisions

### Decision 1: [Decision Title]

**Context**: Why this decision was needed

**Decision**: What was decided

**Consequences**: Impact of the decision (positive and negative)

**Alternatives Considered**: Other options that were evaluated

## Performance Characteristics

Description of performance expectations and optimizations based on GoodGo Platform standards.

| Metric | Target | Notes |
|------------------|-------------------|-----------------|
| API Response Time (P95) | < 200ms | Excluding external API calls |
| API Response Time (P99) | < 500ms | Peak load scenarios |
| Throughput | 1000 req/s | Per service instance |
| Database Query Time (P95) | < 50ms | Simple queries with indexes |
| Cache Hit Rate (L1) | > 40% | In-memory cache |
| Cache Hit Rate (L2) | > 80% | Redis cache |
| Service Availability | > 99.9% | Monthly uptime target |
| Error Rate | < 1% | 4xx + 5xx errors |

**Optimization Strategies**:
- **Multi-layer caching**: L1 (Memory) + L2 (Redis)
- **Connection pooling**: For PostgreSQL connections
- **Pagination**: Max 100 items per page for list endpoints
- **Database indexes**: On frequently queried fields
- **Async events**: Fire-and-forget with RabbitMQ
- **CDN**: For static assets (Next.js)

## Security Considerations

Security features, authentication, authorization, data protection

- Security feature 1
- Security feature 2

## Deployment

How this architecture is deployed and scaled in GoodGo Platform.

### Traefik API Gateway Routing

```yaml
# docker-compose.yml
services:
  storage-service-net:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.storage-service.rule=PathPrefix(`/api/v1/storage`)"
      - "traefik.http.services.storage-service.loadbalancer.server.port=8080"
      - "traefik.http.routers.storage-service.middlewares=strip-prefix@docker"
```

### Kubernetes Deployment

```mermaid
graph LR
    LB[Load Balancer] --> Traefik[Traefik Gateway<br/>2-3 replicas]
    Traefik --> A[Service A<br/>2-10 replicas HPA]
    Traefik --> B[Service B<br/>2-10 replicas HPA]
    Traefik --> C[Service C<br/>2-10 replicas HPA]
    A --> DB[(Neon PostgreSQL<br/>Serverless)]
    B --> DB
    C --> DB
    A --> Cache[(Redis Cluster<br/>3 nodes)]
    B --> Cache
    C --> Cache
    
    style LB fill:#1565c0,stroke:#fff,stroke-width:2px,color:#fff
    style Traefik fill:#0f4c81,stroke:#fff,stroke-width:2px,color:#fff
    style A fill:#283593,stroke:#fff,stroke-width:2px,color:#fff
    style B fill:#4527a0,stroke:#fff,stroke-width:2px,color:#fff
    style C fill:#4527a0,stroke:#fff,stroke-width:2px,color:#fff
    style DB fill:#5e35b1,stroke:#fff,stroke-width:2px,color:#fff
    style Cache fill:#ef6c00,stroke:#fff,stroke-width:2px,color:#fff
```

**Resource Allocation**:

| Service | Requests | Limits |
|---------|----------|--------|
| **Microservices** | 256Mi RAM, 250m CPU | 512Mi RAM, 500m CPU |
| **Traefik** | 512Mi RAM, 500m CPU | 1Gi RAM, 1000m CPU |
| **Redis** | 2Gi RAM, 1 CPU | 4Gi RAM, 2 CPU |

## Monitoring & Observability

How to monitor this architecture, key metrics, alerts

**Key Metrics**:
- Metric 1
- Metric 2

**Health Checks**:
- `/health/live` - Liveness probe
- `/health/ready` - Readiness probe

## Related Documentation

### Architecture Documents
- [System Design](../architecture/system-design.md) - Overall platform architecture
- [Microservices Communication](../architecture/microservices-communication.md) - Service communication patterns
- [Caching Architecture](../architecture/caching-architecture.md) - Redis caching strategies
- [Event-Driven Architecture](../architecture/event-driven-architecture.md) - RabbitMQ event patterns

### Skills Reference
- [CQRS with MediatR](../skills/cqrs-mediatr.md) - CQRS pattern
- [Repository Pattern](../skills/repository-pattern.md) - EF Core repository
- [Domain-Driven Design](../skills/domain-driven-design.md) - DDD patterns

### Guides
- [Local Development](../guides/local-development.md) - Setup dev environment
- [Deployment](../guides/deployment.md) - Kubernetes deployment

## References

- [External Resource 1](https://example.com) - Description
- [External Resource 2](https://example.com) - Description

---

**Last Updated**: 2026-01-14  
**Authors**: VelikHo (hongochai10@icloud.com)  
**Reviewers**: Reviewer Names