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 that pass the same contract fixtures on every commit.

            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.

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 — without behavioral drift. Verified on every commit by the 128 contract fixtures.
• 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 production stack: Streamable HTTP transport, session management, OAuth protected resources, resumable SSE streaming, and CDK deployment constructs. The MCP runtime is a first-class part of the contract, not an experimental add-on — theory-mcp-server itself runs on it.

• 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 theory-cloud.github.io/apptheory — branded with the Theory Cloud design system, with a ⌘K search palette, runtime tabs, and surface-tinted pages.

Most-used entry points:

Per-runtime entry points:

• Go — theory-cloud.github.io/apptheory/runtimes/go/
• TypeScript — theory-cloud.github.io/apptheory/runtimes/typescript/
• Python — theory-cloud.github.io/apptheory/runtimes/python/

Contract reference and feature pages:

• Contract Fixtures — the 128-fixture covenant every runtime is tested against
• 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
• THEORY_CLOUD.md

_{Made with Theory Cloud · docs}