00 · Gravity Standard Architecture
Define the data. Define the process. The Standard supplies the rest.
A reference architecture and foundation for business applications that AI builds from specifications. Serverless on AWS, Go on Lambda, Postgres underneath. Secure by default and opinionated on purpose.
The problem
The same application, rebuilt slightly differently, again and again.
Intake, review, approve, fulfil, report. Business applications of this kind are built repeatedly, and each build re-creates the same architecture with small differences.
- Duplicated effort on identity, access control, workflow, notifications and audit.
- Uneven quality: security and operations differ from one application to the next.
- Slow change, because a business-rule tweak becomes a code release.
- Invisible processes that live only in code and in people's heads, so nobody can say what actually happens.
The Gravity Standard makes two things formal and first-class: Data Domains and Business Processes. Forms, navigation, task lists, permissions, notifications and dashboards follow from them.
Three manuals
An operator's manual first, like a device from the 1980s.
A business stakeholder writes the manual for the application they want. An AI builds the software against it, and tests prove the software does what the manual says. Unlike old manuals, this one comes first and stays binding.
Purpose, data, procedures, decisions, rules, timeouts and troubleshooting, in the operator's terms.
Written by business stakeholders, with AI help.
The architecture, a runbook for every alarm, and the permit process.
Written by engineers.
The library, tooling, infrastructure modules and foundation applications.
Written by the foundation team.
Guiding principles
When a situation isn't covered, reason from these.
| Principle | In practice |
|---|---|
| Simplicity over cleverness | Boring, small, well-understood technology. Every dependency is a liability. |
| Secure by default | The default outcome of a bug is "no data", not "all data". |
| The database is the foundation | The schema is the contract. Code is generated from it, not the reverse. |
| Events over polling | State changes push to interested parties. Nobody asks "are we there yet?" |
| Managed over self-run | AWS-managed services, so teams operate business logic, not infrastructure. |
| Maintainable by a stranger | A new developer, or an AI, understands it with little ramp-up. |
| Push governance left | Compliance lives in permits and policy, not in approval emails. |
| Say it, do it, prove it | State what you will do, do it, then demonstrate that you did. See Permits. |
Technology
One answer per concern.
The choices are deliberately few, so teams and AI assistants make the same decision every time.
| Concern | Choice |
|---|---|
| Back-end language | Go, compiled to native arm64 |
| Compute | AWS Lambda (provided.al2023, arm64) |
| Relational data | Postgres: RDS by default, Aurora when scale demands. DynamoDB where access patterns are known. |
| Data access | sqlc-generated, type-safe queries |
| Workflow | AWS Step Functions |
| Push | API Gateway WebSocket, with database triggers through aws_lambda |
| Front end | HTML, htmx, vanilla JS and CSS on S3 and CloudFront; server-side rendering for sensitive screens |
| Edge | AWS WAF on every public entry point; GuardDuty scanning for uploads |
| Authentication | SSO preferred; passkeys at minimum; no stored passwords |
| Authorization | Amazon Verified Permissions (Cedar), backed by Postgres row level security |
| Encryption | AWS KMS, with envelope encryption for personal data |
| Infrastructure | Terraform |
Non-negotiables
The rules most often broken, with the worst consequences.
These are the flight rules. Newcomers and AI assistants break them most. Where a rule can be checked mechanically, the pipeline checks it.
- The UI shapes; the server enforces. Hiding a button is usability, never security. Every handler authorizes, and RLS backs it up.
- No secrets in environment variables, source control, front-end code or local storage.
- A database trigger is a hint, not a guarantee. Anything vital uses an outbox with positive confirmation.
- Never swallow an error. A failed handler returns failure so retries and dead-letter queues engage.
- Every dead-letter queue has an alarm and a runbook.
- Every
UPDATEandDELETEhas aWHEREclause, and write handlers assert how many rows they changed. - No Lambda-to-Lambda
Invoke. Services call each other over HTTPS. - A Lambda isn't publishable without readable logs, interior timings, defined metrics and an alarm.
- HTTPS and WSS only, with a WAF in front of every public entry point.
- Uploads are hostile until scanned.
- Build once and promote the same artifact, one environment at a time.
- Every alarm links to a runbook.
Chapters
Read in order, or jump to what you need.
Reference company
Tidewater, a fictional lender.
Every example in the Standard uses one company: a small-business lender that services loans for about 40 partner community banks, which are its tenants. It's deliberately contrived, in the way Contoso is, with awkward test scenarios built in.
| Application | Shape |
|---|---|
| Lending | Form-driven, with human tasks and nested sub-processes |
| Payments | File-driven, with waiting, timers and reconciliation |
| Support Desk | The simplest human-task process, built from specifications alone |