The crate hierarchy

Introduction

Navree isn't one big crate. It's a workspace of small crates, one per module, arranged in layers from L0 (the kernel and the macros) to L6 (the navree facade and the CLI), with applications on top. A crate may depend only on crates in lower layers, and only on the ones its layer is allowed to use. A test checks every dependency edge in the workspace each time the tests run.

This keeps the framework honest: the kernel knows nothing about HTTP, HTTP knows nothing about databases, and authentication builds on everything else rather than the other way round. You can read, test or use any crate with only what's below it. Most apps never see the split, because they depend on the facade, but it explains why things are where they are.

The layers

L7  apps/crm-api (Navree app)                    apps/crm-web (Next.js 16)
L6  navree (facade: re-exports + prelude)        navree-cli (binary `navree`; no runtime navree deps)
L5  navree-auth
L4  navree-session  navree-validation  navree-queue  navree-audit  navree-access  navree-schedule  navree-notify
L3  navree-db  navree-testing  navree-observe  navree-api  navree-mail  navree-realtime  navree-storage
L2  navree-http  navree-log  navree-crypto  navree-events  navree-view  navree-cache  navree-http-client
L1  navree-contracts  navree-config
L0  navree-kernel                                navree-macros (proc-macro; no runtime navree deps)

The allowed edges

"Lower layers only" is the shape of the rule, but each crate has an explicit list of the Navree crates it may depend on. A layer-4 crate can't reach for any layer-3 crate it fancies; it gets the ones it needs, and adding one is a deliberate change to the list.

The lists are what's allowed; some crates use less (navree-access doesn't use the cache today, and navree-auth doesn't use sessions). navree-config may use navree-contracts, which sits in the same layer; that's the one edge between crates of one layer.

Two exceptions apply to dev-dependencies, so tests can boot what they need:

• A crate's tests may use any Navree crate in a lower layer. That's how every crate from L4 up tests with navree-testing (L3), and how navree-notify's tests boot ViewModule for MailModule.
• navree-macros may dev-depend on any runtime crate, because its tests expand the macros against the crates the generated code calls.

The framework's own crates implement Module, Injectable and Controller by hand instead of using the macros. The macros sit at L0 with no runtime dependencies, and the generated code names whichever crates the user's crate depends on.

Cross-cutting needs: navree-contracts

Some needs cut across modules. The HTTP pipeline records refused requests in the audit trail; notifications broadcast to WebSocket channels; the database layer hands jobs to the queue after a commit. Letting navree-http depend on navree-audit would point up the hierarchy.

Instead, the shared shape lives in navree-contracts (L1) as a trait. One module implements it and registers it as a dyn Trait provider; the others resolve it, usually as optional:

Two plain types live there too: RequestId, which the HTTP pipeline creates for each request and which logs and audit entries carry, and Secret<T>, the wrapper configuration structs use for keys and passwords so they never show up in logs.

Your own code can use the contracts the same way. This function audits an export when the app has an audit trail, and does nothing otherwise:

use navree::contracts::{AuditEntry, AuditKind, AuditSink};
use navree::prelude::*;
use uuid::Uuid;

pub async fn record_export(ctx: &AppContext, user: Uuid) -> Result<(), BoxError> {
    if let Some(audit) = ctx.try_get::<dyn AuditSink>().await {
        let entry = AuditEntry::new(AuditKind::Custom, "contacts.exported").actor(user);
        audit.record(entry).await?;
    }
    Ok(())
}

And a service that must broadcast can inject the contract instead of the realtime module's types:

use navree::contracts::Broadcaster;

#[injectable]
pub struct DealBroadcasts {
    broadcaster: Arc<dyn Broadcaster>,
}

impl DealBroadcasts {
    pub async fn updated(&self, deal: serde_json::Value) -> Result<(), BoxError> {
        self.broadcaster
            .broadcast(
                vec!["private-crm.deals".to_owned()],
                "deal.updated".to_owned(),
                serde_json::json!({ "deal": deal }),
            )
            .await
    }
}

Two seams aren't in navree-contracts because they need HTTP types: Authenticator and RouteAuthorizer live in navree-http. navree-auth implements the first and navree-access the second, and the pipeline resolves both as dyn providers.

The dependency-graph test

crates/navree/tests/dependency_graph.rs encodes the table above, one row per workspace crate. Run it on its own:

cargo test -p navree --test dependency_graph

It reads the workspace with cargo metadata and checks that:

• every dependency edge between workspace crates (normal, dev and build) is allowed;
• every workspace crate has a row, and every row is a workspace crate;
• the table itself never points upwards and has no cycles;
• Cargo.lock contains none of aws-lc-sys, aws-lc-rs, aws-lc-fips-sys, openssl, openssl-sys, native-tls or cmake: TLS is rustls with the ring provider everywhere, so building needs no C toolchain beyond what SQLite uses.

A forbidden edge fails with a message that says what the crate may use instead:

crate hierarchy violations (spec §3):
  navree-http (L2) -> navree-crypto (L2) (Normal) is not an allowed edge; navree-http may depend on: [navree-kernel, navree-contracts, navree-config]

The CRM is in the table too: crm-core at L7, crm-testkit at L8, the feature crates (crm-users, crm-companies, crm-deals, crm-activities) at L9 and the crm-api binary at L10. They may depend only on the navree facade and the CRM crates below them.

Two more tests in crates/navree/tests/facade.rs keep the facade's features in step with the hierarchy.

Applying the idea to your app

The same discipline works for an application. The CRM's feature crates all build on crm-core, which holds the shared entities, migrations, abilities and platform setup, and none of them depends on another feature crate. When two features need to cooperate, they do it through something lower down: an event, a trait in the shared crate, or a service the shared crate exports. Inside a single crate, modules give you the same structure: a feature imports only what it uses, and the boot fails when it reaches for something it didn't import.