class-ai-agent 1.2.0

package/.claude/rules/naming-conventions.md

@@ -0,0 +1,260 @@
+# Naming Conventions
+
+> Standard naming rules for cache keys, database identifiers, queues, events, environment variables, and more.
+
+## 🔑 Cache Key Naming
+
+### Format
+```
+{app}:{version}:{entity}:{identifier}:{variant}
+```
+
+### Rules
+- Use **colons** (`:`) as separators
+- Use **lowercase snake_case** for each segment
+- Always prefix with app/service name to avoid collision
+- Include version for easy cache invalidation
+
+### Examples
+```
+# User data
+myapp:v1:user:12345
+myapp:v1:user:12345:profile
+myapp:v1:user:12345:permissions
+
+# Lists / collections
+myapp:v1:users:active:list
+myapp:v1:products:category:electronics:page:1
+
+# Sessions
+myapp:v1:session:abc123xyz
+
+# Rate limiting
+myapp:v1:rate_limit:user:12345:api
+myapp:v1:rate_limit:ip:192.168.1.1
+
+# Feature flags
+myapp:v1:feature:new_checkout:enabled
+
+# Temporary locks (mutex)
+myapp:v1:lock:payment:order:99999
+
+# Aggregates / computed
+myapp:v1:dashboard:user:12345:stats:daily
+```
+
+### TTL Conventions
+| Data Type | Recommended TTL |
+|-----------|----------------|
+| User session | 7 days |
+| Auth tokens | 15 minutes |
+| User profile | 1 hour |
+| Product catalog | 6 hours |
+| Config/settings | 24 hours |
+| Rate limit windows | 15 minutes |
+| Temporary locks | 30 seconds |
+
+---
+
+## 🗄️ Database Naming
+
+### Tables
+```sql
+-- snake_case, plural nouns
+users
+order_items
+product_categories
+user_role_mappings    -- junction tables: entity1_entity2_mappings
+```
+
+### Columns
+```sql
+-- snake_case
+id                    -- primary key (always 'id')
+user_id               -- foreign key: {referenced_table_singular}_id
+created_at            -- timestamps: {event}_at
+updated_at
+deleted_at            -- soft delete
+is_active             -- booleans: is_, has_, can_
+has_verified_email
+email                 -- data fields: plain descriptive name
+full_name
+```
+
+### Indexes
+```sql
+-- Pattern: idx_{table}_{columns}
+idx_users_email
+idx_orders_user_id_created_at
+idx_products_category_id_is_active
+
+-- Unique indexes
+uniq_users_email
+uniq_products_sku
+
+-- Full-text search
+fts_products_name_description
+```
+
+### Foreign Keys
+```sql
+-- Pattern: fk_{child_table}_{parent_table}
+fk_orders_users
+fk_order_items_orders
+fk_order_items_products
+```
+
+### Stored Procedures / Functions
+```sql
+-- snake_case verbs
+get_user_by_email()
+calculate_order_total()
+archive_old_sessions()
+```
+
+---
+
+## 📨 Message Queue / Event Naming
+
+### Queue Names
+```
+# Pattern: {app}.{entity}.{action}
+# Use dots as separators for queues
+
+myapp.email.send
+myapp.payment.process
+myapp.order.fulfillment
+myapp.notification.push
+myapp.report.generate
+```
+
+### Event Names (Domain Events)
+```
+# Pattern: {entity}.{past_tense_verb}
+# Events describe things that HAPPENED
+
+user.registered
+user.email_verified
+order.placed
+order.payment_received
+order.fulfilled
+order.cancelled
+payment.failed
+product.stock_depleted
+```
+
+### Dead Letter Queues (DLQ)
+```
+myapp.email.send.dlq
+myapp.payment.process.dlq
+```
+
+---
+
+## 🌍 Environment Variables
+
+### Rules
+- **UPPER_SNAKE_CASE** for all env vars
+- Prefix with app/service name for non-standard vars
+- Be descriptive, avoid abbreviations
+
+### Standard Variables
+```bash
+# App
+NODE_ENV=production
+PORT=3000
+APP_NAME=myapp
+APP_URL=https://myapp.com
+LOG_LEVEL=info
+
+# Database
+DATABASE_URL=postgresql://...
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=myapp_production
+DB_USER=myapp_user
+DB_PASSWORD=...
+DB_POOL_MIN=2
+DB_POOL_MAX=10
+
+# Cache
+REDIS_URL=redis://localhost:6379
+REDIS_PASSWORD=...
+CACHE_TTL_DEFAULT=3600
+
+# Auth
+JWT_SECRET=...
+JWT_EXPIRES_IN=15m
+JWT_REFRESH_SECRET=...
+JWT_REFRESH_EXPIRES_IN=7d
+BCRYPT_ROUNDS=12
+
+# External Services
+SMTP_HOST=...
+SMTP_PORT=587
+SMTP_USER=...
+SMTP_PASS=...
+STRIPE_SECRET_KEY=...
+STRIPE_WEBHOOK_SECRET=...
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+AWS_REGION=ap-southeast-1
+S3_BUCKET_NAME=...
+
+# Monitoring
+SENTRY_DSN=...
+GRAFANA_API_KEY=...
+```
+
+---
+
+## 📁 File & Folder Naming
+
+```
+# Files: kebab-case
+user-service.js
+auth-middleware.js
+order-repository.js
+send-welcome-email.js  # specific action scripts
+
+# Folders: kebab-case, plural for collections
+controllers/
+services/
+repositories/
+utils/
+middleware/
+config/
+
+# Test files: match source file + .test
+user-service.test.js
+auth-middleware.test.js
+
+# Config files
+.env.development
+.env.production
+docker-compose.dev.yml
+docker-compose.prod.yml
+```
+
+---
+
+## 🌐 URL / Route Naming
+
+```
+# REST: plural nouns, kebab-case, versioned
+GET    /api/v1/users
+GET    /api/v1/users/:id
+POST   /api/v1/users
+PATCH  /api/v1/users/:id
+DELETE /api/v1/users/:id
+
+# Nested resources
+GET    /api/v1/users/:id/orders
+POST   /api/v1/users/:id/orders
+
+# Actions that don't fit CRUD (use verbs sparingly)
+POST   /api/v1/auth/login
+POST   /api/v1/auth/logout
+POST   /api/v1/auth/refresh
+POST   /api/v1/payments/:id/refund
+```

