Architecture

[mkovaxx]

Architecture

This discussion is meant to document and evolve the high-level architecture of Anodized, starting with the separation between the anodized and anodized-core crates.

Crate Separation

The split between anodized and anodized-core is primarily structural:

• anodized is a proc-macro crate. As such, it cannot serve as a normal library that other components depend on.
• anodized-core is a normal library crate, intended to host all reusable logic and APIs for component integration.

The guiding rule is therefore:

• anodized contains only the proc-macro entry points and minimal glue.
• Everything else lives in anodized-core, where public vs private boundaries can evolve without reorganizing crates.

This keeps the proc-macro crate thin and stable, and avoids baking proc-macro-specific constraints into reusable logic.

Facilities Provided by anodized-core

anodized-core is designed around a simple taxonomy of use cases for working with #[spec]-annotated Rust code:

1. Consume
   Parse #[spec]-annotated Rust code without reimplementing Anodized's understanding of specs.
   This includes lifting syn structures into Anodized's own representation (currently Spec).

2. Transform
   Operate on Rust syntax informed by spec data.
   Existing runtime instrumentation is one example of this, but the intent is broader: alternative instrumentation, code generation, analysis, etc.

3. Produce
   Generate #[spec]-annotated Rust code programmatically.
   While not implemented yet, this should mirror the consumption side by lowering Anodized representations back into syn structures.

With this framing:

• syn is the shared syntax-level abstraction, since specs are annotations on Rust code.
• Anodized's own representations (e.g. Spec) capture the semantic meaning of those annotations.
• The proc macro is just one frontend that depends on this functionality.

Goals of This Discussion

This thread is intended to:

• document these architectural choices explicitly,
• gather feedback on the existing design and mental model,
• and serve as a reference point as the public API of anodized-core evolves.

Further design details can build on this foundation.