microsoft / microsoft/CCF

Clarify dependencies between framework source components

Open
#3,517 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C++
Stars
876
Forks
260
Avg merge
1d 11h
Merged PRs (30d)
157

Description

## Current status (2026-09-18)

At [`f0ff3f7`](https://github.com/microsoft/CCF/commit/f0ff3f7be), the source-folder include graph has **25 components and 91 direct internal edges**: one **7-component cyclic core** (`common`, `consensus`, `endpoints`, `js`, `kv`, `node`, `service`) and **18 acyclic components**, all 18 with explicit outgoing dependency policies. #8398 took `indexing` out of the core and completed the planned `internal_tables_access.h` relocation; the production graph has not changed since that merge.

**Suggested next cuts:**

1. Finish `common` through or immediately after #8309 by removing the four `node -> common` witnesses, then add its policy. Projected **90 edges, 6 cyclic, 19 acyclic**.
2. Coordinate with #8190 to remove `kv -> {node, service}` by moving node/config integration and service-table-aware deserialisation out of KV core. This frees both `kv` and `service`. Projected, after the `common` cut: **88 edges, 4 cyclic, 21 acyclic**.
3. Put the constitution runtime behind a node-facing interface to remove `node -> js`. Projected **87 edges, 3 cyclic, 22 acyclic**, leaving the explicit `node <-> consensus` and `node <-> endpoints` seams.

See the [latest measured state and cut rationale](https://github.com/microsoft/CCF/issues/3517#issuecomment-5736316570).

## Original scope

The build-time dependency graph between components in CCF has grown messier over time. We originally had `README.md`s in some `src/` folders indicating their intended dependencies, but these have rotted over time.

We should re-evaluate what dependencies we have and can enforce, to keep the code base navigable.

A few high-level goals to start with:
- Public headers should not include any private headers (#2428).
- 3rd party/STL libs are generally useable anywhere/visible everywhere (for instance `nlohmann/json` is used throughout the codebase, including in core containers), with a few exceptions: We should limit visibility of anything platform-specific (including SGX and host-only libraries).
- `ds/` should not depend on anything else. This is a place for generic containers and shims that may be used by multiple other components.
- We should aim to have a set of pure components which depend only on `ds/`. For instance `crypto/`, `tls/`, and `http/` could be written like this - generic protocol implementations and helpers, stripped of platform-integration features.
- Where we have tightly-coupled systems like `kv/` and `consensus/`, we should try to document this coupling to ensure it is required.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Begin with the latest measured state and cut rationale linked in the issue comment, then inspect the src/ component include graph and existing README.md dependency policies. Done means completing an agreed dependency cut and documenting or enforcing the resulting policy, with the projected graph updated.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
build-system, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.