C3 AI Documentation Home

Package structure overview

A C3 AI package is a structured directory containing your application code, data, configuration, and metadata. The C3 Agentic AI Platform enforces specific folder conventions that trigger different behaviors and automations.

This guide explains how C3 AI packages are organized and how the C3 Agentic AI Platform processes files. You'll understand:

  • Package directory structure: The folders that make up a package and what goes in each.
  • How the platform finds your files: The internal path format and categorization system used to locate files.
  • File validation rules: How the platform validates files based on their location.
  • Loading behavior: When and how files are actually loaded into memory.

Understanding these concepts helps you:

  • Organize code correctly so the platform can find and validate it
  • Avoid validation errors from misplaced files
  • Understand error messages that reference file paths or categories
  • Debug issues with missing types, configurations, or data

Package anatomy

At minimum, a valid package requires only a manifest file:

Text
myPackage/
  myPackage.c3pkg.json    # Required manifest file

A fully-featured package may contain multiple folders, each serving a specific purpose:

Text
myPackage/
  myPackage.c3pkg.json    # Package manifest (required)
  src/                     # Type definitions and source code
  test/                    # Test files and test data
  ui/                      # UI components and pages
  metadata/                # System integration definitions
  config/                  # Environment-specific configuration
  seed/                    # SeedData types, loaded on app start or upgrade
  data/                    # Development data loaded manually
  gen/                     # Platform-generated files and caches
  resource/                # Static files like images, PDFs, or other assets

Each folder has specific rules about file organization, naming conventions, and validation requirements. The C3 Agentic AI Platform automatically processes files based on their location and validates them against Type system expectations.

Core directories

These directories contain the different types of files that make up your application. Each serves a distinct purpose and has its own validation rules.

Source code (src/)

The src/ directory contains your Type definitions (.c3typ files) and their implementations (.java, .js, .py files). This is where you define your data models and business logic.

Key rules:

  • Implementation files must be co-located with their Type definition files.
  • File names determine which Type they implement (for instance, User.java implements User.c3typ).
  • The C3 Agentic AI Platform validates that implementations exist for claimed methods.
  • Inner types and runtime-specific files follow special naming conventions.

See Source folder structure for complete details.

Testing (test/)

The test/ directory mirrors your source structure but contains test-specific files. Test files are not deployed to production environments.

Key rules:

  • Test files follow specific naming patterns for framework detection.
  • Directory structure determines which test framework runs the tests.
  • Test data and canonical data live here.
  • Supports multiple test types: JavaScript, Python, notebooks, browser tests.

See Test folder structure for complete details.

User interface (ui/)

The ui/ directory contains React components, page definitions, and UI metadata that define your application's frontend.

Key rules:

  • File paths follow strict patterns for application ID and metadata kind extraction.
  • Integrates with the routing system via metadata definitions.
  • Supports templates, components, and application configurations.

For comprehensive UI development documentation, see the "Develop front-end" section of the C3 AI documentation.

System integration (metadata/)

The metadata/ directory contains definitions that tell the C3 Agentic AI Platform how to configure system services like routing, workflows, and internationalization.

Key rules:

  • Directory structure must match metadata Type names exactly.
  • Only Types that mixin Metadata can have files here.
  • File format (CSV vs JSON) depends on data structure complexity.
  • Files are cached in a two-level cache for performance.

See Metadata folder structure for complete details.

Configuration (config/)

The config/ directory contains environment-specific settings that override Type defaults without code changes.

Key rules:

  • Directory structure must match config Type names exactly.
  • Only Types that mixin Config can have files here.
  • Configuration values merge with Type defaults.
  • Enables environment-specific behavior (dev, staging, production).

Initial data (seed/)

The seed/ directory contains SeedData type instances loaded automatically when the app starts or when the package changes. This populates your application with starter content that can be updated on each deployment.

Key rules:

  • Loaded on app start if seed data hasn't been deployed yet (state.seeded() is false).
  • Reloaded when package fingerprint changes (indicating package upgrade or modification).
  • Uses DbLock to prevent concurrent deployment.
  • Data validated against Type definitions.
  • User modifications to seed data persist across deployments—seed files won't overwrite user changes.

See Seed folder structure for complete details.

Development data (data/)

The data/ directory contains datasets for entity types (Persistable types) that you manually load using package.upsertAllSeed().

