Project layout

The Liberty Framework is split between two repositories that work together at runtime: the framework binary (liberty-next) reads its per-section configuration from the apps repo (liberty-apps). This page is the file map — where each piece lives, what is committed, what is per-installation.

At a glance

The framework is told where the apps repo lives via the LIBERTY_APPS_DIR environment variable. Out of the box, with LIBERTY_APPS_DIR unset, the framework reads its per-section TOML from liberty-next/config/ — convenient for local experimentation but not the production layout.

`liberty-next` — the framework binary

liberty-next/
├── start.sh                  ← run/dev helper (build, init-db, init-config, …)
├── pyproject.toml            ← Python deps + CLI entry points
├── liberty/                  ← FastAPI backend (Python 3.12)
│   ├── main.py               ← app factory, lifespan, routers
│   ├── config.py             ← TOML loading + env expansion
│   ├── connectors/           ← SQL / API connector engine, dictionary (dictionary.py)
│   ├── auth/                 ← local users, OIDC, JWT, permissions
│   ├── screens/              ← screen engine (grid + dialog runtime)
│   ├── dashboards/           ← dashboard layout + widget rendering
│   ├── charts/               ← chart definitions
│   ├── menus/                ← menu tree + permission pruning
│   ├── jobs/                 ← Nomaflow (jobs, steps, scheduler)
│   ├── actions/              ← shared actions
│   ├── notify/               ← notifications
│   ├── ai/                   ← Anthropic tool-use assistant
│   ├── licensing/            ← RS256 license-key verification
│   ├── web/                  ← HTTP routes (one module per area)
│   └── *_cli.py              ← CLI entry points (admin, connectors, crypto, license)
│
├── frontend/                 ← React 19 + Vite SPA (built to frontend/dist/)
│   └── src/
│       ├── pages/            ← pages, including Settings/ (one editor per configuration type)
│       ├── common/           ← shared UI parts (fields, lists, dialogs, SQL editor…)
│       ├── components/       ← layout (sidebar, app picker, tabs)
│       ├── locales/          ← interface texts, en and fr
│       └── api/              ← REST client
│
├── config/                   ← bundled templates + per-installation files
│   ├── app.toml              ← application settings — edited in Liberty Next → Administer → App
│   ├── auth.toml             ← local users — created by init-db, gitignored
│   ├── *.toml.example        ← templates for connectors / dictionary / menus / screens / charts / dashboards
│   └── *.toml                ← real per-section files (only when LIBERTY_APPS_DIR is unset)
│
├── tests/                    ← pytest suite
└── docs/                     ← framework-internal planning notes (not the public docs)

File	Status	Edited by
`liberty/`, `frontend/`, `pyproject.toml`, `start.sh`	Committed	Framework maintainers — don't edit per-installation.
`config/app.toml`	Per-installation	Liberty Next → Administer → App.
`config/auth.toml`	Per-installation, gitignored	`liberty-admin` CLI / the Liberty Next pages.
`config/*.toml.example`	Committed	Framework maintainers — bundled templates.
`config/*.toml` (without `.example`)	Per-installation, gitignored	Editable from the Liberty Next pages when `LIBERTY_APPS_DIR` is unset.

`liberty-apps` — your configuration

liberty-apps/
├── README.md
├── config/                   ← per-section TOML — read by liberty-next at runtime
│   ├── connectors.toml       ← pools, connectors and their queries / endpoints
│   ├── dictionary.toml       ← data items, enums, lookups, sequences
│   ├── menus.toml            ← one menu per app
│   ├── screens.toml          ← grids and dialogs
│   ├── charts.toml           ← saved charts
│   ├── dashboards.toml       ← dashboards
│   ├── actions.toml          ← shared actions
│   └── theme.toml            ← colours and branding
│
├── plugins/                  ← Python packages (functions called by steps and actions)
│   ├── <package>/            ← one folder per package, with __init__.py
│   └── nomaflow/
│       └── jobs.toml         ← the Nomaflow job catalogue
│
└── docs/                     ← deployment & operations notes (per-installation)

File	Edited by	Notes
`config/connectors.toml`	Build → Connectors	Owns the pool registry plus every connector.
`config/dictionary.toml`	Build → Dictionary	Per-column metadata reused by screens and charts.
`config/menus.toml`	Build → Menus	One root per app, optional folder/leaf hierarchy.
`config/screens.toml`	Build → Screens	Grids + dialogs + per-field conditions.
`config/dashboards.toml`	Build → Dashboards	KPI, chart and table widgets.
`config/charts.toml`	Build → Charts	Chart definitions referenced by dashboards.
`config/actions.toml`	Build → Actions	Shared actions called by screens.
`config/theme.toml`	Administer → Theme	Colours and branding.
`plugins/nomaflow/jobs.toml`	Nomaflow → Jobs	The job catalogue.
`plugins//.py`	Developer	Custom step callables — exposed to the framework via `sys.path`.

Every file is plain TOML you can read with cat, diff with git, edit in vim. The Liberty Next pages uses the same on-disk format — what you save in the browser is what git status reports.

How the framework finds your config

The wiring is one environment variable:

export LIBERTY_APPS_DIR="$HOME/work/liberty-apps/config"

When LIBERTY_APPS_DIR is set:

Config	Read from
`connectors.toml`, `dictionary.toml`, `menus.toml`, `screens.toml`, `charts.toml`, `dashboards.toml`	`${LIBERTY_APPS_DIR}/<name>.toml`
`app.toml`	`liberty-next/config/app.toml` (stays per-host)
`auth.toml`	`liberty-next/config/auth.toml` (stays per-host)
`plugins/` packages	`${LIBERTY_APPS_DIR}/../plugins/` added to `sys.path`

When LIBERTY_APPS_DIR is unset, every file is read from liberty-next/config/. Convenient for a single-host dev install; in production keep them separate.

The full env-var contract is documented under Configuration → Environment variables.

Naming conventions

App identifier — every screen, menu and job carries an app field (e.g. nomajde, nomasx1, tutorial). It's the namespace for screen ids and the prefix of the sidebar entry.
Connector name — short, kebab-case (jdedwards, tasks, crm-sql). The same name surfaces in the catalog page, the AI assistant tool list and the URL of a query.
Pool name — short, lowercase. default is reserved for the framework's own pool.
Permission code — sql:<connector>:<query> for SQL queries and api:<connector>:<endpoint> for HTTP/API endpoints. The Liberty Next pages builds them automatically; no manual code is needed.

Version control conventions

liberty-next is upgraded by switching git tags — the framework binary is treated as an external dependency, not modified in place. The liberty-apps repo stays untouched across framework upgrades.
liberty-apps is committed normally — every TOML edit done in the Liberty Next pages ends up as a diff in the repo. Commits made by the operator are reviewable like any other code change.
Secrets — JWT signing key, master key, license key, AI key — live in the environment, not in either repo. See Encryption & secrets.

What's next

The Liberty Next workspace — the in-browser editor for everything under liberty-apps/config/.
Apps & Plugins → Apps — how to organise multiple apps inside liberty-apps.

At a glance​

liberty-next — the framework binary​

liberty-apps — your configuration​

How the framework finds your config​

Naming conventions​

Version control conventions​

What's next​