DevArchy CDK

Simplified AWS CDK constructs for fullstack developers - build cloud infrastructure with minimal AWS knowledge.

Overview

DevArchy CDK is a library of high-level AWS CDK constructs designed to make cloud infrastructure accessible to fullstack web developers. Instead of wrestling with complex AWS configurations, you can focus on building your application while DevArchy handles the infrastructure complexity.

Key Features

• Simplified API: Intuitive, chainable methods that feel natural to JavaScript/TypeScript developers
• Sensible Defaults: Production-ready configurations out of the box
• Minimal AWS Knowledge Required: Build serverless applications without being an AWS expert
• Full CDK Compatibility: Works seamlessly with standard AWS CDK constructs
• Type-Safe: Full TypeScript support with comprehensive type definitions

Installation

NPM Installation

npm install devarchy-cdk

Peer Dependencies

DevArchy CDK requires the following peer dependencies to be installed in your project:

npm install aws-cdk-lib constructs

Required versions:

• aws-cdk-lib: ^2.0.0 or higher
• constructs: ^10.0.0 or higher
• node: >=16.0.0

Complete Installation

For new projects, install all dependencies at once:

npm install devarchy-cdk aws-cdk-lib constructs

TypeScript Support

DevArchy CDK is written in TypeScript and includes full type definitions. No additional @types packages are needed.

Import Patterns

DevArchy CDK supports multiple import patterns to suit your preferences and enable tree-shaking:

Named Imports (Recommended)

import { RestApiConstruct, FunctionConstruct, DynamoConstruct } from 'devarchy-cdk';

Individual Construct Imports (Tree-shaking Friendly)

import { RestApiConstruct } from 'devarchy-cdk/dist/api/rest';
import { FunctionConstruct } from 'devarchy-cdk/dist/compute/lambda';
import { DynamoConstruct } from 'devarchy-cdk/dist/database/dynamo';

Category-based Imports

// Import all API constructs
import * as DevArchyApi from 'devarchy-cdk/dist/api';
const api = new DevArchyApi.RestApiConstruct(this, 'MyApi');

// Import all database constructs  
import * as DevArchyDb from 'devarchy-cdk/dist/database';
const table = new DevArchyDb.DynamoConstruct(this, 'MyTable');

TypeScript Types

All construct props and interfaces are exported alongside the constructs:

import { 
  RestApiConstruct, 
  RestApiConstructProps,
  FunctionConstruct,
  FunctionConstructProps 
} from 'devarchy-cdk';

Quick Start

Here's a simple example that creates a REST API with Lambda and DynamoDB:

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { RestApiConstruct, FunctionConstruct, DynamoConstruct } from 'devarchy-cdk';

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // Create a DynamoDB table
    const usersTable = new DynamoConstruct(this, 'UsersTable');
    usersTable.addKeys('userId', 'timestamp');

    // Create a REST API
    const api = new RestApiConstruct(this, 'MyApi');
    api.cors();

    // Add endpoints with Lambda handlers
    api
      .get('/users/{userId}', async (event) => {
        // Your handler code
        return { statusCode: 200, body: JSON.stringify({ message: 'Hello' }) };
      })
      .readFrom(usersTable);

    api
      .post('/users', async (event) => {
        // Your handler code
        return { statusCode: 201, body: JSON.stringify({ message: 'Created' }) };
      })
      .writeTo(usersTable);
  }
}

Core Constructs

FunctionConstruct

Simplified Lambda function creation with support for inline code, local files, or S3 sources.

const fn = new FunctionConstruct(this, 'MyFunction');
fn.code(async (event) => {
  console.log(event);
  return { success: true };
});

Features:

• ✅ Inline code support
• ✅ Local file deployment
• ✅ S3 source support
• ✅ Layer management
• ✅ Event destinations (success/failure)
• ✅ VPC configuration
• ✅ Environment variables

DynamoConstruct

Easy DynamoDB table creation with stream support and event handlers.

const table = new DynamoConstruct(this, 'MyTable');
table.addKeys('pk', 'sk');

// Add stream handler
table.on('INSERT', async (event) => {
  console.log('New item:', event);
});

Features:

• ✅ Table creation with partition/sort keys
• ✅ DynamoDB Streams
• ✅ Event handlers
• ✅ DAX caching support
• ⚠️ Limitations: Global secondary indexes not yet implemented

RestApiConstruct

