pos-system/docs/en/skills/README.md

# Cursor Skills Documentation

> Comprehensive documentation for all Cursor AI skills used in the GoodGo Microservices Platform

## Overview

Cursor Skills are specialized knowledge modules that guide AI assistants in following project-specific patterns, standards, and best practices. This directory contains detailed documentation for each skill, including when to use them, key concepts, common patterns, and real-world examples from the codebase.

Each skill documentation includes **Mermaid diagrams** that visually illustrate workflows, architectures, patterns, and relationships to enhance understanding of complex concepts.

## Available Skills

The GoodGo platform includes **26 Cursor Skills** organized by category:

### API & Data Layer

#### [API Design](./api-design.md)
RESTful API design standards for GoodGo microservices. Use when creating new API endpoints, designing DTOs, implementing controllers, writing OpenAPI documentation, or standardizing API responses.

#### [Database & Prisma](./database-prisma.md)
Prisma ORM and database patterns for GoodGo microservices. Use when working with databases, creating Prisma schemas, writing migrations, implementing repositories, or optimizing queries.

#### [Error Handling Patterns](./error-handling-patterns.md)
Error handling patterns and conventions for GoodGo microservices. Use when implementing error handling, creating custom error classes, handling exceptions, standardizing error responses, or debugging error scenarios.

#### [Repository Pattern](./repository-pattern.md)
Repository pattern implementation and best practices for GoodGo microservices. Use when implementing data access layers, extending BaseRepository, writing database queries, handling transactions, or optimizing database operations.

#### [Caching Patterns](./caching-patterns.md)
Caching strategies and patterns for GoodGo microservices including multi-layer cache, Redis caching, cache key naming, TTL strategies, cache invalidation, and cache-aside patterns.

### Code Quality & Testing

#### [Testing Patterns](./testing-patterns.md)
Testing best practices for GoodGo microservices. Use when writing unit tests, integration tests, E2E tests, setting up Jest, mocking dependencies, or debugging test failures.

#### [Code Comments](./comment-code.md)
Add bilingual code comments in Vietnamese and English for better documentation. Use when adding comments to code, documenting functions/classes, or when user requests Vietnamese/English documentation.

#### [Middleware Patterns](./middleware-patterns.md)
Express middleware patterns and best practices for GoodGo microservices. Use when creating custom middleware, organizing middleware chains, handling request/response transformation, or implementing cross-cutting concerns.

#### [Service Layer Patterns](./service-layer-patterns.md)
Service layer organization and patterns for GoodGo microservices. Use when implementing business logic, organizing service classes, using dependency injection, composing services, or separating concerns between controllers and repositories.

### Infrastructure & Operations

#### [Kubernetes Deployment](./deployment-kubernetes.md)
Kubernetes deployment patterns for GoodGo microservices. Use when deploying to staging/production, creating K8s manifests, configuring HPA, setting up ingress, or troubleshooting K8s deployments.

#### [Event-Driven Architecture](./event-driven-architecture.md)
Event-driven architecture patterns with Apache Kafka for GoodGo microservices. Use when implementing async communication, event publishing/consuming, event sourcing, CQRS, or integrating event streams with HTTP endpoints.

#### [Inter-Service Communication](./inter-service-communication.md)
Inter-service communication patterns for GoodGo microservices including gRPC, GraphQL, service-to-service authentication, protocol selection, and client patterns. Use when implementing service-to-service calls, choosing communication protocols, or building service clients.

#### [Data Consistency Patterns](./data-consistency-patterns.md)
Data consistency patterns for distributed microservices including Saga patterns, distributed transactions, eventual consistency, compensation, and idempotency. Use when handling distributed transactions, implementing eventual consistency, or managing data synchronization across services.

#### [API Gateway Advanced](./api-gateway-advanced.md)
Advanced API Gateway patterns for GoodGo microservices including API composition, request/response transformation, service mesh integration, advanced routing, and gateway-level resilience. Use when implementing API aggregation, service composition, or advanced gateway features.

#### [Configuration Management](./configuration-management.md)
Configuration management patterns for GoodGo microservices including feature flags, dynamic configuration reloading, environment-specific configurations, and secrets management. Use when implementing feature toggles, managing configuration, or handling environment variables.

#### [Performance Optimization](./performance-optimization.md)
Performance optimization patterns for GoodGo microservices including database query optimization, memory leak detection, profiling, connection pooling, and caching strategies. Use when optimizing performance, profiling applications, or detecting performance bottlenecks.

#### [Observability & Monitoring](./observability-monitoring.md)
Observability and monitoring patterns for GoodGo microservices. Use when adding metrics, implementing logging, setting up tracing, creating health checks, or debugging production issues.

#### [Resilience Patterns](./resilience-patterns.md)
Resilience patterns for GoodGo microservices including circuit breaker, retry strategies, timeout handling, and graceful degradation for improved fault tolerance and system reliability.

#### [Microservices Development Process](./microservices-development-process.md)
Standard development process for creating and maintaining microservices in GoodGo platform. Use when creating new services, migrating services, refactoring services, or planning service implementations.

#### [CI/CD Advanced Patterns](./cicd-advanced-patterns.md)
Advanced CI/CD patterns for GoodGo microservices including blue-green deployments, canary releases, automated rollback, deployment verification, and progressive delivery. Use when implementing advanced deployment strategies, automated rollbacks, or progressive delivery pipelines.