package/.claude/rules/project-structure.md

@@ -0,0 +1,65 @@
+# Project Structure
+
+## Standard Folder Layout
+
+```
+project-root/
+├── .claude/                    # AI Agent configuration
+│   ├── agents/                 # Sub-agent definitions
+│   ├── commands/               # Reusable command workflows
+│   ├── rules/                  # Mandatory rules for AI
+│   ├── skills/                 # Specialized AI skills
+│   ├── settings.json           # Project-level settings
+│   ├── settings.local.json     # Local settings (gitignored)
+│   ├── CLAUDE.md               # Main AI instructions
+│   └── CLAUDE.local.md         # Local AI overrides (gitignored)
+│
+├── src/                        # Application source code
+│   ├── config/                 # Configuration files
+│   ├── controllers/            # Route handlers (thin layer)
+│   ├── middleware/             # Express middleware
+│   ├── models/                 # Database models/schemas
+│   ├── repositories/           # Data access layer
+│   ├── routes/                 # Route definitions
+│   ├── services/               # Business logic layer
+│   ├── utils/                  # Utility functions
+│   └── index.js                # Application entry point
+│
+├── tests/                      # Test files
+│   ├── unit/                   # Unit tests
+│   ├── integration/            # Integration tests
+│   └── e2e/                    # End-to-end tests
+│
+├── docs/                       # Documentation
+│   ├── api/                    # API documentation
+│   └── architecture/           # Architecture diagrams
+│
+├── scripts/                    # Build and utility scripts
+├── .env.example                # Example environment variables
+├── .gitignore                  # Git ignore rules
+├── package.json
+├── README.md
+└── CLAUDE.md                   # Root-level AI instructions (optional)
+```
+
+## Layered Architecture
+```
+Request → Routes → Middleware → Controllers → Services → Repositories → Database
+```
+
+- **Routes**: URL mapping only, no logic
+- **Controllers**: Request/response handling, input validation
+- **Services**: Business logic, orchestration
+- **Repositories**: Data access, queries
+- **Models**: Data schemas and types
+
+## File Naming
+- Source files: `kebab-case.js` (`user-service.js`)
+- Test files: `[name].test.js` (`user-service.test.js`)
+- Config files: `kebab-case.js` or `kebab-case.json`
+
+## Environment Files
+- `.env` — Local development (gitignored)
+- `.env.example` — Template committed to git
+- `.env.test` — Test environment (gitignored)
+- `.env.production` — Set in CI/CD, never committed

