AppTheory

Contract-first serverless runtime for AWS Lambda.
One application model. Three runtimes. Verified on every commit.

Get started → · API reference · Contract fixtures · MCP runtime

AppTheory is a contract-first serverless runtime for AWS Lambda designed to keep request handling, middleware, and event normalization consistent across languages and reliable in generative coding workflows (humans + AI assistants). It ships peer implementations in Go, TypeScript, and Python — not a Go library with bindings, but three independent runtimes verified against the contract fixture corpus on every commit. Go, TypeScript, and Python execute the SP09 MCP and SP12 OAuth fixtures as first-class contract tiers.

            FaceTheory (client delivery)
                      │
      AppTheory (serverless runtime)  ← you are here
                      │
            TableTheory (data layer)
                      │
                  DynamoDB

AppTheory is the runtime layer of the Theory Cloud stack — used in production by Pay Theory.

Install

AppTheory is distributed exclusively through immutable GitHub Releases — no PyPI, no npm. The single distribution path keeps versions aligned across all three runtimes. Pin the release you are consuming and verify downloaded assets before installing them:

VERSION=1.14.0
TAG="v${VERSION}"
REPO="theory-cloud/AppTheory"

# Go resolves the immutable git tag.
go get "github.com/theory-cloud/apptheory@${TAG}"

# TypeScript and Python install from verified GitHub Release assets.
gh release download "${TAG}" --repo "${REPO}" \
  --pattern "theory-cloud-apptheory-${VERSION}.tgz" \
  --pattern "apptheory-${VERSION}-py3-none-any.whl" \
  --pattern "SHA256SUMS.txt" \
  --clobber
grep -E " (theory-cloud-apptheory-${VERSION}\.tgz|apptheory-${VERSION}-py3-none-any\.whl)$" SHA256SUMS.txt | sha256sum -c -
npm install "./theory-cloud-apptheory-${VERSION}.tgz"
python -m pip install "./apptheory-${VERSION}-py3-none-any.whl"

At a glance

Why AppTheory?

Use AppTheory when you want AWS-Lambda-backed services that are:

• Serverless-first — one unified HandleLambda entrypoint dispatches Lambda Function URL, API Gateway v2, ALB, AppSync, SQS, EventBridge, DynamoDB Streams, Kinesis, and WebSockets. The same handler shape covers every event source.
• Cross-language consistent — one routing model, one middleware order, one error envelope — across three runtimes — with drift prevention on the full shared corpus. Go, TypeScript, and Python execute all 223 contract fixtures, including MCP, OAuth, and objectstore.
• Generative-coding friendly — explicit tiers, canonical patterns, and strict verification so AI-generated code stays correct and maintainable.

✅ Treat routing, middleware, and event normalization as a contract ❌ Don't reinvent "the same" middleware chain independently per service/language

MCP server runtime

AppTheory includes a complete Model Context Protocol runtime surface: Streamable HTTP transport, session management, OAuth protected resources, resumable SSE streaming, and CDK deployment constructs. MCP is a first-class part of the contract, not an experimental add-on — Go, TypeScript, and Python execute the shared MCP fixtures alongside OAuth and objectstore fixtures.

• MCP integration guide — transport, JSON-RPC surface, registries, sessions, streaming
• Remote MCP deployment — OAuth, protected resource metadata, Autheory integration
• MCP examples — tools-only, tools-resources-prompts, resumable-sse
• CDK constructs: AppTheoryMcpServer, AppTheoryRemoteMcpServer, AppTheoryMcpProtectedResource

Documentation

The full documentation site lives at apptheory.theorycloud.ai. It is published from the staging integration branch; stable release authority remains the versioned packages, release notes, and API snapshots.

Most-used entry points:

Per-runtime entry points:

• Go — apptheory.theorycloud.ai/runtimes/go/
• TypeScript — apptheory.theorycloud.ai/runtimes/typescript/
• Python — apptheory.theorycloud.ai/runtimes/python/

Contract reference and feature pages:

