@aicgen/aicgen 1.0.0-beta.1

package/data/architecture/hexagonal/ports-adapters.md

@@ -0,0 +1,132 @@
+# Hexagonal Architecture (Ports & Adapters)
+
+## Core Principle
+
+The application core (domain logic) is isolated from external concerns through ports (interfaces) and adapters (implementations).
+
+## Structure
+
+```
+src/
+├── domain/           # Pure business logic, no external dependencies
+│   ├── models/       # Domain entities and value objects
+│   ├── services/     # Domain services
+│   └── ports/        # Interface definitions (driven & driving)
+├── application/      # Use cases, orchestration
+│   └── services/     # Application services
+├── adapters/
+│   ├── primary/      # Driving adapters (controllers, CLI, events)
+│   │   ├── http/
+│   │   ├── grpc/
+│   │   └── cli/
+│   └── secondary/    # Driven adapters (repositories, clients)
+│       ├── persistence/
+│       ├── messaging/
+│       └── external-apis/
+└── config/           # Dependency injection, configuration
+```
+
+## Port Types
+
+### Driving Ports (Primary)
+Interfaces that the application exposes to the outside world:
+
+```typescript
+// domain/ports/driving/user-service.port.ts
+export interface UserServicePort {
+  createUser(data: CreateUserDTO): Promise<User>;
+  getUser(id: string): Promise<User | null>;
+  updateUser(id: string, data: UpdateUserDTO): Promise<User>;
+}
+```
+
+### Driven Ports (Secondary)
+Interfaces that the application needs from the outside world:
+
+```typescript
+// domain/ports/driven/user-repository.port.ts
+export interface UserRepositoryPort {
+  save(user: User): Promise<void>;
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+}
+
+// domain/ports/driven/email-sender.port.ts
+export interface EmailSenderPort {
+  send(to: string, subject: string, body: string): Promise<void>;
+}
+```
+
+## Adapter Implementation
+
+### Primary Adapter (HTTP Controller)
+
+```typescript
+// adapters/primary/http/user.controller.ts
+export class UserController {
+  constructor(private userService: UserServicePort) {}
+
+  async create(req: Request, res: Response) {
+    const user = await this.userService.createUser(req.body);
+    res.status(201).json(user);
+  }
+}
+```
+
+### Secondary Adapter (Repository)
+
+```typescript
+// adapters/secondary/persistence/postgres-user.repository.ts
+export class PostgresUserRepository implements UserRepositoryPort {
+  constructor(private db: DatabaseConnection) {}
+
+  async save(user: User): Promise<void> {
+    await this.db.query('INSERT INTO users...', user);
+  }
+
+  async findById(id: string): Promise<User | null> {
+    const row = await this.db.query('SELECT * FROM users WHERE id = $1', [id]);
+    return row ? this.toDomain(row) : null;
+  }
+}
+```
+
+## Dependency Rule
+
+Dependencies always point inward:
+- Adapters depend on Ports
+- Application depends on Domain
+- Domain has no external dependencies
+
+```
+[External World] → [Adapters] → [Ports] → [Domain]
+```
+
+## Testing Benefits
+
+```typescript
+// Test with mock adapters
+class InMemoryUserRepository implements UserRepositoryPort {
+  private users = new Map<string, User>();
+
+  async save(user: User) { this.users.set(user.id, user); }
+  async findById(id: string) { return this.users.get(id) || null; }
+}
+
+// Domain logic tested without infrastructure
+describe('UserService', () => {
+  it('creates user', async () => {
+    const repo = new InMemoryUserRepository();
+    const service = new UserService(repo);
+    const user = await service.createUser({ name: 'Test' });
+    expect(user.name).toBe('Test');
+  });
+});
+```
+
+## When to Use
+
+- Applications needing multiple entry points (HTTP, CLI, events)
+- Systems requiring easy infrastructure swapping
+- Projects prioritizing testability
+- Long-lived applications expecting technology changes

package/data/architecture/index.md