Fluent API for creating REST APIs with Lambda integration, CORS, and authorization.

const api = new RestApiConstruct(this, 'MyApi');
api
  .cors()
  .authorizer('myAuth', './path/to/authorizer')
  .get('/items', './path/to/handler')
  .post('/items', async (event) => {
    // Inline handler
  });

Features:

• ✅ HTTP methods (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD)
• ✅ CORS configuration
• ✅ Lambda integration
• ✅ Direct DynamoDB integration
• ✅ SQS integration
• ✅ Mock responses
• ✅ HTTP proxy integration
• ✅ Request/response transformations

WebAppConstruct

Deploy static websites with CloudFront CDN and custom domains.

const webapp = new WebAppConstruct(this, 'MyWebApp', {
  domainName: 'example.com',
  hostedZoneId: 'Z1234567890ABC',
  certArn: 'arn:aws:acm:...'
});

webapp
  .run('./frontend', 'npm run build')
  .addAssets('./frontend/dist');

Features:

• ✅ S3 static website hosting
• ✅ CloudFront CDN distribution
• ✅ Custom domain support
• ✅ SSL certificate integration
• ✅ Lambda@Edge support
• ✅ Build command execution
• ✅ Asset deployment

GraphQlApiConstruct

Create AppSync GraphQL APIs with resolvers.

const api = new GraphQlApiConstruct(this, 'MyGraphQLApi');
api
  .schema('./schema.graphql')
  .query('getUser', userResolver)
  .mutation('createUser', createUserResolver);

Features:

• ✅ Schema definition from file or string
• ✅ Lambda resolvers
• ✅ DynamoDB data sources
• ✅ Lambda authorization
• ✅ API key authorization
• ⚠️ Limitations: Direct DynamoDB resolvers not yet implemented, subscription resolvers need more testing

WebSocketApiConstruct

Build real-time WebSocket APIs.

const wsApi = new WebSocketApiConstruct(this, 'MyWebSocketApi');
wsApi.addRoute('$connect', connectHandler);
wsApi.addRoute('$disconnect', disconnectHandler);
wsApi.addRoute('sendMessage', messageHandler);

Features:

• ✅ WebSocket API creation
• ✅ Route handling
• ✅ Lambda integration
• ⚠️ Limitations: Authorization not yet implemented, direct service integrations (DynamoDB, SQS) not available

AuthConstruct

Simplified AWS Cognito user pool and identity management.

const auth = new AuthConstruct(this, 'MyAuth');
auth.addClient({
  domainPrefix: 'myapp-auth',
  redirectUri: 'https://myapp.com',
  callbackUrls: ['https://myapp.com/callback']
});

Features:

• ✅ User pool creation
• ✅ Email/phone verification
• ✅ OAuth flows
• ✅ Custom domains
• ⚠️ Limitations: Identity pools need more testing, custom attributes configuration limited

Construct Maturity Levels

DevArchy CDK constructs are classified into maturity levels to help you understand their stability and production readiness:

• Stable: Production-ready with comprehensive features and extensive testing. API is stable with backward compatibility guarantees.

• Beta: Feature-complete for most use cases but may have some limitations. API may change in minor versions. Suitable for development and testing environments.

• Experimental: Early-stage constructs with limited features. API may change significantly. Use with caution in production.

Advanced Features

Lambda Layers

const fn = new FunctionConstruct(this, 'MyFunction');
fn
  .createLayer('myLayer', './layers/my-layer')
  .useLayer('myLayer')
  .code('./path/to/handler');

DynamoDB Direct Integration

Skip Lambda and integrate API Gateway directly with DynamoDB:

api.get('/users/{userId}').dynamodb(usersTable);
api.post('/users').dynamodb(usersTable);

Event-Driven Architecture

const fn1 = new FunctionConstruct(this, 'Function1');
const fn2 = new FunctionConstruct(this, 'Function2');

fn1
  .code(handler1)
  .then(fn2)  // Success destination
  .catch(errorHandler);  // Failure destination

// DynamoDB Streams
fn2.trigger(usersTable);

Lambda@Edge

webapp
  .path('/api/*')
  .onViewerRequest(authHandler)
  .onOriginResponse(cacheHandler);

Known Limitations

While DevArchy CDK provides powerful abstractions, there are some current limitations to be aware of:

DynamoConstruct

• Global secondary indexes (GSI) are not yet supported
• Local secondary indexes (LSI) are not yet supported
• Advanced table configurations (point-in-time recovery, encryption) use CDK defaults

