GoCPG parses source files and builds a Code Property Graph (CPG). The graph connects declarations, calls, types, control flow and data flow to locations in source files. This section helps integration developers, architects and operators choose an engine interface, interpret analysis results and find instructions for a specific check.
GoCPG runs inside CodeGraph and also provides its own CLI and gRPC server. Read the CPG explanation for the graph model. The separate Rabotnik + GoCPG offering is described at codegraph.tech.
From source files to results
- A language frontend extracts declarations, expressions, calls and syntax edges.
- Analysis passes add types, resolved calls, control flow and data flow.
- GoCPG stores the graph in DuckDB. The language and profile determine which passes run.
- Queries and rules use the graph to find entities, relationships and violations.
- A client receives structured results with source locations.
For example, a call to an imported Python function, helpers.format_greeting, in
service.py starts as a syntax node. Import and call resolution connect it to the
declaration in helpers.py. An architecture rule can then check the dependency
between the components containing those files. An unresolved call target is an
analysis limitation that must be considered when assessing result completeness.
What the engine checks
| Task | Read | Boundary |
|---|---|---|
| Understand the graph model and semantic passes | GoCPG internals and comparison with Joern | Language support does not imply equal precision for every pass. |
| Find a syntax pattern or apply a YAML rule | Structural search | Source search and CPG scanning require different inputs. Rewriting is a separate action. |
| Define components and dependency constraints | Architecture model and rules | An unselected rule or incomplete input is not a successful check. |
| Run an architecture check | Execution and governance | A command exit code alone does not prove release permission. |
| Read a stored run or export findings | Interfaces and results | The run ID must identify a run stored in the selected database. |
Static analysis does not execute the program. Dynamic imports, generated code, reflection and missing source files can limit relationship resolution. Check the parse scope, errors, selected rules and completeness indicators. Without that context, an empty findings list does not establish that the code has no defects.
Interfaces and getting started
The CLI operates on source files and a local database. gRPC lets a client application run operations and receive typed results. The gRPC reference distinguishes remote method contracts from the CodeGraph Python client. The client belongs to the platform integration; its settings are not GoCPG server flags. The platform’s REST and MCP surfaces are also separate from the engine interfaces.
Examples require a compatible GoCPG binary. In a CodeGraph source checkout, open PowerShell at the repository root and inspect the available commands:
.\gocpg\gocpg.exe --help
.\gocpg\gocpg.exe architecture --help
The first command lists engine commands. The second lists architecture subcommands,
including validate, describe and explain. If the binary or command is missing,
follow the environment setup.
This checks a local installation; it does not promise a ready standalone distribution.
For a reproducible analysis, follow the complete
worked run.
Storage and operation
GoCPG owns writes to the project DuckDB. Service consumers read through gRPC; local SQL is for diagnostics. Do not run competing writers against the same database file. The storage reference describes architecture result tables and explains why missing findings and missing data mean different things.
General CodeGraph material retains its own reader task and section: installation, CPG audit, and Dashboard methodology.
Responsibilities of GoCPG and CodeGraph
| GoCPG | CodeGraph |
|---|---|
| Parsing, graph construction and graph updates | Repository integration and development workflows |
| Queries, navigation, rules and analysis results | Audits, scenarios, REST/MCP and user-facing results |
| Findings, source locations and analysis completeness | Dashboard scores, tasks, accountable owners and change acceptance |
GoCPG architecture statuses describe a check of a supplied policy and its inputs. They do not close a development task or replace the release owner’s decision in a consuming platform. This boundary lets other applications use the engine while keeping their own workflow and acceptance rules.