Architecture

Package Dependency Graph

VentureKit is a modular monorepo. Each package has a specific responsibility and a well-defined set of dependencies.

┌─────────────────────────────────────────────────────┐
│                    Consumer App                      │
│  vk.config.ts + src/routes/ + config/        │
└──────┬──────────────┬──────────────┬────────────────┘
       │              │              │
       ▼              ▼              ▼
  @venturekit/    @venturekit/   @venturekit/
     infra          runtime         cli
       │              │              │
       │              ├──────────────┤
       ▼              ▼              ▼
            @venturekit/core
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
@venturekit/  @venturekit/  @venturekit/
   auth          data        storage

    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
@venturekit/  @venturekit/  @venturekit/
  tenancy        ai          billing

Package Roles

Foundation Layer

@venturekit/core

The foundation of the framework. Provides all TypeScript types, configuration presets, config resolution logic, and validation utilities. Every other package depends on core.

Exports: BaseConfig, SecurityConfig, EnvConfigInput, ResolvedConfig, VentureIntent, presets, validators.

Application Layer

@venturekit/runtime

Everything needed to write Lambda handlers. Provides the unified handler() function, request context building, response helpers, structured errors, composable middleware, and structured logging via Pino.

Depends on: core, pino
Optional peers: data (for transactional handlers), AWS SDK (for WebSocket)

@venturekit/infra

The infrastructure abstraction layer. Provides defineVenture() for consumer config files and VentureStack which translates infrastructure intents into AWS CDK constructs. Handles Lambda configuration, API Gateway setup, VPC creation, and WebSocket API.

Depends on: core, aws-cdk-lib, constructs

@venturekit/cli

The developer CLI (vk). Provides project scaffolding (init), development server (dev), deployment (deploy), teardown (remove), code generation (generate), and database migrations (migrate).

Depends on: core, commander, chalk, ora, prompts

Feature Packages

@venturekit/auth

Authentication and authorization. Cognito User Pool configuration, role-based access control, scope checking utilities, and JWT token utilities (decode, extract user, check expiry).

Depends on: core

@venturekit/data

Database and data layer. RDS configuration for PostgreSQL/MySQL, migration utilities (Drizzle Kit integration), query helpers, result mapping, and transaction management.

Depends on: core, pg

@venturekit/storage

Storage layer. S3 bucket configuration with CDN (CloudFront), lifecycle policies, CORS settings, and versioning.

Depends on: core

@venturekit-pro/tenancy

Multi-tenant utilities. Tenant resolution (subdomain, custom domain, path, header, JWT), tenant context management, data isolation strategies, and quota enforcement middleware.

Depends on: core

@venturekit-pro/ai

AI utilities. Embeddings (OpenAI, Bedrock), vector stores (Pinecone, pgvector, in-memory), RAG pipelines (chunking, retrieval, context building), and agents with tool use (OpenAI function calling).

Depends on: core
Optional peers: openai, @aws-sdk/client-bedrock-runtime, @pinecone-database/pinecone

@venturekit-pro/billing

Billing and invoicing. Plan definitions with feature limits, feature checking, usage-to-invoice mapping, and auto-migration support for billing tables.

Depends on: core

Request Lifecycle

When a request hits your VentureKit application:

1. API Gateway receives the request — API Gateway routes the request to the appropriate Lambda function based on the HTTP method and path.
2. Handler is invoked — The handler() function from @venturekit/runtime wraps your business logic.
3. Middleware executes — Error boundary, logging, and any custom middleware run in order.
4. Auth check (if scopes defined) — If scopes are specified, the handler verifies the JWT and checks scope permissions.
5. Body parsing — The request body is parsed from JSON automatically.
6. Your handler runs — Your business logic executes with typed body, ctx, and logger.
7. Response is returned — The return value is serialized to JSON with the appropriate HTTP status code.

Infrastructure Flow

When you deploy with vk deploy:

1. Configuration resolved — defineVenture() merges base + security + environment config into a single ResolvedConfig.
2. Routes discovered — File-based routing scans your routesDir and maps files to API routes.
3. Intents translated — Infrastructure intents (databases, storage, queues, etc.) are translated to CDK constructs.
4. Resources created — CDK creates Lambda functions, API Gateway, VPC, and all declared infrastructure.
5. Outputs available — Infrastructure outputs (endpoints, ARNs, URLs) are injected into Lambda environment variables.

Technology Stack

Layer	Technology
Language	TypeScript (ES2022)
Runtime	AWS Lambda (Node.js 20)
API	Amazon API Gateway v2 (HTTP + WebSocket)
Infrastructure	AWS CDK
Auth	Amazon Cognito
Database	Amazon RDS (PostgreSQL, MySQL)
Storage	Amazon S3 + CloudFront
Queues	Amazon SQS
Cache	Amazon ElastiCache (Redis, Memcached)
Scheduling	Amazon EventBridge
Logging	Pino (structured JSON)
Migrations	Drizzle Kit
Package manager	pnpm (workspace monorepo)