@aicgen/aicgen 1.0.0-beta.1

package/data/database/indexing.md

@@ -0,0 +1,136 @@
+# Database Indexing
+
+## When to Add Indexes
+
+```sql
+-- ✅ Columns in WHERE clauses
+CREATE INDEX idx_users_email ON users(email);
+
+-- ✅ Foreign key columns
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+
+-- ✅ Columns used in ORDER BY
+CREATE INDEX idx_products_created_at ON products(created_at DESC);
+
+-- ✅ Columns used in JOIN conditions
+CREATE INDEX idx_order_items_product_id ON order_items(product_id);
+```
+
+## Composite Indexes
+
+```sql
+-- Order matters! Put most selective column first
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+
+-- This index helps with:
+SELECT * FROM orders WHERE user_id = 123;
+SELECT * FROM orders WHERE user_id = 123 AND status = 'pending';
+
+-- But NOT with:
+SELECT * FROM orders WHERE status = 'pending'; -- Can't use index
+```
+
+## Partial Indexes
+
+```sql
+-- Index only rows matching condition
+CREATE INDEX idx_active_users ON users(email) WHERE is_active = true;
+
+-- Smaller index, faster queries on active users
+SELECT * FROM users WHERE email = 'x@y.com' AND is_active = true;
+```
+
+## Unique Indexes
+
+```sql
+-- Enforces uniqueness and improves lookup
+CREATE UNIQUE INDEX idx_users_email ON users(email);
+
+-- Multi-column unique
+CREATE UNIQUE INDEX idx_unique_order_item ON order_items(order_id, product_id);
+```
+
+## Index Types
+
+```sql
+-- B-tree (default): =, <, >, <=, >=, BETWEEN
+CREATE INDEX idx_products_price ON products(price);
+
+-- Hash: Only equality (=)
+CREATE INDEX idx_users_id_hash ON users USING hash (id);
+
+-- GIN: Arrays, JSONB, full-text search
+CREATE INDEX idx_products_tags ON products USING gin (tags);
+
+-- GiST: Geometric data, range queries
+CREATE INDEX idx_locations ON places USING gist (location);
+```
+
+## Analyze Query Performance
+
+```sql
+-- EXPLAIN ANALYZE shows actual execution
+EXPLAIN ANALYZE
+SELECT * FROM users WHERE email = 'test@example.com';
+
+-- Look for:
+-- ✅ Index Scan / Index Only Scan (good)
+-- ❌ Seq Scan on large tables (bad)
+-- ❌ High "actual time" values (slow)
+```
+
+## Index Maintenance
+
+```sql
+-- Monitor index usage (PostgreSQL)
+SELECT
+  schemaname, tablename, indexname, idx_scan, idx_tup_read
+FROM pg_stat_user_indexes
+ORDER BY idx_scan ASC;
+
+-- Remove unused indexes (0 scans)
+DROP INDEX IF EXISTS unused_index_name;
+
+-- Rebuild bloated indexes
+REINDEX INDEX index_name;
+```
+
+## Anti-Patterns
+
+```sql
+-- ❌ Indexing every column
+-- Slows down INSERT/UPDATE, wastes space
+
+-- ❌ Indexes on low-cardinality columns
+-- Boolean columns rarely benefit from indexes
+
+-- ❌ Functions on indexed columns
+-- SELECT * FROM users WHERE LOWER(email) = 'x'; -- Can't use index!
+
+-- ✅ Use expression index instead
+CREATE INDEX idx_users_email_lower ON users(LOWER(email));
+```
+
+## Connection Pooling
+
+```typescript
+// ❌ New connection per query
+const getUser = async (id: string) => {
+  const conn = await createConnection(); // Expensive!
+  const user = await conn.query('SELECT * FROM users WHERE id = ?', [id]);
+  await conn.close();
+  return user;
+};
+
+// ✅ Use connection pool
+const pool = new Pool({ max: 20, idleTimeoutMillis: 30000 });
+
+const getUser = async (id: string) => {
+  const client = await pool.connect();
+  try {
+    return await client.query('SELECT * FROM users WHERE id = $1', [id]);
+  } finally {
+    client.release(); // Return to pool
+  }
+};
+```

package/data/database/nosql.md

