Quick Start

This guide walks you through creating a Kinotic App, defining an entity, syncing it with the server, and using the auto-generated service to read and write data.

Prerequisites

• Bun -- Install from https://bun.sh
• bunup -- Used for building TypeScript packages

Install the Kinotic CLI

bun install -g @kinotic-ai/kinotic-cli

Verify the installation:

kinotic --version

Initialize a Project

Create a new directory for your application and initialize it with the CLI:

mkdir my-app && cd my-app
kinotic init --application my.app --entities src/entities --repository src/generated

This creates a .kinotic.json configuration file and sets up the directory structure the CLI expects.

Install Dependencies

bun add @kinotic-ai/core @kinotic-ai/persistence

Define an Entity

Create a file at src/entities/Person.ts:

import { Entity, AutoGeneratedId, NotNull, Precision, PrecisionType, MultiTenancyType } from '@kinotic-ai/persistence'

@Entity(MultiTenancyType.NONE)
export class Person {
    @AutoGeneratedId
    id: string | null = null

    @NotNull
    firstName: string = ''

    @NotNull
    lastName: string = ''

    @Precision(PrecisionType.SHORT)
    age: number = 0
}

A few things to note:

• @Entity(MultiTenancyType.NONE) marks the class as a persisted entity with no multi-tenancy.
• @AutoGeneratedId tells the platform to generate an ID when one is not provided.
• @NotNull enforces that a field must have a value.
• @Precision(PrecisionType.SHORT) tells the platform this number is a short integer, which influences how it is stored and indexed.

Sync with the Server

Push your entity definitions to a running Kinotic OS instance and generate the typed service classes:

kinotic sync -p --server http://localhost:9090

The -p flag publishes the entity definitions so the platform creates the backing storage and registers the services. Sync also generates a complete repository class in the src/generated directory with methods for CRUD operations and querying.

Use the Generated Service

Create a file at src/index.ts to try it out:

import { Kinotic } from '@kinotic-ai/core'
import { PersistencePlugin } from '@kinotic-ai/persistence'
import { PersonRepository } from './generated/PersonRepository'

Kinotic.use(PersistencePlugin)

await Kinotic.connect({
    host: 'localhost',
    port: 58503
})

const personService = new PersonRepository()

// Create a person
const person = await personService.save({
    id: null,
    firstName: 'Jane',
    lastName: 'Doe',
    age: 28
})

console.log('Saved:', person)

// Find all people
const page = await personService.findAll({ page: 0, size: 10 })
console.log('People:', page.content)

Run it with Bun:

bun run src/index.ts

You should see the saved person printed to the console, followed by a page of results containing that person.

What's Next?

Now that you have a working application, explore the rest of the documentation:

• Application Structure -- Understand how organizations, applications, projects, and artifacts are organized.
• Services -- Learn how to publish and consume services across your application.
• Persistence -- Dive deeper into entity definitions, relationships, and querying.