aigroup-workflow 2.1.2 → 2.2.0

package/skills/backend/fullstack-guardian/references/backend-patterns.md

@@ -0,0 +1,237 @@
+# Backend Patterns
+
+## Microservices Architecture
+
+### Circuit Breaker Pattern
+```typescript
+class CircuitBreaker {
+  private failures = 0;
+  private threshold = 5;
+  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
+
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'OPEN') throw new Error('Circuit breaker is OPEN');
+    try {
+      const result = await fn();
+      this.failures = 0;
+      this.state = 'CLOSED';
+      return result;
+    } catch (error) {
+      this.failures++;
+      if (this.failures >= this.threshold) {
+        this.state = 'OPEN';
+        setTimeout(() => this.state = 'HALF_OPEN', 60000);
+      }
+      throw error;
+    }
+  }
+}
+```
+
+### Saga Pattern (Distributed Transactions)
+```typescript
+class OrderSaga {
+  async execute(order: Order) {
+    const compensations: (() => Promise<void>)[] = [];
+    try {
+      await inventoryService.reserve(order.items);
+      compensations.push(() => inventoryService.release(order.items));
+
+      await paymentService.charge(order.amount);
+      compensations.push(() => paymentService.refund(order.amount));
+
+      return { success: true };
+    } catch (error) {
+      for (const compensate of compensations.reverse()) await compensate();
+      throw error;
+    }
+  }
+}
+```
+
+## Message Queue Integration
+
+### Producer/Consumer with DLQ
+```typescript
+// RabbitMQ Consumer with Dead Letter Queue
+class MessageConsumer {
+  async consume(queue: string, handler: (msg: any) => Promise<void>) {
+    const channel = await this.connection.createChannel();
+
+    // Setup DLQ
+    await channel.assertExchange('dlx', 'direct', { durable: true });
+    await channel.assertQueue(`${queue}.dlq`, { durable: true });
+    await channel.bindQueue(`${queue}.dlq`, 'dlx', queue);
+
+    // Main queue
+    await channel.assertQueue(queue, {
+      durable: true,
+      deadLetterExchange: 'dlx',
+      deadLetterRoutingKey: queue,
+    });
+
+    channel.consume(queue, async (msg) => {
+      if (!msg) return;
+      try {
+        await handler(JSON.parse(msg.content.toString()));
+        channel.ack(msg);
+      } catch (error) {
+        const retryCount = (msg.properties.headers['x-retry-count'] || 0) + 1;
+        if (retryCount >= 3) {
+          channel.nack(msg, false, false); // Send to DLQ
+        } else {
+          setTimeout(() => channel.nack(msg, false, true), retryCount * 1000);
+        }
+      }
+    });
+  }
+}
+```
+
+### Idempotency
+```typescript
+class IdempotentHandler {
+  async handle(messageId: string, fn: () => Promise<void>) {
+    const exists = await db.processedMessages.findOne({ messageId });
+    if (exists) return; // Already processed
+
+    await fn();
+    await db.processedMessages.insert({ messageId, processedAt: new Date() });
+  }
+}
+```
+
+## Database Optimization
+
+### Connection Pooling
+```typescript
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  max: 20,
+  min: 5,
+  idleTimeoutMillis: 30000,
+});
+
+export async function query(sql: string, params: any[]) {
+  const client = await pool.connect();
+  try {
+    return await client.query(sql, params);
+  } finally {
+    client.release();
+  }
+}
+```
+
+### Read Replica Strategy
+```typescript
+class DatabaseRouter {
+  async query(sql: string, params: any[]) {
+    const isWrite = /^(INSERT|UPDATE|DELETE)/i.test(sql);
+    if (isWrite) return this.primary.query(sql, params);
+
+    // Round-robin read replica
+    const replica = this.replicas[Math.floor(Math.random() * this.replicas.length)];
+    return replica.query(sql, params);
+  }
+}
+```
+
+## Monitoring & Observability
+
+### Prometheus Metrics
+```typescript
+import { Counter, Histogram, Registry } from 'prom-client';
+
+const register = new Registry();
+
+const httpDuration = new Histogram({
+  name: 'http_request_duration_seconds',
+  labelNames: ['method', 'route', 'status_code'],
+  registers: [register],
+});
+
+// Middleware
+app.use((req, res, next) => {
+  const start = Date.now();
+  res.on('finish', () => {
+    httpDuration.observe({
+      method: req.method,
+      route: req.route?.path,
+      status_code: res.statusCode
+    }, (Date.now() - start) / 1000);
+  });
+  next();
+});
+
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', register.contentType);
+  res.end(await register.metrics());
+});
+```
+
+### Distributed Tracing
+```typescript
+import { trace } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('my-service');
+
+async function processOrder(orderId: string) {
+  const span = tracer.startSpan('processOrder');
+  span.setAttribute('orderId', orderId);
+
+  try {
+    await db.query('SELECT * FROM orders WHERE id = $1', [orderId]);
+    span.addEvent('Order fetched');
+    span.setStatus({ code: SpanStatusCode.OK });
+  } catch (error) {
+    span.recordException(error);
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+```
+
+## Docker & Deployment
+
+### Multi-stage Dockerfile
+```dockerfile
+FROM node:18-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production && npm run build
+
+FROM node:18-alpine
+WORKDIR /app
+RUN adduser -S nodejs -u 1001
+COPY --from=builder --chown=nodejs /app/dist ./dist
+COPY --from=builder --chown=nodejs /app/node_modules ./node_modules
+USER nodejs
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD node healthcheck.js
+CMD ["node", "dist/main.js"]
+```
+
+### Graceful Shutdown
+```typescript
+process.on('SIGTERM', async () => {
+  console.log('Shutting down gracefully');
+  server.close(() => console.log('HTTP server closed'));
+  await db.end();
+  await messageQueue.close();
+  process.exit(0);
+});
+```
+
+## Quick Reference
+
+| Pattern | Use Case | Key Benefit |
+|---------|----------|-------------|
+| Circuit Breaker | External service calls | Prevent cascade failures |
+| Saga | Distributed transactions | Data consistency |
+| Message Queue | Async processing | Decoupling & scalability |
+| Connection Pool | Database access | Performance optimization |
+| Read Replicas | High read load | Horizontal scaling |
+| Distributed Tracing | Microservices debugging | End-to-end visibility |
+| Graceful Shutdown | Container orchestration | Zero downtime deploys |

