@aicgen/aicgen 1.0.0-beta.1

package/data/architecture/modular-monolith/boundaries.md

@@ -0,0 +1,133 @@
+# Modular Monolith Boundaries
+
+## High Cohesion, Low Coupling
+
+```typescript
+// ❌ Bad: Tight coupling - direct repository access
+@Injectable()
+export class OrderService {
+  constructor(private userRepo: UserRepository) {} // Crosses module boundary
+
+  async createOrder(userId: string) {
+    const user = await this.userRepo.findById(userId); // Direct access
+  }
+}
+
+// ✅ Good: Loose coupling via service
+@Injectable()
+export class OrderService {
+  constructor(private userService: UserService) {} // Service dependency
+
+  async createOrder(userId: string) {
+    const user = await this.userService.findById(userId); // Through public API
+  }
+}
+```
+
+## No Direct Cross-Module Database Access
+
+```typescript
+// ❌ Never query another module's tables directly
+class BookingService {
+  async createBooking(data: CreateBookingDto) {
+    const user = await this.prisma.user.findUnique({ where: { id: data.userId } });
+    // This bypasses the User module!
+  }
+}
+
+// ✅ Use the module's public service API
+class BookingService {
+  constructor(private userService: UserService) {}
+
+  async createBooking(data: CreateBookingDto) {
+    const user = await this.userService.findById(data.userId);
+    // Properly goes through User module
+  }
+}
+```
+
+## Separated Interface Pattern
+
+```typescript
+// Define interface in consuming module
+// modules/order/interfaces/user-provider.interface.ts
+export interface UserProvider {
+  findById(id: string): Promise<User>;
+  validateUser(id: string): Promise<boolean>;
+}
+
+// Implement in providing module
+// modules/user/user.service.ts
+@Injectable()
+export class UserService implements UserProvider {
+  async findById(id: string): Promise<User> {
+    return this.userRepo.findById(id);
+  }
+
+  async validateUser(id: string): Promise<boolean> {
+    const user = await this.findById(id);
+    return user && user.isActive;
+  }
+}
+```
+
+## Domain Events for Loose Coupling
+
+```typescript
+// ✅ Publish events instead of direct calls
+@Injectable()
+export class UserService {
+  constructor(private eventEmitter: EventEmitter2) {}
+
+  async createUser(dto: CreateUserDto): Promise<User> {
+    const user = await this.userRepo.create(dto);
+
+    this.eventEmitter.emit('user.created', new UserCreatedEvent(user.id, user.email));
+
+    return user;
+  }
+}
+
+// Other modules subscribe to events
+@Injectable()
+export class NotificationListener {
+  @OnEvent('user.created')
+  async handleUserCreated(event: UserCreatedEvent) {
+    await this.notificationService.sendWelcomeEmail(event.email);
+  }
+}
+```
+
+## Handling Circular Dependencies
+
+```typescript
+// Use forwardRef() when modules depend on each other
+@Module({
+  imports: [
+    forwardRef(() => AuthModule), // Break circular dependency
+    UserModule,
+  ],
+})
+export class UserModule {}
+
+@Module({
+  imports: [
+    forwardRef(() => UserModule),
+  ],
+})
+export class AuthModule {}
+```
+
+## Export Only What's Necessary
+
+```typescript
+@Module({
+  providers: [
+    UserService,        // Public service
+    UserRepository,     // Internal
+    PasswordHasher,     // Internal
+  ],
+  exports: [UserService], // Only export the service, not internals
+})
+export class UserModule {}
+```

package/data/architecture/modular-monolith/structure.md