GraphQlApiConstruct

• Direct DynamoDB resolvers (VTL templates) are not implemented
• Subscription resolvers need additional testing
• Custom scalar types require manual schema definition
• Pipeline resolvers are not yet supported

WebSocketApiConstruct

• Authorization mechanisms are not implemented
• Direct service integrations (DynamoDB, SQS, SNS) are not available
• Route selection expressions are limited to basic patterns

AuthConstruct

• Identity pools integration needs more testing
• Custom attributes configuration is limited
• Advanced security features (MFA, risk-based authentication) use Cognito defaults
• Custom authentication flows are not yet supported

General Limitations

• Some advanced AWS service features may not be exposed through the simplified API
• Complex IAM policies may require direct CDK usage
• Multi-region deployments are not specifically addressed
• Cost optimization features are limited to basic configurations

Supported AWS Services

DevArchy CDK provides simplified constructs for the following AWS services:

Compute Services

• AWS Lambda - Serverless functions with support for inline code, local files, and S3 sources
  • Lambda Layers for shared dependencies
  • Event destinations (success/failure routing)
  • VPC configuration and security groups
  • Environment variables and timeout configuration

Storage & Database Services

• Amazon DynamoDB - NoSQL database with streams and event handling

  • Partition and sort key configuration
  • DynamoDB Streams for real-time data processing
  • DAX caching support for improved performance
  • Event-driven triggers for Lambda functions

• Amazon S3 - Object storage for static assets and application artifacts

  • Static website hosting configuration
  • CORS policy management
  • Asset deployment and build integration

API & Networking Services

• Amazon API Gateway (REST) - RESTful APIs with Lambda integration

  • HTTP methods (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD)
  • CORS configuration and custom headers
  • Lambda authorizers for authentication
  • Direct DynamoDB integration (proxy mode)
  • SQS integration for asynchronous processing
  • Mock responses and HTTP proxy integration

• AWS AppSync (GraphQL) - Managed GraphQL APIs

  • Schema definition from files or strings
  • Lambda resolvers for custom business logic
  • DynamoDB data sources
  • API key and Lambda authorization
  • Real-time subscriptions (beta)

• Amazon API Gateway (WebSocket) - Real-time bidirectional communication

  • WebSocket route handling ($connect, $disconnect, custom routes)
  • Lambda integration for message processing
  • Connection management and broadcasting

Content Delivery & Web Services

• Amazon CloudFront - Global content delivery network

  • Static website distribution
  • Custom domain support with SSL certificates
  • Lambda@Edge for request/response processing
  • Origin failover and caching strategies

• Amazon Route 53 - DNS and domain management

  • Custom domain configuration
  • SSL certificate integration
  • Health checks and routing policies

Security & Identity Services

• Amazon Cognito - User authentication and authorization
  • User pools for sign-up and sign-in
  • Email and phone verification
  • OAuth 2.0 flows (Authorization Code, Implicit)
  • Custom domains for hosted UI
  • Identity pools for AWS resource access (beta)

Developer Tools & CI/CD

• AWS CodePipeline - Continuous integration and deployment

  • Source code integration (CodeCommit, GitHub)
  • Build automation with CodeBuild
  • Multi-stage deployment workflows

• AWS CodeBuild - Managed build service

  • Custom build specifications
  • Docker container support
  • Integration with CodePipeline

• AWS CodeCommit - Git repository hosting

  • Source code version control
  • Integration with CI/CD pipelines

Development Environment

• AWS Cloud9 - Cloud-based IDE
  • EC2-based development environments
  • Automatic hibernation for cost optimization
  • SSM-based secure connections
  • Custom instance types and configurations

Specialized Services

• TinyVector Database - Custom vector database implementation

  • Vector similarity search
  • Lambda-based processing
  • S3 storage backend

• TinyGraph Database - Custom graph database implementation

  • Graph data modeling
  • Relationship traversal
  • JSON-based storage

Roadmap

DevArchy CDK is focused on building comprehensive serverless tooling to enable event-driven, scalable applications. Our roadmap prioritizes AWS services that complement our existing serverless foundation.

Current Serverless Foundation ✅

• Compute: Lambda functions with layers and triggers
• Storage: DynamoDB with streams and event handling
• Web: Static sites with CloudFront and S3
• APIs: REST and GraphQL APIs with API Gateway and AppSync
• Real-time: WebSocket APIs for live communication
• CI/CD: CodePipeline and CodeBuild for deployment automation
• Auth: Cognito for user management

