@aicgen/aicgen 1.0.0-beta.1

package/data/api/rest.md

@@ -0,0 +1,137 @@
+# REST API Design
+
+## Resource-Oriented URLs
+
+```
+✅ Good (nouns, plural)
+GET    /api/v1/books           # List books
+GET    /api/v1/books/123       # Get book
+POST   /api/v1/books           # Create book
+PUT    /api/v1/books/123       # Replace book
+PATCH  /api/v1/books/123       # Update book
+DELETE /api/v1/books/123       # Delete book
+
+❌ Bad (verbs, actions)
+POST /api/v1/createBook
+GET  /api/v1/getBookById/123
+POST /api/v1/updateBook/123
+```
+
+## HTTP Methods
+
+```typescript
+// GET - Read (safe, idempotent)
+app.get('/api/v1/users/:id', async (req, res) => {
+  const user = await userService.findById(req.params.id);
+  res.json({ data: user });
+});
+
+// POST - Create (not idempotent)
+app.post('/api/v1/users', async (req, res) => {
+  const user = await userService.create(req.body);
+  res.status(201)
+    .location(`/api/v1/users/${user.id}`)
+    .json({ data: user });
+});
+
+// PUT - Replace entire resource (idempotent)
+app.put('/api/v1/users/:id', async (req, res) => {
+  const user = await userService.replace(req.params.id, req.body);
+  res.json({ data: user });
+});
+
+// PATCH - Partial update (idempotent)
+app.patch('/api/v1/users/:id', async (req, res) => {
+  const user = await userService.update(req.params.id, req.body);
+  res.json({ data: user });
+});
+
+// DELETE - Remove (idempotent)
+app.delete('/api/v1/users/:id', async (req, res) => {
+  await userService.delete(req.params.id);
+  res.status(204).end();
+});
+```
+
+## Status Codes
+
+```typescript
+// Success
+200 OK           // GET, PUT, PATCH succeeded
+201 Created      // POST succeeded
+204 No Content   // DELETE succeeded
+
+// Client errors
+400 Bad Request  // Validation failed
+401 Unauthorized // Not authenticated
+403 Forbidden    // Authenticated but not allowed
+404 Not Found    // Resource doesn't exist
+409 Conflict     // Duplicate, version conflict
+422 Unprocessable // Business rule violation
+
+// Server errors
+500 Internal Server Error
+```
+
+## Response Format
+
+```typescript
+// Single resource
+{
+  "data": {
+    "id": 123,
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+
+// Collection with pagination
+{
+  "data": [
+    { "id": 1, "name": "Item 1" },
+    { "id": 2, "name": "Item 2" }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8
+  }
+}
+
+// Error response
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "The request contains invalid data",
+    "details": [
+      { "field": "email", "message": "Invalid email format" }
+    ]
+  }
+}
+```
+
+## Hierarchical Resources
+
+```
+✅ Limit nesting to 2-3 levels
+GET /api/v1/authors/456/books       # Books by author
+GET /api/v1/orders/789/items        # Items in order
+
+❌ Too deep
+GET /api/v1/publishers/1/authors/2/books/3/reviews/4
+
+✅ Use query parameters instead
+GET /api/v1/reviews?bookId=3
+```
+
+## API Versioning
+
+```
+✅ Always version from the start
+/api/v1/books
+/api/v2/books
+
+❌ No version
+/api/books
+```

package/data/api/versioning.md

@@ -0,0 +1,60 @@
+# API Versioning
+
+## Versioning Strategies
+
+### URL Path Versioning
+```
+GET /api/v1/users
+GET /api/v2/users
+```
+
+### Header Versioning
+```
+GET /api/users
+Accept: application/vnd.api+json; version=2
+```
+
+### Query Parameter
+```
+GET /api/users?version=2
+```
+
+## Implementation
+
+```typescript
+// URL path versioning
+app.use('/api/v1', v1Router);
+app.use('/api/v2', v2Router);
+
+// Header versioning middleware
+function versionMiddleware(req, res, next) {
+  const version = req.headers['api-version'] || '1';
+  req.apiVersion = parseInt(version);
+  next();
+}
+
+app.get('/users', versionMiddleware, (req, res) => {
+  if (req.apiVersion >= 2) {
+    return handleV2(req, res);
+  }
+  return handleV1(req, res);
+});
+```
+
+## Deprecation Strategy
+
+```typescript
+// Add deprecation headers
+res.setHeader('Deprecation', 'true');
+res.setHeader('Sunset', 'Sat, 01 Jan 2025 00:00:00 GMT');
+res.setHeader('Link', '</api/v2/users>; rel="successor-version"');
+```
+
+## Best Practices
+
+- Version from the start
+- Support at least N-1 versions
+- Document deprecation timeline
+- Provide migration guides
+- Use semantic versioning for breaking changes
+- Consider backwards-compatible changes first

