Code Generator and Templates

Relevant source files

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

• generator/src/lib.rs
• generator/src/writer.rs
• generator/src/templates/actix.rs
• generator/src/templates/axum.rs
• generator/src/templates/poem.rs
• cli/src/main.rs

The Code Generator and Templates system in Seaography is responsible for automating the creation of a fully functional GraphQL server based on existing SeaORM entities. It bridges the gap between database models and a running web service by generating boilerplate code, configuration files, and framework-specific integration logic. This system allows developers to bootstrap a backend in minutes by targeting specific web frameworks such as Actix, Axum, or Poem.

Sources: generator/src/lib.rs:17-48, README.md:16-24

Core Orchestration

The generation process is orchestrated by the write_project function, which serves as the primary entry point for the generator. It coordinates various specialized writer functions to construct the project structure, including the Cargo.toml, environment configurations, and the Rust source files.

Execution Flow

The generator follows a sequential path to build the project directory:

The generator uses std::process::Command to run cargo fmt at the end of the process to ensure the generated code adheres to standard Rust formatting.

Sources: generator/src/lib.rs:17-48

Project Structure Writers

The writer.rs module contains the logic for generating the foundational files of the new Rust project.

Query Root Generation

The generate_query_root function scans the provided entities directory to identify SeaORM models. It filters out internal files like mod.rs, prelude.rs, and sea_orm_active_enums.rs to build a clean list of entities to register in the GraphQL schema.

Key features of the generated query_root.rs:

• Schema Builder: Initializes a seaography::Builder with database connections.
• Entity Registration: Automatically calls register_entity_modules(builder).
• Active Enums: Detects if sea_orm_active_enums.rs exists and generates the code to register them via register_active_enums(builder).
• Limits: Configures depth and complexity limits for the GraphQL schema.

Sources: generator/src/writer.rs:12-104

Configuration and Metadata

The generator handles the project's metadata and environment settings through specialized functions:

Function	Output File	Purpose
write_cargo_toml	Cargo.toml	Injects the crate name, SQL library (e.g., sqlx-mysql), and Seaography version into framework-specific templates.
write_lib	src/lib.rs	Defines the module structure, exposing entities and query_root.
write_env	.env	Sets the DATABASE_URL and placeholder comments for COMPLEXITY_LIMIT and DEPTH_LIMIT.

Sources: generator/src/writer.rs:110-165

Web Framework Templates

Seaography provides dedicated templates for different web frameworks. Each template implements a generate_main function that produces a main.rs file using the quote! macro.

Framework Integration Logic

The templates share a common structure for the generated main function:

1. Environment Setup: Loads variables via dotenv.
2. Database Connection: Initializes a sea_orm::Database connection.
3. Schema Initialization: Calls the generated query_root::schema with configured limits.
4. Handler Definition: Implements a GraphQL handler and a Playground handler.
5. Server Lifecycle: Binds to a TCP listener and starts the web server.

Supported Frameworks

• Actix (actix.rs): Uses actix-web and async-graphql-actix-web. It configures routes for GET (Playground) and POST (GraphQL handler) using web::resource.
• Axum (axum.rs): Uses axum and async-graphql-axum. It utilizes Axum's State to share the GraphQL schema across requests.
• Poem (poem.rs): Uses poem and async-graphql-poem. It configures routes via Route::new() and passes the schema as Data.

Sources: generator/src/templates/actix.rs:11-66, generator/src/templates/axum.rs:11-66, generator/src/templates/poem.rs:11-66

CLI Integration

The seaography-cli acts as the user interface for the generator. It parses command-line arguments and maps them to the generator's internal types.

Argument Mapping

The CLI handles the translation of user input to generator configurations:

• Web Framework: Maps the --framework flag to the WebFrameworkEnum.
• Database Scheme: Parses the database URL to determine the required SQL library (e.g., postgres:// becomes sqlx-postgres).
• Limits: Pass-through for depth-limit and complexity-limit.

Sources: cli/src/main.rs:7-140

Conclusion

The Code Generator and Templates system is a critical component for the Seaography "Ready to serve in 3 minutes" experience. By combining directory parsing in writer.rs with framework-specific logic in the templates/ directory, it provides a robust mechanism for turning static SeaORM entities into dynamic, framework-agnostic GraphQL APIs.

Sources: README.md:126-130