@@ -0,0 +1,12 @@
+# Architecture Patterns
+
+Architecture-specific guidelines and best practices.
+
+## Available Architectures
+
+- `microservices/` - Microservices architecture
+- `modular-monolith/` - Modular monolith patterns
+- `event-driven/` - Event-driven architecture
+- `layered/` - Layered architecture
+- `hexagonal/` - Hexagonal (Ports & Adapters) architecture
+- `refactor/` - Refactoring strategies

package/data/architecture/layered/index.md

@@ -0,0 +1,7 @@
+# Layered Architecture
+
+This directory contains layered architecture patterns.
+
+## Available Chunks
+
+- **layers.md** - Presentation, Domain, Data Access layers

package/data/architecture/layered/layers.md

@@ -0,0 +1,100 @@
+# Layered Architecture
+
+## Layer Structure
+
+```
+┌─────────────────────────────────────┐
+│        Presentation Layer           │
+│    (Controllers, Views, APIs)       │
+└───────────────┬─────────────────────┘
+                │
+┌───────────────▼─────────────────────┐
+│          Domain Layer               │
+│    (Business Logic, Services)       │
+└───────────────┬─────────────────────┘
+                │
+┌───────────────▼─────────────────────┐
+│       Data Access Layer             │
+│    (Repositories, ORM, DAOs)        │
+└─────────────────────────────────────┘
+```
+
+## Presentation Layer
+
+Handles user interaction and HTTP requests.
+
+```typescript
+class OrderController {
+  constructor(private orderService: OrderService) {}
+
+  async createOrder(req: Request, res: Response): Promise<void> {
+    const dto = req.body as CreateOrderDTO;
+    const result = await this.orderService.createOrder(dto);
+    res.status(201).json(result);
+  }
+}
+```
+
+## Domain Layer
+
+Contains business logic and rules.
+
+```typescript
+class OrderService {
+  constructor(
+    private orderRepository: OrderRepository,
+    private productRepository: ProductRepository
+  ) {}
+
+  async createOrder(dto: CreateOrderDTO): Promise<Order> {
+    const products = await this.productRepository.findByIds(dto.productIds);
+
+    if (products.length !== dto.productIds.length) {
+      throw new ProductNotFoundError();
+    }
+
+    const order = new Order(dto.customerId, products);
+    order.calculateTotal();
+
+    await this.orderRepository.save(order);
+    return order;
+  }
+}
+```
+
+## Data Access Layer
+
+Handles persistence operations.
+
+```typescript
+class OrderRepository {
+  constructor(private db: Database) {}
+
+  async save(order: Order): Promise<void> {
+    await this.db.query(
+      'INSERT INTO orders (id, customer_id, total) VALUES ($1, $2, $3)',
+      [order.id, order.customerId, order.total]
+    );
+  }
+
+  async findById(id: string): Promise<Order | null> {
+    const row = await this.db.queryOne('SELECT * FROM orders WHERE id = $1', [id]);
+    return row ? this.mapToOrder(row) : null;
+  }
+}
+```
+
+## Layer Rules
+
+1. Upper layers depend on lower layers
+2. Never skip layers
+3. Each layer exposes interfaces to the layer above
+4. Domain layer should not depend on data access implementation
+
+## Best Practices
+
+- Keep layers focused on their responsibility
+- Use DTOs to transfer data between layers
+- Define interfaces in domain layer, implement in data access
+- Avoid business logic in presentation or data access layers
+- Consider dependency inversion for testability

package/data/architecture/microservices/api-gateway.md

