# Spicy Automation

## Project Overview

AWS CDK infrastructure and Jenkins shared library for deploying VPCs, ECS clusters, and ECS services on AWS. Provides type-safe TypeScript CDK constructs and Jenkins pipeline functions for automated infrastructure deployment with blue/green deployments, mixed capacity strategies (EC2 + Fargate), and persistent ALB patterns.

## Architecture Principles

### Language & Stack

- **TypeScript** for CDK constructs (AWS CDK v2)
- **Groovy** for Jenkins shared library pipelines
- **AWS CDK** for infrastructure as code
- **Jest** for testing
- **pnpm** for package management

### Code Organization

```text
spicy-automation/
├── bin/spicy-cdk.ts              # CDK app entry point
├── lib/
│   ├── constructs/               # Reusable CDK constructs
│   │   ├── spicy-vpc.ts          # VPC construct
│   │   ├── spicy-ecs-cluster.ts  # ECS cluster construct
│   │   ├── spicy-ecs-service.ts  # ECS service construct
│   │   └── spicy-alb.ts          # Persistent ALB construct
│   └── stacks/                   # CDK stacks (fromContext factories)
│       ├── spicy-vpc-stack.ts
│       ├── spicy-ecs-cluster-stack.ts
│       ├── spicy-ecs-service-stack.ts
│       └── spicy-alb-stack.ts
├── vars/                         # Jenkins shared library
│   ├── spicyVPC.groovy          # VPC pipeline
│   ├── spicyECSCluster.groovy   # ECS cluster pipeline
│   ├── spicyECSService.groovy   # ECS service pipeline
│   ├── spicyRollback.groovy     # Blue/green rollback
│   ├── cdkUtils.groovy          # CDK command utilities
│   ├── dockerUtils.groovy       # Docker/Nexus utilities
│   ├── gitUtils.groovy          # Git utilities
│   └── accounts.groovy          # Account configurations
├── docs/                         # Documentation
├── test/                         # Jest tests
└── Dockerfile                    # Jenkins agent image
```

**Directory Rules:**

- `lib/constructs/` - Reusable CDK constructs (no stack logic)
- `lib/stacks/` - Stack factories that read from CDK context
- `vars/` - Jenkins shared library functions (Groovy)
- `docs/` - User-facing documentation (keep minimal, avoid duplication)
- `test/` - Unit tests for constructs

## Coding Standards

### TypeScript Conventions

- Use interfaces for all public APIs
- Document exported functions and types with JSDoc
- Prefer readonly properties where possible
- Use strict TypeScript settings
- One construct per file, named exports only
- Use CDK best practices (overrideLogicalId for stability)

### Error Handling

- Validate required parameters early in constructors
- Throw descriptive errors with usage examples
- Use CDK's built-in validation where possible
- Don't swallow errors silently

### Concurrency

- CDK constructs are synchronous (no async/await needed)
- Jenkins pipelines handle concurrency at the stage level
- No shared mutable state in constructs

## Documentation

- Keep README.md updated
- Code comments for complex logic

## Minimal Viable Product (MVP)

1. **Keep it minimal**: Code should be the smallest implementation that works correctly
2. **Avoid over-engineering**: Don't add features "just in case" - add them when needed
3. **Simple solutions first**: Prefer simple, straightforward code over complex abstractions
4. **One thing at a time**: Each function/type should do one thing well

## When Making Changes

1. **Write tests first**: Define all expectations and error cases in tests BEFORE any implementation
2. **Mock third-party dependencies**: Use mocks for external libraries, don't test their internals
3. **Implement minimal code**: Write only what's needed to pass the tests
4. **Follow patterns**: Use existing code patterns
5. **Keep it simple**: Prefer simple, readable code over clever solutions

## Questions to Ask

If unsure about implementation:

1. Does it follow existing patterns?
2. Is it testable?
3. Does it maintain thread safety?
4. Is it documented?
5. Does it validate inputs?
6. Does it handle errors properly?