#### [Infrastructure as Code](./infrastructure-as-code.md)
Infrastructure as Code patterns for GoodGo platform including Terraform modules, Kubernetes operators, infrastructure testing, GitOps workflows, and multi-environment management. Use when managing infrastructure, implementing GitOps, or creating reusable infrastructure modules.

#### [API Versioning Strategy](./api-versioning-strategy.md)
API versioning strategies for GoodGo microservices including semantic versioning, backward compatibility patterns, API deprecation, version negotiation, and breaking changes handling. Use when versioning APIs, handling breaking changes, or implementing API deprecation strategies.

#### [Service Discovery & Registry](./service-discovery-registry.md)
Service discovery and registry patterns for GoodGo microservices including service registry, health check orchestration, load balancing strategies, and service mesh integration. Use when implementing service discovery, managing service health, or integrating with service mesh.

### Standards & Security

#### [Project Rules](./project-rules.md)
GoodGo Microservices Platform coding standards and architecture patterns. Use when working with services, apps, packages, or infrastructure.

#### [Security](./security.md)
Security best practices and patterns for GoodGo microservices platform. Use when implementing authentication, authorization, data protection, input validation, rate limiting, secrets management, or security testing across all services.

#### [Documentation](./documentation.md)
Guidelines for writing technical documentation in the GoodGo project. Use when creating or updating README files, guides, architecture docs, or API documentation. Ensures bilingual (EN/VI) consistency and proper structure.

## Quick Reference

### By Use Case

| Task | Recommended Skills |
|------|-------------------|
| Create new API endpoint | API Design, Security, Testing Patterns |
| Setup new service | Project Rules, Database & Prisma, Observability |
| Write tests | Testing Patterns, Comment Code |
| Deploy to production | Kubernetes Deployment, Observability, Security |
| Debug production issues | Observability & Monitoring, Security |
| Write documentation | Documentation, Comment Code |
| Implement authentication | Security, API Design, Database & Prisma |
| Optimize database queries | Database & Prisma, Observability |
| Implement event-driven communication | Event-Driven Architecture, Resilience Patterns |
| Implement service-to-service calls | Inter-Service Communication, Security, Resilience Patterns |
| Handle distributed transactions | Data Consistency Patterns, Event-Driven Architecture |
| Optimize performance | Performance Optimization, Observability & Monitoring |
| Manage feature flags | Configuration Management |
| Deploy with zero downtime | CI/CD Advanced Patterns, Deployment Kubernetes |

### Skill Dependencies

```
Project Rules (Foundation)
    ├── API Design
    ├── Database & Prisma
    ├── Security
    ├── Microservices Development Process
    └── Testing Patterns
        └── Comment Code

Data Layer
    ├── Repository Pattern
    │   ├── Database & Prisma
    │   └── Error Handling Patterns
    └── Caching Patterns
        └── Repository Pattern

Application Layer
    ├── Service Layer Patterns
    │   ├── Repository Pattern
    │   ├── Caching Patterns
    │   └── Error Handling Patterns
    └── Middleware Patterns
        └── Error Handling Patterns

Infrastructure
    ├── Event-Driven Architecture
    │   ├── Resilience Patterns
    │   ├── Error Handling Patterns
    │   └── Observability & Monitoring
    ├── Inter-Service Communication
    │   ├── API Design
    │   ├── Security
    │   └── Resilience Patterns
    ├── Data Consistency Patterns
    │   ├── Event-Driven Architecture
    │   ├── Database & Prisma
    │   └── Error Handling Patterns
    ├── API Gateway Advanced
    │   ├── Middleware Patterns
    │   ├── Security
    │   └── API Design
    ├── Configuration Management
    │   └── Observability & Monitoring
    ├── Performance Optimization
    │   ├── Database & Prisma
    │   ├── Caching Patterns
    │   └── Observability & Monitoring
    ├── CI/CD Advanced Patterns
    │   ├── Deployment Kubernetes
    │   └── Testing Patterns
    ├── Infrastructure as Code
    │   └── Deployment Kubernetes
    ├── API Versioning Strategy
    │   ├── API Design
    │   └── Middleware Patterns
    ├── Service Discovery & Registry
    │   ├── Deployment Kubernetes
    │   └── Observability & Monitoring
    └── Resilience Patterns
        ├── Error Handling Patterns
        └── Service Layer Patterns

Documentation (Cross-cutting)
    └── All skills
Observability (Cross-cutting)
    └── All services
Kubernetes Deployment (Infrastructure)
    └── All services
```

## How to Use Skills

1. **When starting new task**: Review relevant skills in this directory
2. **During development**: Reference skill documentation for patterns and examples
3. **When stuck**: Check skill docs for best practices and common solutions
4. **During code review**: Use skills as checklist to ensure standards compliance

## Related Documentation

- [System Architecture](../architecture/system-design.md) - System design patterns
- [Development Guide](../guides/development.md) - Development workflow
- [Deployment Guide](../guides/deployment.md) - Deployment procedures
- [API Documentation](../api/openapi/) - OpenAPI specifications

## Contributing

When updating or adding new skills:

1. Update skill source file in `.cursor/skills/{skill-name}/SKILL.md`
2. Update corresponding documentation in `docs/en/skills/{skill-name}.md`
3. Update Vietnamese translation in `docs/vi/skills/{skill-name}.md`
4. Update this index file with any changes
5. Ensure bilingual consistency

## Resources

- [Cursor Skills Documentation](https://cursor.sh/docs) - Official Cursor documentation
- [Cursor AI](https://cursor.sh) - Cursor IDE homepage
- Project Skills: `.cursor/skills/` - Source skill files