@@ -0,0 +1,131 @@
+# Modular Monolith Structure
+
+## Project Organization
+
+```
+project-root/
+├── apps/
+│   └── api/
+│       ├── src/
+│       │   ├── app/              # Application bootstrap
+│       │   ├── modules/          # Business modules
+│       │   │   ├── auth/
+│       │   │   ├── user/
+│       │   │   ├── booking/
+│       │   │   ├── payment/
+│       │   │   └── notification/
+│       │   ├── common/           # Shared infrastructure
+│       │   │   ├── decorators/
+│       │   │   ├── guards/
+│       │   │   └── interceptors/
+│       │   └── prisma/           # Database service
+│       └── main.ts
+├── libs/                         # Shared libraries
+│   └── shared-types/
+└── package.json
+```
+
+## Module Structure
+
+```
+modules/booking/
+├── entities/              # Domain models and DTOs
+│   ├── booking.entity.ts
+│   ├── create-booking.dto.ts
+│   └── booking-response.dto.ts
+├── repositories/          # Data access layer
+│   └── booking.repository.ts
+├── services/              # Business logic
+│   ├── booking.service.ts
+│   └── availability.service.ts
+├── controllers/           # HTTP/API layer
+│   └── bookings.controller.ts
+└── booking.module.ts      # Module definition
+```
+
+## Module Definition
+
+```typescript
+@Module({
+  imports: [
+    PrismaModule,
+    forwardRef(() => AuthModule),
+    NotificationsModule,
+  ],
+  controllers: [BookingsController],
+  providers: [
+    BookingService,
+    AvailabilityService,
+    BookingRepository,
+  ],
+  exports: [BookingService], // Only export public API
+})
+export class BookingsModule {}
+```
+
+## Layered Architecture Within Modules
+
+```typescript
+// Controller - HTTP layer
+@Controller('api/v1/bookings')
+export class BookingsController {
+  constructor(private bookingService: BookingService) {}
+
+  @Get('calendar')
+  async getCalendarBookings(@Query() dto: GetBookingsDto) {
+    return this.bookingService.getBookingsForCalendar(dto);
+  }
+}
+
+// Service - Business logic
+@Injectable()
+export class BookingService {
+  constructor(
+    private bookingRepository: BookingRepository,
+    private availabilityService: AvailabilityService,
+  ) {}
+
+  async getBookingsForCalendar(dto: GetBookingsDto) {
+    const bookings = await this.bookingRepository.findByDateRange(
+      dto.startDate,
+      dto.endDate
+    );
+    return bookings.map(this.mapToCalendarDto);
+  }
+}
+
+// Repository - Data access
+@Injectable()
+export class BookingRepository {
+  constructor(private prisma: PrismaService) {}
+
+  async findByDateRange(start: Date, end: Date) {
+    return this.prisma.booking.findMany({
+      where: {
+        startTime: { gte: start },
+        endTime: { lte: end }
+      }
+    });
+  }
+}
+```
+
+## Shared Infrastructure
+
+```typescript
+// common/guards/jwt-auth.guard.ts
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  canActivate(context: ExecutionContext) {
+    const isPublic = this.reflector.get<boolean>('isPublic', context.getHandler());
+    return isPublic ? true : super.canActivate(context);
+  }
+}
+
+// common/decorators/current-user.decorator.ts
+export const CurrentUser = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    return ctx.switchToHttp().getRequest().user;
+  }
+);
+```

package/data/architecture/serverless/best-practices.md

