Base Template

The base template is the foundation of every FORGE application. It is always included, regardless of which additional templates you select. It provides the essential features that every production application needs: user management, authentication, role-based access control, an admin dashboard, content management, and more.

What is Included

┌──────────────────────────────────────────────────────────┐
│                     BASE TEMPLATE                        │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  Authentication        Admin Dashboard                   │
│  ├─ Login              ├─ Dashboard overview             │
│  ├─ Registration       ├─ User management                │
│  ├─ Password reset     ├─ Role management                │
│  └─ OTP (optional)     ├─ Permission management          │
│                        ├─ Content management              │
│  User Management       ├─ Menu management                │
│  ├─ CRUD operations    ├─ Media library                  │
│  ├─ Profile editing    ├─ Lookup tables                  │
│  ├─ Avatar upload      ├─ Translation management         │
│  └─ Role assignment    ├─ API key management             │
│                        ├─ Settings                       │
│  Role & Permission     └─ Audit log                      │
│  ├─ Role CRUD                                            │
│  ├─ Permission assign  Web Application                   │
│  └─ Middleware checks  ├─ Home page                      │
│                        ├─ Content pages (by slug)        │
│  Multi-Language        ├─ User profile                   │
│  ├─ JSONB translations ├─ Dynamic navigation             │
│  ├─ RTL support        └─ Language switcher              │
│  └─ Per-request locale                                   │
│                                                          │
└──────────────────────────────────────────────────────────┘

Usage

# Create a new project with the base template (default)
forge new --name=myapp

# Explicitly specify the base template
forge new --name=myapp --template=base

# With full options
forge new \
  --name=myapp \
  --backend=rust \
  --frontend=nextjs \
  --template=base \
  --auth=email_password \
  --default-lang=en \
  --languages=en,ar

Database Tables

The base template creates the following database tables through versioned SQL migrations:

Core Tables (Authentication and Authorization)

Table	Migration	Description
users	00002_create_users_table	User accounts with email, mobile, password, status, avatar
roles	00003_create_roles_table	Named roles with translatable display names
permissions	00004_create_permissions_table	Granular permissions grouped by module
role_user	00005_create_role_user_table	Many-to-many pivot between users and roles
permission_role	00006_create_permission_role_table	Many-to-many pivot between permissions and roles
password_resets	00007_create_password_resets_table	Password reset tokens with expiration
otp_codes	00008_create_otp_codes_table	One-time password codes for mobile verification

System Tables

Table	Migration	Description
languages	00001_create_languages_table	Supported languages with code, name, direction
settings	00009_create_settings_table	Key-value application settings with encryption support
translations	00010_create_translations_table	UI translation strings keyed by group and key
api_keys	00011_create_api_keys_table	Third-party API keys with rate limiting
audit_logs	00012_create_audit_logs_table	Activity audit trail with user, action, resource, details

Content Tables

Table	Migration	Description
media	00013_create_media_table	Polymorphic file uploads with metadata
contents	00014_create_contents_table	CMS content pages with translatable title, body, slug
menus	00015_create_menus_table	Navigation menu items with hierarchy and ordering
lookups	00017_create_lookups_table	Configurable key-value lookup tables

Migration numbering

Migrations are numbered sequentially (00001 through 00017). When additional templates are added, their migrations start at higher numbers (e.g., 00020 for CRM) to avoid conflicts.

Permissions Generated

The base template seeds the following permissions, all assigned to the default admin role:

User Management

Permission	Description
users.view	View user list and details
users.create	Create new users
users.edit	Edit existing users
users.delete	Delete users

Role Management

Permission	Description
roles.view	View role list and details
roles.create	Create new roles
roles.edit	Edit roles and assign permissions
roles.delete	Delete non-system roles

Content Management

Permission	Description
contents.view	View content pages
contents.create	Create new content pages
contents.edit	Edit content pages
contents.delete	Delete content pages

Menu Management

Permission	Description
menus.view	View navigation menus
menus.create	Create menu items
menus.edit	Edit menu items
menus.delete	Delete menu items

Media Management

Permission	Description
media.view	View media library
media.upload	Upload files and images
media.delete	Delete media files

System Permissions

Permission	Description
settings.view	View application settings
settings.edit	Modify application settings
translations.view	View translation strings
translations.edit	Edit translation strings
api_keys.view	View API keys
api_keys.create	Create API keys
api_keys.delete	Revoke API keys
audit.view	View audit log entries
lookups.view	View lookup tables
lookups.create	Create lookup entries
lookups.edit	Edit lookup entries
lookups.delete	Delete lookup entries

Admin Pages Generated

The base template generates the following admin dashboard pages:

