Project Structure

Directory Layout

A typical Paradox project:

my-project/
  dox.yaml              # Project manifest (required)
  types.dox             # Core types
  validation.dox        # Validation rules
  api.dox               # API definitions

  models/               # Sub-module directory
    user.dox
    pet.dox

dox.yaml

Every Paradox project needs a dox.yaml manifest in its root:

name: my-project
description: My domain specification

Both fields are required. The name identifies the project and the description provides a short summary.

File Organization

All .dox files in a directory are part of the same module. Types, functions, and interfaces defined in any file are visible to all other files in the same directory.

Subdirectories

Use import /path to include subdirectories:

import /models
import /api/types

Path imports start with / and are relative to the project root. All .dox files in the target directory are loaded.

Multiple Files vs. Single File

There is no difference between putting everything in one file versus splitting across multiple files in the same directory. Paradox loads all .dox files from the project root and any imported paths.

Split files when it improves readability — for example, separating type definitions from validation rules from API endpoints.

PARADOX_ATLAS

The PARADOX_ATLAS environment variable tells Paradox where to find importable modules (like the standard library).

In the Nix development shell, this is set automatically. When running outside Nix, set it to the directory containing the standard library:

export PARADOX_ATLAS=/path/to/paradox/lib/dox

Check available modules:

paradox atlas

Import Resolution Order

When you write import foo:

Check if foo is a directory relative to the project root
Check if foo is a module in PARADOX_ATLAS
Report an error if not found

Imports with / prefix are always resolved relative to the project root.