@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

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

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

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

const context: AppContext = {
  appName: 'permits',
  environment: 'dev',
  department: '4-oit',
  team: 'Software Engineering',
  contact: '[email protected]',
  compliance: [],
  confidentiality: Confidentiality.MEDIUM,
};

VPC Lookup

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

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

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

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

PostgreSQL (RDS)

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

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

S3 Buckets

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 });

ECS Service

import { PhilaEcsService } from '@phila/constructs';

const service = new PhilaEcsService(stack, 'Service', {
  context,
  vpc,
  cluster,
  taskDefinition
});

L2 Constructs

Multi-resource pattern constructs that combine multiple AWS services.

Lambda API

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

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.

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.

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.

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:

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 for complete examples.

Development

# Build
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint

License

Part of the City of Philadelphia AWS Infrastructure Library.