{"id":51340789,"url":"https://github.com/standardapplied/monolith","last_synced_at":"2026-07-02T07:05:14.215Z","repository":{"id":361697863,"uuid":"1255440835","full_name":"standardapplied/monolith","owner":"standardapplied","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-08T00:24:01.000Z","size":765,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T05:36:56.888Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/standardapplied.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":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T20:40:41.000Z","updated_at":"2026-06-08T00:24:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/standardapplied/monolith","commit_stats":null,"previous_names":["singlr-ai/monolith","standardapplied/monolith"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/standardapplied/monolith","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/standardapplied%2Fmonolith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/standardapplied%2Fmonolith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/standardapplied%2Fmonolith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/standardapplied%2Fmonolith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/standardapplied","download_url":"https://codeload.github.com/standardapplied/monolith/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/standardapplied%2Fmonolith/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35036611,"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-07-02T02:00:06.368Z","response_time":173,"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-07-02T07:05:13.335Z","updated_at":"2026-07-02T07:05:14.193Z","avatar_url":"https://github.com/standardapplied.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Monolith\n\n*Live, typed queries on real Postgres.*\n\nMonolith is a set of small Java libraries for building applications on PostgreSQL where the schema,\nthe typed data access, the client reader, and the live (reactive) queries all come from a single\ndeclaration. You write a record, sometimes carrying its SQL, and an annotation processor generates\nthe rest at compile time. It runs on ordinary relational tables: you keep SQL, JOINs, transactions,\nand foreign keys.\n\nIt started from one question: can a Java team get the \"subscribe, and the UI updates when the data\nchanges\" experience of Firebase or InstantDB *without* giving up a real relational database? This is\n**v0.x: experimental, and the API will change.**\n\n```java\n// One declaration → Postgres DDL, a binary reader/builder, and a TypeScript reader for the same layout.\n// @Encrypted fields use envelope encryption (a per-value AES-256-GCM data key); Postgres stores only ciphertext.\n@PgType\npublic record Patient(UUID id, String name, @Encrypted String ssn) {}\n\n// A @PgQuery record carries its SQL. The processor also generates a reader, a typed run(), and the\n// reactive invalidation rule for this query.\n@PgQuery(\"\"\"\n    SELECT o.id, c.name AS customer, o.status,\n           coalesce(sum(li.qty * li.unit_price), 0) AS total\n      FROM orders o\n      JOIN customers c        ON c.id = o.customer_id\n      LEFT JOIN line_items li ON li.order_id = o.id\n     WHERE c.region = $1\n     GROUP BY o.id, c.name, o.status\"\"\")\npublic record OrderSummary(UUID id, String customer, String status, BigDecimal total) {}\n```\n\n```java\n// Reactive: wake when a row that affects the result changes, even a line item two joins away.\nvar hub  = new ReactiveHub(pool, List.of(new OrderSummaryInvalidation()));  // rule is generated\nvar feed = new Invalidator(\"host=localhost dbname=app\", hub, \"app_feed\");   // tails the WAL\nhub.subscribe(\"OrderSummary\", \"EU\", () -\u003e pushFreshResultToClients());\n```\n\n## What it does\n\n- **One declaration, generated outputs**: DDL, a binary reader/builder over the Postgres wire layout, a\n  TypeScript reader, and a reactive invalidation rule, at compile time, no runtime reflection.\n- **Live queries over joined tables**: precise re-execution, not incremental view maintenance; the\n  generated rule maps a change back to the affected subscribers, walking joins where needed.\n- **libpq, not JDBC**: the binary protocol via the Java FFM API; TLS and SCRAM are libpq's.\n- **Transactions with automatic retry**, **schema migrations**, **binary parameters** (arrays, enums,\n  prepared statements), and a **durable transactional queue** (outbox + jobs in one primitive).\n- **Compliance _primitives_ in the database**: `@Encrypted` envelope encryption, `@Tenant` and\n  `@AccessControlled` forced row-level security (a unified RBAC/ACL/consent grant model), `@Audited`\n  trails. These are building blocks, not a turnkey HIPAA/SOC 2 posture — key custody defaults to an\n  in-process key, and read-access audit and PHI-safe observability are not yet shipped. See\n  [`SECURITY.md`](SECURITY.md) and the [roadmap](ROADMAP.md) for exactly what is and isn't covered.\n- **Scale-out routing**: read replicas and tenant sharding over a common `ConnectionSource`.\n- **A library, not a platform**: pure-JDK core, no web framework; bring your own `main` and routes.\n\n## Documentation\n\nFull guides, concepts, and design notes: **\u003chttps://singlr-ai.github.io/monolith\u003e**. The docs site also\npublishes an [`llms.txt`](https://singlr-ai.github.io/monolith/llms.txt) and `llms-full.txt` so coding\nagents can ingest the documentation as context. A complete, runnable example app (a live, multi-client\ntask board) is in [`examples/collab`](examples/collab).\n\n## Modules\n\n| Module | What it is |\n|---|---|\n| `monolith-api` | Declaration annotations: `@PgType`, `@PgQuery`, `@PgProjection`, `@PgNull`, `@Encrypted`, `@Tenant`, `@Audited`, `@AccessControlled`, `Json`. |\n| `monolith-codegen` | The `javac` annotation processor. Generates DDL, readers/builders, TypeScript readers, and invalidation rules. |\n| `monolith-runtime` | libpq via Panama FFM, a connection pool, the binary tuple bridge and codecs, transactions, field encryption, and the WAL change-feed primitives. Pure JDK. |\n| `monolith-reactive` | Live queries: `ReactiveHub` plus the WAL-tailing `Invalidator`. No web dependency. |\n| `monolith-queue` | A durable, transactional, at-least-once message queue (outbox + jobs) over the same Postgres. Pure JDK. |\n| `monolith-helidon` | Optional adapter: a Helidon SE `WsListener` that serves live queries over WebSockets. |\n\nEvery module except `monolith-helidon` has no web dependency, and nothing in the core depends on it.\n\n## Status \u0026 requirements\n\n**v0.x: experimental; APIs will change.** Requires **JDK 25+** (Panama FFM, virtual threads) and\n**PostgreSQL 14+** (`wal_level = logical` for the reactive layer). **macOS and Linux** (libpq is loaded\nvia FFM); Windows via WSL2. The Maven build enforces the JDK floor (`maven-enforcer-plugin`), so an older\nJDK fails fast with a clear message instead of cryptic compiler errors.\n\n**Reproducing CI locally.** Many integration tests self-skip when no database is reachable, so a bare\n`mvn verify` can pass while exercising none of the FFM/WAL/queue/compliance paths. Run the CI-equivalent\nbuild against a real Postgres with logical decoding:\n\n```sh\n# Postgres 18 with wal_level=logical, created exactly as CI does (see .github/workflows/ci.yml):\n# the monolith_test database and trust auth (password-free, as the conninfo below expects) are\n# set up by the container's own env vars, and wal_level=logical enables logical decoding.\n#   docker run -d --name monolith-pg \\\n#     -e POSTGRES_DB=monolith_test -e POSTGRES_HOST_AUTH_METHOD=trust \\\n#     -p 5432:5432 postgres:18 -c wal_level=logical\nMONOLITH_TEST_CONNINFO=\"host=localhost dbname=monolith_test user=postgres\" \\\n  mvn -B -Pci clean verify\n```\n\nThe `-Pci` profile sets `monolith.requireDb=true`, which makes the build **fail** (rather than silently\nskip) if that database is not actually reachable.\n\n**Goals.** A live-subscription developer experience on a real relational database, for Java teams; type\nsafety carried from the database row to the client; libraries you embed, not a platform you adopt.\n**Non-goals.** Not an incremental-view-maintenance engine, not an ORM (you write SQL), not a managed\nservice.\n\n## License\n\nMIT, Standard Applied Intelligence Labs. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstandardapplied%2Fmonolith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstandardapplied%2Fmonolith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstandardapplied%2Fmonolith/lists"}