package/data/architecture/clean-architecture/index.md

@@ -0,0 +1,7 @@
+# Clean Architecture
+
+This directory contains Clean Architecture patterns.
+
+## Available Chunks
+
+- **layers.md** - Dependency rule, layers, use cases, adapters

package/data/architecture/clean-architecture/layers.md

@@ -0,0 +1,111 @@
+# Clean Architecture
+
+## Core Principle
+
+Dependencies point inward. Inner layers know nothing about outer layers.
+
+```
+┌─────────────────────────────────────────────┐
+│            Frameworks & Drivers             │
+│  ┌─────────────────────────────────────┐    │
+│  │       Interface Adapters            │    │
+│  │  ┌─────────────────────────────┐    │    │
+│  │  │     Application Business    │    │    │
+│  │  │  ┌─────────────────────┐    │    │    │
+│  │  │  │  Enterprise Business│    │    │    │
+│  │  │  │     (Entities)      │    │    │    │
+│  │  │  └─────────────────────┘    │    │    │
+│  │  │       (Use Cases)           │    │    │
+│  │  └─────────────────────────────┘    │    │
+│  │    (Controllers, Gateways)          │    │
+│  └─────────────────────────────────────┘    │
+│      (Web, DB, External APIs)               │
+└─────────────────────────────────────────────┘
+```
+
+## The Dependency Rule
+
+Source code dependencies only point inward.
+
+## Layer Structure
+
+### Entities (Enterprise Business Rules)
+
+```typescript
+class Order {
+  constructor(
+    public readonly id: string,
+    private items: OrderItem[],
+    private status: OrderStatus
+  ) {}
+
+  calculateTotal(): Money {
+    return this.items.reduce(
+      (sum, item) => sum.add(item.subtotal()),
+      Money.zero()
+    );
+  }
+
+  canBeCancelled(): boolean {
+    return this.status === OrderStatus.Pending;
+  }
+}
+```
+
+### Use Cases (Application Business Rules)
+
+```typescript
+class CreateOrderUseCase {
+  constructor(
+    private orderRepository: OrderRepository,
+    private productRepository: ProductRepository
+  ) {}
+
+  async execute(request: CreateOrderRequest): Promise<CreateOrderResponse> {
+    const products = await this.productRepository.findByIds(request.productIds);
+    const order = new Order(generateId(), this.createItems(products));
+    await this.orderRepository.save(order);
+    return { orderId: order.id };
+  }
+}
+```
+
+### Interface Adapters
+
+```typescript
+// Controller (adapts HTTP to use case)
+class OrderController {
+  constructor(private createOrder: CreateOrderUseCase) {}
+
+  async create(req: Request, res: Response) {
+    const result = await this.createOrder.execute(req.body);
+    res.json(result);
+  }
+}
+
+// Repository Implementation (adapts use case to database)
+class PostgreSQLOrderRepository implements OrderRepository {
+  async save(order: Order): Promise<void> {
+    await this.db.query('INSERT INTO orders...');
+  }
+}
+```
+
+### Frameworks & Drivers
+
+```typescript
+// Express setup
+const app = express();
+app.post('/orders', (req, res) => orderController.create(req, res));
+
+// Database connection
+const db = new Pool({ connectionString: process.env.DATABASE_URL });
+```
+
+## Best Practices
+
+- Keep entities pure with no framework dependencies
+- Use cases orchestrate domain logic
+- Interfaces defined in inner layers, implemented in outer layers
+- Cross boundaries with simple data structures
+- Test use cases independently of frameworks

package/data/architecture/ddd/index.md

@@ -0,0 +1,8 @@
+# Domain-Driven Design
+
+This directory contains DDD patterns.
+
+## Available Chunks
+
+- **tactical.md** - Entities, Value Objects, Aggregates, Domain Events
+- **strategic.md** - Bounded Contexts, Ubiquitous Language, Context Mapping

package/data/architecture/ddd/strategic.md