admin.myapp.test/
├── /                           # Dashboard with statistics overview
├── /login                      # Admin login page
│
├── /users                      # User list (data table, search, filters)
├── /users/create               # Create user form
├── /users/[id]                 # User detail view
├── /users/[id]/edit            # Edit user form
│
├── /roles                      # Role list
├── /roles/create               # Create role with permission assignment
├── /roles/[id]/edit            # Edit role permissions
│
├── /contents                   # Content page list
├── /contents/create            # Create content (rich text editor)
├── /contents/[id]              # Content detail view
├── /contents/[id]/edit         # Edit content
│
├── /menus                      # Menu item list
├── /menus/create               # Create menu item
├── /menus/[id]/edit            # Edit menu item
│
├── /lookups                    # Lookup table list
├── /lookups/create             # Create lookup entry
├── /lookups/[id]/edit          # Edit lookup entry
│
├── /media                      # Media library (grid/list view)
│
├── /settings                   # Application settings
├── /translations               # Translation string editor
├── /api-keys                   # API key management
└── /audit                      # Audit log viewer

Each admin page includes:

• Data tables with sorting, pagination, search, and column visibility
• Form validation using React Hook Form with Zod schemas
• Permission gates that hide UI elements the user cannot access
• Responsive layout with collapsible sidebar navigation
• Dark mode support via next-themes
• RTL support for right-to-left languages

Web Pages Generated

The base template generates the following public web pages:

myapp.test/
├── /                           # Home page with dynamic content
├── /[slug]                     # Dynamic content pages (e.g., /about, /contact)
│
├── /login                      # User login
├── /register                   # User registration
├── /password/forgot            # Forgot password
├── /password/reset             # Reset password
│
└── /profile                    # User profile (protected)
    ├── /profile/edit           # Edit profile
    └── /profile/password       # Change password

Web pages include:

• Dynamic navigation driven by menus created in the admin panel
• Language switcher with locale persistence in cookies
• Content pages rendered from the CMS with SEO metadata
• Authentication flows with JWT token management
• RTL layout that switches automatically based on the active language

API Endpoints

The base template generates a complete REST API:

Authentication

POST   /api/v1/auth/login              # Login with email/password
POST   /api/v1/auth/register           # Register new account
POST   /api/v1/auth/refresh            # Refresh JWT token
POST   /api/v1/auth/logout             # Logout (invalidate token)
POST   /api/v1/auth/password/forgot    # Request password reset
POST   /api/v1/auth/password/reset     # Reset password with token
POST   /api/v1/auth/otp/send           # Send OTP code
POST   /api/v1/auth/otp/verify         # Verify OTP code

Profile

GET    /api/v1/profile                 # Get current user profile
PUT    /api/v1/profile                 # Update profile
PUT    /api/v1/profile/password        # Change password
POST   /api/v1/profile/avatar          # Upload avatar

Admin - Users

GET    /api/v1/admin/users             # List users (paginated)
POST   /api/v1/admin/users             # Create user
GET    /api/v1/admin/users/:id         # Get user details
PUT    /api/v1/admin/users/:id         # Update user
DELETE /api/v1/admin/users/:id         # Delete user

Admin - Roles

GET    /api/v1/admin/roles             # List roles
POST   /api/v1/admin/roles             # Create role
GET    /api/v1/admin/roles/:id         # Get role with permissions
PUT    /api/v1/admin/roles/:id         # Update role
DELETE /api/v1/admin/roles/:id         # Delete role

Admin - Content

GET    /api/v1/admin/contents          # List content pages
POST   /api/v1/admin/contents          # Create content page
GET    /api/v1/admin/contents/:id      # Get content page
PUT    /api/v1/admin/contents/:id      # Update content page
DELETE /api/v1/admin/contents/:id      # Delete content page

Public

GET    /api/v1/contents/:slug          # Get published content by slug
GET    /api/v1/menus                   # Get navigation menus
GET    /api/v1/lookups/:type           # Get lookup values by type
GET    /api/v1/languages               # Get supported languages
GET    /api/v1/translations/:lang      # Get translations for locale

Seeded Data

When the database is seeded, the base template creates:

Data	Details
Admin user	admin@myapp.test / admin123
Regular user	user@myapp.test / user123
Admin role	All permissions assigned
User role	Basic permissions (profile, content viewing)
Languages	Based on --languages flag (default: English)
Translations	UI strings for all configured languages
Settings	Default application settings
Permissions	All permissions listed above

Change default passwords

The seeded credentials are for development only. Always change the admin password before deploying to any shared or production environment.

Default Configuration

The base template generates a forge.yaml configuration file:

app:
  name: myapp
  display_name: My Application
  version: 1.0.0

backend:
  framework: rust
  port: 8080

frontend:
  framework: nextjs
  web_port: 3000
  admin_port: 3001

database:
  driver: postgresql
  host: localhost
  port: 5432
  name: myapp

auth:
  method: email_password
  jwt_expiry: 60m
  refresh_expiry: 7d

languages:
  default: en
  list:
    - { code: en, name: English, direction: ltr }

domains:
  web: myapp.test
  admin: admin.myapp.test
  api: api.myapp.test

providers:
  sms: null
  email: smtp
  storage: local
  payments: null

Next Steps

• Available Templates -- Add domain-specific features to your base application
• Custom Templates -- Create your own templates
• Backend Overview -- Understand the Rust API architecture
• Frontend Overview -- Explore the Next.js applications