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

# CUE and StackKits architecture

> How CUE schemas power the StackKits validation and generation system

StackKits use CUE as their schema language. Understanding this architecture helps you customize kits and create your own.

## Why CUE?

CUE (Configure, Unify, Execute) provides something that YAML and JSON Schema cannot: **types, constraints, and composition** in a single language.

```cue theme={null}
// CUE catches errors that YAML cannot
#Service: {
    name:    string & =~"^[a-z][a-z0-9-]*$"
    port:    int & >0 & <65536
    enabled: bool | *true  // default: true
}
```

**Key advantages:**

* **Type safety** — Catch configuration errors before deployment
* **Composable** — Kits can extend and override each other
* **Defaults** — Sensible defaults reduce configuration burden
* **Constraints** — Express rules like "port must be > 1024" or "domain must be valid"

## Three-layer architecture

Every StackKit follows a three-layer model:

```mermaid theme={null}
graph TB
    subgraph App["Application Layer"]
        S1["Traefik"]
        S2["Immich"]
        S3["Authelia"]
    end

    subgraph Platform["Platform Layer"]
        Docker["Docker Compose"]
        Networks["Networks"]
        Volumes["Volumes"]
    end

    subgraph OS["OS Layer"]
        Ubuntu["Ubuntu Baseline"]
        Security["Security Hardening"]
        Networking["Networking"]
    end

    App --> Platform --> OS

    style App fill:#1e293b,stroke:#38bdf8,color:#f8fafc
    style Platform fill:#1e293b,stroke:#fbbf24,color:#f8fafc
    style OS fill:#1e293b,stroke:#4ade80,color:#f8fafc
```

1. **OS Layer** — Base operating system configuration, security hardening, networking
2. **Platform Layer** — Container runtime (Docker Compose), standard networks, volumes
3. **Application Layer** — Modular services that users select and configure

## How validation works

When you run `stackkit validate`, your `stack-spec.yaml` is checked against the CUE schema of your selected StackKit:

<Steps>
  <Step title="Schema loading">
    The StackKit's CUE schema is loaded, including all layer definitions and constraints.
  </Step>

  <Step title="Unification">
    Your configuration is unified with the schema. CUE checks that every value satisfies its type and constraints.
  </Step>

  <Step title="Default resolution">
    Missing optional values are filled with CUE defaults.
  </Step>

  <Step title="Error reporting">
    Any validation errors are reported with clear messages indicating what went wrong and where.
  </Step>
</Steps>

## Extending kits

StackKits are designed to be extended. You can:

* **Override defaults** — Change any default value in your `stack-spec.yaml`
* **Add services** — Include additional services not in the base kit
* **Customize layers** — Modify OS or platform settings for your environment

## Further reading

<CardGroup cols={2}>
  <Card title="Spec-driven design" icon="file-code" href="https://docs.kombify.io/stackkits/reference/spec-format">
    The philosophy behind declarative infrastructure
  </Card>

  <Card title="Available kits" icon="boxes-stacked" href="https://docs.kombify.io/stackkits/overview">
    Browse the StackKit catalog
  </Card>
</CardGroup>