@@ -0,0 +1,89 @@
+# DDD Strategic Patterns
+
+## Ubiquitous Language
+
+Use the same terminology in code, documentation, and conversations.
+
+```typescript
+// Domain experts say "place an order"
+class Order {
+  place(): void { /* not submit(), not create() */ }
+}
+
+// Domain experts say "items are added to cart"
+class ShoppingCart {
+  addItem(product: Product): void { /* not insert(), not push() */ }
+}
+```
+
+## Bounded Contexts
+
+Explicit boundaries where a model applies consistently.
+
+```
+┌─────────────────┐    ┌─────────────────┐
+│    Sales        │    │   Warehouse     │
+│    Context      │    │    Context      │
+├─────────────────┤    ├─────────────────┤
+│ Order           │    │ Order           │
+│ - customerId    │    │ - shipmentId    │
+│ - items[]       │    │ - pickingList   │
+│ - total         │    │ - status        │
+└─────────────────┘    └─────────────────┘
+   Same term, different model
+```
+
+## Context Mapping Patterns
+
+### Shared Kernel
+Two contexts share a subset of the model.
+
+### Customer/Supplier
+Upstream context provides what downstream needs.
+
+### Conformist
+Downstream adopts upstream's model entirely.
+
+### Anti-Corruption Layer
+Translate between contexts to protect domain model.
+
+```typescript
+class InventoryAntiCorruptionLayer {
+  constructor(private legacyInventorySystem: LegacyInventory) {}
+
+  checkAvailability(productId: ProductId): Promise<boolean> {
+    // Translate from legacy format to domain model
+    const legacyResult = await this.legacyInventorySystem.getStock(
+      productId.toString()
+    );
+    return legacyResult.qty > 0;
+  }
+}
+```
+
+## Module Organization
+
+```
+src/
+├── sales/                    # Sales bounded context
+│   ├── domain/
+│   │   ├── order.ts
+│   │   └── customer.ts
+│   ├── application/
+│   │   └── place-order.ts
+│   └── infrastructure/
+│       └── order-repository.ts
+├── warehouse/                # Warehouse bounded context
+│   ├── domain/
+│   │   └── shipment.ts
+│   └── ...
+└── shared/                   # Shared kernel
+    └── money.ts
+```
+
+## Best Practices
+
+- Define context boundaries based on team structure and business capabilities
+- Use ubiquitous language within each context
+- Communicate between contexts via events or explicit APIs
+- Protect domain model with anti-corruption layers when integrating legacy systems

package/data/architecture/ddd/tactical.md

@@ -0,0 +1,132 @@
+# DDD Tactical Patterns
+
+## Entities
+
+Objects with identity that persists through state changes.
+
+```typescript
+class User {
+  constructor(
+    public readonly id: UserId,
+    private email: Email,
+    private name: string
+  ) {}
+
+  changeEmail(newEmail: Email): void {
+    this.email = newEmail;
+  }
+
+  equals(other: User): boolean {
+    return this.id.equals(other.id);
+  }
+}
+```
+
+## Value Objects
+
+Immutable objects defined by their attributes.
+
+```typescript
+class Email {
+  private readonly value: string;
+
+  constructor(email: string) {
+    if (!this.isValid(email)) {
+      throw new InvalidEmailError(email);
+    }
+    this.value = email.toLowerCase();
+  }
+
+  equals(other: Email): boolean {
+    return this.value === other.value;
+  }
+}
+
+class Money {
+  constructor(
+    public readonly amount: number,
+    public readonly currency: Currency
+  ) {
+    Object.freeze(this);
+  }
+
+  add(other: Money): Money {
+    this.assertSameCurrency(other);
+    return new Money(this.amount + other.amount, this.currency);
+  }
+}
+```
+
+## Aggregates
+
+Cluster of entities and value objects with a root entity.
+
+```typescript
+class Order {
+  private items: OrderItem[] = [];
+
+  constructor(
+    public readonly id: OrderId,
+    private customerId: CustomerId
+  ) {}
+
+  addItem(product: Product, quantity: number): void {
+    const item = new OrderItem(product.id, product.price, quantity);
+    this.items.push(item);
+  }
+
+  // All modifications go through aggregate root
+  removeItem(productId: ProductId): void {
+    this.items = this.items.filter(item => !item.productId.equals(productId));
+  }
+}
+```
+
+## Domain Events
+
+Capture something that happened in the domain.
+
+```typescript
+class OrderPlaced implements DomainEvent {
+  constructor(
+    public readonly orderId: OrderId,
+    public readonly customerId: CustomerId,
+    public readonly occurredOn: Date = new Date()
+  ) {}
+}
+
+class Order {
+  private events: DomainEvent[] = [];
+
+  place(): void {
+    this.status = OrderStatus.Placed;
+    this.events.push(new OrderPlaced(this.id, this.customerId));
+  }
+
+  pullEvents(): DomainEvent[] {
+    const events = [...this.events];
+    this.events = [];
+    return events;
+  }
+}
+```
+
+## Repositories
+
+Abstract persistence for aggregates.
+
+```typescript
+interface OrderRepository {
+  findById(id: OrderId): Promise<Order | null>;
+  save(order: Order): Promise<void>;
+  nextId(): OrderId;
+}
+```
+
+## Best Practices
+
+- One repository per aggregate root
+- Aggregates should be small
+- Reference other aggregates by ID
+- Publish domain events for cross-aggregate communication
+- Keep value objects immutable

package/data/architecture/event-driven/index.md

@@ -0,0 +1,7 @@
+# Event-Driven Architecture
+
+This directory contains event-driven architecture patterns.
+
+## Available Chunks
+
+- **patterns.md** - Event Sourcing, CQRS, Sagas, Event Versioning