Template System Overview

FORGE templates are pre-built application modules that generate complete, production-ready features from a single command. Rather than writing boilerplate code for common business domains, you select a template and FORGE generates models, migrations, API endpoints, admin pages, web pages, permissions, and seeders -- all wired together and ready to run.

How Templates Work

Every FORGE application starts with the base template, which provides the foundational features every app needs. Additional templates layer on top, adding domain-specific functionality without conflicting with the base or each other.

                          YOUR APPLICATION
┌─────────────────────────────────────────────────────────┐
│                                                         │
│   ┌─────────────────────────────────────────────────┐   │
│   │              OPTIONAL TEMPLATES                 │   │
│   │  ┌─────────┐  ┌──────────┐  ┌──────────────┐   │   │
│   │  │   CRM   │  │ Helpdesk │  │  Invoicing   │   │   │
│   │  └─────────┘  └──────────┘  └──────────────┘   │   │
│   └─────────────────────────────────────────────────┘   │
│                                                         │
│   ┌─────────────────────────────────────────────────┐   │
│   │              BASE TEMPLATE (always)             │   │
│   │  Users, Roles, Permissions, Auth, Settings,     │   │
│   │  Translations, API Keys, Audit, Media, CMS      │   │
│   └─────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Using Templates

Create a new project with the base template

bash

forge new --name=myapp --template=base

This generates a complete application with authentication, RBAC, admin dashboard, content management, menu system, media uploads, audit logging, and more.

Create a project with a specific template

bash

forge new --name=mycrm --template=crm

This generates everything from the base template plus all CRM-specific features (contacts, companies, deals, pipelines, activities).

Add a template to an existing project

bash

forge template:add crm

This adds the CRM module to a project that was already created. FORGE handles migrations, permission seeding, admin page generation, and route registration automatically.

Templates are additive

You can combine multiple templates in a single project. For example, a project can use both the CRM and Invoicing templates together. Each template adds its own models, pages, and permissions without conflicting with the others.

List available templates

bash

forge template:list

This displays all templates available for installation, along with their descriptions and status.

What a Template Includes

Every template is a self-contained module that generates the following components:

Models

Database models with full CRUD operations, relationships, and validation. Each model includes a Rust struct with SeaORM entity definitions, query scopes, and translation support where applicable.

Migrations

SQL migration files that create all necessary database tables, indexes, foreign keys, and constraints. Migrations are numbered to run in the correct order after the base migrations.

Permissions

A set of granular permissions for each model (e.g., contacts.view, contacts.create, contacts.edit, contacts.delete). These permissions are automatically seeded and assigned to the admin role.

Admin Pages

Next.js admin dashboard pages with:

List pages with data tables, search, filtering, and pagination
Create pages with validated forms
Edit pages with pre-populated form data
View/detail pages with related data

Web Pages

Public-facing pages where applicable (e.g., a booking page for the Appointment template, a pricing page for the Subscriptions template).

API Endpoints

RESTful API endpoints for both admin and public access, with proper authentication, authorization, request validation, and response formatting.

Seeders

Default data to populate the template's tables with sample records, configuration defaults, and required reference data.

Template Structure

Each template follows a consistent directory structure:

templates/modules/crm/
├── manifest.yaml              # Template metadata and configuration
├── migrations/
│   └── 00020_create_crm_tables.sql.tera
├── seeders/
│   └── crm_permissions.sql.tera
├── backends/
│   └── rust/
│       ├── models/
│       │   ├── contact.rs.tera
│       │   ├── company.rs.tera
│       │   └── deal.rs.tera
│       ├── handlers/
│       │   ├── admin/
│       │   │   └── crm.rs.tera
│       │   └── crm.rs.tera
│       ├── services/
│       │   └── crm.rs.tera
│       └── dto/
│           └── crm.rs.tera
└── frontends/
    └── nextjs/
        └── admin/
            └── pages/crm/
                ├── contacts/
                ├── companies/
                ├── deals/
                └── pipelines/

Template Manifest

Every template includes a manifest.yaml that declares its metadata, dependencies, and generated files:

yaml

name: crm
display_name: CRM
version: 1.0.0
description: Customer Relationship Management with contacts, deals, and pipelines

