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]**

skills/assets/ARCHITECTURE-monolith.md

@@ -0,0 +1,214 @@
+# Architecture Overview - Monolithic Application
+
+This document describes the monolithic architecture, providing clear understanding of the application structure, module organization, and system design.
+
+## 1. Project Structure
+
+```
+[Project Root]/
+├── src/                       # Source code
+│   ├── api/                  # API layer (controllers, routes)
+│   ├── services/             # Business logic layer
+│   ├── models/               # Data models
+│   ├── repositories/         # Data access layer
+│   ├── middleware/           # Request processing middleware
+│   ├── utils/                # Utility functions
+│   └── config/               # Configuration files
+├── tests/                    # Test suites
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+├── migrations/               # Database migrations
+├── public/                   # Static assets (if serving frontend)
+├── docs/                     # Documentation
+└── scripts/                  # Build and deployment scripts
+```
+
+## 2. High-Level System Diagram
+
+```
+[User/Client]
+      |
+      v
+[Load Balancer] (optional)
+      |
+      v
+[Application Server]
+      |
+      +-- [API Layer]
+      |        |
+      |        v
+      +-- [Service Layer]
+      |        |
+      |        v
+      +-- [Data Access Layer]
+      |        |
+      |        v
+      +-- [Database]
+      |
+      +-- [Cache] (optional)
+      |
+      +-- [External Services]
+```
+
+## 3. Core Components
+
+### 3.1. Application Server
+
+**Name:** [e.g., Main Application, Web Server]
+
+**Description:** Single unified application handling all business logic
+
+**Technologies:** [e.g., Node.js/Express, Python/Django, Java/Spring Boot, .NET]
+
+**Deployment:** [e.g., AWS EC2, Heroku, Docker container]
+
+### 3.2. Layered Architecture
+
+#### 3.2.1. API/Controller Layer
+
+**Description:** Handles HTTP requests, routing, and response formatting
+
+**Key Modules:** [List main controllers/route groups]
+
+**Responsibilities:** Request validation, authentication, response serialization
+
+#### 3.2.2. Service/Business Logic Layer
+
+**Description:** Core business logic and workflows
+
+**Key Modules:** [List main service classes/modules]
+
+**Responsibilities:** Business rules, transaction management, orchestration
+
+#### 3.2.3. Data Access Layer
+
+**Description:** Database interactions and data persistence
+
+**Key Modules:** [List repositories/DAO classes]
+
+**Responsibilities:** CRUD operations, query building, ORM management
+
+### 3.3. Frontend (if integrated)
+
+**Name:** [e.g., Web UI, Admin Panel]
+
+**Description:** User interface served by the monolith
+
+**Technologies:** [e.g., Server-side rendered with Jinja/EJS, or SPA with React/Vue]
+
+**Location:** [public/ or templates/ directory]
+
+## 4. Data Stores
+
+### 4.1. Primary Database
+
+**Name:** [e.g., Main Application Database]
+
+**Type:** [PostgreSQL, MySQL, MongoDB, etc.]
+
+**Purpose:** Stores all application data
+
+**Key Schemas/Collections:**
+- users
+- [entity names]
+- [domain tables]
+
+### 4.2. Cache (if used)
+
+**Name:** [e.g., Redis Cache]
+
+**Type:** Redis, Memcached
+
+**Purpose:** Performance optimization, session storage
+
+**Cached Data:** [What gets cached]
+
+## 5. External Integrations / APIs
+
+**Service Name:** [e.g., Payment Processor, Email Service]
+
+**Purpose:** [Functionality]
+
+**Integration Method:** [REST API, SDK, Webhook]
+
+**Integration Location:** [Which service/module handles it]
+
+## 6. Deployment & Infrastructure
+
+**Cloud Provider:** [AWS, GCP, Azure, On-premise]
+
+**Hosting:** [EC2, App Engine, Virtual Machine, Container]
+
+**Database Hosting:** [RDS, Cloud SQL, Managed service]
+
+**CI/CD Pipeline:** [GitHub Actions, Jenkins, GitLab CI]
+
+**Load Balancing:** [ALB, nginx, Cloud Load Balancer]
+
+**Monitoring & Logging:** [CloudWatch, Application Insights, ELK]
+
+**Scaling Strategy:** [Vertical scaling, horizontal with load balancer]
+
+## 7. Security Considerations
+
+**Authentication:** [Session-based, JWT, OAuth2]
+
+**Authorization:** [RBAC implementation, middleware]
+
+**Data Encryption:** [TLS/HTTPS, database encryption]
+
+**Security Practices:**
+- Input validation and sanitization
+- SQL injection prevention (ORM/parameterized queries)
+- CSRF protection
+- Rate limiting
+- Security headers
+
+**Secrets Management:** [Environment variables, vault, cloud secrets]
+
+## 8. Development & Testing Environment
+
+**Local Setup Instructions:** [Steps to run locally]
+
+**Development Database:** [Docker, local instance]
+
+**Testing Frameworks:** 
+- Unit: [e.g., Jest, Pytest, JUnit]
+- Integration: [e.g., Supertest, TestContainers]
+- E2E: [e.g., Cypress, Selenium]
+
+**Code Quality Tools:** [ESLint, Prettier, SonarQube]
+
+**Development Workflow:** [Git workflow, branch strategy]
+
+## 9. Future Considerations / Roadmap
+
+- [e.g., Consider extracting high-traffic modules into separate services]
+- [e.g., Implement caching layer for better performance]
+- [e.g., Add background job processing with queue]
+- [e.g., Evaluate migration to microservices if scaling demands increase]
+
+## 10. Project Identification
+
+**Project Name:** [Application Name]
+
+**Repository URL:** [Git repository]
+
+**Primary Contact/Team:** [Development team]
+
+**Date of Last Update:** [YYYY-MM-DD]
+
+**Application Version:** [Current version]
+
+## 11. Glossary / Acronyms
+
+**Monolith:** Single-tiered application where all components are tightly coupled
+
+**ORM:** Object-Relational Mapping - translates between database and objects
+
+**Repository Pattern:** Data access abstraction layer
+
+**Service Layer:** Business logic layer between controllers and data access
+
+**[Add application-specific terms]**

