{"id":40305218,"url":"https://github.com/theory-cloud/apptheory","last_synced_at":"2026-05-27T14:01:14.286Z","repository":{"id":333537521,"uuid":"1137604136","full_name":"theory-cloud/AppTheory","owner":"theory-cloud","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-23T02:26:16.000Z","size":89864,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"staging","last_synced_at":"2026-05-23T03:32:41.922Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theory-cloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-19T15:32:42.000Z","updated_at":"2026-05-23T02:26:23.000Z","dependencies_parsed_at":"2026-05-16T00:03:27.923Z","dependency_job_id":null,"html_url":"https://github.com/theory-cloud/AppTheory","commit_stats":null,"previous_names":["theory-cloud/apptheory"],"tags_count":114,"template":false,"template_full_name":null,"purl":"pkg:github/theory-cloud/AppTheory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FAppTheory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FAppTheory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FAppTheory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FAppTheory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theory-cloud","download_url":"https://codeload.github.com/theory-cloud/AppTheory/tar.gz/refs/heads/staging","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FAppTheory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33568859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-20T06:00:43.924Z","updated_at":"2026-05-27T14:01:14.279Z","avatar_url":"https://github.com/theory-cloud.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AppTheory — Serverless Application Framework for AWS (Go, TypeScript, Python)\n\nAppTheory is a contract-first serverless runtime for AWS Lambda. It provides a single application model across Go,\nTypeScript, and Python — with behavioral parity enforced by 89 shared contract test fixtures, not convention.\n\nAI code generation and multi-team environments produce drift: the same endpoint implemented in two languages behaves\ndifferently in subtle ways. AppTheory eliminates this by constraining each language runtime to one correct path for\nrouting, middleware, error handling, and event normalization. The result is deterministic framework behavior that\ngenerative coding tools can rely on.\n\nAppTheory is part of the [Theory Cloud](THEORY_CLOUD.md) stack. [TableTheory](https://github.com/theory-cloud/TableTheory)\nprovides the data layer; AppTheory provides the runtime and CDK deployment constructs;\n[FaceTheory](https://github.com/theory-cloud/FaceTheory) provides client application delivery.\n\n## MCP Server Runtime\n\nAppTheory includes a complete [Model Context Protocol](https://modelcontextprotocol.io) production stack: Streamable\nHTTP transport, session management, OAuth protected resources, SSE streaming, and CDK deployment constructs.\n\n- [MCP integration guide](docs/integrations/mcp.md) — transport, JSON-RPC surface, registries, sessions, streaming\n- [Remote MCP deployment](docs/integrations/remote-mcp.md) — OAuth, protected resource metadata, Autheory integration\n- [MCP examples](examples/mcp/) — tools-only, tools-resources-prompts, resumable-sse\n- CDK constructs: `AppTheoryMcpServer`, `AppTheoryRemoteMcpServer`, `AppTheoryMcpProtectedResource`\n\n## Status\n\nAppTheory is pre-1.0 and under active development. The runtime contract is stable across Go, TypeScript, and Python,\nverified by 89 contract test fixtures on every commit. Production systems at [Pay Theory](https://paytheory.com) run on\nAppTheory today. See [CHANGELOG](CHANGELOG.md) for release history.\n\n## Getting Started\n\n- [Getting started guide](docs/getting-started.md) — local workspace, deterministic app path in each runtime, deployment\n- [API reference](docs/api-reference.md) — full Go runtime surface\n- [Logging profiles](docs/features/logging-profiles.md) — fixture-backed structured JSON log profiles and migration guidance\n- [Release process](docs/release-process.md) — single release train, forbidden recovery actions, safe recovery path\n- [FaceTheory-first SSR CDK guide](docs/cdk/ssr-site.md) — canonical CloudFront + S3 + Lambda URL deployment story\n- [TypeScript docs](ts/docs/README.md) | [Python docs](py/docs/README.md) | [CDK docs](cdk/docs/README.md)\n\n## Charter\n\nAppTheory exists to provide a **portable runtime core** (and contract tests) for AWS serverless applications that must be\nfirst-class in **Go, TypeScript, and Python**.\n\nTarget audiences and use cases:\n\n- Platform and application teams building HTTP APIs on AWS Lambda (Lambda Function URL, API Gateway v2).\n- Event-driven workloads (SQS, EventBridge, DynamoDB Streams) and WebSockets are required for Lift parity and are tracked\n  as remaining contract work (see `docs/development/planning/apptheory/apptheory-gap-analysis-lesser.md`).\n- Internal tooling and shared libraries that need consistent request/response semantics across languages.\n\nNon-goals (near-term):\n\n- Not a general-purpose web framework; contract-first serverless runtime only.\n- Not registry-published packages (no npm or PyPI); releases ship via GitHub assets.\n\n## Package Names\n\n- Go module path: `github.com/theory-cloud/apptheory`\n- Go runtime package: `github.com/theory-cloud/apptheory/runtime`\n- npm package: `@theory-cloud/apptheory`\n- Python distribution name: `apptheory`\n- Python import name: `apptheory`\n\n## Supported Runtimes\n\n- Go toolchain: `1.26.3`\n- Node.js: `24`\n- Python: `3.14`\n\nDistribution: **GitHub Releases only** (no npm/PyPI publishing).\n\n## Runtime Tiers (P0/P1/P2)\n\n- **P0:** routing + request/response normalization + error envelope\n- **P1:** request-id, tenant extraction, auth hooks, CORS, size/time guardrails, middleware ordering\n- **P2 (default):** P1 + observability hooks + rate limiting / load shedding policy hooks\n\n## Architecture\n\n```\n                          AWS Event Sources\n                 ┌──────────┬──────────┬──────────┐\n                 │ Lambda   │ API GW   │ AppSync  │\n                 │ Func URL │ v2/Proxy │ Resolver │\n                 └────┬─────┴────┬─────┴────┬─────┘\n                      │          │          │\n                      ▼          ▼          ▼\n              ┌─────────────────────────────────────┐\n              │         HandleLambda (unified)       │\n              │    event detection + normalization   │\n              └──────────────┬──────────────────────┘\n                             │\n                             ▼\n              ┌────────────────────────���────────────┐\n              │          AppTheory Router            │\n              │   path matching + method dispatch    │\n              └─────────────���┬──────────────────────┘\n                             │\n                             ▼\n              ┌─────────────────────��───────────────┐\n              │        Middleware Chain (P0→P2)      │\n              │  request-id, auth, CORS, guardrails  │\n              │  observability, rate limiting         │\n              └──────────────┬──────────────────────┘\n                             │\n                  ┌──────────┴──────────┐\n                  ▼                     ▼\n        ┌──────────────────┐  ┌──────────────────┐\n        │  HTTP Handler    │  │  MCP Server       │\n        │  (your code)     │  │  (Streamable HTTP)│\n        └──────────────────┘  └──────────────────┘\n                  │                     │\n                  ▼                     ▼\n              ┌─────────────────────────────────────┐\n              │          Response Pipeline           │\n              │    error envelope + serialization    │\n              └─────────────────────────────────────┘\n\n   ┌─────────────────────────────────────────────────────┐\n   │              Contract Test Fixtures (89)             │\n   │   Same fixtures run against Go, TS, and Python      │\n   │   runtimes to verify behavioral parity              │\n   └─────────────────────────────────────────────────────┘\n\n   ┌────────────────────────────────────────────���────────┐\n   │              CDK Constructs                          │\n   │   AppTheoryHttpApi, AppTheoryMcpServer,             │\n   │   AppTheoryRemoteMcpServer, AppTheoryQueue,         │\n   │   AppTheoryS3Ingest, AppTheoryJobsTable, ...        │\n   └────────────────────────────────────────────���────────┘\n```\n\n## Security \u0026 Production Notes\n\n- CSRF protection and secure cookie flags are application concerns; set `Secure`/`HttpOnly`/`SameSite` explicitly in `Set-Cookie`.\n- Request IDs can be supplied via `x-request-id`; validate/override if your threat model requires it.\n- Retries/backoff for event sources are handled by AWS trigger settings (retry policies, DLQs/redrive), not by the runtime.\n\n## Go Runtime (P2 default)\n\nThe Go runtime implements the fixture-backed contract across P0/P1/P2 tiers (default: P2).\n\nNotes:\n\n- Header names are case-insensitive, but `Request.Headers` / `Response.Headers` keys are canonicalized to lowercase.\n- If two routes are equally specific, the router prefers earlier registration order.\n\nMinimal local invocation:\n\n```go\nenv := testkit.New()\napp := env.App()\n\napp.Get(\"/ping\", func(ctx *apptheory.Context) (*apptheory.Response, error) {\n\treturn apptheory.Text(200, \"pong\"), nil\n})\n\nresp := env.Invoke(context.Background(), app, apptheory.Request{Method: \"GET\", Path: \"/ping\"})\n_ = resp\n```\n\nTo force the P0 core (minimal surface area), pass `apptheory.WithTier(apptheory.TierP0)` when creating the app.\n\nUnit test without AWS (deterministic time + IDs + HTTP event builder):\n\n```go\nfunc TestHello(t *testing.T) {\n\tenv := testkit.NewWithTime(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC))\n\tenv.IDs.Queue(\"req-1\")\n\n\tapp := env.App()\n\tapp.Get(\"/hello\", func(ctx *apptheory.Context) (*apptheory.Response, error) {\n\t\treturn apptheory.MustJSON(200, map[string]any{\n\t\t\t\"now_unix\": ctx.Now().Unix(),\n\t\t\t\"id\":       ctx.NewID(),\n\t\t}), nil\n\t})\n\n\tevent := testkit.APIGatewayV2Request(\"GET\", \"/hello\", testkit.HTTPEventOptions{\n\t\tHeaders: map[string]string{\"x-request-id\": \"request-1\"},\n\t})\n\tresp := env.InvokeAPIGatewayV2(context.Background(), app, event)\n\n\tif resp.StatusCode != 200 {\n\t\tt.Fatalf(\"expected status 200, got %d\", resp.StatusCode)\n\t}\n\tif resp.Headers[\"x-request-id\"] != \"request-1\" {\n\t\tt.Fatalf(\"expected x-request-id request-1, got %#v\", resp.Headers[\"x-request-id\"])\n\t}\n\n\tvar body map[string]any\n\tif err := json.Unmarshal([]byte(resp.Body), \u0026body); err != nil {\n\t\tt.Fatalf(\"parse response json: %v\", err)\n\t}\n\tif body[\"id\"] != \"req-1\" {\n\t\tt.Fatalf(\"expected id req-1, got %#v\", body[\"id\"])\n\t}\n}\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for how to report issues, run tests, and submit pull requests.\n\n## Links\n\n- Planning index: `docs/development/planning/apptheory/README.md`\n- Main roadmap: `docs/development/planning/apptheory/apptheory-multilang-roadmap.md`\n- Import pipeline reference example (CDK + handlers): `examples/cdk/import-pipeline/`\n- Migration from Lift (draft): `docs/migration/from-lift.md`\n- [Theory Cloud overview](THEORY_CLOUD.md)\n\n## License\n\nApache 2.0 (see [LICENSE](LICENSE))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheory-cloud%2Fapptheory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheory-cloud%2Fapptheory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheory-cloud%2Fapptheory/lists"}