npm package: @phila/constructs
Description: AWS CDK constructs for City of Philadelphia
Latest version: 0.6.4

# @phila/constructs

AWS CDK construct library for City of Philadelphia infrastructure. Provides secure, compliant, and well-architected AWS resources with NIST 800-53 Rev 5 compliance built-in.

## Installation

```bash
npm install @phila/constructs aws-cdk-lib constructs
# or
pnpm add @phila/constructs aws-cdk-lib constructs
```

## Overview

This package provides three levels of constructs:

- **L1 Constructs**: Single-resource constructs with security defaults
- **L2 Constructs**: Multi-resource pattern constructs
- **Core Utilities**: Naming, tagging, VPC lookup, and base classes

All constructs include automatic NIST 800-53 Rev 5 compliance enforcement via CDK Nag.

## Core Utilities

### Naming

```typescript
import { PhilaNames, NamingContext, ResourceNamingContext } from '@phila/constructs';

const nameCtx: ResourceNamingContext = {
  appName: 'permits',
  environment: 'dev',
  resourceType: 'lambda',
  resourceId: 'submitForm',
};

const resourceName = PhilaNames.resource(nameCtx); // 'dev-permits-lambda-submitform'
```

### Context

```typescript
import { AppContext, Confidentiality } from '@phila/constructs';

const context: AppContext = {
  appName: 'permits',
  environment: 'dev',
  department: '4-oit',
  team: 'Software Engineering',
  contact: 'it.support@phila.gov',
  compliance: [],
  confidentiality: Confidentiality.MEDIUM,
};
```

### VPC Lookup

```typescript
import { lookupVpc } from '@phila/constructs';

const vpc = lookupVpc(scope, {
  environment: 'dev',
  account: '123456789012',
  region: 'us-east-1'
});
```

## L1 Constructs

Single-resource constructs with security best practices applied by default.

### Lambda

```typescript
import { PhilaLambda } from '@phila/constructs';

const lambda = new PhilaLambda(this, 'SubmitForm', {
  appName: 'permits',
  environment: 'dev',
  lambdaId: 'submitForm',
  runtime: 'nodejs20',
  codeDir: 'apps/submitForm',
  handler: 'index.handler',
});
```

### DynamoDB

```typescript
import { PhilaDynamoDB } from '@phila/constructs';

const table = new PhilaDynamoDB(stack, 'Table', {
  context,
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }
});
```

### PostgreSQL (RDS)

```typescript
import { PhilaPostgres } from '@phila/constructs';

const db = new PhilaPostgres(stack, 'Database', {
  context,
  vpc,
  databaseName: 'myapp'
});
```

### S3 Buckets

```typescript
import { PhilaWebBucket, PhilaFilesBucket, PhilaLogBucket } from '@phila/constructs';

const webBucket = new PhilaWebBucket(stack, 'WebBucket', { context });
const filesBucket = new PhilaFilesBucket(stack, 'FilesBucket', { context });
const logBucket = new PhilaLogBucket(stack, 'LogBucket', { context });
```

Each of PhilaWebBucket, PhilaFilesBucket, and EcsApi accepts an optional `logBucket`; when omitted, a PhilaLogBucket is created. To share one log bucket, pass it in and each construct will use a dedicated object prefix (e.g. `web-access-logs/`, `files-access-logs/`, `alb-{apiId}-access-logs`).

## L2 Constructs

Multi-resource pattern constructs that combine multiple AWS services.

### Lambda API

Complete API with Lambda, API Gateway, and optional DynamoDB or PostgreSQL.

```typescript
import { LambdaApi } from '@phila/constructs';

const api = new LambdaApi(this, 'Api', {
  ...context, // from AppContext example
  apiId: 'main',
  runtime: 'nodejs20',
  handler: 'index.handler',
  codeDir: 'dist/apps/api',
  database: 'postgres',
});
```

### Static Site

Frontend deployment with S3, CloudFront, and Route53.

```typescript
import { StaticSite } from '@phila/constructs';

const site = new StaticSite(stack, 'Site', {
  context,
  domainName: 'app.phila.gov',
  certificateArn: 'arn:aws:acm:...'
});
```

### ECS API

Containerized API with ECS, Application Load Balancer, and optional PostgreSQL.

```typescript
import { EcsApi } from '@phila/constructs';

const api = new EcsApi(stack, 'Api', {
  context,
  vpc,
  containerImage: ecs.ContainerImage.fromAsset('.'),
  // Optional: add database
  postgres: { databaseName: 'myapp' }
});
```

### Queue Processor

SQS queue with Lambda or ECS processor.

```typescript
import { QueueProcessor } from '@phila/constructs';

const processor = new QueueProcessor(stack, 'Processor', {
  context,
  vpc,
  processorType: 'lambda', // or 'ecs'
  processorCode: lambda.Code.fromAsset('dist')
});
```

## Compliance

All constructs automatically include NIST 800-53 Rev 5 compliance checks via CDK Nag. Suppressions can be added when necessary:

```typescript
import { NagSuppressions } from 'cdk-nag';

NagSuppressions.addStackSuppressions(stack, [
  {
    id: 'AwsSolutions-IAM4',
    reason: 'Managed policies are acceptable for this use case'
  }
]);
```

## Examples

See the [examples documentation](../../docs/examples.md) for complete examples.

## Development

```bash
# Build
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint
```

## License

Part of the City of Philadelphia AWS Infrastructure Library.