Next Quarter (Q1 2026) 🚀

Priority: Time Series & Load Balancing

• TimestreamConstruct

  • Simplified time series database for IoT, monitoring, and analytics
  • Built-in retention policies and query optimization
  • Integration with Lambda for data ingestion and processing

• LoadBalancerConstruct

  • Application Load Balancer with intelligent traffic routing
  • Support for Lambda targets, Fargate containers, and EC2 instances
  • Health checks and auto-scaling integration

• EventBridgeConstruct

  • Event-driven architecture with custom event buses
  • Rule-based event routing and filtering
  • Integration with all existing constructs for reactive patterns

Following Quarter (Q2 2026) 🔮

Priority: Container & Compute Expansion

• FargateConstruct

  • Serverless containers with auto-scaling
  • Integration with LoadBalancerConstruct
  • Support for scheduled and event-driven tasks

• EC2Construct

  • Simplified EC2 instance management
  • Auto Scaling Groups with intelligent policies
  • Integration with existing networking and security patterns

Continuous Improvements 🔄

• Enhanced DynamoDB: Global Secondary Indexes, advanced configurations
• WebSocket Auth: Authorization mechanisms for real-time APIs
• Monitoring: CloudWatch dashboards and alerting constructs
• Security: Enhanced IAM patterns and security best practices

Community Driven 💡

Have ideas for new constructs or improvements? We'd love to hear from you:

• Request a Feature
• Join Discussions
• Contribute - Help us build the future of serverless tooling

Documentation

• API Documentation
• Getting Started Guide
• Best Practices
• Architecture Overview
• Troubleshooting
• Examples

Examples

Check out the examples directory for complete working examples:

• Simple REST API - Basic CRUD API with Lambda and DynamoDB
• Fullstack Application - Complete app with frontend, backend, and auth
• Serverless Backend - Event-driven architecture with WebSockets

TypeScript Configuration

DevArchy CDK is built with TypeScript and provides full type safety. Here's the recommended TypeScript configuration for your CDK project:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "declaration": true,
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": false,
    "inlineSourceMap": true,
    "inlineSources": true,
    "experimentalDecorators": true,
    "strictPropertyInitialization": false,
    "typeRoots": ["./node_modules/@types"]
  },
  "exclude": ["cdk.out"]
}

Package.json Scripts

Add these scripts to your package.json for a smooth development experience:

{
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
    "cdk": "cdk",
    "deploy": "cdk deploy",
    "diff": "cdk diff",
    "synth": "cdk synth"
  }
}

Requirements

• Node.js: >=16.0.0
• AWS CDK: ^2.0.0 (peer dependency)
• Constructs: ^10.0.0 (peer dependency)
• TypeScript: ^4.9.0 or higher (recommended)
• AWS Account: With appropriate permissions for the services you plan to use

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Common Installation Issues

Peer dependency warnings:

npm WARN [email protected] requires a peer of aws-cdk-lib@^2.0.0 but none is installed.

Solution: Install the required peer dependencies:

npm install aws-cdk-lib constructs

TypeScript compilation errors:

Cannot find module 'devarchy-cdk' or its corresponding type declarations.

Solution: Ensure TypeScript can find the package:

1. Check that devarchy-cdk is in your package.json dependencies
2. Run npm install to ensure the package is installed
3. Restart your TypeScript language server

Import errors:

Module '"devarchy-cdk"' has no exported member 'RestApiConstruct'

Solution: Check your import syntax and ensure you're using the correct construct names:

// Correct
import { RestApiConstruct } from 'devarchy-cdk';

// Incorrect
import { RestApi } from 'devarchy-cdk';

Version Compatibility

| DevArchy CDK | AWS CDK | Node.js | TypeScript | |--------------|---------|---------|------------| | ^0.2.0 | ^2.0.0 | >=16.0 | ^4.9.0 |

Getting Help

If you encounter issues not covered here:

1. Check the troubleshooting guide
2. Search existing issues
3. Create a new issue with:
   • Your Node.js version (node --version)
   • Your npm version (npm --version)
   • Your package.json dependencies
   • The complete error message

Support

• GitHub Issues
• Discussions

Author

Diego Torres [email protected]

Built with ❤️ and ☕ to make AWS accessible to all developers