@@ -0,0 +1,223 @@
+# NoSQL Database Patterns
+
+## Document Databases (MongoDB, CouchDB)
+
+### Schema Design
+
+```typescript
+// Embed vs Reference
+
+// ✅ Embed: Data accessed together, 1:few relationship
+interface Order {
+  _id: ObjectId;
+  customerId: ObjectId;
+  items: Array<{           // Embedded
+    productId: ObjectId;
+    name: string;
+    quantity: number;
+    price: number;
+  }>;
+  shippingAddress: {       // Embedded
+    street: string;
+    city: string;
+    country: string;
+  };
+}
+
+// ✅ Reference: Data accessed separately, 1:many relationship
+interface Post {
+  _id: ObjectId;
+  title: string;
+  content: string;
+  authorId: ObjectId;      // Reference to User
+}
+
+interface Comment {
+  _id: ObjectId;
+  postId: ObjectId;        // Reference to Post
+  authorId: ObjectId;      // Reference to User
+  content: string;
+}
+```
+
+### Indexing
+
+```typescript
+// Single field index
+db.users.createIndex({ email: 1 });
+
+// Compound index (order matters!)
+db.orders.createIndex({ customerId: 1, createdAt: -1 });
+
+// Partial index
+db.users.createIndex(
+  { email: 1 },
+  { partialFilterExpression: { status: "active" } }
+);
+
+// Text search index
+db.products.createIndex({ name: "text", description: "text" });
+```
+
+### Query Patterns
+
+```typescript
+// Avoid N+1 queries - use $lookup for joins
+const ordersWithCustomers = await db.orders.aggregate([
+  {
+    $lookup: {
+      from: "customers",
+      localField: "customerId",
+      foreignField: "_id",
+      as: "customer"
+    }
+  },
+  { $unwind: "$customer" }
+]).toArray();
+
+// Use projections to limit returned fields
+const userNames = await db.users.find(
+  { status: "active" },
+  { projection: { name: 1, email: 1 } }
+).toArray();
+```
+
+## Key-Value Stores (Redis, DynamoDB)
+
+### Redis Patterns
+
+```typescript
+// Caching with TTL
+await redis.setex(`user:${userId}`, 3600, JSON.stringify(user));
+
+// Rate limiting
+async function isRateLimited(userId: string): Promise<boolean> {
+  const key = `rate:${userId}`;
+  const count = await redis.incr(key);
+  if (count === 1) {
+    await redis.expire(key, 60); // 60 second window
+  }
+  return count > 100; // 100 requests per minute
+}
+
+// Distributed locks
+async function acquireLock(key: string, ttl: number): Promise<boolean> {
+  const result = await redis.set(`lock:${key}`, "1", "NX", "EX", ttl);
+  return result === "OK";
+}
+
+// Pub/Sub
+await redis.publish("events", JSON.stringify({ type: "user.created", data: user }));
+```
+
+### DynamoDB Patterns
+
+```typescript
+// Single table design - access patterns first
+interface Item {
+  PK: string;           // Partition key: USER#<userId>
+  SK: string;           // Sort key: ORDER#<orderId>
+  GSI1PK?: string;      // Global Secondary Index
+  GSI1SK?: string;
+  // ... attributes
+}
+
+// Write with condition
+await dynamodb.put({
+  TableName: "orders",
+  Item: order,
+  ConditionExpression: "attribute_not_exists(PK)"  // Prevent duplicates
+});
+
+// Query with begins_with
+const userOrders = await dynamodb.query({
+  TableName: "orders",
+  KeyConditionExpression: "PK = :pk AND begins_with(SK, :sk)",
+  ExpressionAttributeValues: {
+    ":pk": `USER#${userId}`,
+    ":sk": "ORDER#"
+  }
+});
+```
+
+## Wide Column Stores (Cassandra)
+
+### Data Modeling
+
+```sql
+-- Design for queries, not relationships
+-- One table per query pattern
+
+CREATE TABLE orders_by_customer (
+  customer_id UUID,
+  order_date TIMESTAMP,
+  order_id UUID,
+  total DECIMAL,
+  PRIMARY KEY ((customer_id), order_date, order_id)
+) WITH CLUSTERING ORDER BY (order_date DESC);
+
+CREATE TABLE orders_by_date (
+  order_date DATE,
+  order_id UUID,
+  customer_id UUID,
+  total DECIMAL,
+  PRIMARY KEY ((order_date), order_id)
+);
+```
+
+## Best Practices
+
+### Denormalization
+- Duplicate data for read performance
+- Design for query patterns, not normalization
+- Accept eventual consistency
+
+### Data Modeling
+- Start with access patterns
+- One table per query (or single-table design for DynamoDB)
+- Embed related data that's always accessed together
+- Reference data that's accessed independently
+
+### Performance
+- Use indexes strategically
+- Batch operations when possible
+- Use TTL for temporary data
+- Consider sharding/partitioning for scale
+
+### Consistency
+- Understand your consistency model (eventual vs strong)
+- Use transactions when available and necessary
+- Design for idempotency
+
+```typescript
+// Idempotent writes with version/timestamp
+async function updateUser(user: User): Promise<void> {
+  await db.users.updateOne(
+    { _id: user._id, version: user.version },
+    { $set: { ...user, version: user.version + 1 } }
+  );
+}
+```
+
+### Error Handling
+
+```typescript
+// Retry with exponential backoff
+async function withRetry<T>(
+  operation: () => Promise<T>,
+  maxRetries = 3
+): Promise<T> {
+  let lastError: Error;
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error as Error;
+      await sleep(Math.pow(2, i) * 100);
+    }
+  }
+
+  throw lastError!;
+}
+```

package/data/database/schema.md

@@ -0,0 +1,137 @@
+# Database Schema Design
+
+## Naming Conventions
+
+```sql
+-- Tables: plural, snake_case
+CREATE TABLE users (...);
+CREATE TABLE order_items (...);
+
+-- Columns: singular, snake_case
+user_id, created_at, is_active
+
+-- Primary keys: id
+id SERIAL PRIMARY KEY
+
+-- Foreign keys: singular_table_id
+user_id REFERENCES users(id)
+```
+
+## Primary Keys
+
+```sql
+-- ✅ Auto-incrementing integer (simple cases)
+id SERIAL PRIMARY KEY
+
+-- ✅ UUID for distributed systems
+id UUID PRIMARY KEY DEFAULT gen_random_uuid()
+
+-- ❌ Avoid composite primary keys when possible
+-- They complicate joins and foreign keys
+```
+
+## Essential Columns
+
+```sql
+-- ✅ Standard audit columns
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  price DECIMAL(10,2) NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  deleted_at TIMESTAMP NULL  -- Soft delete
+);
+
+-- ✅ Version column for optimistic locking
+version INTEGER DEFAULT 1
+```
+
+## Relationships
+
+```sql
+-- One-to-Many: Foreign key on "many" side
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
+  total DECIMAL(10,2)
+);
+
+-- Many-to-Many: Junction table
+CREATE TABLE order_items (
+  order_id INTEGER REFERENCES orders(id) ON DELETE CASCADE,
+  product_id INTEGER REFERENCES products(id),
+  quantity INTEGER NOT NULL,
+  PRIMARY KEY (order_id, product_id)
+);
+```
+
+## Constraints
+
+```sql
+-- ✅ NOT NULL for required fields
+email VARCHAR(255) NOT NULL
+
+-- ✅ UNIQUE constraints
+email VARCHAR(255) UNIQUE NOT NULL
+
+-- ✅ CHECK constraints for validation
+age INTEGER CHECK (age >= 0 AND age <= 150)
+status VARCHAR(20) CHECK (status IN ('pending', 'active', 'cancelled'))
+
+-- ✅ DEFAULT values
+is_active BOOLEAN DEFAULT true
+role VARCHAR(20) DEFAULT 'user'
+```
+
+## Data Types
+
+```sql
+-- Strings
+VARCHAR(255) -- Variable length, max 255
+TEXT         -- Unlimited length
+
+-- Numbers
+INTEGER      -- Whole numbers
+BIGINT       -- Large whole numbers
+DECIMAL(10,2) -- Exact decimals (money)
+REAL/DOUBLE  -- Approximate decimals (scientific)
+
+-- Dates/Times
+TIMESTAMP    -- Date and time
+DATE         -- Date only
+INTERVAL     -- Duration
+
+-- Other
+BOOLEAN      -- true/false
+UUID         -- Unique identifier
+JSONB        -- JSON with indexing (PostgreSQL)
+```
+
+## Normalization Guidelines
+
+```sql
+-- ✅ 1NF: Atomic values, no repeating groups
+-- ❌ Bad: tags VARCHAR = 'tag1,tag2,tag3'
+-- ✅ Good: Separate tags table
+
+-- ✅ 2NF: No partial dependencies
+-- All non-key columns depend on entire primary key
+
+-- ✅ 3NF: No transitive dependencies
+-- Non-key columns don't depend on other non-key columns
+```
+
+## Denormalization (When Appropriate)
+
+```sql
+-- Cache computed values for read performance
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER REFERENCES users(id),
+  items_count INTEGER DEFAULT 0,  -- Denormalized
+  total DECIMAL(10,2) DEFAULT 0   -- Denormalized
+);
+
+-- Update via triggers or application logic
+```

package/data/devops/ci-cd.md

@@ -0,0 +1,66 @@
+# CI/CD Practices
+
+## Continuous Integration
+
+Run on every commit:
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build
+```
+
+## Continuous Deployment
+
+Deploy automatically after CI passes:
+
+```yaml
+deploy:
+  needs: build
+  if: github.ref == 'refs/heads/main'
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - run: npm ci
+    - run: npm run build
+    - run: npm run deploy
+      env:
+        DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+```
+
+## Deployment Strategies
+
+### Blue-Green Deployment
+Run two identical environments, switch traffic instantly.
+
+### Canary Releases
+Route small percentage of traffic to new version first.
+
+### Rolling Updates
+Gradually replace instances with new version.
+
+## Best Practices
+
+- Run fast tests first, slow tests later
+- Cache dependencies between runs
+- Use matrix builds for multiple versions/platforms
+- Keep secrets in secure storage
+- Automate database migrations
+- Include rollback procedures
+- Monitor deployments with health checks
+- Use feature flags for safer releases