@@ -0,0 +1,322 @@
+# Serverless Best Practices
+
+## Function Design
+
+### Single Responsibility
+
+```typescript
+// ❌ Bad: Multiple responsibilities
+export const handler = async (event: APIGatewayEvent) => {
+  if (event.path === '/users') {
+    // Handle users
+  } else if (event.path === '/orders') {
+    // Handle orders
+  } else if (event.path === '/products') {
+    // Handle products
+  }
+};
+
+// ✅ Good: One function per responsibility
+// createUser.ts
+export const handler = async (event: APIGatewayEvent) => {
+  const userData = JSON.parse(event.body);
+  const user = await userService.create(userData);
+  return { statusCode: 201, body: JSON.stringify(user) };
+};
+```
+
+### Keep Functions Small
+
+```typescript
+// ✅ Good: Small, focused function
+export const handler = async (event: SNSEvent) => {
+  for (const record of event.Records) {
+    const message = JSON.parse(record.Sns.Message);
+    await processMessage(message);
+  }
+};
+
+// Extract business logic to separate module
+async function processMessage(message: OrderMessage): Promise<void> {
+  const order = await orderService.process(message);
+  await notificationService.sendConfirmation(order);
+}
+```
+
+## Cold Start Optimization
+
+### Minimize Dependencies
+
+```typescript
+// ❌ Bad: Heavy imports at top level
+import * as AWS from 'aws-sdk';
+import moment from 'moment';
+import _ from 'lodash';
+
+// ✅ Good: Import only what you need
+import { DynamoDB } from '@aws-sdk/client-dynamodb';
+
+// ✅ Good: Lazy load optional dependencies
+let heavyLib: typeof import('heavy-lib') | undefined;
+
+async function useHeavyFeature() {
+  if (!heavyLib) {
+    heavyLib = await import('heavy-lib');
+  }
+  return heavyLib.process();
+}
+```
+
+### Initialize Outside Handler
+
+```typescript
+// ✅ Good: Reuse connections across invocations
+import { DynamoDB } from '@aws-sdk/client-dynamodb';
+
+// Created once, reused
+const dynamodb = new DynamoDB({});
+let cachedConnection: Connection | undefined;
+
+export const handler = async (event: Event) => {
+  // Reuse existing connection
+  if (!cachedConnection) {
+    cachedConnection = await createConnection();
+  }
+
+  return process(event, cachedConnection);
+};
+```
+
+### Provisioned Concurrency
+
+```yaml
+# serverless.yml
+functions:
+  api:
+    handler: handler.api
+    provisionedConcurrency: 5  # Keep 5 instances warm
+```
+
+## Error Handling
+
+### Structured Error Responses
+
+```typescript
+class LambdaError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number,
+    public code: string
+  ) {
+    super(message);
+  }
+}
+
+export const handler = async (event: APIGatewayEvent) => {
+  try {
+    const result = await processRequest(event);
+    return {
+      statusCode: 200,
+      body: JSON.stringify(result)
+    };
+  } catch (error) {
+    if (error instanceof LambdaError) {
+      return {
+        statusCode: error.statusCode,
+        body: JSON.stringify({
+          error: { code: error.code, message: error.message }
+        })
+      };
+    }
+
+    console.error('Unexpected error:', error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({
+        error: { code: 'INTERNAL_ERROR', message: 'Internal server error' }
+      })
+    };
+  }
+};
+```
+
+### Retry and Dead Letter Queues
+
+```yaml
+# CloudFormation
+Resources:
+  MyFunction:
+    Type: AWS::Lambda::Function
+    Properties:
+      DeadLetterConfig:
+        TargetArn: !GetAtt DeadLetterQueue.Arn
+
+  DeadLetterQueue:
+    Type: AWS::SQS::Queue
+    Properties:
+      QueueName: my-function-dlq
+```
+
+## State Management
+
+### Use External State Stores
+
+```typescript
+// ❌ Bad: In-memory state (lost between invocations)
+let requestCount = 0;
+
+export const handler = async () => {
+  requestCount++; // Unreliable!
+};
+
+// ✅ Good: External state store
+import { DynamoDB } from '@aws-sdk/client-dynamodb';
+
+const dynamodb = new DynamoDB({});
+
+export const handler = async (event: Event) => {
+  // Atomic counter in DynamoDB
+  await dynamodb.updateItem({
+    TableName: 'Counters',
+    Key: { id: { S: 'requests' } },
+    UpdateExpression: 'ADD #count :inc',
+    ExpressionAttributeNames: { '#count': 'count' },
+    ExpressionAttributeValues: { ':inc': { N: '1' } }
+  });
+};
+```
+
+### Step Functions for Workflows
+
+```yaml
+# Step Functions state machine
+StartAt: ValidateOrder
+States:
+  ValidateOrder:
+    Type: Task
+    Resource: arn:aws:lambda:...:validateOrder
+    Next: ProcessPayment
+
+  ProcessPayment:
+    Type: Task
+    Resource: arn:aws:lambda:...:processPayment
+    Catch:
+      - ErrorEquals: [PaymentFailed]
+        Next: NotifyFailure
+    Next: FulfillOrder
+
+  FulfillOrder:
+    Type: Task
+    Resource: arn:aws:lambda:...:fulfillOrder
+    End: true
+
+  NotifyFailure:
+    Type: Task
+    Resource: arn:aws:lambda:...:notifyFailure
+    End: true
+```
+
+## Security
+
+### Least Privilege IAM
+
+```yaml
+# serverless.yml
+provider:
+  iam:
+    role:
+      statements:
+        # Only the permissions needed
+        - Effect: Allow
+          Action:
+            - dynamodb:GetItem
+            - dynamodb:PutItem
+          Resource: arn:aws:dynamodb:*:*:table/Users
+
+        - Effect: Allow
+          Action:
+            - s3:GetObject
+          Resource: arn:aws:s3:::my-bucket/*
+```
+
+### Secrets Management
+
+```typescript
+import { SecretsManager } from '@aws-sdk/client-secrets-manager';
+
+const secretsManager = new SecretsManager({});
+let cachedSecret: string | undefined;
+
+async function getSecret(): Promise<string> {
+  if (!cachedSecret) {
+    const response = await secretsManager.getSecretValue({
+      SecretId: 'my-api-key'
+    });
+    cachedSecret = response.SecretString;
+  }
+  return cachedSecret!;
+}
+```
+
+## Monitoring and Observability
+
+### Structured Logging
+
+```typescript
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger({
+  serviceName: 'order-service',
+  logLevel: 'INFO'
+});
+
+export const handler = async (event: Event, context: Context) => {
+  logger.addContext(context);
+
+  logger.info('Processing order', {
+    orderId: event.orderId,
+    customerId: event.customerId
+  });
+
+  try {
+    const result = await processOrder(event);
+    logger.info('Order processed', { orderId: event.orderId });
+    return result;
+  } catch (error) {
+    logger.error('Order processing failed', { error, event });
+    throw error;
+  }
+};
+```
+
+### Tracing
+
+```typescript
+import { Tracer } from '@aws-lambda-powertools/tracer';
+
+const tracer = new Tracer({ serviceName: 'order-service' });
+
+export const handler = async (event: Event) => {
+  const segment = tracer.getSegment();
+  const subsegment = segment.addNewSubsegment('ProcessOrder');
+
+  try {
+    const result = await processOrder(event);
+    subsegment.close();
+    return result;
+  } catch (error) {
+    subsegment.addError(error);
+    subsegment.close();
+    throw error;
+  }
+};
+```
+
+## Cost Optimization
+
+- Set appropriate memory (more memory = faster CPU)
+- Use ARM architecture when possible (cheaper)
+- Batch operations to reduce invocations
+- Use reserved concurrency to limit costs
+- Monitor and alert on spending
+- Clean up unused functions and versions

