Core Concepts
Forgecroft provides organizational context for autonomous operations — a verifiable, calibrated map of your real systems that agents and humans can query before they act. At its center is a small set of ideas: a handful of nouns and the relationships between them, the same regardless of whether the thing being modeled is application code, infrastructure, a CI pipeline, a container, or a governance rule. Surfaces like the merge gate and the console (below) consume this map; they don’t redefine it.
The core model
Section titled “The core model”The five nouns
Section titled “The five nouns”| Noun | What it is |
|---|---|
| System | A repository or deployable root — a bounded operational domain. The unit you select and scope to (org → project → System); a project owns one or more. Controls and Exceptions attach here. |
| Component | A discrete unit within a System — a module, database, API endpoint, or config file. Carries a vendor reference: an abstract type above, a concrete reference (an ARN, a Kubernetes resource, a file path) below. |
| Control | A constraint governing how Components may change — a naming convention, a deployment gate, a compliance requirement. Has a scope selector, a severity tier, framework mapping (SOC2, NIST, SLSA), and Evidence. |
| Evidence | A traceable artifact proving a Control is satisfied or a relationship exists. Append-only, and carries an expiry — so compliance is continuously re-evaluated, not asserted once. |
| Exception | A documented, time-bound deviation from a Control, with an owner, an approver, a remediation plan, and an expiration. Separation of duties is structural — you cannot approve your own — and there are no permanent Exceptions, only renewals. |
Beyond the five, the graph may carry extension nouns (Identity, Data Asset, Dependency, Environment, Cost) using the same structure.
How nodes are classified
Section titled “How nodes are classified”Every node carries three open fields:
- noun — what the thing is, in your words (“PCI-DSS Scope Boundary”, “Billing API Handler”)
- verb — what it does (“restricts which components may process cardholder data”)
- taxonomy — where it sits in your hierarchy (“compliance/pci/scope”, “core/revenue/billing/api”)
All structural nodes live in one table differentiated by these fields plus a
layer (app code, IaC, CI/CD, container, governance); relationships live in one
edge table with an open vocabulary. The practical consequence: onboarding a new,
different-industry customer is a matter of data, not code — no new schema, no
migration.
Two ideas apply to the whole map rather than a single node:
- Graph-wide rules — constraints that hold across everything (“every System must have an owner”). Distinct from a Control, which constrains a single Component.
- Your data — the model defines the shape; the systems, components, and controls you connect are the content.
What you can do with it
Section titled “What you can do with it”Everything you do with the map falls into one of four questions:
- What’s here? — resolve and browse your systems and their components.
- What do we know, and how sure are we? — query the map and get an honest confidence score, not a guess dressed as certainty.
- What does this change touch, and is it safe? — evaluate a proposed change against your Controls and see its blast radius before you ship.
- Where are we weak? — see where coverage or confidence is thin, and get ranked remediation.
The surfaces that consume the map
Section titled “The surfaces that consume the map”The model above is the same no matter who reads it. Two surfaces put it to work.
Tenancy
Section titled “Tenancy”Everything you connect lives inside a two-level boundary, shared by every surface:
- Organization — the top-level boundary for access control, billing, and ownership. Every object belongs to exactly one. Members have roles: owner, admin, member, reader.
- Project — a grouping of related Systems, separating concerns by team, product, or region. A project is one map; sibling projects stay separate unless you deliberately combine them.
The merge gate
Section titled “The merge gate”The primary surface is the gate that evaluates a change before it merges. On every pull request — or inside an AI coding agent’s loop — Forgecroft matches the changed files to the Components they touch, applies the Controls that govern them, and returns a safe-to-ship verdict with blast radius and honest confidence about what it can and cannot see. The check is deterministic and carries no per-change cost: the same change always produces the same verdict. See the CI Gate and Coding Agents guides.
The console
Section titled “The console”The console is the operator and architect view of the same map. It renders a project’s cross-layer graph — Components across application code, infrastructure, CI/CD, containers, and governance, with the Controls governing them, the Evidence behind those Controls, and any Exceptions in flight — so you can see what is here, where to make a change, and what happens when you do. See Exploring the Graph.