New to TableTheory? Start with the Go getting-started guide. TypeScript and Python runtime-specific package docs are staged alongside this surface as sibling package entrypoints in the shared TheoryCloud TableTheory subtree.
| Go Guides | Getting Started | API Reference | Core Patterns | Testing | Troubleshooting |
| Schema | Struct Definition Guide | DMS v0.1 remains a repo-local planning document and is not published to TheoryCloud |
| Release State | Release-State Safety Patterns |
| FaceTheory | ISR Cache Schema | ISR Transaction Recipes | TTL Cache Patterns | ISR Idempotency |
| CDK | CDK Integration |
| Migration | Migration Guide |
This directory contains the OFFICIAL documentation for TableTheory. All content follows AI-friendly patterns so both humans and AI assistants can learn, reason, and troubleshoot effectively.
- Go (this folder): Getting Started, Core Patterns, API Reference
- TypeScript: package docs are authored under
ts/docs/and published as a runtime-specific package surface alongside the canonical Go docs. - Python: package docs are authored under
py/docs/and published as a runtime-specific package surface alongside the canonical Go docs.
- Getting Started Guide (Go) – Installation, configuration, and first deployment (Go SDK)
- API Reference (Go) – Go SDK public API (DB, Query, Transactions)
- Core Patterns (Go) – Go SDK canonical usage patterns (Lambda, Batch, Streams)
- Release-State Safety Patterns – Immutable event history, protected registry fields, transactional transitions, outbox/reconciliation, and deterministic provenance/confidence
- FaceTheory ISR Cache Schema – Recommended cache metadata + regeneration lease item shapes
- FaceTheory ISR Transaction Recipes – Correctness-first patterns for publishing metadata under lease
- FaceTheory TTL Cache Patterns – Freshness vs expiry, TTL lag, and operational guidance for ISR tables
- FaceTheory ISR Idempotency Patterns – Request-id driven regeneration guidance and replay safety
- Testing Guide – Repo-wide testing strategy (Go + TS + Python)
- Troubleshooting (Go) – Go SDK troubleshooting (TypeScript/Python have their own)
- Struct Definition Guide (Go) – Canonical guide for defining DynamoDB models in Go
- Concepts – Machine-readable concept hierarchy
- Patterns – Correct vs. incorrect usage patterns
- Decisions – Decision trees for architectural choices
- LLM FAQ – Frequently asked questions for AI assistants
- CDK Integration Guide – How to define tables in CDK for TableTheory models
- Planning, decision, and clarification templates live under
docs/development/**andhgm-infra/planning/**. - These maintainer artifacts are intentionally excluded from the TheoryCloud user-facing TableTheory subtree.
- Go developers building serverless applications on AWS
- TypeScript developers building Node.js services and AWS Lambda functions
- Python developers building services and AWS Lambda functions
- DevOps engineers configuring DynamoDB infrastructure
- AI assistants answering questions about TableTheory usage and best practices
- Start here: begin with the Go getting-started guide. TypeScript and Python package guides are staged alongside this surface as runtime-specific package entrypoints.
- Use Core Patterns for copy-pasteable recipes in Go.
- Use API Reference when you need detailed signature information for Go public methods.
- Use Troubleshooting when encountering errors like
ValidationExceptionorResourceNotFoundException.
- Examples First – Every concept starts with a runnable code snippet.
- Explicit Context – We clearly label
✅ CORRECTand❌ INCORRECTpatterns. - Lambda Optimization – We prioritize serverless performance patterns (cold start reduction).
- Type Safety – We emphasize Go's type system to prevent runtime errors.
- Machine Parsable – We include YAML metadata for AI tooling.
- Maintainer authoring standards live in repo-local
docs/PAY_THEORY_DOCUMENTATION_GUIDE.mdand are intentionally excluded from the TheoryCloud user-facing surface. - Validate examples against live code
- Include CORRECT/INCORRECT blocks for integration snippets
- Update troubleshooting alongside code changes