package/data/architecture/serverless/index.md

@@ -0,0 +1,7 @@
+# Serverless Architecture
+
+This directory contains serverless architecture patterns.
+
+## Available Chunks
+
+- **patterns.md** - FaaS, BaaS, cold starts, best practices

package/data/architecture/serverless/patterns.md

@@ -0,0 +1,80 @@
+# Serverless Architecture
+
+## Key Principles
+
+- **Stateless functions**: Each invocation is independent
+- **Event-driven**: Functions triggered by events
+- **Auto-scaling**: Platform handles scaling
+- **Pay-per-use**: Billed by execution
+
+## Function Design
+
+```typescript
+// Handler pattern
+export async function handler(
+  event: APIGatewayEvent,
+  context: Context
+): Promise<APIGatewayProxyResult> {
+  try {
+    const body = JSON.parse(event.body || '{}');
+    const result = await processOrder(body);
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify(result)
+    };
+  } catch (error) {
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: 'Internal error' })
+    };
+  }
+}
+```
+
+## Cold Start Optimization
+
+```typescript
+// Initialize outside handler (reused across invocations)
+const dbPool = createPool(process.env.DATABASE_URL);
+
+export async function handler(event: Event): Promise<Response> {
+  // Use cached connection
+  const result = await dbPool.query('SELECT * FROM orders');
+  return { statusCode: 200, body: JSON.stringify(result) };
+}
+```
+
+## State Management
+
+```typescript
+// Use external state stores
+class OrderService {
+  constructor(
+    private dynamodb: DynamoDB,
+    private redis: Redis
+  ) {}
+
+  async getOrder(id: string): Promise<Order> {
+    // Check cache first
+    const cached = await this.redis.get(`order:${id}`);
+    if (cached) return JSON.parse(cached);
+
+    // Fall back to database
+    const result = await this.dynamodb.get({ Key: { id } });
+    await this.redis.set(`order:${id}`, JSON.stringify(result));
+    return result;
+  }
+}
+```
+
+## Best Practices
+
+- Keep functions small and focused
+- Use environment variables for configuration
+- Minimize dependencies to reduce cold start time
+- Handle timeouts gracefully
+- Use async/await for all I/O operations
+- Implement idempotency for event handlers
+- Log structured data for observability
+- Set appropriate memory and timeout limits

package/data/architecture/solid/index.md

@@ -0,0 +1,7 @@
+# SOLID Principles
+
+This directory contains SOLID design principles.
+
+## Available Chunks
+
+- **principles.md** - SRP, OCP, LSP, ISP, DIP with TypeScript examples