package/data/devops/index.md

@@ -0,0 +1,8 @@
+# DevOps Guidelines
+
+This directory contains DevOps and CI/CD patterns.
+
+## Available Chunks
+
+- **ci-cd.md** - Continuous Integration and Deployment pipelines
+- **practices.md** - Infrastructure as Code, monitoring, observability

package/data/devops/observability.md

@@ -0,0 +1,73 @@
+# Observability
+
+## Overview
+
+Observability is the ability to understand the internal state of a system by examining its outputs. In modern distributed systems, it goes beyond simple monitoring to include logging, metrics, and tracing.
+
+## Three Pillars
+
+### 1. Structured Logging
+
+Logs should be machine-readable (JSON) and contain context.
+
+```json
+// ✅ Good: Structured JSON logging
+{
+  "level": "info",
+  "message": "Order processed",
+  "orderId": "ord_123",
+  "userId": "user_456",
+  "amount": 99.99,
+  "durationMs": 145,
+  "status": "success"
+}
+```
+```text
+// ❌ Bad: Unstructured text
+"Order processed: ord_123 for user_456"
+```
+
+### 2. Metrics
+
+Aggregatable data points for identifying trends and health.
+
+- **Counters**: Total requests, error counts (`http_requests_total`)
+- **Gauges**: Queue depth, memory usage (`memory_usage_bytes`)
+- **Histograms**: Request latency distribution (`http_request_duration_seconds`)
+
+### 3. Distributed Tracing
+
+Tracking requests as they propagate through services.
+
+- **Trace ID**: Unique ID for the entire request chain
+- **Span ID**: Unique ID for a specific operation
+- **Context Propagation**: Passing IDs between services (e.g., W3C Trace Context)
+
+## Implementation Strategy
+
+### OpenTelemetry (OTel)
+
+Use OpenTelemetry as the vendor-neutral standard for collecting telemetry data.
+
+```text
+# Initialize OpenTelemetry SDK
+SDK.Configure({
+  TraceExporter: Console/OTLP,
+  Instrumentations: [Http, Database, Grpc]
+})
+SDK.Start()
+```
+
+### Health Checks
+
+Expose standard health endpoints:
+
+- `/health/live`: Is the process running? (Liveness)
+- `/health/ready`: Can it accept traffic? (Readiness)
+- `/health/startup`: Has it finished initializing? (Startup)
+
+## Alerting Best Practices
+
+- **Alert on Symptoms, not Causes**: "High Error Rate" (Symptom) vs "CPU High" (Cause).
+- **Golden Signals**: Latency, Traffic, Errors, Saturation.
+- **Actionable**: Every alert should require a specific human action.

