WS.Eng Monorepo Starter
What is the WS.Eng Monorepo Starter?
The WS.Eng Monorepo Starter is a production-ready monorepo template for building full-stack web applications on AWS. It provides:
- Backend API — A serverless REST API built with Hono running on AWS Lambda, featuring OpenAPI documentation, Cognito authentication, and AI chat with MCP tool use.
- Frontend SPA — A React single-page application built with Vite, Redux Toolkit, and Tailwind CSS, served via CloudFront.
- Infrastructure as Code — AWS CDK stacks that provision API Gateway, Lambda, DynamoDB, Cognito, CloudFront, S3, and more.
- AI Chat — A streaming AI chat feature powered by Amazon Bedrock with Model Context Protocol (MCP) tool integrations.
Quick Links
- Getting Started — Set up your local development environment and run the application.
- Architecture — Understand the backend layered pattern, frontend module structure, and dependency injection.
- CI/CD & Environments — Learn about deployment workflows, environment types, and the release pipeline.
- API Reference — Interactive API documentation auto-generated from the deployed OpenAPI specification.
High-Level Architecture
The repository is organized as a pnpm monorepo with five workspace packages:
| Package | Path | Purpose |
|---|---|---|
backend |
backend/ |
Hono API server, Lambda handlers, DI containers, business logic |
frontend |
frontend/ |
React SPA with Vite, Redux Toolkit, and Tailwind CSS |
infra |
infra/ |
AWS CDK constructs and stacks for all cloud resources |
shared |
shared/ |
Shared TypeScript types, constants, and auto-generated API client |
api-tests |
api-tests/ |
Auto-generated and hand-written integration tests for the API |
The shared package acts as the single source of truth for types and API contracts — both frontend and api-tests consume the generated API client from shared/ts/api/generated/.
Environments
The monorepo supports three environment types, each with different configurations:
| Type | Name Pattern | Purpose | Lifecycle |
|---|---|---|---|
| Production | production |
Live user-facing environment | Manual deploy via workflow_dispatch |
| Integration | integration |
Staging and continuous integration | Auto-deploys on merge to main |
| Ephemeral | pr0001–pr9999 |
Per-PR preview environments | Auto-created on PR, destroyed on close |
Key differences between environments:
- Data retention: Production retains DynamoDB tables on stack deletion; integration and ephemeral destroy them.
- Self-signup: Only enabled on ephemeral environments for easy testing.
- SSO sign-in: Available on production and integration; disabled on ephemeral.
- Source maps: Included in integration and ephemeral builds for easier debugging; excluded from production.
For a full comparison, see the CI/CD & Environments guide.