Foundgine

Foundgine documentation

This directory contains the current Foundgine documentation, covering both implementations, released together as 2.2.1: .NET and Java. The two share the same architecture and vocabulary; pages below describe that shared model unless a section calls out a language-specific difference. See Current status for exactly what is and isn’t ported to Java today.

The repository itself is the source of truth. Documentation describes implemented architecture and tested behavior; it does not use old release notes or historical benchmark snapshots as current product guidance.

Read in order

This is the reading path — each page ends with a link to the next one, so you can also just start at Getting started and follow the links.

  1. Getting started — build the repository and run the main sample.
  2. Why Foundgine — the problem, and the boundary it draws.
  3. What Foundgine is designed for — what, how, where it fits, and the categories of applications it targets.
  4. Architecture — the intent-to-provider pipeline.
  5. Metadata → Semantics — what exists versus what it means.
  6. Mapping and connections — how the semantic model attaches to the physical/EF model.
  7. Open Intent API — typed, dynamic, and JSON ways to express intent.
  8. Lexical grounding — resolving free-form language against the semantic contract.
  9. Grounding decisions — telling a competing meaning apart from routing noise, and when Foundgine must ask instead of guess.
  10. Authorization — what a caller may exercise, and under what conditions.
  11. Security — the untrusted-input boundary and fail-closed rules.
  12. Runtime — how a request actually moves through resolution, planning, and execution.
  13. AOT — moving metadata discovery to compile time.
  14. Public API — the shape of the day-to-day application surface.
  15. AI agents — exposing capabilities to agents and MCP without granting database authority.
  16. PostgreSQL E2E — the real database integration path.
  17. Testing — how the boundaries above are proven, not just asserted.
  18. Current status — what the active code and tests support today.
  19. Roadmap — what’s next, and what’s deliberately out of scope.

Package-specific architecture and usage guidance lives in the README.md of every project under src/csharp/ and src/java/. Java sample tutorials live alongside each sample under src/java/samples/*.

Documentation rules

The documentation follows four rules:

  1. Current code wins. If prose disagrees with source or tests, the source/tests are authoritative.
  2. Implemented and planned are separated. A planned feature is not documented as a shipped capability.
  3. Transport and provider boundaries stay explicit. GraphQL, MCP, JSON, AI, and SQL are adapters/providers around the semantic core.
  4. Historical material stays out of the active guide. Release notes, old benchmark runs, and implementation diaries are not part of the current documentation set.
This site is open source. Improve this page.