Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Crucible is a service framework that manages API lifecycles through a central Intermediate Representation (IR). It utilizes a modeling language front end (.cru) to define services, which it subsequently lowers into a validated IR. This IR serves as the single source of truth for generating server runtimes, native client SDKs, documentation, and infrastructure-as-code (IaC) providers. Sources: AGENTS.md:3-8, crates/crucible-cli/src/main.rs:16-18
The project architecture emphasizes deterministic output and shared semantics. A central goal is ensuring that nullability, effective constraints, HTTP bindings, and pagination rules remain consistent across all generated targets by settling their logic once within the IR layer. Sources: AGENTS.md:104-108, AGENTS.md:121-122
Core Components and Boundaries
The Crucible ecosystem consists of several specialized crates that handle distinct phases of the API development pipeline.
System Pipeline Flow
The following diagram illustrates the data flow from source model to generated artifacts.
This flow ensures that all generators consume the same validated semantics while allowing for audience-specific projections. Sources: AGENTS.md:46-77, crates/crucible-cli/src/main.rs:495-502
Component Responsibilities
| Crate | Responsibility |
|---|---|
crucible-lang | Lexing, parsing, name resolution, and lowering .cru to IR. |
crucible-ir | Shared Intermediate Representation, validation, and release snapshots. |
crucible-server-runtime-rust | Core Rust server framework, protocols, and pipeline orchestration. |
crucible-codegen-* | Language-specific logic for mapping IR to native code or artifacts. |
crucible-cli | Primary interface for checking models and triggering generation. |
Sources: AGENTS.md:48-77
The Intermediate Representation (IR)
The IR is the stable boundary between model definitions and generation logic. It settles all model semantics, including effective constraints and timestamp formats, to prevent generators from re-deriving logic inconsistently. Sources: AGENTS.md:104-108
Projection and Audience
Crucible supports audience-specific views of the IR. The Audience parameter (External or Internal) filters API elements based on visibility markers like @internal. The system projects the IR to these views before passing them to generators to ensure public artifacts omit private members and operations. Sources: crates/crucible-cli/src/main.rs:125-131, crates/crucible-cli/src/main.rs:518-522
Code Generation Architecture
Generators follow target-language conventions while maintaining consistency through crucible-codegen-common.
Shared Codegen Logic
The crucible-codegen-common crate provides utilities shared by all generators:
- Guide Generation: Standardized templates for
README.mdandAGENTS.mdacross all SDKs. Sources: crates/crucible-codegen-common/src/guide.rs:1-12 - Escaping and Redaction: Unified rules for doc-comment escaping and
@sensitivedata redaction. Sources: AGENTS.md:71-74, crates/crucible-codegen-common/src/guide.rs:141-160 - Schema Descriptions: Compact wire semantics for bundled client runtimes. Sources: AGENTS.md:71-73
Language-Specific Mapping
Each language generator maps IR shapes to native types. For example:
- Go: Structures map to pointers, simple types map to Go primitives (e.g.,
Longtoint64), and members use accessor methods (Set,Get,Has). Sources: crates/crucible-codegen-go/src/lib.rs:77-111, crates/crucible-codegen-go/src/lib.rs:144-147 - TypeScript: Acronyms are handled for method naming (e.g.,
SQLQuerybecomessqlQuery), and globals are accessed viaglobalThisto avoid shadowing. Sources: crates/crucible-codegen-ts/src/names.rs:24-30, crates/crucible-codegen-ts/src/names.rs:66-84
CLI and Development Workflow
The crucible-cli provides the main developer interface for model validation and artifact creation.
Command Execution Sequence
The CLI dispatches commands that interact with the model and generators.
Stability and Freezing
Crucible uses a "freezing" mechanism to ensure backward compatibility. Developers freeze a model's release as a snapshot (releases/<version>.json). The CLI's diff and check commands use these baselines to detect breaking changes that lack corresponding migrations. Sources: crates/crucible-cli/src/main.rs:107-115, crates/crucible-cli/src/main.rs:643-678
Summary
Crucible's architecture centers on the crucible-ir as a strictly versioned and validated contract. By consolidating complex semantics into this shared layer, the project allows for a diverse ecosystem of generators that produce native-feeling code without sacrificing cross-language consistency. The system enforces strict boundaries through automated policy checks and frozen baselines, enabling reliable evolution of large-scale service models. Sources: AGENTS.md:46-77, AGENTS.md:104-108