skills/assets/ARCHITECTURE.md

@@ -0,0 +1,121 @@
+# Architecture Overview
+
+This document serves as a critical, living template designed to equip agents with a rapid and comprehensive understanding of the codebase's architecture, enabling efficient navigation and effective contribution from day one. Update this document as the codebase evolves.
+
+## 1. Project Structure
+
+This section provides a high-level overview of the project's directory and file structure, categorised by architectural layer or major functional area.
+
+```
+[Project Root]/
+├── [Add your project structure here]
+```
+
+## 2. High-Level System Diagram
+
+Provide a simple diagram showing major components and their interactions. Focus on data flow and key boundaries.
+
+```
+[User] <--> [Component] <--> [Component] <--> [Data Store]
+```
+
+## 3. Core Components
+
+List and describe the main components of the system.
+
+### 3.1. Frontend
+
+**Name:** [e.g., Web App, Mobile App]
+
+**Description:** [Describe primary purpose and key functionalities]
+
+**Technologies:** [e.g., React, Vue.js, Angular, React Native]
+
+**Deployment:** [e.g., Vercel, Netlify, S3/CloudFront]
+
+### 3.2. Backend Services
+
+#### 3.2.1. [Service Name]
+
+**Name:** [e.g., API Service, User Service]
+
+**Description:** [Describe purpose]
+
+**Technologies:** [e.g., Node.js, Python, Java, Go]
+
+**Deployment:** [e.g., AWS, Kubernetes, Cloud Run]
+
+## 4. Data Stores
+
+List databases and persistent storage solutions.
+
+### 4.1. [Data Store Name]
+
+**Name:** [e.g., Primary Database, Cache]
+
+**Type:** [e.g., PostgreSQL, MongoDB, Redis]
+
+**Purpose:** [Describe what data it stores and why]
+
+**Key Schemas/Collections:** [List main tables/collections]
+
+## 5. External Integrations / APIs
+
+List third-party services and external APIs.
+
+**Service Name:** [e.g., Stripe, SendGrid]
+
+**Purpose:** [e.g., Payment processing]
+
+**Integration Method:** [e.g., REST API, SDK]
+
+## 6. Deployment & Infrastructure
+
+**Cloud Provider:** [e.g., AWS, GCP, Azure]
+
+**Key Services Used:** [e.g., EC2, Lambda, Kubernetes]
+
+**CI/CD Pipeline:** [e.g., GitHub Actions, GitLab CI]
+
+**Monitoring & Logging:** [e.g., Prometheus, CloudWatch]
+
+## 7. Security Considerations
+
+**Authentication:** [e.g., OAuth2, JWT, API Keys]
+
+**Authorization:** [e.g., RBAC, ACLs]
+
+**Data Encryption:** [e.g., TLS in transit, AES-256 at rest]
+
+**Key Security Tools/Practices:** [e.g., WAF, security audits]
+
+## 8. Development & Testing Environment
+
+**Local Setup Instructions:** [Link or brief steps]
+
+**Testing Frameworks:** [e.g., Jest, Pytest, JUnit]
+
+**Code Quality Tools:** [e.g., ESLint, SonarQube]
+
+## 9. Future Considerations / Roadmap
+
+Note any known architectural debts or planned major changes.
+
+- [e.g., Migrate to microservices]
+- [e.g., Implement caching layer]
+
+## 10. Project Identification
+
+**Project Name:** [Insert Project Name]
+
+**Repository URL:** [Insert Repository URL]
+
+**Primary Contact/Team:** [Insert Lead Developer/Team]
+
+**Date of Last Update:** [YYYY-MM-DD]
+
+## 11. Glossary / Acronyms
+
+Define project-specific terms.
+
+**[Term]:** [Definition]