package/.claude/rules/security.md

@@ -0,0 +1,90 @@
+# Security Rules
+
+## 🚨 CRITICAL — Never Violate These
+
+- **Never** hardcode secrets, API keys, passwords, or tokens in source code
+- **Never** commit `.env` files to version control
+- **Never** log sensitive data (passwords, tokens, PII)
+- **Never** use `eval()` or `Function()` with user input
+- **Always** validate and sanitize all user inputs
+
+## Environment Variables
+```js
+// ✅ Always use environment variables for secrets
+const dbPassword = process.env.DB_PASSWORD;
+const jwtSecret = process.env.JWT_SECRET;
+
+// ❌ Never hardcode secrets
+const dbPassword = 'mypassword123';
+```
+
+## Input Validation
+```js
+// ✅ Validate all incoming data with a schema
+import { z } from 'zod';
+
+const loginSchema = z.object({
+  email: z.string().email().max(255),
+  password: z.string().min(8).max(128)
+});
+
+// Sanitize HTML to prevent XSS
+import DOMPurify from 'dompurify';
+const cleanContent = DOMPurify.sanitize(userInput);
+```
+
+## Authentication
+- Use **JWT** with short expiry (15 min access token, 7 day refresh token)
+- Hash passwords with **bcrypt** (rounds: 12+)
+- Implement rate limiting on auth endpoints
+```js
+import bcrypt from 'bcrypt';
+const SALT_ROUNDS = 12;
+const hashed = await bcrypt.hash(password, SALT_ROUNDS);
+```
+
+## Authorization
+```js
+// ✅ Check permissions on every protected route
+router.delete('/posts/:id', authenticate, authorize('admin'), asyncHandler(deletePost));
+
+// ✅ Verify resource ownership
+if (post.authorId !== req.user.id && req.user.role !== 'admin') {
+  throw new AppError('Forbidden', 403);
+}
+```
+
+## HTTP Security Headers
+```js
+// Use Helmet.js
+import helmet from 'helmet';
+app.use(helmet());
+
+// Configure CORS strictly
+app.use(cors({
+  origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
+  credentials: true
+}));
+```
+
+## Rate Limiting
+```js
+import rateLimit from 'express-rate-limit';
+
+const apiLimiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 100 });
+const authLimiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 5 });
+
+app.use('/api/', apiLimiter);
+app.use('/api/auth/', authLimiter);
+```
+
+## SQL Injection Prevention
+- Always use ORM parameterized queries
+- Never concatenate user input into SQL strings
+
+## Dependency Security
+```bash
+# Regularly audit dependencies
+npm audit
+npm audit fix
+```

package/.claude/rules/system-design.md

