A conventions framework for building consistent, sovereign, container-native systems on AWS.
Every workload runs as a container on ECS. Long-running services, scheduled jobs, one-off tasks. No Lambdas. No cold starts, no 15-minute execution limits. One runtime, one deployment story.
Postgres is the relational data layer. No DynamoDB, no Aurora-only features that bind you to AWS forever. Connection pooling, read replicas where needed, migrations checked into the repo.
OpenTofu with Terragrunt. Everything is declared, versioned, reviewed. No console clicks survive past prototyping.
Valkey for caching, session storage, and in-memory data. Open source, no Redis license entanglement, drop-in for the protocol you already know.
Runtime and toolchain in one binary. Package manager, test runner, bundler, dev server. Fast cold starts in containers, native TypeScript. No Node/npm/yarn/tsc/jest sprawl.
Type-safe HTTP framework. Schema-first, Bun-native. Routes carry validation, response shapes, and OpenAPI metadata in one place.
One cloud provider, one IAM model, one billing surface. Multi-cloud abstractions add complexity for portability you almost never exercise.
Documents, artifacts, backups, static assets. Containers serve content; consistency wins over edge-caching micro-optimizations.
TypeScript everywhere. Services, scripts, infrastructure helpers, build tooling. Strict mode on. Types cross service boundaries through shared workspace packages.
Independent deploy cadences, blast-radius isolation, per-service scaling. The monolith revival is a reaction to bad microservices — distributed monoliths with shared databases and chatty synchronous chains. Done well, microservices remain the better long-term shape.
All services and shared code live in a single repo. Bun workspaces define module boundaries. Deployment boundaries are explicit; development boundaries are fluid. Refactor across services freely.
Enforced mechanically. Files past a thousand lines are almost always doing too many things. The limit forces decomposition where it's cheapest. It also pairs naturally with AI-assisted work — smaller files load cleanly into agent context.
Type errors block at the git level. Broken types do not reach main. The first few months are the tax. Every month after is the blessing — refactors that would terrify other teams become routine.
Refactor work is first-class. Same backlog as features, same review rigor, same release process. A team that ships clean code one release and lets it rot for six isn't doing this.
If it runs continuously, it's a service. There is no "just a script." Proper service management, documented procedures, runbooks. The discipline matters more than the runtime.
Transit Gateway pattern. Each environment VPC routes egress through a central VPC. Security groups are tight by default; cross-service communication is explicit.
Secrets Manager for credentials, Parameter Store for configuration. IaC references secrets by ARN; containers pull at task start via task role. No secrets in environment files, ever.
Each worktree hosts a long-running Claude agent. The pipeline dispatches to agents that already have context loaded. Multiple worktrees run in parallel — refactoring here, drafting a migration there, reviewing a PR somewhere else. No context bleeding.
Microservices bound the context window. TypeScript catches hallucinations at compile time. Husky pre-commit hooks verify agent output mechanically. Monorepo workspace imports give agents deterministic navigation. The stack wasn't designed for AI, but the choices that made it good for humans made it good for agents too.
If there's a CLI for it, the agent uses the CLI. Text in, text out, exit codes. They compose naturally, run in containers, and are debuggable with the same tools as everything else. A short markdown README is usually all the integration you need.
Agents get SES access and send HTML email notifications. Rich notifications — formatted diffs, PR links, run logs, screenshots. Agents communicate in the medium humans actually check.
Agents read tickets the same way they read code — through git, with file paths and grep. Changes to tickets are version-controlled. The history of "what we said we'd build" lives alongside "what we built."
Deploy controllers, dispatch interfaces, status dashboards — all built with the same React mental model as the rest of the codebase. Build the tool around the workflow, not the data model.
Epic Beast is opinionated, not inflexible. The goal is one mental model from dev to prod.
No exotic compute primitives, no proprietary lock-in where an open alternative exists, no special-case services that fragment how you reason about the system. Defaults are strong; deviation is allowed when there's a concrete reason, not a hypothetical one.
If you can't answer "where does this run?" with "in a container," it doesn't belong in Epic Beast by default.
The pillars are the load-bearing walls. The architectural conventions are how teams decorate the rooms. Conventions have shelf lives — the decision history makes that visible.
It's not a starter kit. It's not a framework. It's a set of conventions — load-bearing decisions about how systems are shaped so that teams can move fast without re-litigating the foundation every quarter.