# Requires base template
depends_on:
  - base

# FORGE version compatibility
forge_compatibility:
  minimum: "2.0.0"

# Models this template adds
models:
  - Contact
  - Company
  - Deal
  - Pipeline
  - Activity
  - Tag

# Permissions to seed
permissions:
  - group: contacts
    actions: [view, create, edit, delete]
  - group: companies
    actions: [view, create, edit, delete]
  - group: deals
    actions: [view, create, edit, delete]
  - group: pipelines
    actions: [view, create, edit, delete]
  - group: activities
    actions: [view, create, edit, delete]

# Admin navigation items
navigation:
  - label: CRM
    icon: Users
    children:
      - { label: Contacts, path: /admin/crm/contacts }
      - { label: Companies, path: /admin/crm/companies }
      - { label: Deals, path: /admin/crm/deals }
      - { label: Pipelines, path: /admin/crm/pipelines }
      - { label: Reports, path: /admin/crm/reports }

Template Variables

Templates use the Tera templating engine with access to the full project context:

{{ app.name }}              # Project name (e.g., "myapp")
{{ app.display_name }}      # Display name (e.g., "My Application")
{{ backend.framework }}     # Backend framework (e.g., "rust")
{{ frontend.framework }}    # Frontend framework (e.g., "nextjs")
{{ languages.default }}     # Default language code
{{ domains.api }}           # API domain (e.g., "api.myapp.test")

Custom filters are available for case conversion:

{{ app.name | snake_case }}     # my_app
{{ app.name | pascal_case }}    # MyApp
{{ app.name | kebab_case }}     # my-app
{{ app.name | camel_case }}     # myApp

Template files use the .tera extension

All template files end in .tera (e.g., contact.rs.tera, page.tsx.tera). The extension is stripped during generation, producing clean source files in the output project. Files without the .tera extension are copied as-is.

Generation Flow

When you run forge new or forge template:add, FORGE follows this process:

1. LOAD CONFIGURATION
   ├── Parse CLI arguments and forge.yaml
   ├── Build template context (app name, languages, providers, etc.)
   └── Validate template compatibility

2. LOAD MANIFESTS
   ├── Base template manifest
   ├── Selected template manifest(s)
   └── Resolve dependencies

3. CREATE DIRECTORIES
   └── Create output directory structure

4. PROCESS TEMPLATES
   ├── For each .tera file: render with Tera engine
   └── For static files: copy directly

5. POST-GENERATION
   ├── Run migrations
   ├── Seed permissions and default data
   ├── Install dependencies
   └── Verify output with cargo check / npm run build

Available Templates

FORGE provides templates for common business domains:

Template	Description	Status
Base	Users, roles, permissions, auth, admin, CMS, media	Included
CRM	Contacts, companies, deals, pipelines	Available
Helpdesk	Tickets, SLAs, knowledge base	Available
Appointment	Services, staff, booking, calendar	Available
Invoicing	Invoices, quotes, payments, tax	Available
Inventory	Products, warehouses, stock, orders	Available
Subscriptions	Plans, billing, usage, coupons	Available

See Available Templates for detailed documentation on each template, or learn how to create your own.

Next Steps

Base Template -- Understand everything included in every FORGE project
Available Templates -- Browse all domain-specific templates
Custom Templates -- Build your own templates

Template System Overview ​

How Templates Work ​

Using Templates ​

Create a new project with the base template ​

Create a project with a specific template ​

Add a template to an existing project ​

List available templates ​

What a Template Includes ​

Models ​

Migrations ​

Permissions ​

Admin Pages ​

Web Pages ​

API Endpoints ​

Seeders ​

Template Structure ​

Template Manifest ​

Template Variables ​

Generation Flow ​

Available Templates ​

Next Steps ​

Template System Overview

How Templates Work

Using Templates

Create a new project with the base template

Create a project with a specific template

Add a template to an existing project

List available templates

What a Template Includes

Models

Migrations

Permissions

Admin Pages

Web Pages

API Endpoints

Seeders

Template Structure

Template Manifest

Template Variables

Generation Flow

Available Templates

Next Steps