A comprehensive, opinionated framework for building enterprise-grade cloud-native applications on AWS. It covers everything from architecture principles and software design patterns to CI/CD pipelines, observability, AI integration, and hands-on workshops.
This is not just documentation — it's a decision framework that tells you:
- What to build with (services, tools, patterns)
- How to structure code (hexagonal architecture, DDD)
- How to deploy safely (TPF, canary, Express mode)
- How to govern at scale (SCPs, RCPs, policy-as-code)
- How to operate (frontier agents, observability, drift detection)
- How to develop with AI (AI-DLC, Kiro, ThothCTL)
flowchart TD
subgraph Principles["PRINCIPLES & PATTERNS"]
ARCH["Architecture Principles<br/>(16-Factor, Well-Architected, Cell-Based)"]
SW["Software Architecture<br/>(Hexagonal, DDD, CQRS, Vertical Slice)"]
end
subgraph Infrastructure["INFRASTRUCTURE"]
COMPUTE["Compute<br/>(Lambda, ECS, Step Functions)"]
IAC["IaC<br/>(CDK + Express, SAM, SST)"]
API["API & Events<br/>(AppSync, EventBridge, VPC Lattice)"]
DATA["Data Layer<br/>(DynamoDB, Aurora, ElastiCache)"]
FRONT["Frontend<br/>(Amplify, SST, Edge)"]
end
subgraph Delivery["DELIVERY & OPERATIONS"]
CICD["CI/CD<br/>(TPF, Ten Pillars, CDK Pipelines)"]
OBS["Observability<br/>(OpenTelemetry, ADOT, Powertools)"]
SEC["Security<br/>(Continuum, Guardrails, RCPs)"]
AIOPS["AI Operations<br/>(DevOps Agent, FinOps Agent)"]
end
subgraph Intelligence["INTELLIGENCE LAYER"]
BRAIN["Custom AI Brain<br/>(Knowledge Bases, AgentCore Memory, MCP)"]
AGENTS["Agentic Platform<br/>(Strands SDK, AgentCore Runtime)"]
end
subgraph Methodology["METHODOLOGY & TOOLS"]
AIDLC["AI-DLC<br/>(Inception → Construction → Operations)"]
THOTH["ThothCTL<br/>(Platform Engineering CLI)"]
KIRO["Kiro<br/>(AI-assisted development)"]
end
subgraph Workshops["HANDS-ON WORKSHOPS"]
W1["Serverless<br/>(Lambda + CDK)"]
W2["Enterprise<br/>(Constructs + CodeArtifact)"]
W3["ECS Backend<br/>(Containers + Express Mode)"]
W4["CI/CD<br/>(Pipelines + Agents)"]
end
Principles --> Infrastructure
Infrastructure --> Delivery
Delivery --> Intelligence
Intelligence --> Methodology
Methodology --> Workshops
# Install the platform CLI
pip install thothctl
# Initialize development environment (installs all tools)
thothctl init env
# Scaffold a new project
git clone https://github.com/thothforge/cdkv2_typescript_scaffold.git my-project
cd my-project && npm install
# Start AI-DLC workflow with Kiro
kiro-cli chat
> Using AI-DLC, build a serverless order processing API...This index follows the same six-group learning path as the site navigation (defined in
zensical.toml). Read top-to-bottom for a guided path, or jump to the group you need.
| Document | Description |
|---|---|
| Architecture Principles | 16-Factor App, Well-Architected, TPF, Platform Engineering, Cell-Based |
| Software Architecture | Hexagonal, Vertical Slice, CQRS, Event Sourcing, DDD — when to use each |
| Platform Engineering | Manifesto, golden paths, self-service, DX metrics, maturity model |
| IDP → ADP | Four levels of agentic maturity, 3 path types, 8 core paths |
| AI-SDLC | AWS AI-DLC methodology, Agentic SDLC, 5-layer reference architecture |
| DevOps & CI/CD (TPF) | Ten Pillars of Pragmatic Deployments, DORA metrics, canary, Express mode |
| Testing Strategy | Testing pyramid, hexagonal testing, contract, chaos, load |
| APIOps Model | Contract-first, API lifecycle, OpenAPI/AsyncAPI/GraphQL, governance |
| Data Strategy | Cell data ownership, ECST, data mesh, data contracts, DynamoDB patterns |
| Document | Description |
|---|---|
| Compute Layer | Lambda (SnapStart, ARM64, streaming), Step Functions, ECS Fargate |
| Infrastructure as Code | CDK + Express Mode, SAM, SST v3, Terraform — post-Express comparison |
| CloudFormation Express | How Express mode changes the IaC landscape |
| API & Event Patterns | API Gateway, AppSync, EventBridge (Bus, Pipes, Scheduler), VPC Lattice |
| Data Layer | DynamoDB, Aurora Serverless v2, ElastiCache, OpenSearch, S3 Express |
| Frontend & Full-Stack | Amplify Gen 2, SST v3, CloudFront Functions, Lambda@Edge |
| AI/ML Integration | Bedrock, AgentCore, Strands SDK, Guardrails, RAG patterns |
| Document | Description |
|---|---|
| Observability | OpenTelemetry (ADOT), Lambda Powertools, Application Signals, Frontier Agents |
| Security Baseline | Defense-in-depth, IAM, zero-trust, data classification, AI security, secrets |
| Multi-Account Landing Zone | Control Tower, SCPs, RCPs, permission boundaries, networking, centralized logging |
| FinOps & Cost Governance | Tagging, service-level optimization, FinOps Agent, cost gates |
| Disaster Recovery & Continuity | RTO/RPO tiers, serverless DR patterns, failover runbooks |
| Ephemeral Environments & Concurrency | Per-developer sandboxes, per-PR environments, agent isolation, TTL auto-cleanup, cost guardrails |
| Reference Architecture | E-commerce, SaaS, IoT — complete stack diagrams |
| Recommendations | Final recommendations by team type and application |
| Document | Description |
|---|---|
| Adoption Roadmap | Why this framework, framework comparison, staged roadmap, checklists |
| Developer Onboarding | Prerequisites, first-30-minutes, architecture, dev workflow |
| Document | Description |
|---|---|
| Custom Intelligent AI Brains | How organizations build shared, learning memory layers (AI Brains) to support the entire product lifecycle — architecture, implementation on AWS, case studies (Peloton, Meta, McKinsey), and adoption roadmap |
| Team Topologies, Roles & Permissions | Modern team structures, new AI-era roles (Intent Engineer, AgentOps, Context Engineer), 3-tier decision authority, RACI matrix, AWS permissions model (IAM + Cedar), and staged adoption path |
| Document | Description |
|---|---|
| Workshop 0: Foundations | Your first serverless deploy — one Lambda + HTTP API with plain CDK, deploy → verify → destroy. Start here if you're new to IaC. |
| Workshop: Serverless End-to-End | Lambda + CDK + AI-DLC + ThothCTL — full application from scratch |
| Workshop: Enterprise CDK | Private constructs, CodeArtifact, Projen, multi-account, RCPs |
| Workshop: ECS Backend | Containers, ECS Express Mode, Docker Compose → cloud, Service Connect |
| Workshop: CI/CD Phase 1 | CDK Pipelines, canary, feature flags, ThothCTL DevSecOps |
| Workshop: CI/CD Phase 2 | Continuum, DevOps Agent, FinOps Agent, supply chain, SCPs + RCPs |
| Workshop: Micro-Frontends | Micro-frontends on CloudFront + S3 vs Amplify, composition, caching |
| Document | Description |
|---|---|
| Glossary | Definitions of key terms used across the framework, grouped by area, each linking to its dedicated chapter |
| Layer | Technology | Role |
|---|---|---|
| AI Methodology | AWS AI-DLC + Kiro | AI-driven development lifecycle (Inception → Construction → Operations) |
| Platform CLI | ThothCTL | DevSecOps automation, scanning, cost analysis, governance |
| IaC | CDK v2 + Express Mode | Fast, type-safe infrastructure with compliance (cdk-nag) |
| Compute | Lambda + ECS Fargate | Serverless functions + serverless containers |
| API | AppSync + API Gateway | GraphQL (real-time) + REST |
| Events | EventBridge | Async backbone (Bus + Pipes + Scheduler) |
| Data | DynamoDB + Aurora Serverless v2 | NoSQL (default) + SQL (when needed) |
| AI/ML | Bedrock + AgentCore + Strands | Foundation models + agent runtime + agent SDK |
| AI Brain | Knowledge Bases + AgentCore Memory + MCP | Organizational learning memory for agents + humans |
| Observability | OpenTelemetry (ADOT) + Powertools | Vendor-neutral traces/metrics/logs |
| Security | Continuum + Guardrails + cdk-nag | Continuous pen testing + AI safety + compliance |
| Operations | DevOps Agent + FinOps Agent | Autonomous incident investigation + cost monitoring |
| Deployment | CDK Pipelines + CodeDeploy | Self-mutating CI/CD + canary rollouts |
| Governance | SCPs + RCPs + OPA/Rego | Principal controls + resource controls + policy-as-code |
| Scaffold | cdkv2_typescript_scaffold | Golden path project template |
- Serverless-First — Managed services that scale to zero
- AI-Native — Bedrock + agents as first-class capabilities
- Event-Driven — Async by default; sync only at edges
- Cell-Based — Independent, blast-radius-contained units
- Hexagonal Code — Ports & adapters; domain never depends on infrastructure
- Zero-Trust Security — SCPs + RCPs + Cedar + least privilege
- Shift-Left — Security, cost, compliance validated before merge
- Observable — OpenTelemetry + Powertools + Application Signals from day one
- Cost-Aware — ARM64, SnapStart, Valkey, scales-to-zero
- Platform Engineering — Golden paths via constructs, scaffolds, and ThothCTL
flowchart LR
L1["L1: TEAM<br/>Single scaffold<br/>Manual deploy<br/>Local cdk-nag"] --> L2["L2: STANDARDIZED<br/>CDK Pipelines<br/>Canary deploy<br/>ThothCTL scan"]
L2 --> L3["L3: GOVERNED<br/>Private constructs<br/>SCPs + RCPs<br/>OPA policies<br/>Multi-account"]
L3 --> L4["L4: AUTONOMOUS<br/>AI agents operate<br/>Self-healing<br/>Continuous compliance<br/>FinOps optimization"]
| Level | Deploy | Security | Cost | Operations |
|---|---|---|---|---|
| L1 | cdk deploy manually |
cdk-nag locally | Manual review | CloudWatch dashboards |
| L2 | CDK Pipelines + canary | ThothCTL scan in CI | Cost estimation in PR | Application Signals |
| L3 | Multi-account + approval gates | Continuum + SCPs + RCPs | FinOps Agent monitoring | DevOps Agent investigation |
| L4 | AI proposes + human approves | Auto-remediation | Auto-optimization | Self-healing with guardrails |
| Your Goal | Start Here |
|---|---|
| New to AWS IaC — first deploy | Workshop 0: Foundations |
| Build a new serverless app | Workshop: Serverless End-to-End |
| Build a container-based backend | Workshop: ECS Backend |
| Set up enterprise CI/CD | Workshop: CI/CD Phase 1 |
| Understand architecture decisions | Architecture Principles |
| Learn software design patterns | Software Architecture Patterns |
| Set up organizational governance | Workshop: Enterprise CDK |
| Build an organizational AI Brain | Custom Intelligent AI Brains |
# Install Zensical
pip install zensical
# Preview with hot-reload
zensical serve
# Build static site
zensical build
# → Output in site/ (deploy to S3 + CloudFront, Amplify Hosting, etc.)