Key rules:

  • Not automatically deployed (manual loading only).
  • Useful for populating development environments with test datasets.
  • File structure mirrors seed/ directory.
  • Safe to reload repeatedly during development.

See Data folder structure for complete details.

Generated files (gen/)

The gen/ directory contains platform-generated files including dependency caches, fingerprints, and build artifacts.

Key rules:

  • Automatically created by the C3 Agentic AI Platform.
  • Contains performance optimization caches.
  • Stores dependency information to speed up type loading.
  • Generally should not be manually edited.

See Generated folder structure for complete details.

Static resources (resource/)

The resource/ directory contains static files like images, PDFs, and other assets not tied to data models.

Key rules:

  • Optional folder for non-model assets.
  • Accessible as application resources.
  • Useful for bundled documentation, images, and media files.

Web-accessible content (ui/content/)

The ui/content/ directory contains files that are directly accessible from web clients, such as images, stylesheets, and other static assets.

Key rules:

  • Any file type allowed.
  • Publicly accessible from web browsers.
  • Used for UI assets referenced by frontend components.
  • Different from resource/ which is for application-level resources.

How the platform references files

While you organize files in directories on disk, the C3 Agentic AI Platform internally references them using a structured URL format. Understanding this helps you interpret error messages and debug file-related issues.

Internal path format

The platform uses URLs to identify files within packages:

Text
scheme://package/[overlay]/[category]/subpath

This format lets the platform:

  • Distinguish between files in different packages.
  • Mark test-only files that shouldn't deploy to production.
  • Track generated files separately from source files.
  • Reference files from dependency packages.

Path components:

  • scheme: Usually meta:// for package files.
  • package: The package name that owns the file.
  • overlay: Optional modifier (test/, gen/, dep/).
  • category: File category (src/, metadata/, seed/, etc.).
  • subpath: Relative path within the category.

How the platform categorizes files

The C3 Agentic AI Platform assigns each file to a category based on its directory location. Categories determine how files are validated, when they're loaded, and how they impact deployment.

File categories table

CategoryDirectoryPurposeValidation
SRCsrc/Type definitions and implementationsCo-location, naming conventions
TESTtest/src/Test implementationsTest framework patterns
SEEDseed/SeedData type instancesType validation, loaded on app start/upgrade
METADATAmetadata/System integration definitionsType must mixin Metadata
CONFIGconfig/Configuration overridesType must mixin Config
DATAdata/Entity/Persistable type dataType validation, manual load
UIui/UI components and pagesPath patterns, routing
UI_CONTENTui/content/Web-accessible assetsFile type validation
RESOURCEresource/Static assets and filesFile type validation
PACKAGE/ (root)Package manifestJSON schema
CACHEgen/cache/Generated cache filesPlatform-managed

How the platform determines file category

The platform looks at the directory path to assign the category:

  1. If path contains /test/: mark with test overlay.
  2. If path contains /gen/: mark with gen overlay.
  3. Look at first non-overlay directory: that's the category.
  4. Validate file matches category rules.

Examples:

  • /platform/src/User.c3typ: Category: SRC.
  • /platform/test/src/TestUser.c3typ: Category: SRC, Overlay: test.
  • /platform/metadata/Role/Admin.json: Category: METADATA.
  • /platform/gen/cache/fingerprints.txt: Category: CACHE, Overlay: gen.

Validation and loading

The C3 Agentic AI Platform validates files based on their location and uses lazy loading to load files only when needed rather than all at once. This improves performance by avoiding unnecessary work during package initialization.

Why loading differs by file type:

Different types of files are loaded at different times based on when they're typically needed:

  • Source files (Types) are loaded on first access when your code references the Type. This is the most common form of lazy loading.
  • Metadata and configuration are cached when requested, allowing the platform to avoid repeated file reads.
  • Seed data is loaded automatically during first deployment only, using package fingerprints to detect when redeployment is needed.
  • Development data is never loaded automatically. You must explicitly call package.upsertAllSeed() to load it.

Each folder's detailed guide explains its specific validation rules and loading behavior.

Next steps

For detailed information about each folder's rules, validation requirements, and best practices, see the individual folder structure guides:

For UI development, see the "Develop front-end" section of the C3 AI documentation.

Was this page helpful?