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

# Architecture

> ubx compiler internals and codebase structure.

ubx is a Go application organised as a single-pass compiler followed by Pulumi Automation API orchestration.

## Repository Structure

```
ubx/
  cmd/                    # CLI commands (cobra)
    root.go               # root command, global flags
    apply.go              # ubx apply
    plan.go               # ubx plan
    validate.go           # ubx validate
    fmt.go                # ubx fmt
    explain.go            # ubx explain (AI)
    fix.go                # ubx fix (AI)
    ...
  internal/
    compiler/
      lexer/              # tokenizer
      parser/
        ast/              # AST node types
        parser.go         # recursive descent parser
      typechecker/        # symbol resolution, `Pending<T>` tracking
      codegen/            # TypeScript emitter
        emitter.go
        registry.go       # resource type → TS class mapping
      formatter/          # ubx fmt
      merger/             # extend block merging
      schema/             # provider schema registry
    ai/                   # AI client (net/http → Anthropic API)
    config/               # ubx.yaml parsing
    ignore/               # .ubxignore implementation
    pulumi/               # Automation API wrapper
    testing/              # ubx test framework
  examples/               # example .iac projects
  ARCHITECTURE.md
  CLAUDE.md               # AI session context
  Technical_Reference.md
```

## Compiler Pipeline

```
Source (.iac files)
  → Lexer       (internal/compiler/lexer/)
  → Parser      (internal/compiler/parser/)
  → Merger      (internal/compiler/merger/)
  → TypeChecker (internal/compiler/typechecker/)
  → CodeGen     (internal/compiler/codegen/)
  → index.ts    (written to .ubx/)
  → pulumi up   (internal/pulumi/ via Automation API)
```

## Key Design Decisions

* **No TypeScript runtime dependency** — users write `.iac`, TypeScript is a build artifact
* **No external AI SDK** — `net/http` only for Anthropic API calls
* **Pulumi Automation API** — replaces all `exec.Command("pulumi", ...)` subprocess calls
* **Single label for `component`** — `source` attribute is the type identifier
* **`output` not `export`** — familiar to Terraform users

## Adding a New Resource Type

See [Adding Resources](/v1/contributing/adding-resources).

## Adding a New CLI Command

1. Create `cmd/<command>.go`
2. Define a `cobra.Command` with `Use`, `Short`, `RunE`
3. Register in `cmd/root.go` via `rootCmd.AddCommand()`
4. Write tests in `cmd/<command>_test.go`