Skip to main content

Your First Service

This guide walks you through creating a minimal ArkOS microservice from scratch.

1. Define Your Entity in meta/​

Create a YAML definition in meta/entities/:

# meta/entities/product.yml
name: Product
fields:
  - name: id
    type: uuid
  - name: name
    type: string
  - name: price
    type: number
  - name: tenantId
    type: uuid

2. Generate Contracts​

Run arkgen to generate TypeScript contracts:

pnpm generate

This produces typed contracts in @arkos/contracts, including:

  • Entity types
  • Repository interfaces
  • Connector adapters

3. Create the Service Structure​

services/product/
├── src/
│   ├── domain/
│   │   ├── product.entity.ts
│   │   ├── product.errors.ts
│   │   └── usecases/
│   │       └── create-product.usecase.ts
│   ├── data/
│   │   ├── db-create-product.usecase.ts
│   │   └── product.repository.ts
│   ├── application/
│   │   └── product.controller.ts
│   └── platform/
│       ├── postgres-product.repository.ts
│       └── main.ts
└── package.json

4. Implement the Domain Entity​

// src/domain/product.entity.ts
export class Product {
  constructor(
    public readonly id: string,
    public readonly name: string,
    public readonly price: number,
    public readonly tenantId: string,
  ) {
    Object.freeze(this)
  }

  withPrice(price: number): Product {
    return new Product(this.id, this.name, price, this.tenantId)
  }
}

Key rules:

  • Entities are immutable — Object.freeze(this) in every constructor
  • Mutations return new instances, never mutate in place

5. Implement a Use Case​

// src/data/db-create-product.usecase.ts
import { Injectable } from '@arkos/core'
import { ProductRepository } from '../domain/product.repository.ts'
import { Product } from '../domain/product.entity.ts'

@Injectable({ token: 'CreateProductUseCase' })
export class DbCreateProductUseCase {
  constructor(
    @Inject('ProductRepository') private readonly repo: ProductRepository,
  ) {}

  async execute(input: CreateProductInput): Promise<Product> {
    const product = new Product(
      crypto.randomUUID(),
      input.name,
      input.price,
      input.tenantId,
    )
    return this.repo.save(product)
  }
}

6. Bootstrap the Service​

// src/platform/main.ts
import { PlatformService } from '@arkos/core'

PlatformService.launch({
  name: 'product-service',
  port: 3010,
})

7. Run the Service​

pnpm --filter @arkos/product-service dev

Next Steps​