@@ -0,0 +1,56 @@
+# API Gateway
+
+## Overview
+
+An API Gateway acts as a single entry point for a group of microservices. It handles cross-cutting concerns and routes requests to the appropriate backend services.
+
+## Core Responsibilities
+
+1.  **Routing**: Forwarding requests to the correct service (e.g., `/api/users` -> User Service).
+2.  **Authentication & Authorization**: Verifying identity and permissions at the edge.
+3.  **Rate Limiting**: Protecting services from abuse.
+4.  **Protocol Translation**: Converting public HTTP/REST to internal gRPC or AMQP.
+5.  **Response Aggregation**: Combining data from multiple services into a single response.
+
+## Patterns
+
+### Backend for Frontend (BFF)
+
+Create separate gateways for different client types (Mobile, Web, 3rd Party) to optimize the API for each consumer.
+
+```mermaid
+graph TD
+    Web[Web App] --> WebBFF[Web BFF]
+    Mobile[Mobile App] --> MobileBFF[Mobile BFF]
+    
+    WebBFF --> SvcA[Service A]
+    WebBFF --> SvcB[Service B]
+    
+    MobileBFF --> SvcA
+    MobileBFF --> SvcC[Service C]
+```
+
+## Implementation
+
+### Cross-Cutting Concerns
+
+Handle these at the gateway to keep microservices focused on business logic:
+
+- **SSL Termination**: Decrypt HTTPS at the gateway.
+- **CORS**: Handle Cross-Origin Resource Sharing headers.
+- **Request Validation**: Basic schema validation before hitting services.
+- **Caching**: Cache common responses.
+
+### When to Use
+
+| Use API Gateway When... | Avoid API Gateway When... |
+|-------------------------|---------------------------|
+| You have multiple microservices | You have a monolithic application |
+| You need centralized auth/security | You need ultra-low latency (extra hop) |
+| You have diverse clients (Web, Mobile) | Your architecture is very simple |
+
+## Best Practices
+
+- **Keep it Logic-Free**: Don't put business logic in the gateway. It should be a router, not a processor.
+- **High Availability**: The gateway is a single point of failure; deploy it in a cluster.
+- **Observability**: Ensure the gateway generates trace IDs and logs all traffic.

package/data/architecture/microservices/boundaries.md

@@ -0,0 +1,80 @@
+# Service Boundaries
+
+## Defining Service Boundaries
+
+Each service should own a specific business capability:
+
+```
+✅ Good Boundaries:
+- User Service: Authentication, profiles, preferences
+- Order Service: Order processing, fulfillment
+- Payment Service: Payment processing, billing
+- Notification Service: Emails, SMS, push notifications
+
+❌ Bad Boundaries:
+- Data Access Service (technical, not business)
+- Utility Service (too generic)
+- God Service (does everything)
+```
+
+## Bounded Contexts
+
+Use Domain-Driven Design to identify boundaries:
+
+- Each service represents a bounded context
+- Services are organized around business domains
+- Clear ownership of data and logic
+- Services should be independently deployable
+
+## Ownership Rules
+
+**Each service:**
+- Owns its own database (no shared databases)
+- Owns its domain logic
+- Exposes well-defined APIs
+- Can be developed by autonomous teams
+
+## Communication Rules
+
+**Avoid:**
+- Direct database access between services
+- Chatty communication (N+1 service calls)
+- Tight coupling through shared libraries
+
+**Prefer:**
+- API-based communication
+- Event-driven for data synchronization
+- Async messaging where possible
+
+## Data Ownership
+
+```text
+// ✅ Good - Service owns its data
+Class OrderService:
+  Method CreateOrder(data):
+    # Order service owns order data
+    Order = OrderRepository.Save(data)
+
+    # Publish event for other services
+    EventBus.Publish("order.created", {
+      orderId: Order.id,
+      userId: Order.userId,
+      total: Order.total
+    })
+
+    Return Order
+
+// ❌ Bad - Direct access to another service's database
+Class OrderService:
+  Method CreateOrder(data):
+    # Don't do this!
+    User = UserDatabase.FindOne({ id: data.userId })
+```
+
+## Sizing Guidelines
+
+Keep services:
+- Small enough to be maintained by a small team (2-3 developers)
+- Large enough to provide business value
+- Focused on a single bounded context
+- Independently deployable and scalable

package/data/architecture/microservices/communication.md