package/skills/backend/fullstack-guardian/references/common-patterns.md

@@ -0,0 +1,134 @@
+# Common Patterns
+
+## API + Frontend Flow
+
+```
+User Action → Frontend Validation → API Call → Backend Validation
+→ Business Logic → Database → Response → UI Update
+```
+
+## CRUD Implementation
+
+### Create
+
+```typescript
+// Frontend
+const createUser = async (data: CreateUserDto) => {
+  const response = await fetch('/api/users', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(data),
+  });
+  if (!response.ok) throw await response.json();
+  return response.json();
+};
+
+// Backend (NestJS)
+@Post()
+async create(@Body() dto: CreateUserDto): Promise<User> {
+  return this.userService.create(dto);
+}
+```
+
+### Read (List with Pagination)
+
+```typescript
+// Frontend
+const { data, isLoading } = useQuery({
+  queryKey: ['users', page, limit],
+  queryFn: () => fetch(`/api/users?page=${page}&limit=${limit}`).then(r => r.json()),
+});
+
+// Backend
+@Get()
+async findAll(
+  @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
+  @Query('limit', new DefaultValuePipe(20), ParseIntPipe) limit: number,
+): Promise<PaginatedResponse<User>> {
+  return this.userService.findAll({ page, limit });
+}
+```
+
+### Update
+
+```typescript
+// Frontend with optimistic update
+const updateUser = useMutation({
+  mutationFn: (data: UpdateUserDto) => api.patch(`/users/${id}`, data),
+  onMutate: async (newData) => {
+    await queryClient.cancelQueries(['user', id]);
+    const previous = queryClient.getQueryData(['user', id]);
+    queryClient.setQueryData(['user', id], (old) => ({ ...old, ...newData }));
+    return { previous };
+  },
+  onError: (err, newData, context) => {
+    queryClient.setQueryData(['user', id], context.previous);
+  },
+});
+
+// Backend
+@Patch(':id')
+async update(
+  @Param('id') id: string,
+  @Body() dto: UpdateUserDto,
+): Promise<User> {
+  return this.userService.update(id, dto);
+}
+```
+
+### Delete
+
+```typescript
+// Frontend with confirmation
+const handleDelete = async () => {
+  if (!confirm('Are you sure?')) return;
+  await api.delete(`/users/${id}`);
+  router.push('/users');
+};
+
+// Backend (soft delete)
+@Delete(':id')
+@HttpCode(204)
+async remove(@Param('id') id: string): Promise<void> {
+  await this.userService.softDelete(id);
+}
+```
+
+## Form Handling
+
+```typescript
+// React Hook Form + Zod
+const schema = z.object({
+  name: z.string().min(1, 'Required'),
+  email: z.string().email('Invalid email'),
+});
+
+function UserForm({ onSubmit }: Props) {
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(schema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('name')} />
+      {errors.name && <span>{errors.name.message}</span>}
+
+      <input {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+## Quick Reference
+
+| Pattern | Frontend | Backend |
+|---------|----------|---------|
+| Create | POST + form | Validate + insert |
+| Read | GET + query | Paginate + filter |
+| Update | PATCH + optimistic | Validate + update |
+| Delete | DELETE + confirm | Soft delete |
+| Auth | Token storage | JWT middleware |
+| Upload | FormData | Multer/streaming |

package/skills/backend/fullstack-guardian/references/deliverables-checklist.md

@@ -0,0 +1,354 @@
+# Deliverables Checklist
+
+## Code Deliverables
+
+### Backend Files
+- [ ] API endpoint implementations
+- [ ] Database models and schemas
+- [ ] Validation schemas (Zod/Pydantic)
+- [ ] Business logic services
+- [ ] Middleware (auth, error handling, logging)
+- [ ] Database migrations with rollback
+- [ ] Environment configuration files
+- [ ] Docker/container configuration
+
+### Frontend Files
+- [ ] Component files with TypeScript interfaces
+- [ ] Custom hooks for data fetching
+- [ ] State management setup (Redux/Zustand/Context)
+- [ ] API client/service layer
+- [ ] Form components with validation
+- [ ] Error boundary components
+- [ ] Routing configuration
+- [ ] Style files (CSS/SCSS/styled-components)
+
+### Shared/Integration Files
+- [ ] Shared TypeScript types package
+- [ ] Shared validation schemas
+- [ ] API contract definitions
+- [ ] Utility functions used across stack
+- [ ] Configuration types
+- [ ] Constants and enums
+
+## Testing Deliverables
+
+### Unit Tests
+```typescript
+// Backend: Service layer tests
+describe('UserService', () => {
+  it('should create user with hashed password', async () => {
+    const user = await userService.create({
+      email: 'test@example.com',
+      password: 'SecurePass123!',
+    });
+    expect(user.password).not.toBe('SecurePass123!');
+    expect(user.email).toBe('test@example.com');
+  });
+});
+
+// Frontend: Component tests
+describe('UserForm', () => {
+  it('should validate email format', async () => {
+    render(<UserForm onSubmit={jest.fn()} />);
+    await userEvent.type(screen.getByLabelText('Email'), 'invalid');
+    await userEvent.click(screen.getByText('Submit'));
+    expect(screen.getByText(/invalid email/i)).toBeInTheDocument();
+  });
+});
+```
+
+### Integration Tests
+```typescript
+// API endpoint tests
+describe('POST /api/users', () => {
+  it('should create user and return 201', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'new@example.com', password: 'Pass123!' });
+
+    expect(response.status).toBe(201);
+    expect(response.body).toHaveProperty('id');
+    expect(response.body.email).toBe('new@example.com');
+  });
+
+  it('should return 422 for duplicate email', async () => {
+    await createUser({ email: 'existing@example.com' });
+
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'existing@example.com', password: 'Pass123!' });
+
+    expect(response.status).toBe(422);
+    expect(response.body.error.code).toBe('DUPLICATE_EMAIL');
+  });
+});
+```
+
+### E2E Tests
+```typescript
+// Playwright test
+test('complete user registration flow', async ({ page }) => {
+  await page.goto('/register');
+  await page.fill('[name="email"]', 'newuser@example.com');
+  await page.fill('[name="password"]', 'SecurePass123!');
+  await page.click('button[type="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.locator('[data-testid="welcome-message"]'))
+    .toContainText('Welcome');
+});
+```
+
+### Test Coverage Requirements
+- [ ] Unit tests: >80% coverage
+- [ ] Integration tests: All critical paths
+- [ ] E2E tests: Main user journeys
+- [ ] Performance tests: Load/stress scenarios
+- [ ] Security tests: OWASP Top 10 validation
+
+## Documentation Deliverables
+
+### Technical Documentation
+```markdown
+# Feature: User Management API
+
+## Overview
+Complete CRUD API for user management with authentication and authorization.
+
+## Endpoints
+
+### Create User
+POST /api/v1/users
+
+Request:
+{
+  "email": "user@example.com",
+  "name": "John Doe",
+  "password": "SecurePass123!"
+}
+
+Response (201):
+{
+  "id": "usr_abc123",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "createdAt": "2025-01-15T10:00:00Z"
+}
+
+### Authentication
+All endpoints except POST /users require Bearer token:
+Authorization: Bearer <jwt_token>
+
+### Error Responses
+422 Validation Error:
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": { "email": ["Must be valid email"] }
+  }
+}
+```
+
+### Component Documentation
+```typescript
+/**
+ * UserProfileForm - Editable user profile form with validation
+ *
+ * @example
+ * <UserProfileForm
+ *   initialData={currentUser}
+ *   onSubmit={handleUpdate}
+ *   onCancel={() => router.back()}
+ * />
+ *
+ * @param initialData - User data to pre-populate form
+ * @param onSubmit - Callback when form is submitted with valid data
+ * @param onCancel - Optional callback when user cancels editing
+ */
+export function UserProfileForm({
+  initialData,
+  onSubmit,
+  onCancel
+}: UserProfileFormProps) {
+  // Component implementation
+}
+```
+
+### README Updates
+- [ ] Installation instructions
+- [ ] Environment variable configuration
+- [ ] Development setup steps
+- [ ] Build and deployment commands
+- [ ] Testing instructions
+- [ ] Troubleshooting guide
+
+### Storybook Documentation (Frontend)
+```typescript
+// UserCard.stories.tsx
+export default {
+  title: 'Components/UserCard',
+  component: UserCard,
+} as Meta;
+
+export const Default: Story = {
+  args: {
+    user: {
+      name: 'John Doe',
+      email: 'john@example.com',
+      avatar: 'https://example.com/avatar.jpg',
+    },
+  },
+};
+
+export const Loading: Story = {
+  args: { isLoading: true },
+};
+
+export const WithLongName: Story = {
+  args: {
+    user: {
+      name: 'Johnathan Alexander Wellington III',
+      email: 'johnathan@example.com',
+    },
+  },
+};
+```
+
+## Performance Deliverables
+
+### Metrics Report
+```markdown
+## Performance Metrics
+
+### Backend API
+- Average response time: 45ms
+- P95 response time: 120ms
+- P99 response time: 250ms
+- Throughput: 1000 req/s
+- Error rate: 0.02%
+
+### Frontend Bundle
+- Initial bundle size: 245 KB (gzipped)
+- Largest chunk: 180 KB
+- Time to Interactive: 1.2s
+- Lighthouse score: 95/100
+
+### Database Queries
+- Average query time: 15ms
+- Slowest query: 85ms (user search)
+- Index usage: 98%
+- Connection pool utilization: 60%
+```
+
+### Bundle Analysis
+- [ ] Webpack/Vite bundle analysis report
+- [ ] Lighthouse performance audit
+- [ ] Core Web Vitals measurements
+- [ ] Bundle size comparison (before/after)
+
+## Security Deliverables
+
+### Security Checklist
+- [ ] Input validation on all endpoints
+- [ ] Output sanitization (XSS prevention)
+- [ ] SQL injection prevention (parameterized queries)
+- [ ] CSRF protection enabled
+- [ ] Rate limiting configured
+- [ ] Authentication required where needed
+- [ ] Authorization checks implemented
+- [ ] Sensitive data excluded from responses
+- [ ] Secrets in environment variables
+- [ ] HTTPS enforced in production
+- [ ] Security headers configured (CSP, HSTS, etc.)
+
+### Security Audit Report
+```markdown
+## Security Review
+
+### Authentication
+- JWT with RS256 algorithm
+- 15-minute access tokens
+- 7-day refresh tokens
+- Secure cookie storage
+
+### Authorization
+- Role-based access control (RBAC)
+- Resource ownership validation
+- Permission checks on all mutations
+
+### Data Protection
+- Passwords hashed with bcrypt (12 rounds)
+- Sensitive data encrypted at rest
+- PII excluded from logs
+- Rate limiting: 100 req/15min per IP
+```
+
+## Deployment Deliverables
+
+### Configuration Files
+- [ ] `Dockerfile` with multi-stage build
+- [ ] `docker-compose.yml` for local dev
+- [ ] CI/CD pipeline configuration
+- [ ] Environment-specific configs
+- [ ] Database migration scripts
+- [ ] Health check endpoints
+- [ ] Kubernetes manifests (if applicable)
+
+### Deployment Guide
+```markdown
+## Deployment Steps
+
+### Prerequisites
+- Node.js 18+
+- PostgreSQL 15+
+- Redis 7+
+
+### Environment Variables
+DATABASE_URL=postgresql://user:pass@host:5432/dbname
+REDIS_URL=redis://localhost:6379
+JWT_SECRET=<generate-secure-secret>
+API_PORT=3000
+
+### Build & Deploy
+npm run build
+npm run migrate
+npm run start:prod
+
+### Health Check
+GET /api/health
+Expected: { "status": "ok", "database": "connected" }
+```
+
+## Handoff Checklist
+
+### Before Handoff
+- [ ] All tests passing
+- [ ] Code reviewed and approved
+- [ ] Documentation complete
+- [ ] Performance validated
+- [ ] Security reviewed
+- [ ] Deployed to staging
+- [ ] E2E tests pass in staging
+- [ ] Accessibility audit complete
+
+### Handoff Package
+- [ ] Links to merged PRs
+- [ ] Deployment instructions
+- [ ] Database migration notes
+- [ ] Known issues/limitations
+- [ ] Monitoring dashboard URLs
+- [ ] Rollback procedure
+- [ ] Support contact information
+
+## Quick Reference
+
+| Category | Key Deliverables | Coverage Target |
+|----------|-----------------|-----------------|
+| Backend | API, models, migrations | 80% test coverage |
+| Frontend | Components, hooks, routes | 85% test coverage |
+| Tests | Unit, integration, E2E | All critical paths |
+| Docs | API, components, setup | Complete |
+| Performance | Metrics, bundle analysis | <200ms P95 API, <2s TTI |
+| Security | Audit, OWASP validation | All vulnerabilities addressed |
+| Deployment | Docker, CI/CD, guides | Zero-downtime capable |