https://github.com/theory-cloud/tabletheory
DynamoDB-first multi-language data contract.
https://github.com/theory-cloud/tabletheory
aws aws-dynamodb golang python typescript
Last synced: about 13 hours ago
JSON representation
DynamoDB-first multi-language data contract.
- Host: GitHub
- URL: https://github.com/theory-cloud/tabletheory
- Owner: theory-cloud
- License: apache-2.0
- Created: 2026-01-18T13:36:04.000Z (6 months ago)
- Default Branch: staging
- Last Pushed: 2026-07-03T00:59:11.000Z (4 days ago)
- Last Synced: 2026-07-03T01:10:33.703Z (4 days ago)
- Topics: aws, aws-dynamodb, golang, python, typescript
- Language: Go
- Homepage: https://tabletheory.theorycloud.ai/
- Size: 2.93 MB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
README
TableTheory
DynamoDB-first multi-language data contract.
One specification. Three runtimes. Verified on every commit.
Get started → ·
API reference ·
Contract scenarios ·
DMS spec
---
TableTheory is a **DynamoDB-first ORM and schema contract** designed to keep data access 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 P0 contract scenarios on every commit.
```
FaceTheory (client delivery)
│
AppTheory (serverless runtime)
│
TableTheory (data layer) ← you are here
│
DynamoDB
```
TableTheory is the foundation of the [Theory Cloud](https://github.com/theory-cloud/AppTheory/blob/main/THEORY_CLOUD.md) stack — used in production by [Pay Theory](https://paytheory.com).
## Install
TableTheory is distributed exclusively through immutable **[GitHub Releases](https://github.com/theory-cloud/tabletheory/releases)** — no PyPI, no npm. The single distribution path keeps versions aligned across all three runtimes.
| Runtime | Install |
|---|---|
| **Go** | `go get github.com/theory-cloud/tabletheory@vX.Y.Z` |
| **TypeScript** | install the `npm pack` release asset — see [TypeScript getting started](https://tabletheory.theorycloud.ai/runtimes/typescript/) |
| **Python** | install the wheel/sdist release asset — see [Python getting started](https://tabletheory.theorycloud.ai/runtimes/python/) |
## At a glance
| | |
|---|---|
| **P0 contract scenarios** | 9 — CRUD, omit-empty, lifecycle, locking, TTL, and release-state fixtures |
| **Runtimes** | Go · TypeScript · Python (peers, not ports) |
| **Distribution** | Immutable GitHub Releases — version-aligned across all runtimes |
| **License** | Apache-2.0 — open source, production use |
| **Status** | Post-1.0 stable API across all three runtimes |
## Why TableTheory?
Use TableTheory when you want DynamoDB-backed systems that are:
- **Serverless-first** — patterns that work well in AWS Lambda: cold-start aware `LambdaInit`, batching with Lambda timeout awareness, transactions, streams, optional KMS-backed field encryption that's [fail-closed](https://tabletheory.theorycloud.ai/features/encryption/) by design.
- **Cross-language consistent** — one table, multiple services, multiple runtimes — without schema or behavior drift. Verified on every commit by the [P0 contract scenarios](https://tabletheory.theorycloud.ai/reference/contract-scenarios/).
- **Generative-coding friendly** — explicit schema, canonical patterns, strict verification, and downloadable [LLM artifacts](https://tabletheory.theorycloud.ai/ai/) (`llms.txt`, vocabulary JSON, rules template, prompt recipes) so AI-generated code stays correct and maintainable.
✅ Treat schema + semantics as a contract
❌ Don't redefine "the same" table shape independently per service/language
## Documentation
The full documentation site lives at **[tabletheory.theorycloud.ai](https://tabletheory.theorycloud.ai/)** — branded with the Theory Cloud design system, with a ⌘K search palette, runtime tabs, and surface-tinted pages.
**Most-used entry points:**
| Section | Link |
|---|---|
| Getting started | [tabletheory.theorycloud.ai/getting-started/](https://tabletheory.theorycloud.ai/getting-started/) |
| API reference | [tabletheory.theorycloud.ai/api-reference/](https://tabletheory.theorycloud.ai/api-reference/) |
| Struct definition guide | [tabletheory.theorycloud.ai/struct-definition-guide/](https://tabletheory.theorycloud.ai/struct-definition-guide/) |
| Core patterns | [tabletheory.theorycloud.ai/core-patterns/](https://tabletheory.theorycloud.ai/core-patterns/) |
| Architecture patterns | [tabletheory.theorycloud.ai/architecture-patterns/](https://tabletheory.theorycloud.ai/architecture-patterns/) |
| Testing | [tabletheory.theorycloud.ai/testing-guide/](https://tabletheory.theorycloud.ai/testing-guide/) |
| Troubleshooting | [tabletheory.theorycloud.ai/troubleshooting/](https://tabletheory.theorycloud.ai/troubleshooting/) |
| Generative coding artifacts | [tabletheory.theorycloud.ai/ai/](https://tabletheory.theorycloud.ai/ai/) |
**Per-runtime entry points:**
- **Go** — [tabletheory.theorycloud.ai/runtimes/go/](https://tabletheory.theorycloud.ai/runtimes/go/)
- **TypeScript** — [tabletheory.theorycloud.ai/runtimes/typescript/](https://tabletheory.theorycloud.ai/runtimes/typescript/)
- **Python** — [tabletheory.theorycloud.ai/runtimes/python/](https://tabletheory.theorycloud.ai/runtimes/python/)
**P0 contract reference and related feature pages:**
- [Contract Scenarios](https://tabletheory.theorycloud.ai/reference/contract-scenarios/) — the current 9-fixture P0 surface
- [CRUD & Marshaling](https://tabletheory.theorycloud.ai/features/crud/)
- [Optimistic Locking](https://tabletheory.theorycloud.ai/features/optimistic-locking/)
- [Lifecycle Timestamps](https://tabletheory.theorycloud.ai/features/lifecycle-timestamps/)
- [TTL](https://tabletheory.theorycloud.ai/features/ttl/)
- [Encryption (fail-closed)](https://tabletheory.theorycloud.ai/features/encryption/)
- [Transactions](https://tabletheory.theorycloud.ai/features/transactions/)
**Integrations** — how downstream Theory Cloud frameworks use TableTheory:
- [MCP Memory](https://tabletheory.theorycloud.ai/integrations/mcp-memory/)
- [AppTheory](https://tabletheory.theorycloud.ai/integrations/apptheory/)
- [KnowledgeTheory](https://tabletheory.theorycloud.ai/integrations/knowledgetheory/)
- [Autheory](https://tabletheory.theorycloud.ai/integrations/autheory/)
## Repository layout
| Path | What |
|---|---|
| `docs/` | Public documentation site (Jekyll) — also the canonical doc tree |
| `ts/` | TypeScript SDK — [TS docs index](ts/docs/README.md) |
| `py/` | Python SDK — [Py docs index](py/docs/README.md) |
| `contract-tests/` | Cross-language P0 fixtures + runners |
| `examples/cdk-multilang/` | Deployable demo: one DynamoDB table, three Lambdas (Go, Node.js 24, Python 3.14) |
| `.github/workflows/` | CI: rubric, language gates, release-please, Pages publish |
## Serverless data demo (CDK)
The CDK demo deploys one DynamoDB table + three Lambda Function URLs (Go, Node.js 24, Python 3.14) that read/write the same item shape and exercise portability-sensitive features (encryption, batching, transactions):
→ [`examples/cdk-multilang/README.md`](examples/cdk-multilang/README.md)
For infrastructure patterns, see the [CDK integration guide](https://tabletheory.theorycloud.ai/cdk/).
## DMS — the language-neutral schema
TableTheory's drift-prevention story centers on a shared, language-neutral schema document: **TableTheory Spec (DMS)**.
```yaml
dms_version: "0.1"
models:
- name: "Note"
table: { name: "notes_contract" }
keys:
partition: { attribute: "PK", type: "S" }
sort: { attribute: "SK", type: "S" }
attributes:
- { attribute: "PK", type: "S", required: true, roles: ["pk"] }
- { attribute: "SK", type: "S", required: true, roles: ["sk"] }
- { attribute: "value", type: "N" }
```
DMS is **authored independently** of any runtime — Go, TypeScript, and Python all validate against the same spec. See the [DMS Specification v0.1](https://tabletheory.theorycloud.ai/reference/dms-spec/) for the public summary.
## Development & verification
```bash
make rubric # full repo verification (the all-gates gate)
make docker-up # start DynamoDB Local
make test # full suite incl. integration
```
For multi-language work:
```bash
cd ts && npm run lint && npm run typecheck && npm run test:unit
uv --directory py run pytest -q tests/unit
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for full contributor docs, including the [Authoring documentation](CONTRIBUTING.md#authoring-documentation) section if you're updating the docs site.
## Theory Cloud
TableTheory is the data foundation of the Theory Cloud stack. **Nothing in Theory Cloud precedes it.**
- [AppTheory](https://github.com/theory-cloud/AppTheory) (serverless runtime) → depends on TableTheory
- [FaceTheory](https://github.com/theory-cloud/FaceTheory) (client delivery) → depends on TableTheory
- KnowledgeTheory (platform state + knowledge graph) → depends on TableTheory
- Autheory (identity) → depends on TableTheory
- theory-mcp-server → depends on TableTheory
The single-path philosophy starts here: one way to define a table, one way to access data, one way to handle encryption — enforced by the framework, not by convention. When generative coding tools produce TableTheory code, the constrained API surface means the output converges on correct implementations instead of drifting across equivalent-but-incompatible patterns.
## License & contributing
- [LICENSE](LICENSE) — Apache-2.0
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- [CHANGELOG.md](CHANGELOG.md)
Made with Theory Cloud · docs