• Contract Fixtures — the 223-fixture covenant across Go, TypeScript, and Python, including MCP, OAuth, and objectstore
• Event Shape Dispatch — which Lambda event shapes route to which handler
• HTTP Runtime — P0/P1/P2 tier surface
• Jobs Ledger
• Sanitization

Integrations — how AppTheory connects to the rest of the stack:

• MCP Method Surface
• Remote MCP
• Remote MCP + Autheory
• Bedrock AgentCore MCP

CDK — the blessed deployment surface:

• CDK Getting Started
• CDK API Reference
• SSR Site (FaceTheory-first)

Repository layout

Universal Lambda dispatcher (CDK)

The CDK multilang demo deploys one HTTP entry + three Lambda runtimes (Go, Node.js 24, Python 3.14) that route the same request through the same middleware chain and assert identical responses:

→ examples/cdk/multilang/

For infrastructure patterns, see the CDK integration guide.

Runtime tiers

AppTheory's middleware surface is tiered, not flag-based. Each tier is additive over the previous one.

Tiers are a contract, not a menu — see HTTP Runtime for the exact slot list and per-tier behavior.

Minimal app

package main

import (
    "context"
    "encoding/json"

    "github.com/aws/aws-lambda-go/lambda"
    apptheory "github.com/theory-cloud/apptheory/runtime"
)

func main() {
    app := apptheory.New()

    app.Get("/ping", func(ctx *apptheory.Context) (*apptheory.Response, error) {
        return apptheory.Text(200, "pong"), nil
    })

    // One entrypoint handles HTTP, AppSync, SQS, EventBridge,
    // DynamoDB Streams, Kinesis, and WebSockets.
    lambda.Start(func(ctx context.Context, event json.RawMessage) (any, error) {
        return app.HandleLambda(ctx, event)
    })
}

import { createApp, text } from "@theory-cloud/apptheory";

const app = createApp();
app.get("/ping", () => text(200, "pong"));

export const handler = async (event: unknown, ctx: unknown) =>
  app.handleLambda(event, ctx);

from apptheory import create_app, text

app = create_app()

@app.get("/ping")
def ping(ctx):
    return text(200, "pong")

def handler(event, ctx):
    return app.handle_lambda(event, ctx)

The same contract fixtures verify all three.

Development & verification

make rubric        # full repo verification (the all-gates gate)
make test          # full test suite incl. contract fixtures

For multi-language work:

cd ts && npm run lint && npm run typecheck && npm test
uv --directory py run pytest -q

See CONTRIBUTING.md for full contributor docs, including the Authoring documentation section if you're updating the docs site.

Security & production notes

• CSRF protection and secure cookie flags are application concerns; set Secure/HttpOnly/SameSite explicitly in Set-Cookie.
• Request IDs can be supplied via x-request-id; validate/override if your threat model requires it.
• Retries/backoff for event sources are handled by AWS trigger settings (retry policies, DLQs/redrive), not by the runtime.
• Distribution is GitHub Releases only — there is no npm publish, no PyPI publish, and no raw-SDK escape hatch.

Theory Cloud

AppTheory is the runtime layer of the Theory Cloud stack. It depends on TableTheory for data access, and is depended on by FaceTheory for client delivery.

• TableTheory (data layer) → AppTheory builds on it
• FaceTheory (client delivery) → depends on AppTheory
• KnowledgeTheory (platform state + knowledge graph) → depends on AppTheory
• Autheory (identity) → depends on AppTheory
• theory-mcp-server → runs on AppTheory

The single-path philosophy applies here: one way to register a route, one way to order middleware, one way to dispatch a Lambda event — enforced by the framework, not by convention. When generative coding tools produce AppTheory code, the constrained API surface means the output converges on correct implementations instead of drifting across equivalent-but-incompatible patterns.

License & contributing

• LICENSE — Apache-2.0
• CONTRIBUTING.md
• CHANGELOG.md
• UPGRADING.md
• THEORY_CLOUD.md

_{Made with Theory Cloud · docs}