@@ -0,0 +1,162 @@
+# System Design Rules
+
+> Principles from "System Design Interview" (Alex Xu), "Designing Data-Intensive Applications" (Martin Kleppmann), and industry best practices.
+
+## 🏗️ Core Principles
+
+### CAP Theorem
+- A distributed system can only guarantee 2 of 3: **Consistency**, **Availability**, **Partition Tolerance**
+- **CP systems** (sacrifice availability): MySQL, ZooKeeper, HBase → use when data correctness is critical
+- **AP systems** (sacrifice consistency): Cassandra, DynamoDB, CouchDB → use for high availability
+
+### Design for Failure
+- Every external call CAN fail — design for it
+- Use **circuit breakers** to prevent cascade failures
+- Use **bulkhead pattern** to isolate failures
+- Implement **graceful degradation** (serve cached/partial data when dependencies fail)
+
+---
+
+## 📐 Scalability Patterns
+
+### Horizontal vs Vertical Scaling
+```
+Vertical  → More CPU/RAM on one machine (limited ceiling)
+Horizontal → More machines (preferred for production)
+```
+
+### Load Balancing
+- **Round Robin** — equal distribution
+- **Least Connections** — route to least busy server
+- **Consistent Hashing** — for cache/session affinity (minimize remapping on scale)
+
+### Caching Strategies
+| Strategy | Use Case |
+|----------|----------|
+| **Cache-Aside** (Lazy Loading) | Read-heavy, content changes frequently |
+| **Write-Through** | Write-heavy, data must be consistent |
+| **Write-Behind** (Write-Back) | High write throughput, some lag acceptable |
+| **Read-Through** | Cache is always up to date |
+
+### Database Scaling
+- **Read Replicas** — scale read-heavy workloads
+- **Sharding** — partition data horizontally by shard key
+- **Vertical Partitioning** — split tables by column groups
+- **CQRS** — separate read model and write model
+
+---
+
+## 🔄 Async Patterns
+
+### Message Queues
+Use queues (Redis, RabbitMQ, Kafka) when:
+- Processing can be deferred
+- Tasks are slow/expensive (email, PDF gen, notifications)
+- You need to decouple producers from consumers
+
+```
+Producer → [Queue] → Consumer(s)
+```
+
+### Event-Driven Architecture
+```js
+// Publish domain events instead of direct service calls
+eventBus.publish('order.created', { orderId, userId, total });
+// Other services subscribe independently
+```
+
+### Saga Pattern (Distributed Transactions)
+- **Choreography** — each service reacts to events (no central coordinator)
+- **Orchestration** — a saga orchestrator tells each service what to do
+
+---
+
+## 🗄️ Database Design
+
+### Normalization vs Denormalization
+- **Normalize** (OLTP) — avoid data duplication, use JOINs
+- **Denormalize** (OLAP/Read-heavy) — duplicate data to eliminate JOINs
+
+### Indexing Rules
+```sql
+-- ✅ Index columns used in WHERE, JOIN, ORDER BY
+CREATE INDEX idx_users_email ON users(email);
+
+-- ❌ Don't index every column — indexes slow down writes
+```
+
+### N+1 Query Prevention
+```js
+// ❌ N+1: one query per user
+const users = await db.users.findAll();
+for (const user of users) {
+  user.orders = await db.orders.findAll({ where: { userId: user.id } });
+}
+
+// ✅ Single query with JOIN or include
+const users = await db.users.findAll({ include: [{ model: db.orders }] });
+```
+
+---
+
+## 🌐 API Design Patterns
+
+### Rate Limiting Algorithms
+| Algorithm | Best For |
+|-----------|----------|
+| **Token Bucket** | Burst traffic allowed (API gateways) |
+| **Leaky Bucket** | Smooth/constant output rate |
+| **Fixed Window** | Simple, but spiky at window boundaries |
+| **Sliding Window** | Most accurate, higher memory cost |
+
+### Idempotency
+- GET, PUT, DELETE must be idempotent
+- POST operations: use **idempotency keys** for payment/critical actions
+```
+POST /api/payments
+Idempotency-Key: <uuid>
+```
+
+### Pagination Patterns
+```
+Offset: ?page=2&limit=20          → Simple but slow on large offsets
+Cursor: ?cursor=<encoded>&limit=20 → ✅ Preferred for large datasets
+```
+
+---
+
+## 🔒 Reliability
+
+### Circuit Breaker States
+```
+CLOSED → OPEN (after N failures) → HALF-OPEN (probe) → CLOSED
+```
+
+### Retry Strategy
+```js
+// ✅ Exponential backoff with jitter
+const delay = Math.min(baseDelay * 2 ** attempt + Math.random() * 1000, maxDelay);
+```
+
+### Health Checks
+```
+GET /health        → Basic liveness (is the service running?)
+GET /health/ready  → Readiness (is the service ready to serve traffic?)
+GET /health/live   → Liveness (should Kubernetes restart this pod?)
+```
+
+---
+
+## 📊 Back-of-Envelope Estimation
+
+| Resource | Approximate Speed |
+|----------|------------------|
+| L1 cache reference | 0.5 ns |
+| L2 cache reference | 7 ns |
+| RAM access | 100 ns |
+| SSD random read | 150 μs |
+| Network round trip (same DC) | 0.5 ms |
+| HDD seek | 10 ms |
+| Network round trip (cross continent) | 150 ms |
+
+> Rule of thumb: Prefer Redis (in-memory) over DB for anything needing < 1ms latency