Applications and Projects

An application is the deployable unit in Kinotic. Projects are the building blocks that make up an application. This page explains how to configure both.

Applications

Every application has:

• Name -- A human-readable name (e.g., Inventory App).
• Id -- Derived from the name at creation: the slugified name, made of lowercase letters, digits, and interior dashes (e.g., inventory-app). The id forms the final label of the application's zone.
• Description -- A human-readable summary of what the application does.

Applications are created and managed through the Kinotic CLI and the Kinotic OS dashboard.

Projects

A project is a directory with its own package.json and a .config/kinotic.config.ts configuration file. The CLI uses that config to understand how the project fits into the broader application.

The .config/kinotic.config.ts File

Every project carries a .config/kinotic.config.ts, created when Kinotic OS provisions the project repository. It is a TypeScript module exporting a KinoticProjectConfig, so your editor type-checks it:

import type { KinoticProjectConfig } from '@kinotic-ai/management-api'

const config: KinoticProjectConfig = {
  organizationId: "my-org",
  applicationId: "my-app",
  projectId: "my-app-main",
  entitiesPaths: [
    {
      path: "packages/domain/model",
      repositoryPath: "packages/domain/repositories",
      mirrorFolderStructure: true
    }
  ],
  fileExtensionForImports: ".js",
  validate: false
}

export default config

The CLI reads the first kinotic.config.* file it finds in .config, so a .js or .json config is loaded the same way.

Fields

Project Dependencies

Projects within the same application can depend on each other. For example, a microservice project might import entity types defined in a persistence project. These dependencies are managed through standard package.json -- you add the dependency just like any other Bun package.

{
    "dependencies": {
        "@my-org/data": "workspace:*"
    }
}

When the application is deployed, the platform resolves these internal dependencies and ensures all projects are available to each other through the Service Directory.

Deployable packages

When a push deploys a project (see Push to Deploy), the platform finds the packages it deploys by where they sit in the workspace:

• Microservices live directly under packages/microservices, one package each. A microservice runs in a VM of its own from its package.json main, or src/main.ts when it declares none.
• UIs live directly under packages/ui, one package each, and declare a build script that writes dist/index.html. A package under packages/ui without a build script is a library and is left alone.

A package's identity is the unscoped part of its package.json name (@acme/admin is admin), which must be lowercase letters, digits, and interior dashes and unique among the packages of its kind. The directory name never matters.

The UI build contract

Every UI is built during the deployment with bun run build, and the build is handed the platform's address as three variables. Vite exposes VITE_* variables to the page on its own, so a Vite project reads them with no configuration; a UI with another build tool must pass them through itself:

await Kinotic.connect({
    server: {
        host: import.meta.env.VITE_KINOTIC_HOST,
        port: parseInt(import.meta.env.VITE_KINOTIC_PORT),
        useSSL: import.meta.env.VITE_KINOTIC_USE_SSL === 'true',
    },
})

A build that does not write dist/index.html fails the deployment naming the UI.

dist is published as it is, from the site's root: files under assets/ carry a content hash in their name and are cached for a year, everything else is never cached. Each site also publishes the commit it serves as version.json next to its index.html, never cached, as { "commitSha": "<commit>" }. A publish replaces the previous commit's files; a tab left open on the previous commit loads the new commit when it next reloads.

Typical Setup

Most applications start with a single project created through Kinotic OS, which provisions a GitHub repository scaffolded as a Bun workspace mono repo: packages/domain (entity model and generated repositories), packages/microservices, packages/ui, and a .config/kinotic.config.ts wired to the owning organization and application. Clone the provisioned repository and start building.

As the application grows, you can add additional projects for microservices, batch jobs, or frontends -- each with its own .config/kinotic.config.ts pointing to the same application identifier.