# helocorecorp/bailiwick architecture

> Architecture diagram of the GitHub repository helocorecorp/bailiwick, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/helocorecorp/bailiwick
- Repository: https://github.com/helocorecorp/bailiwick

## Overview

Bailiwick is a typed infrastructure-requirements language and evaluator: users describe workload needs and policies, then compare them with provider offers to get admissibility decisions and reasons. Its principal workflow parses and checks BWK, resolves imports, evaluates each workload against offers, and reports feasibility. Separate capabilities cover importing existing deployment formats, checking Terraform/Kubernetes plans, proving claims across possible offers, issuing offline certificates, exchanging canonical JSON/Protobuf IR, and language-editor support. Some subsystem links are documented only in the README; unsampled implementation details are not inferred.

Main entry points: [`src/main.rs`](https://github.com/helocorecorp/bailiwick/blob/main/src/main.rs) (CLI), [`src/feasibility.rs`](https://github.com/helocorecorp/bailiwick/blob/main/src/feasibility.rs) (Offer evaluator), [`src/lsp.rs`](https://github.com/helocorecorp/bailiwick/blob/main/src/lsp.rs) (Language server), [`src/parser.rs`](https://github.com/helocorecorp/bailiwick/blob/main/src/parser.rs) (BWK parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language core"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_parser["BWK parser<br/>[parser.rs]"]
  node_ast["BWK model<br/>[ast.rs]"]
  node_semantics["Semantic tables<br/>[semantics.rs]"]
  node_checker["Type checker<br/>[check.rs]"]
  node_loader["Import resolver<br/>[loader.rs]"]
end

subgraph group_evaluation["Policy evaluation"]
  node_policy["Policy composition<br/>[policy.rs]"]
  node_feasibility["Offer evaluator<br/>[feasibility.rs]"]
  node_report["Verdict reports<br/>[report.rs]"]
  node_prove["Universal proof<br/>[prove.rs]"]
  node_cert["Certificates<br/>[cert.rs]"]
end

subgraph group_integrations["Infrastructure integrations"]
  node_importers["Deployment importers<br/>[mod.rs]"]
  node_yaml["YAML reader<br/>[yaml_min.rs]"]
  node_hcl["HCL reader<br/>[hcl_min.rs]"]
  node_plancheck["Plan checker<br/>[plancheck.rs]"]
end

subgraph group_interfaces["Tooling interfaces"]
  node_cli["CLI<br/>[main.rs]"]
  node_ir["Canonical IR<br/>[ir.rs]"]
  node_json["JSON codec<br/>[json.rs]"]
  node_proto["Protobuf codec<br/>[proto.rs]"]
  node_lsp["Language server<br/>[lsp.rs]"]
end

node_user(("Engineer"))
node_offers["Offer catalog"]
node_deployment["Deployment files"]
node_plan["Terraform/K8s plan"]

node_user -->|"runs commands"| node_cli
node_cli -.->|"loads BWK"| node_loader
node_loader -->|"parses files"| node_parser
node_loader -->|"checks files"| node_checker
node_parser -->|"tokenizes with"| node_lexer
node_parser -->|"builds model"| node_ast
node_checker -->|"validates against"| node_semantics
node_checker -->|"checks model"| node_ast
node_cli -->|"reads catalog"| node_offers
node_cli -.->|"evaluates workload"| node_feasibility
node_feasibility -->|"applies policies"| node_policy
node_feasibility -->|"uses semantics"| node_semantics
node_cli -->|"shows reasons"| node_report
node_report -->|"formats verdicts"| node_feasibility
node_cli -->|"imports configs"| node_importers
node_importers -->|"reads YAML"| node_yaml
node_importers -->|"reads HCL"| node_hcl
node_deployment -->|"converted from"| node_importers
node_cli -->|"checks plans"| node_plancheck
node_plan -->|"checked against rules"| node_plancheck
node_plancheck -->|"evaluates resources"| node_feasibility
node_cli -->|"proves claims"| node_prove
node_prove -->|"tests offers"| node_feasibility
node_cli -->|"certifies decisions"| node_cert
node_cert -->|"records decisions"| node_feasibility
node_cli -.->|"exchanges IR"| node_ir
node_ir -->|"encodes model"| node_ast
node_ir -->|"serializes as"| node_json
node_cli -.->|"uses codec"| node_proto
node_cli -->|"serves editor"| node_lsp
node_lsp -->|"resolves imports"| node_loader
node_lsp -->|"parses documents"| node_parser
node_lsp -->|"handles JSON-RPC"| node_json

click node_cli "https://github.com/helocorecorp/bailiwick/blob/main/src/main.rs"
click node_lexer "https://github.com/helocorecorp/bailiwick/blob/main/src/lexer.rs"
click node_parser "https://github.com/helocorecorp/bailiwick/blob/main/src/parser.rs"
click node_ast "https://github.com/helocorecorp/bailiwick/blob/main/src/ast.rs"
click node_semantics "https://github.com/helocorecorp/bailiwick/blob/main/src/semantics.rs"
click node_checker "https://github.com/helocorecorp/bailiwick/blob/main/src/check.rs"
click node_loader "https://github.com/helocorecorp/bailiwick/blob/main/src/loader.rs"
click node_policy "https://github.com/helocorecorp/bailiwick/blob/main/src/policy.rs"
click node_feasibility "https://github.com/helocorecorp/bailiwick/blob/main/src/feasibility.rs"
click node_report "https://github.com/helocorecorp/bailiwick/blob/main/src/report.rs"
click node_prove "https://github.com/helocorecorp/bailiwick/blob/main/src/prove.rs"
click node_cert "https://github.com/helocorecorp/bailiwick/blob/main/src/cert.rs"
click node_importers "https://github.com/helocorecorp/bailiwick/blob/main/src/import/mod.rs"
click node_yaml "https://github.com/helocorecorp/bailiwick/blob/main/src/import/yaml_min.rs"
click node_hcl "https://github.com/helocorecorp/bailiwick/blob/main/src/import/hcl_min.rs"
click node_plancheck "https://github.com/helocorecorp/bailiwick/blob/main/src/plancheck.rs"
click node_ir "https://github.com/helocorecorp/bailiwick/blob/main/src/ir.rs"
click node_json "https://github.com/helocorecorp/bailiwick/blob/main/src/json.rs"
click node_proto "https://github.com/helocorecorp/bailiwick/blob/main/src/proto.rs"
click node_lsp "https://github.com/helocorecorp/bailiwick/blob/main/src/lsp.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lexer,node_parser,node_ast,node_semantics,node_checker,node_loader toneBlue
class node_policy,node_feasibility,node_report,node_prove,node_cert toneAmber
class node_importers,node_yaml,node_hcl,node_plancheck toneMint
class node_cli,node_ir,node_json,node_proto,node_lsp toneRose
class node_user,node_offers,node_deployment,node_plan toneIndigo
```

## Components

### Language core

- [Lexer](https://github.com/helocorecorp/bailiwick/blob/main/src/lexer.rs): `src/lexer.rs`
- [BWK parser](https://github.com/helocorecorp/bailiwick/blob/main/src/parser.rs): `src/parser.rs`
- [BWK model](https://github.com/helocorecorp/bailiwick/blob/main/src/ast.rs): `src/ast.rs`
- [Semantic tables](https://github.com/helocorecorp/bailiwick/blob/main/src/semantics.rs): `src/semantics.rs`
- [Type checker](https://github.com/helocorecorp/bailiwick/blob/main/src/check.rs): `src/check.rs`
- [Import resolver](https://github.com/helocorecorp/bailiwick/blob/main/src/loader.rs): `src/loader.rs`

### Policy evaluation

- [Policy composition](https://github.com/helocorecorp/bailiwick/blob/main/src/policy.rs): `src/policy.rs`
- [Offer evaluator](https://github.com/helocorecorp/bailiwick/blob/main/src/feasibility.rs): `src/feasibility.rs`
- [Verdict reports](https://github.com/helocorecorp/bailiwick/blob/main/src/report.rs): `src/report.rs`
- [Universal proof](https://github.com/helocorecorp/bailiwick/blob/main/src/prove.rs): `src/prove.rs`
- [Certificates](https://github.com/helocorecorp/bailiwick/blob/main/src/cert.rs): `src/cert.rs`

### Infrastructure integrations

- [Deployment importers](https://github.com/helocorecorp/bailiwick/blob/main/src/import/mod.rs): `src/import/mod.rs`
- [YAML reader](https://github.com/helocorecorp/bailiwick/blob/main/src/import/yaml_min.rs): `src/import/yaml_min.rs`
- [HCL reader](https://github.com/helocorecorp/bailiwick/blob/main/src/import/hcl_min.rs): `src/import/hcl_min.rs`
- [Plan checker](https://github.com/helocorecorp/bailiwick/blob/main/src/plancheck.rs): `src/plancheck.rs`

### Tooling interfaces

- [CLI](https://github.com/helocorecorp/bailiwick/blob/main/src/main.rs): `src/main.rs`
- [Canonical IR](https://github.com/helocorecorp/bailiwick/blob/main/src/ir.rs): `src/ir.rs`
- [JSON codec](https://github.com/helocorecorp/bailiwick/blob/main/src/json.rs): `src/json.rs`
- [Protobuf codec](https://github.com/helocorecorp/bailiwick/blob/main/src/proto.rs): `src/proto.rs`
- [Language server](https://github.com/helocorecorp/bailiwick/blob/main/src/lsp.rs): `src/lsp.rs`

### Other components

- **Engineer**
- **Offer catalog**
- **Deployment files**
- **Terraform/K8s plan**

## Connections

- Engineer → CLI: runs commands
- CLI → Import resolver: loads BWK
- Import resolver → BWK parser: parses files (evidence: `src/loader.rs`)
- Import resolver → Type checker: checks files (evidence: `src/loader.rs`)
- BWK parser → Lexer: tokenizes with (evidence: `src/parser.rs`)
- BWK parser → BWK model: builds model (evidence: `src/parser.rs`)
- Type checker → Semantic tables: validates against (evidence: `src/check.rs`)
- Type checker → BWK model: checks model (evidence: `src/check.rs`)
- CLI → Offer catalog: reads catalog
- CLI → Offer evaluator: evaluates workload
- Offer evaluator → Policy composition: applies policies (evidence: `src/feasibility.rs`)
- Offer evaluator → Semantic tables: uses semantics (evidence: `src/feasibility.rs`)
- CLI → Verdict reports: shows reasons
- Verdict reports → Offer evaluator: formats verdicts (evidence: `src/report.rs`)
- CLI → Deployment importers: imports configs
- Deployment importers → YAML reader: reads YAML (evidence: `src/import/mod.rs`)
- Deployment importers → HCL reader: reads HCL (evidence: `src/import/mod.rs`)
- Deployment files → Deployment importers: converted from
- CLI → Plan checker: checks plans
- Terraform/K8s plan → Plan checker: checked against rules
- Plan checker → Offer evaluator: evaluates resources (evidence: `src/plancheck.rs`)
- CLI → Universal proof: proves claims
- Universal proof → Offer evaluator: tests offers (evidence: `src/prove.rs`)
- CLI → Certificates: certifies decisions
- Certificates → Offer evaluator: records decisions (evidence: `src/cert.rs`)
- CLI → Canonical IR: exchanges IR
- Canonical IR → BWK model: encodes model (evidence: `src/ir.rs`)
- Canonical IR → JSON codec: serializes as (evidence: `src/ir.rs`)
- CLI → Protobuf codec: uses codec
- CLI → Language server: serves editor
- Language server → Import resolver: resolves imports (evidence: `src/lsp.rs`)
- Language server → BWK parser: parses documents (evidence: `src/lsp.rs`)
- Language server → JSON codec: handles JSON-RPC (evidence: `src/lsp.rs`)