@@ -0,0 +1,97 @@
+# Microservices Communication
+
+## Synchronous vs Asynchronous
+
+```text
+# ⚠️ Synchronous creates coupling and multiplicative downtime
+# If Service A calls B calls C, any failure breaks the chain
+
+# ✅ Prefer asynchronous messaging for most inter-service communication
+# Limit synchronous calls to one per user request
+
+# Async Message Format Example
+Event: "order.created"
+Data: {
+  orderId: "ord_123",
+  userId: "user_456",
+  items: [...]
+}
+
+# Subscribers process independently
+Service Inventory -> ReserveItems(items)
+Service Notification -> SendEmail(user)
+```
+
+## API-Based Communication
+
+```text
+# ✅ Well-defined REST APIs between services
+GET /users/{userId}
+
+# ✅ Use circuit breaker for resilience
+Function getUserSafe(userId):
+  Try:
+    return UserClient.getUser(userId)
+  Catch Error:
+    return getCachedUser(userId) # Fallback
+```
+
+## Event-Driven Integration
+
+```text
+# ✅ Publish events for state changes
+Function CreateOrder(data):
+  order = Repository.Save(data)
+  
+  # Failures here don't block the user
+  EventBus.Publish("order.created", {
+    orderId: order.id,
+    userId: order.userId,
+    timestamp: Now()
+  })
+
+  return order
+
+# ✅ Consumers handle events independently (Decoupled)
+Service Notification:
+  On("order.created"): SendConfirmation(event)
+
+Service Inventory:
+  On("order.created"): ReserveInventory(event)
+```
+
+## Tolerant Reader Pattern
+
+```text
+# ✅ Don't fail on unknown fields - enables independent evolution
+Structure UserResponse:
+  id: string
+  name: string
+  ...ignore other fields...
+
+# ✅ Use sensible defaults for missing optional fields
+Function ParseUser(data):
+  return User {
+    id: data.id,
+    name: data.name,
+    role: data.role OR 'user',   # Default
+    avatar: data.avatar OR null
+  }
+```
+
+## Anti-Patterns
+
+```text
+# ❌ Chatty communication (N+1 service calls)
+For each orderId in orderIds:
+  GetOrder(orderId)  # N network calls!
+
+# ✅ Batch requests
+GetOrders(orderIds)  # 1 network call
+
+# ❌ Tight coupling via shared databases
+# Service A directly queries Service B's tables
+
+# ✅ API-based communication
+UserClient.GetUsers(userIds)
+```

package/data/architecture/microservices/data.md

@@ -0,0 +1,92 @@
+# Microservices Data Management
+
+## Database Per Service
+
+```
+Each service owns its database:
+
+✅ Order Service → order_db (PostgreSQL)
+✅ User Service → user_db (PostgreSQL)
+✅ Catalog Service → catalog_db (MongoDB)
+✅ Search Service → search_index (Elasticsearch)
+
+❌ Never share databases between services
+❌ Never query another service's tables directly
+```
+
+## Polyglot Persistence
+
+```text
+# Each service uses the best database for its needs
+
+# User Service -> Relational (ACID, relationships)
+Repository UserRepository:
+  Method Create(user):
+    SQL "INSERT INTO users..."
+
+# Catalog Service -> Document (Flexible schema)
+Repository ProductRepository:
+  Method Create(product):
+    Collection("products").Insert(product)
+
+# Analytics Service -> Time-Series (High write volume)
+Repository MetricsRepository:
+  Method Record(metric):
+    InfluxDB.Write(metric)
+```
+
+## Eventual Consistency
+
+```text
+# ✅ Embrace eventual consistency for cross-service data
+
+1. Order Service: Save Order -> Publish "order.created"
+2. Inventory Service: Listen "order.created" -> Reserve Inventory
+
+# Data may be temporarily inconsistent - that's OK
+
+# ✅ Use compensating actions for failures
+Function ProcessOrder(order):
+  Try:
+    InventoryService.Reserve(order.items)
+    PaymentService.Charge(order.total)
+  Catch Error:
+    # Compensate: undo previous actions
+    InventoryService.Release(order.items)
+    Throw Error
+```
+
+## Data Synchronization Patterns
+
+```text
+# Pattern: Event Sourcing / CQRS
+Service OrderQuery:
+  On("product.updated"):
+    # Update local read-optimized copy
+    Cache.Set(event.productId, { name: event.name, price: event.price })
+
+# Pattern: Saga for distributed transactions
+Saga CreateOrder:
+  Step 1:
+    Action: Inventory.Reserve()
+    Compensate: Inventory.Release()
+  Step 2:
+    Action: Payment.Charge()
+    Compensate: Payment.Refund()
+```
+
+## Data Ownership
+
+```text
+# ✅ Each service is the source of truth for its data
+Service User:
+  Function UpdateEmail(userId, email):
+    Database.Update(userId, email)
+    EventBus.Publish("user.email.changed", { userId, email })
+
+# Other services maintain their own copies (projections)
+Service Order:
+  On("user.email.changed"):
+    # Update local cache, never query User DB directly
+    LocalUserCache.Update(event.userId, event.email)
+```

