> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrakairo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Kairo Language Syntax: Modules, Imports, and Structure

> Learn Kairo syntax: declare modules, write imports, control visibility, and structure source files for readable, maintainable codebases.

Kairo uses a clean, brace-based syntax inspired by languages like C#, Kotlin, and Swift. Every construct uses `{}` blocks for scope, statements terminate at newlines without semicolons, and the language enforces explicit structure to keep large codebases predictable and navigable. If you have written code in any modern statically-typed language, Kairo's syntax will feel immediately familiar — while its business-domain-first conventions give your code a distinctly readable shape.

## Modules and File Structure

Every `.ak` file declares exactly one module using the `module` keyword at the top of the file. A module name uses dot-separated Pascal-case segments and should reflect the business or technical domain the file represents.

```kairo theme={null}
module Demo.App
```

<Note>
  A file must contain exactly one `module` declaration, and it must appear before any imports or declarations. Omitting a module declaration is a compile error.
</Note>

Module names are dot-separated identifiers and typically mirror your project's logical namespace hierarchy. There is no requirement that module names map directly to file-system paths, but keeping them aligned makes projects easier to navigate.

## Import Statements

Use `import` to bring another module's public declarations into scope. Kairo does not support wildcard imports — every import names a specific module explicitly.

```kairo theme={null}
import Astra.Data
```

### Import with Alias

When two modules share a common short name, or when you simply want a shorter qualifier, use `as` to assign a local alias:

```kairo theme={null}
import Astra.Data as Data
```

After this, you can refer to `Data.SomeType` rather than `Astra.Data.SomeType`.

### Type-Only Import

Use `import type` when you only need a specific type from a module — for example, to reference it in a signature without pulling in all of the module's declarations:

```kairo theme={null}
import type Astra.UIX.Button
```

<Tip>
  Prefer `import type` for UI or infrastructure types that appear only in signatures. It communicates intent clearly and keeps the module's dependency surface minimal.
</Tip>

Here is a complete file header showing all three import forms together:

```kairo theme={null}
module Orders.Checkout

import Astra.Data as Data
import type Astra.UIX.Button
import Payments.Gateway
```

## Visibility Modifiers

Kairo has three visibility levels. The default — used when you write no modifier at all — is `internal`.

| Modifier   | Scope                                             |
| ---------- | ------------------------------------------------- |
| `public`   | Accessible to any module that imports this one    |
| `internal` | Accessible only within the same package (default) |
| `private`  | Accessible only within the declaring type or file |

```kairo theme={null}
module Demo.Visibility

// Visible to all importers
public value ProductId {
    value: Text
}

// Visible only within this package (default — no keyword needed)
value CartLine {
    productId: ProductId
    quantity: Int32
}

public object Cart {
    id: CartId

    // Visible only inside Cart
    private var lineCount: Int32

    init(id: CartId) {
        this.id = id
        this.lineCount = 0
    }
}
```

<Note>
  `private` on a type member restricts access to the declaring type itself. `private` on a top-level declaration restricts access to the declaring file. You cannot use `private` as a package-level modifier — that is what `internal` (the default) is for.
</Note>

## Statement Termination

Kairo does not use semicolons. Each statement ends at the newline. This keeps code vertically readable and avoids the noise of trailing punctuation.

```kairo theme={null}
let name: Text = "Kairo"
let version: Int32 = 1
```

Placing two statements on a single line is not supported — each statement occupies its own line.

## Keywords and Contextual Keywords

The following identifiers are reserved as keywords and cannot be used as names:

<CodeGroup>
  ```text Declaration keywords theme={null}
  module  import  value  object  contract  enum
  public  internal  private
  init  func  let  var
  async  await
  ```

  ```text Control flow keywords theme={null}
  if  else  for  while  match  return
  ```

  ```text Literal keywords theme={null}
  true  false  null  not
  ```
</CodeGroup>

The following identifiers are **contextual keywords** — they carry special meaning in certain positions but can appear as regular identifiers elsewhere:

```text theme={null}
as   type   get   set   this
```

## File Naming Conventions

Kairo source files use the `.ak` extension. File names must be **lowercase kebab-case**:

| ✅ Valid               | ❌ Invalid            |
| --------------------- | -------------------- |
| `customer-service.ak` | `CustomerService.ak` |
| `order-checkout.ak`   | `orderCheckout.ak`   |
| `product.ak`          | `Product.ak`         |

Keeping file names lowercase and hyphenated makes projects portable across case-sensitive and case-insensitive file systems and avoids ambiguity when multiple developers work on the same codebase.

## Putting It All Together

Here is a small but complete `.ak` file that demonstrates every structural element covered on this page:

```kairo theme={null}
module Orders.Confirmation

import Astra.Data as Data
import type Astra.Notifications.EmailSender

public value OrderId {
    value: Text
}

public value ConfirmationResult {
    orderId: OrderId
    confirmedAt: DateTime
}

public object ConfirmationService {
    private var sender: EmailSender

    init(sender: EmailSender) {
        this.sender = sender
    }

    public func confirm(orderId: OrderId): ConfirmationResult {
        let result = ConfirmationResult {
            orderId: orderId
            confirmedAt: DateTime.now()
        }
        return result
    }
}
```

<Tip>
  Notice that the file name for this module would be `confirmation.ak` or `order-confirmation.ak` — lowercase kebab-case, ending in `.ak`.
</Tip>