C3 AI Documentation Home

Source folder structure

The src/ folder contains the Type definitions, implementations, and documentation for your package. The C3 Agentic AI Platform reads these files to discover your Types, attach method logic, and load them at runtime. This topic explains what belongs in this folder, why the structure matters, and how the C3 Agentic AI Platform resolves Types across dependencies.

Understand what belongs in src/

The source folder defines the Types and logic for your package. It contains Type definitions, method implementations, and Type-level documentation.

Examples:

Text
src/
  User.c3typ
  User.java

src/order/
  Order.c3typ
  Order.js
  Order.c3doc.md

src/retail/
  Store.c3typ
  Store.Inventory.c3typ
  Store.Inventory.java

Type definition files (*.c3typ)

A Type definition declares fields, methods, annotations, and inner Types. The C3 Agentic AI Platform parses these files to build Type metadata and identify how your Types participate in application logic. To understand the Type System syntax, see Type File Syntax.

Implementation files (.java, .js, .py)

Implementation files contain executable method logic for your Types. The C3 Agentic AI Platform attaches these files to the Type during loading. To learn how to implement methods, see Implement Type Methods, Implement Python Methods, and Implement JavaScript Methods.

Documentation files (*.c3doc.md)

Documentation files describe the Type for developers. The C3 AI Console displays these files when you view the Type. To learn how to document Types, see Document Types and Topics.

How src/ relates to other folders

Several folders depend on the structure and content of your src/ folder.

  • Metadata folder (metadata/) Metadata references Types declared in src/. For example, UI metadata can reference fields or methods from Types declared in this folder. See Metadata Folder.

  • Seed folder (seed/) Seed files create initial instances of Types from src/. The C3 Agentic AI Platform validates seed data against the Type definitions. See Seed Folder.

  • Test folder (test/) Tests run against the Types declared in src/. Any change in this folder affects your tests immediately. See Test Folder.

  • Generated folder (gen/) The C3 Agentic AI Platform generates artifacts such as method stubs or TypeScript declarations based on the .c3typ files in src/. See Gen Folder.

These interactions make the src/ folder the foundation of your package’s behavior.

Structural rules

The C3 Agentic AI Platform enforces structure in the src/ folder to discover Types, validate them, and attach implementations reliably.

Co-location

Type definitions, implementations, and documentation must be in the same directory.

Text
src/models/User.c3typ
src/models/User.java
src/models/User.c3doc.md

If these files are not co-located, the C3 Agentic AI Platform raises an issue during package load. The loader enforces this rule through Pkg.Path.

File naming

File names must match the Type name exactly, including case.

Correct:

Text
User.c3typ
User.js

Incorrect:

Text
user.c3typ
User.js

The C3 Agentic AI Platform cannot load a Type if its file name does not match the Type name.

Inner Types

Inner Types use dotted names to represent hierarchy.

Text
Store.Inventory.c3typ
Store.Inventory.js

To learn more about inner Types, see Inner Types.

Runtime-specific implementations

Some runtimes require specialized logic. You can use runtime suffixes:

Text
User.js-server.js
User.js-browser.js

The C3 Agentic AI Platform selects the correct implementation based on the runtime environment.

How Types are loaded

The C3 Agentic AI Platform loads Types through coordinated file‑change events, remix resolution, and caching. These processes determine which Type definition is active at any time and ensure your changes appear instantly in the Console and APIs.

File change detection, reloading, and cache invalidation

When you add, update, or remove files in src/, Pkg.Store emits events such as ADD, UPDATE, REMOVE, and ISSUE. The loader listens to these events and detects which Types are affected.

When a file changes, the C3 Agentic AI Platform immediately:

  • Revalidates the affected Type.
  • Invalidates any existing cached version of that Type.
  • Rebuilds the Type from its definition and remixes.
  • Updates dependent Types that reference it.

This real‑time feedback loop ensures that the environment stays in sync with your development. Your newly added or modified Types are available for immediate use in the C3 AI Console and through API calls.

Example:

Text
save src/User.c3typ  -> UPDATE event
invalidate User + dependents  -> reload  -> Console uses new shape

Remix collection and ordering

When multiple packages define or extend the same Type, the C3 Agentic AI Platform creates a single effective definition by locating the base definition (earliest in breadth-first dependency traversal) and applying remixes in reverse dependency order—allowing application-level overrides of library-level changes. The result is one composed Type containing all fields, methods, and annotations from the chain.

Example:

Text
Package dependency chain:
yourPkg
 └─ depends on pkgA
        └─ depends on pkgB (defines User base)

pkgB/src/User.c3typ (base definition):

Type
type User {
  id: string
  name: string
  email: string
}

pkgA/src/User.c3typ (remix adds field):

Type
remix type User {
  region: string
  lastLogin: datetime
}

yourPkg/src/User.c3typ (remix adds app-specific field):

Type
remix type User {
  appFlag: boolean
  customerId: string
}

Effective composed Type at runtime:

Type
type User {
  // From pkgB (base)
  id: string
  name: string
  email: string
  
  // From pkgA (first remix)
  region: string
  lastLogin: datetime
  
  // From yourPkg (final remix)
  appFlag: boolean
  customerId: string
}

Each package extends the Type without modifying upstream definitions, and the final Type contains all accumulated fields. If a conflict occurs (for example, two remixes define the same property), the later remix in the dependency order takes precedence.

The loader reports an Pkg.Issue event if it detects incompatible structure or validation problems.

To inspect the final composed Type at runtime, see Type Introspection in the C3 AI Type System.

See also

Was this page helpful?