package/data/devops/practices.md

@@ -0,0 +1,77 @@
+# DevOps Practices
+
+## Infrastructure as Code
+
+```text
+# Define infrastructure as code (e.g., Terraform, Pulumi)
+
+Resource S3Bucket "app-bucket":
+  Access: Private
+  Versioning: Enabled
+
+Resource LambdaFunction "api":
+  Runtime: Node.js / Python / Go
+  Handler: index.handler
+  Code: ./dist
+```
+
+## Containerization
+
+```dockerfile
+# Build Stage
+FROM base-image AS builder
+WORKDIR /app
+COPY dependency-files ./
+RUN install-dependencies
+COPY source-code .
+RUN build-application
+
+# Runtime Stage
+FROM runtime-image
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+EXPOSE 8080
+CMD ["run", "application"]
+```
+
+## Observability
+
+### Logging
+```json
+{
+  "level": "info",
+  "message": "Order created",
+  "orderId": "ord_123",
+  "customerId": "cust_456",
+  "total": 99.99,
+  "timestamp": "2023-10-27T10:00:00Z"
+}
+```
+
+### Metrics
+```text
+Metrics.Increment("orders.created")
+Metrics.Histogram("order.value", total)
+Metrics.Timing("order.processing_time", duration)
+```
+
+### Health Checks
+```text
+GET /health
+Response 200 OK:
+{
+  "status": "healthy",
+  "version": "1.2.3",
+  "uptime": 3600
+}
+```
+
+## Best Practices
+
+- Version control all infrastructure
+- Use immutable infrastructure
+- Implement proper secret management
+- Set up alerting for critical metrics
+- Use structured logging (JSON)
+- Include correlation IDs for tracing
+- Document runbooks for incidents