Initial commit

skills/assets/ARCHITECTURE-microservices.md

@@ -0,0 +1,176 @@
+# Architecture Overview - Microservices
+
+This document serves as a comprehensive guide to the microservices architecture, enabling rapid understanding of service boundaries, communication patterns, and system design.
+
+## 1. Project Structure
+
+```
+[Project Root]/
+├── services/                   # Microservices
+│   ├── api-gateway/           # Entry point for all requests
+│   ├── user-service/          # User management
+│   ├── [service-name]/        # Additional services
+│   └── shared/                # Shared libraries
+├── infrastructure/            # Infrastructure as code
+│   ├── k8s/                  # Kubernetes manifests
+│   └── terraform/            # Terraform configs
+├── docs/                     # Documentation
+└── scripts/                  # DevOps scripts
+```
+
+## 2. High-Level System Diagram
+
+```
+[API Gateway] <--> [Service Mesh/Load Balancer]
+                            |
+        +-------------------+-------------------+
+        |                   |                   |
+    [Service 1]        [Service 2]         [Service 3]
+        |                   |                   |
+    [Database 1]       [Database 2]        [Database 3]
+        |                                       |
+        +-------------[Message Queue]-----------+
+```
+
+## 3. Core Components
+
+### 3.1. API Gateway
+
+**Name:** [e.g., Kong, AWS API Gateway, Custom Gateway]
+
+**Description:** Routes requests, handles authentication, rate limiting, and request aggregation
+
+**Technologies:** [e.g., Kong, Express Gateway, Spring Cloud Gateway]
+
+**Deployment:** [e.g., Kubernetes, AWS]
+
+### 3.2. Microservices
+
+#### 3.2.1. [Service Name]
+
+**Name:** [e.g., User Service, Order Service]
+
+**Description:** [Service responsibility and domain]
+
+**Technologies:** [Language and framework]
+
+**API Endpoints:** [Key endpoints this service exposes]
+
+**Dependencies:** [Other services it calls]
+
+**Database:** [Dedicated database if any]
+
+**Deployment:** [Container registry, orchestration]
+
+### 3.3. Service Mesh
+
+**Name:** [e.g., Istio, Linkerd, Consul]
+
+**Description:** Handles service-to-service communication, observability, and security
+
+**Key Features:** [Traffic management, circuit breaking, etc.]
+
+## 4. Data Stores
+
+### 4.1. Service-Specific Databases
+
+Each microservice has its own database following the database-per-service pattern.
+
+#### [Service Name] Database
+
+**Type:** [PostgreSQL, MongoDB, etc.]
+
+**Purpose:** [Data domain this service owns]
+
+**Key Schemas:** [Main tables/collections]
+
+### 4.2. Shared Data Stores
+
+**Name:** [e.g., Redis Cache, Message Queue]
+
+**Type:** [Redis, RabbitMQ, Kafka]
+
+**Purpose:** [Cross-service caching or messaging]
+
+## 5. External Integrations / APIs
+
+**Service Name:** [e.g., Payment Gateway, Email Service]
+
+**Purpose:** [Functionality]
+
+**Integration Method:** [REST, gRPC, Message Queue]
+
+**Owning Service:** [Which microservice handles this integration]
+
+## 6. Deployment & Infrastructure
+
+**Cloud Provider:** [AWS, GCP, Azure]
+
+**Orchestration:** [Kubernetes, Docker Swarm, ECS]
+
+**Service Discovery:** [Consul, Eureka, Kubernetes DNS]
+
+**CI/CD Pipeline:** [Jenkins, GitLab CI, GitHub Actions]
+
+**Container Registry:** [Docker Hub, ECR, GCR]
+
+**Monitoring & Logging:** [Prometheus, Grafana, ELK, Jaeger for tracing]
+
+**Configuration Management:** [Consul, etcd, ConfigMap]
+
+## 7. Security Considerations
+
+**Authentication:** [OAuth2, JWT at API Gateway]
+
+**Authorization:** [Service-level RBAC, mutual TLS]
+
+**Service-to-Service Security:** [mTLS, API keys, service mesh policies]
+
+**Data Encryption:** [TLS in transit, encrypted at rest]
+
+**Secrets Management:** [Vault, AWS Secrets Manager, Kubernetes Secrets]
+
+## 8. Development & Testing Environment
+
+**Local Setup Instructions:** [Docker Compose, Minikube, or Skaffold]
+
+**Testing Strategy:**
+- Unit Tests: [Per service]
+- Integration Tests: [Between services]
+- Contract Tests: [API contracts]
+- E2E Tests: [Full system tests]
+
+**Testing Frameworks:** [Service-specific frameworks]
+
+## 9. Future Considerations / Roadmap
+
+- [e.g., Implement event sourcing for specific services]
+- [e.g., Add service mesh for better observability]
+- [e.g., Break down Service X into smaller services]
+- [e.g., Implement CQRS pattern]
+
+## 10. Project Identification
+
+**Project Name:** [Microservices System Name]
+
+**Repository URL:** [Monorepo or organization URL]
+
+**Primary Contact/Team:** [Platform Team]
+
+**Date of Last Update:** [YYYY-MM-DD]
+
+**Service Catalog:** [Link to service registry/documentation]
+
+## 11. Glossary / Acronyms
+
+**API Gateway:** Entry point for all external requests
+
+**Service Mesh:** Infrastructure layer for service-to-service communication
+
+**Circuit Breaker:** Pattern to prevent cascading failures
+
+**CQRS:** Command Query Responsibility Segregation
+
+**Event Sourcing:** Storing state changes as events
+
+**[Add domain-specific terms]**