Skip to main content

Massive Codegen Refactoring: Modular Templates & Native AI Agent Support

· 3 min read
TeaQL Team
TeaQL Team
Core Team

We are excited to announce a massive overhaul of the teaql-forge-rs code generation engine. This update fundamentally transforms how our templates are structured and significantly enhances how AI coding agents interact with TeaQL-generated codebases.

The Monolith is Dead: Modular Template Architecture​

Previously, our code generation relied on massive, monolithic templates. For example, src/q.rs.j2 (responsible for generating Query APIs) alone spanned over 1,700 lines. This made maintaining, extending, and debugging the code generator extremely difficult.

In this update, we have completely shattered the monolith. The lib/ directory now contains finely-grained, modular Jinja2 templates:

  • lib/request/index.j2
  • lib/entity/struct.rs.j2
  • lib/request_support/index.j2
  • lib/expression/index.j2
  • lib/runtime/index.j2

By isolating the logic into distinct modules, the core q.rs.j2 has shrunk from 1,728 lines to just 41 lines! This decoupling dramatically improves maintainability and makes it far easier for contributors to customize specific parts of the generation lifecycle.

Explosion in Detail: From 3,700 to 8,800 Lines of Templates​

With fine-grained modularity comes increased expressiveness. At the refactoring commit, the template tree contained more than 9,300 lines. The Rust control code also grew to support template composition, evaluation, and generation.

Despite the larger line count, the code is vastly cleaner, heavily structured, and heavily tested.

Native Support for AI Coding Agents​

One of the most exciting additions is the rust-assist-* directory. We have embedded comprehensive prompt templates directly into the codegen engine.

When you generate a project, TeaQL now outputs context-aware prompts designed specifically for AI agents (like GitHub Copilot, Gemini, or ChatGPT). These prompts teach the AI about:

  • How to write complex Queries (rust-assist-query)
  • How to implement Runtime Customizations (rust-assist-runtime-custom)
  • How to structure Data Manipulations (rust-assist-create, rust-assist-delete, rust-assist-update)
  • How to use the Tool APIs (rust-assist-tool-api)

This means that AI agents can now assist you in developing business logic using TeaQL's deterministic APIs without hallucinating generic SQL or ORM boilerplate.

Automated Architecture & Documentation Generation​

Documentation generated from the same reviewed model is easier to keep aligned with the code. We added a new doc/ template suite that generates Markdown documentation representing the system architecture. This includes data-design and model-view templates that create comprehensive, human-readable (and AI-readable) specs of your database schemas, relations, and even frontend React bindings.

A Complete Workspace Skeleton​

Finally, the workspace/ templates have been expanded. Generating a project now yields a runnable workspace skeleton, including Makefile, .gitignore, README.md, TOOL_API_GUIDE.md, and RUNTIME_CUSTOM_GUIDE.md. Applications still need their own security, operations, deployment, and production qualification work.

This update sets a solid foundation for the future of metadata-driven, AI-assisted development. Happy coding!