package/data/architecture/microservices/index.md

@@ -0,0 +1,11 @@
+# Microservices Architecture
+
+Guidelines for building microservices.
+
+## Chunks
+
+- `boundaries.md` - Defining service boundaries
+- `communication.md` - Inter-service communication
+- `data.md` - Data management and consistency
+- `deployment.md` - Deployment strategies
+- `resilience.md` - Resilience patterns

package/data/architecture/microservices/resilience.md

@@ -0,0 +1,111 @@
+# Microservices Resilience
+
+## Circuit Breaker Pattern
+
+```text
+Class CircuitBreaker:
+  State: CLOSED | OPEN | HALF_OPEN
+  
+  Method Execute(operation):
+    If State is OPEN:
+      If TimeoutExpired:
+        State = HALF_OPEN
+      Else:
+        Throw Error("Circuit Open")
+    
+    Try:
+      Result = operation()
+      OnSuccess()
+      Return Result
+    Catch Error:
+      OnFailure()
+      Throw Error
+```
+
+## Retry with Exponential Backoff
+
+```text
+Function Retry(operation, maxAttempts, baseDelay):
+  For attempt in 1..maxAttempts:
+    Try:
+      return operation()
+    Catch Error:
+      If attempt == maxAttempts: Throw Error
+      
+      # Exponential Backoff + Jitter
+      delay = baseDelay * (2 ^ attempt) + RandomJitter()
+      Sleep(delay)
+```
+
+## Bulkhead Pattern
+
+```text
+# Isolate resources to prevent cascading failures
+Class Bulkhead:
+  MaxConcurrent = 5
+  Active = 0
+  
+  Method Execute(operation):
+    If Active >= MaxConcurrent:
+      Throw Error("Bulkhead Full")
+      
+    Active++
+    Try:
+      return operation()
+    Finally:
+      Active--
+
+# Usage: Separate bulkheads per dependency
+PaymentBulkhead = New Bulkhead(5)
+EmailBulkhead = New Bulkhead(10)
+```
+
+## Timeouts
+
+```text
+Function WithTimeout(operation, timeoutMs):
+  Race:
+    1. Result = operation()
+    2. Sleep(timeoutMs) -> Throw Error("Timeout")
+
+# Always set timeouts for external calls
+Result = WithTimeout(UserService.GetUser(id), 5000)
+```
+
+## Graceful Degradation
+
+```text
+Function GetProductRecommendations(userId):
+  Try:
+    return RecommendationService.GetPersonalized(userId)
+  Catch Error:
+    # Fallback to cached popular items
+    Log("Recommendation service unavailable")
+    return GetPopularProducts()
+
+# Partial responses instead of complete failure
+Function GetDashboard(userId):
+  User = GetUser(userId) OR null
+  Orders = GetOrders(userId) OR []
+  Stats = GetStats(userId) OR null
+
+  return { User, Orders, Stats }
+```
+
+## Health Checks
+
+```text
+Endpoint GET /health:
+  Checks = [
+    CheckDatabase(),
+    CheckRedis(),
+    CheckExternalAPI()
+  ]
+  
+  Healthy = All(Checks) passed
+  
+  Return HTTP 200/503 {
+    status: Healthy ? "healthy" : "degraded",
+    checks: { ...details... }
+  }
+```