Codebase Introduction

This guide covers the required directory structure and explains what each directory and file type does. Getting this structure right is essential because the Insites engine reads specific directories to know how to build your application.

Required Directory Structure

Put the site itself in the directory. Put code you want to reuse or package in , with and folders that follow the same layout as . A project can use , , or both.

Views: Pages, Layouts, and Partials

The directory contains three subdirectories, each with a distinct role:

Pages are the entry points for every URL in your application. Each page file maps to a route and handles an HTTP method (GET, POST, PUT, DELETE). Pages fetch data via GraphQL and delegate rendering to partials.

Insites supports multiple content types beyond HTML. You can create JSON endpoints, JavaScript endpoints, PDF generators, RSS feeds, and more by using the appropriate file extension:

Layouts are wrappers around page content. They hold the outer HTML structure that stays consistent across pages, like headers, footers, and navigation. Without layouts, you would duplicate this code on every page. You can create multiple layouts and assign each page to the layout it needs.

Partials are reusable code snippets. They contain your HTML templates, UI components, and presentation logic. Use the tag to include a partial for HTML output, or the tag to invoke a partial that returns data.

app
|-- views
    |-- layouts
    |   |-- 1col.html.liquid
    |-- pages
    |   |-- index.html.liquid
    |   |-- unauthorized.html.liquid
    |-- partials
        |-- layout
            |-- constants.liquid
            |-- foot.liquid
            |-- footer.liquid
            |-- head.liquid
            |-- header.liquid

Assets

The directory holds static files that the web server serves directly without any backend processing. This includes JavaScript files, CSS stylesheets, images, fonts, documents, and media files.

While only the top-level directory is required, we recommend organizing files into subdirectories:

app
|-- assets
    |-- fonts
    |-- images
    |   |-- favicon.ico
    |-- scripts
    |   |-- app.js
    |   |-- vendor.js
    |-- styles
        |-- app.css
        |-- vendor.css

Migrations

Migrations are Liquid files that run once per environment during a deployment. They are useful for modifying existing data when you change a schema, setting initial values, or seeding data.

Migration filenames must follow the pattern . The timestamp ensures uniqueness and controls execution order. Generate a new migration with:

app
|-- migrations
    |-- 20200811133711_set_superadmins.liquid
    |-- 20210114080833_set_defaults_for_country.liquid

Forms

Forms are the primary tool for persisting data, running validation, enforcing authorization, and triggering notifications. They give you control over which fields can be saved, who can submit the form, what happens on successful submission (redirect, send email, call an API), and what validation rules apply.

You can also define synchronous or asynchronous callbacks using GraphQL mutations for additional processing after a form is submitted.

app
|-- forms
    |-- create_contact_request_form.liquid
    |-- feedback_form.liquid

Users

Users are identified by their unique email address. You can define properties that apply to all users in the file, and create different user profile types in the directory for role-based access and custom fields.

app
|-- user.yml
|-- user_profile_types
    |-- default.yml

Database Schema

Tables define the structure of your application's data. Each file in the directory creates a table with its fields and types. Think of tables as custom database tables that you define through YAML configuration.

app
|-- schema
    |-- blog_post.yml

Notifications

Notifications are messages sent when specific events occur. They can be emails, SMS messages, or programmatic API calls to third-party services. Each notification type has its own directory:

app
|-- api_calls
|   |-- ping_example_com_on_user_sign_up.liquid
|-- emails
|   |-- welcome_user.liquid
|-- smses
    |-- welcome_user.liquid

Authorization Policies

Authorization policies control who can access pages and submit forms. Each policy is a Liquid file that evaluates to true or false. You can attach multiple policies to a single page or form, and they are checked in the order they appear in the configuration.

When a policy check fails, the system either redirects the user to a URL you specify or returns an error status (such as 403 Forbidden).

app
|-- authorization_policies
    |-- example_policy.liquid

Translations

Translation files support multilingual sites and also define date formats, flash messages, and system-wide default error messages. Each YAML file contains a map of translation keys that you reference in your templates using the filter.

app
|-- translations
    |-- en.yml
    |-- pl.yml

Modules

Modules allow code reuse and sharing across projects while protecting the intellectual property of creators. The directory sits at the same level as .

Module code is split into and directories. Both have the same structure as the directory. When developers pull a module from an instance, they only receive the public files. Private files remain on the server.

modules
|-- my_admin
    |-- private
    |   |-- graphql
    |       |-- get_records.graphql
    |       |-- get_pages.graphql
    |-- public
        |-- views
            |-- pages
                |-- admin.liquid