Core Concepts

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/lib.rs
• generator/src/writer.rs
• CHANGELOG.md
• examples/sea-draw/src/schema.rs
• generator/src/templates/poem.rs
• generator/src/lib.rs

Seaography is an extensible GraphQL framework for Rust built to bridge SeaORM and async-graphql. Its primary purpose is to transform database schemas into fully-typed GraphQL APIs with minimal manual intervention by utilizing a dynamic schema engine rather than heavy static code generation.

Sources: src/lib.rs:18-23, README.md:18-23

The framework exposes SeaORM entities directly as GraphQL schemas, supporting complex features such as relational queries (1-to-1, 1-to-N, M-to-N), diverse pagination methods, and advanced filtering. It is designed to be highly customizable through a functional API, lifecycle hooks, and RBAC (Role-Based Access Control) integrations.

Sources: src/lib.rs:25-30, CHANGELOG.md:144-155

Architecture Overview

Seaography functions by parsing SeaORM entities and mapping them to dynamic GraphQL objects via the async-graphql dynamic schema builder. This process is orchestrated by a Builder and configured through a BuilderContext.

Component Relationship

The following diagram illustrates how Seaography sits between the database layer and the web framework layer.

Schema Construction

The core of a Seaography application is the QueryRoot, which initializes the GraphQL schema. The schema is generated using a Builder that registers entities, enumerations, and custom modules.

The Builder Pattern

Seaography uses a functional approach where the Builder takes a BuilderContext and a DatabaseConnection to assemble the schema.

Component	Responsibility
Builder	The main engine for registering entities, mutations, and queries.
BuilderContext	Holds configuration like naming functions, pagination limits, and lifecycle hooks.
register_entity	Maps a SeaORM Entity to a GraphQL Object with its relations and filters.
register_active_enums	Automatically maps SeaORM active enums to GraphQL enums.

Sources: generator/src/writer.rs:77-109, examples/sea-draw/src/schema.rs:77-105, CHANGELOG.md:173-185

pub fn schema_builder(
    context: &'static BuilderContext,
    database: DatabaseConnection,
    depth: Option<usize>,
    complexity: Option<usize>,
) -> SchemaBuilder {
    let mut builder = Builder::new(context, database.clone());

    builder = register_entity_modules(builder);

    builder
        .set_depth_limit(depth)
        .set_complexity_limit(complexity)
        .schema_builder()
        .data(database)
}

Sources: generator/src/writer.rs:88-109

Lifecycle Hooks and Security

Seaography introduces LifecycleHooks to allow developers to intercept operations and apply custom logic, such as authorization and data filtering, at runtime.

Hook Interfaces

The LifecycleHooksInterface provides three main entry points:

1. Guard Actions: entity_guard and field_guard determine if a user has permission to perform an action (e.g., Allow, Block).
2. Entity Filtering: entity_filter allows the injection of additional sea_orm::Condition objects into queries to restrict data access at the database level (e.g., multi-tenancy).

Sources: CHANGELOG.md:57-100, examples/sea-draw/src/schema.rs:118-142

Data Operations

Querying and Filtering

Seaography supports rich filtering operators (eq, gt, lt, contains, etc.) and allows filtering by related entities. Filtering is handled dynamically by mapping GraphQL input objects to SeaORM Condition objects.

• Pagination: Supports both offset-based (page/limit) and cursor-based pagination.
• Ordering: Allows ordering by any database column.

Sources: src/lib.rs:52-60, CHANGELOG.md:14-25

Mutations

The framework provides standardized mutations for entity lifecycle management:

• create_one / create_batch: Insertion of new records.
• update: Modifying existing records based on a filter.
• delete: Removing records based on a filter.

Sources: CHANGELOG.md:162-172, README.md:59

Project Generation and Tooling

Seaography provides a CLI (seaography-cli) and a generator module to bootstrap projects quickly. The generator produces a complete Rust project including Cargo.toml, main.rs, and query_root.rs.

Supported Frameworks

The generator can produce boilerplate for several web frameworks:

• Actix: WebFrameworkEnum::Actix
• Axum: WebFrameworkEnum::Axum
• Poem: WebFrameworkEnum::Poem (Default)

Sources: generator/src/lib.rs:10-20, cli/src/main.rs:114-124, generator/src/templates/poem.rs:9-15

Generation Flow

Summary

Seaography's core concepts revolve around the dynamic mapping of SeaORM entities to async-graphql structures. By providing a Builder that centralizes configuration, filters, and lifecycle hooks, it enables the rapid development of secure, feature-rich GraphQL backends while maintaining the flexibility to add custom business logic through a functional API.

Sources: src/lib.rs:18-35, CHANGELOG.md:144-160