Home → Documentation → Reference → Glossary
This glossary defines the core terminology used throughout the Foundgine framework. The terms below have specific architectural meanings and should be used consistently across documentation, code, and discussions.
A physical storage object.
An Entity represents the database structure rather than the public application model.
Examples include:
Entities map directly to storage metadata.
A public CLR representation exposed to the application.
A model may map to:
Models are transport-independent.
The physical table or storage object used by SQL generation.
Every storage entity has:
A logical member exposed by a model.
Fields may represent:
Fields are not always physical columns.
A physical database column.
Columns belong to storage entities.
Example:
Customer.Name
becomes
Customer
↓
Name Column
A lightweight object describing a physical column.
Typically includes:
Column references eliminate repeated metadata lookups.
Immutable information describing the application’s data model.
Examples include:
Metadata is generated during compilation.
The runtime source of metadata.
Example:
IMetadataProvider
Typical implementation:
GeneratedMetadataProvider
Runtime depends only upon the interface.
A read operation.
Queries produce immutable QueryPlans which Runtime executes.
A write operation.
Mutations produce immutable MutationPlans containing dependency information and SQL operations.
Converts selections into immutable QueryPlans.
Responsibilities include:
Converts mutation requests into immutable MutationPlans.
Responsibilities include:
An immutable description of a read operation.
Contains everything Runtime requires for execution.
An immutable description of a write operation.
Includes:
Generated code that converts database rows into CLR objects.
Materializers replace reflection.
Generated code that converts CLR objects into mutation values.
Dematerializers replace runtime property inspection.
A generated registry that maps identifiers to planners.
Runtime uses the registry to locate generated planners without reflection.
A graph representation consisting of:
Graph metadata exists independently of relational metadata.
A relationship between two storage entities.
Joins are resolved during planning rather than SQL generation.
A provider responsible for graph-specific SQL generation.
Example implementations:
A component that converts immutable execution plans into executable SQL statements.
SQL Writers do not perform planning.
Defines database-specific SQL syntax.
Examples include:
Only serialization changes between dialects.
The Roslyn Incremental Source Generator responsible for compile-time analysis and code generation.
The Generator produces:
Source emitted during compilation.
Generated code should contain:
Generated code should contain very little business logic.
The lowest architectural layer.
Defines:
Foundation references no other Foundgine project.
The execution engine.
Consumes:
Runtime performs execution only.
The serialization layer responsible for converting execution plans into SQL.
It does not understand GraphQL or CLR models.
An adapter that translates external requests into Runtime plans.
Examples include:
Transports do not execute queries.
An architectural principle where Runtime depends upon interfaces rather than generated implementations.
Example:
Runtime
↓
IMetadataProvider
↓
GeneratedMetadataProvider
This keeps Runtime reusable and testable.
Ahead-of-Time compilation supported through compile-time generation and the avoidance of runtime reflection.
Foundgine is designed to remain fully compatible with Native AOT.
Using this terminology consistently helps maintain a shared architectural language across the Foundgine codebase. Contributors should prefer these definitions when naming types, writing documentation, reviewing pull requests, and discussing future design decisions.
| ← Previous: FAQ | Next: Roadmap → |