Repository layout and code layering

BlockX is a single Go repository (module name github.com/Chaintable/blockx); python/ holds the Python executor, SDK, and auditor. This page helps you find your way around the code quickly once you have the repository; for the system-level division of responsibilities, see Architecture overview.

blockx/
├── AGENTS.md                 # Repo-level collaboration and directory conventions (CLAUDE.md is just a pointer to it)
├── Makefile                  # proto generation, fmt/vet, go test with coverage
├── Dockerfile                # Multi-stage build: Go binaries + python:3.12 runtime image
├── test.sh                   # Runs e2e/perf under systemd cgroup constraints
├── analyze_spans.py          # Aggregates span JSONL exported by Go/Python into a trace tree
├── api/                      # Protocol definitions shared across modules; data structures and codecs only
│   ├── etcd/                 # Worker heartbeat structs, registry prefix parsing
│   ├── grpc/                 # .proto files and generated code for worker / coordinator / bundlecoordinator / syncinvoker
│   └── uds/                  # UDS message envelope and codec between Worker and Python Executor
├── cmd/                      # Process entry points; only app.Profile manifests and main
│   ├── worker/               # Full block worker (includes process-level e2e tests)
│   ├── bundle_worker/        # Bundle pool worker; registers only bundle-related builders/plugins
│   ├── coordinator/          # Block Coordinator
│   ├── bundle_coordinator/   # Bundle Coordinator
│   ├── syncinvoker/          # Sync invocation service; assembly logic lives directly in this directory
│   ├── perf/                 # CLI for load-testing a live deployment
│   ├── bundle-loadgen/       # Load-test CLI that submits synthetic tasks through the bundle coordinator
│   └── blockdb_grpc_stub/    # BlockDB gRPC stub service for benchmarks
├── internal/                 # Implementation code
│   ├── worker/               # Worker: core/ (Sans-IO) + adapters/ + app/ + devstub/
│   ├── coordinator/          # Coordinator: core/ + adapters/ + app/
│   ├── syncinvoker/          # sync-invoker: core/ + adapters/
│   ├── functioncode/         # Function Code View: core/ + adapters/{redis,blockdb} + audit/
│   ├── io/                   # IO access subsystem (scope-oriented): core/ assembly/ cache/ quota/ sflight/ adaptive/ capabilitywire/
│   ├── plugin/               # Call Builder (callbuilder/) and Writer Plugin (event/) + schema/
│   ├── sdk/                  # Backend clients: blockdb / noderpc / meta / logicaltypes / iceberg / router / localtestservice / grpcclient
│   ├── duckdb/borrowed/      # Low-allocation read layer on top of the DuckDB native bindings
│   ├── obs/                  # Logging, Prometheus metrics, OpenTelemetry tracing
│   ├── usage/                # Usage collection and Kafka publishing
│   ├── common/               # Shared types such as TaskID/Stage, clientid, argspool, unsafebytes
│   └── testutil/             # Process-level test scaffolding: spawns etcd/worker/coordinator subprocesses
├── python/                   # uv-managed Python project (pyproject.toml)
│   ├── blockx_executor/      # Executor process: UDS session, greenlet runtime, SDK bridge
│   ├── blockx_sdk/           # Lightweight SDK for function code (db / rpc / sleep / call_subfunc)
│   ├── blockx_audit/         # Pure-stdlib static auditor and framed daemon
│   └── tests/                # unittest unit tests
├── e2e/                      # Cross-component Go E2E: contract/ system/ perf/
├── examples/local_test_service/  # Example that submits a task to a local worker with blockx-py
├── deploy/                   # EC2 systemd + nerdctl deployment scripts, env examples, and script tests
└── docs/                     # deploy.md, capability-backend-guide.md, specs/ (design docs)

Layering conventions

AGENTS.md defines the directory skeleton, and docs/specs/code-style.md expands it into checkable implementation constraints. The key points:

cmd/: assembly and startup only. The Worker and Coordinator entry points are an app.Profile manifest plus a single app.Run(...) line; workerProfile() in cmd/worker/main.go lists Deployment, Service, WorkerRegistryPrefix, UsageService, Builders, and Plugins, while cmd/bundle_worker/main.go just swaps in a different manifest and adjusts defaults through TuneDefaults. Assembly order, shutdown order, and config parsing live in internal/worker/app/ and internal/coordinator/app/; they must not be copied per entry point.
internal/<module>/core/: Sans-IO domain logic. State machines, idempotency decisions, phase advancement, and result convergence all live here, for example WorkerCore in internal/worker/core/worker.go and DispatcherCore in internal/worker/core/dispatcher.go.
internal/<module>/adapters/: side effects such as transport, storage, clocks, logging, and metrics. For example internal/worker/adapters/grpc_server.go, etcd_publisher.go, orchestrator*.go, and the subpackage internal/worker/adapters/executor/ (UDS executor adapter and process pool).
internal/<module>/app/: assembly and configuration. WorkerFullConfig in internal/worker/app/config.go is the source of truth for configuration; app.go builds the builder/plugin registries and IO backend modules according to the Profile and chains startup and shutdown together.
Scope-oriented modules: internal/io/ does not use an event/command core; instead it uses WorkerIOScope (internal/io/core/worker_scope.go) and TaskIOScope (internal/io/core/task_scope.go) to bind quota, cache, singleflight, and cleanup to the scope lifecycle.
api/: protocol structs, message envelopes, and field conventions shared across modules. Side-effect-free validation and codec helpers are allowed; handlers, storage models, and state machines are not.
python/: not directly governed by code-style.md; see python/README.md and AGENTS.md for run and test commands.

The dependency rules for the three layers in code-style.md §3 and §5 can be summarized in one paragraph: core/ must not reference gRPC, etcd clients, database clients, logging implementations, or metrics implementations; it does not read the clock, generate random values, or start goroutines on its own, and avoids taking context.Context where possible. Cancellation, timeouts, and TTL expiry are all passed in as explicit inputs, and the output is an enumerable set of commands, decision results, or state snapshots. adapters/ own all IO and concurrency, translate core commands into side effects, and repackage timers, executors, plugins, and IO callbacks as core events. app/ and cmd/ only do assembly, with no domain decisions, admission policy, or protocol-semantics branches. When an adapter calls core it depends on the concrete types directly (WorkerCore, CoordinatorCore); no extra interface is abstracted for core.

Module index

Site page links point to the corresponding component page; “Main spec” refers to files under docs/specs/ in the blockx repository.

`cmd/`

Directory	Purpose	Component page	Main spec
`cmd/worker/`	Entry point for the full block worker; the `Profile` registers the dbscan/call_list/bundlescan and devstub builders plus four writer plugins. The `worker_process_*_test.go` files in the same directory are the Worker process-level E2E tests	Worker	`worker.md`, `worker-test-organization.md`
`cmd/bundle_worker/`	Entry point for the bundle pool worker; registers only `BuilderBundleScan`/`BuilderCallList` and `PluginBundleWrite`/`PluginTableUpserts`, and `TuneDefaults` turns on stream build	Bundle clusters	`2026-07-21-block-bundle-clusters.md`
`cmd/coordinator/`	Entry point for the block Coordinator; watches the legacy block registry prefix	Coordinator	`task-resource-coordinator.md`
`cmd/bundle_coordinator/`	Entry point for the bundle Coordinator; watches the legacy and prod-default bundle registry prefixes	Bundle clusters	`2026-07-23-bundle-coordinator-api.md`, `2026-07-28-registry-prefix-migration.md`
`cmd/syncinvoker/`	Entry point for the sync invocation service. The assembly code (`config.go`, `io.go`, `function_code.go`, `health.go`) lives directly in this directory; there is no separate `app/` package	Sync Invoker	`sync-invoker.md`
`cmd/perf/`	CLI that runs reserve/submit/poll load tests against a live deployment and reports P50/P90/P99	Testing	`perf-methodology.md`
`cmd/bundle-loadgen/`	Submits synthetic tasks through the bundle coordinator to measure bundle worker throughput; `cgroup-snapshot.sh` samples cumulative CPU	Bundle clusters	`2026-07-30-ec2-worker-profiling.md`
`cmd/blockdb_grpc_stub/`	Benchmark-only BlockDB gRPC stub service with an endpoint probe	Backend Adapter	See `cmd/blockdb_grpc_stub/README.md`

`internal/`

Directory	Purpose	Component page	Main spec
`internal/worker/core/`	`WorkerCore` (slot/task state machine, TTL, result retention) and `DispatcherCore` (call scheduling, batch submission)	Worker, Call execution	`worker.md`, `call-execution-subsystem.md`
`internal/worker/adapters/`	gRPC server, etcd heartbeat publishing, the `Orchestrator` actor (phase advancement, subcalls, wedge detection), audit gate, shadow forwarding, metrics	Worker	`worker.md`
`internal/worker/adapters/executor/`	Python executor process pool, UDS send/receive, bare and sandbox spawners	Call execution, Python Executor	`worker-executor-connection-and-python-sdk-hook.md`, `executor-sandbox-isolation.md`
`internal/worker/app/`	`Profile`, `WorkerFullConfig`, `Run`: builds registries per profile, assembles IO backends, startup/shutdown order, memory diagnostics	Worker	`worker.md`, `2026-07-21-block-bundle-clusters.md`
`internal/worker/devstub/`	static/payload builders, log/test plugins, stub backend, and noop function-code provider for dev/e2e	Testing	`system-e2e-testing.md`
`internal/coordinator/core/`	`CoordinatorCore`: worker view, candidate selection, red lines and circuit breaking	Coordinator	`task-resource-coordinator.md`
`internal/coordinator/adapters/`	etcd watcher, `CoordinatorServer`/`BundleCoordinatorServer` gRPC, `WorkerRPCClient`	Coordinator	`task-resource-coordinator.md`
`internal/coordinator/app/`	`Profile` (`WorkerRegistryPrefixes`) and `Run`	Coordinator	`2026-07-28-registry-prefix-migration.md`
`internal/syncinvoker/core/`	sync-call state machine, executor registry, admission selection	Sync Invoker	`sync-invoker.md`
`internal/syncinvoker/adapters/`	`Service` (Invoke/DebugInvoke/Precheck), gRPC server, exec adapter	Sync Invoker	`sync-invoker.md`, `sync-invoker-failure-origin.md`
`internal/functioncode/core/`	`SnapshotStore`, `TaskFunctionView`, source digests	Function Code	`function-code-view.md`
`internal/functioncode/adapters/{redis,blockdb}/`	Syncs function code from Redis snapshots or BlockDB scan/subscribe	Function Code	`function-code-view.md`
`internal/functioncode/audit/`	Go-side auditor: `blockx_audit` daemon subprocess pool, digest cache, `RejectionError`	Function Code	`function-code-audit-design.md`
`internal/io/core/`	`WorkerIOScope`/`TaskIOScope`, `model/` (`BackendAdapter`, `BackendKind`, `ReadReq`), `stats/`	IO subsystem	`io-subsystem.md`
`internal/io/assembly/`	`assembly.Build`: turns the `Module` manifest into backend registrations wrapped with adaptive admission	IO subsystem	`io-backend-module-design.md` (in `docs/`)
`internal/io/{cache,quota,sflight}/`	Bounded LRU cache, channel semaphore, singleflight table	IO subsystem	`io-subsystem.md`
`internal/io/adaptive/`	Transport-agnostic AIMD concurrency control and the `observed/` metrics wrapper	IO subsystem	`io-subsystem.md`
`internal/io/capabilitywire/`	Decodes the binary request envelope of gRPC-style capability backends	IO subsystem	`capability-backend-guide.md` (in `docs/`)
`internal/plugin/callbuilder/`	`BuilderRegistry`, `types/` (`CallBuilder` interface, `Call`, Substrait-style `Plan`), `dbscan/`, `call_list/`, `bundlescan/`	Plugins	`plugin-system.md`, `substrait_ast.md`
`internal/plugin/event/`	`PluginRegistry`, `types/` (`WriterPlugin`, `TaskIO`), `blockdbwrite/`, `returnvalue/`, `bundlewrite/`, `tableupserts/`, `batchwrite/`	Plugins	`plugin-system.md`, `2026-07-30-bundle-write-batch-api.md`
`internal/plugin/schema/`	Helper for reading table schemas through IO (`ReadColumns`)	Plugins	`plugin-system.md`
`internal/sdk/blockdb/`	BlockDB gRPC `Adapter`, the `BridgeAdapter` used by the executor, BatchWrite, stub, `proto/` and `gen/`	Backend Adapter	`io-subsystem.md`, `2026-07-23-grpc-client-balancing.md`
`internal/sdk/noderpc/`	Node JSON-RPC forwarding, HTTP sharding, semantic batching	Backend Adapter	`noderpc-semantic-batching.md`, `2026-08-06-noderpc-binary-sidecar.md`
`internal/sdk/meta/`, `internal/sdk/logicaltypes/`	meta service HTTP client; `TableMetaService` gRPC logical type adapter	Backend Adapter	`io-subsystem.md`
`internal/sdk/iceberg/`	Read-only Glue/Iceberg `Planner` used by bundle scan to resolve data files	Backend Adapter	`2026-07-21-block-bundle-clusters.md`
`internal/sdk/router/`	Function discovery capability backend (returns matching function names for given arguments); wraps the `Service` of the external module `github.com/chaintable/router/go` in-process	Backend Adapter	No standalone spec; the integration style follows `capability-backend-guide.md` (in `docs/`)
`internal/sdk/localtestservice/`	End-to-end template for a capability backend: `proto/`, `service.go`, `adapter.go`	Backend Adapter	`capability-backend-guide.md` (in `docs/`)
`internal/sdk/grpcclient/`	Multi-connection strategies and protobuf wire helpers	Backend Adapter	`2026-07-23-grpc-client-balancing.md`
`internal/duckdb/borrowed/`	Connection pool, interruption, and zero-copy chunk decoding on top of the DuckDB native bindings; contains no bundle-scan policy	Bundle clusters	See the `README.md` in the directory
`internal/obs/`	`slog` handler and ctx injection, Prometheus metrics (including IO adaptive, noderpc batch, syncinvoke), OTel tracing initialization	Observability	`logging.md`, `tracing.md`, `blockx-log-types.md`
`internal/usage/`	Usage aggregation and Kafka sink (`NewKafkaCollector` is fail-closed)	Observability	`2026-07-13-blockx-usage-collection.md`
`internal/common/`	`types/` (`TaskID`, `Stage`, `TaskCtx`), `clientid/`, `argspool/`, `unsafebytes/`	Design principles	`client-id-propagation.md`
`internal/testutil/`	Spawns etcd/worker/coordinator subprocesses, build binary cache, `RunTestMain`	Testing	`system-e2e-testing.md`

`api/`, `python/`, `e2e/`, and others

Directory	Purpose	Component page	Main spec
`api/grpc/{worker,coordinator,bundlecoordinator,syncinvoker}/`	`.proto` files and generated `*pb/`; regenerate with `make proto`	Protocols and interfaces	`worker.md`, `task-resource-coordinator.md`, `sync-invoker.md`
`api/uds/`	`MessageEnvelope` and the individual payloads, frame codec	Protocols and interfaces	`worker-executor-connection-and-python-sdk-hook.md`
`api/etcd/`	`WorkerHeartbeat`, registry prefix constants and parsing	Protocols and interfaces	`2026-07-28-registry-prefix-migration.md`
`python/blockx_executor/`	Executor process: `uds_session.py`, `runtime.py`, `sdk_bridge.py`, `blockdb_bridge.py`, `noderpc_bridge.py`, `module_registry.py`	Python Executor	`python-function-executor.md`
`python/blockx_sdk/`	SDK that function code can import: `db`, `rpc`, `sleep`, `call_subfunc`, `get_provider`	Python Executor	`worker-executor-connection-and-python-sdk-hook.md`
`python/blockx_audit/`	Pure-stdlib static auditor and stdin/stdout framed daemon	Function Code	`function-code-audit-design.md`, `function-code-python-whitelist.md`
`python/tests/`	`unittest` unit tests	Testing	`python-test-organization.md`
`e2e/contract/`	coordinator↔etcd and coordinator↔worker contract E2E (slot TTL, timeouts, restarts, failover)	Testing	`system-e2e-testing.md`
`e2e/system/`	smoke/routing/recovery/logical_type end-to-end E2E	Testing	`system-e2e-testing.md`
`e2e/perf/`	Performance tests organized by the S0–S5 matrix; artifacts land in `_artifacts/`	Testing	`perf-methodology.md`, `perf-test-how-to-v2.md`
`examples/local_test_service/`	`submit.py`/`local_proxy.py`: calls `LocalTestService` through a local worker with blockx-py	Local development	`capability-backend-guide.md` (in `docs/`)
`deploy/`	`systemd/` units, `scripts/` install/start/health/cleanup scripts, `env/` examples, `tests/` bash tests	Deployment	`docs/deploy.md`, `docs/deploy/*.md`
`docs/`	`deploy.md`, `capability-backend-guide.md`, `io-backend-module-design.md`, `sync-invoker-grafana.md`, `deploy/`, `specs/`	Deployment	See the next section
`Makefile`	`proto` (including blockdb/meta/localtestservice), `fmt`, `vet`, `test` (fast packages in one run, syncinvoker file by file)	Local development	—
`Dockerfile`	Builds two coordinators, two workers, and syncinvoker, and packs them into a `python:3.12-slim` runtime	Deployment	—
`test.sh`	Runs `./e2e/perf/...` under `systemd-run --scope` with CPUQuota/MemoryMax	Testing	`perf-methodology.md`
`analyze_spans.py`	Aggregates span files such as `/tmp/blockx_spans.jsonl` into a trace tree	Observability	`tracing.md`

To build a single binary, use go build ./cmd/<name>; this is the same command the Dockerfile and each cmd/*/README.md use.

docs/specs index

docs/specs/ holds the design documents for behavioral semantics. There are two kinds of file names: those without a date prefix are long-lived subsystem designs (named after the subsystem, e.g. plugin-system.md), and those with a YYYY-MM-DD- prefix are incremental designs or change proposals, where the date is when the proposal was made. Files stay in place after they land, and some note their status at the top (e.g. “Status: Implemented” in 2026-07-21-block-bundle-clusters.md). Six must-reads: architecture.md, worker.md, call-execution-subsystem.md, io-subsystem.md, plugin-system.md, code-style.md.

Subsystem designs (no date prefix)

File	Topic
`architecture.md`	System overview: Coordinator/Worker/Executor and the `onchain table -> onchain table` compute model
`worker.md`	Worker: slot/task state machine, protocol, TTL, and result retention
`call-execution-subsystem.md`	Call scheduling, execution, suspend/resume, subfunction calls, and code loading inside the Worker
`io-subsystem.md`	IO access subsystem: scopes, quota, cache, singleflight, backends
`plugin-system.md`	Interfaces, data structures, and assembly of Call Builders and Writer Plugins
`code-style.md`	`core/adapters/api/scope` boundaries and constraints on error and time semantics
`task-resource-coordinator.md`	Coordinator: worker view, candidates, red lines, circuit breaking
`function-code-view.md`	Sources, publishing, and pinning of function code snapshots
`function-code-audit-design.md`	Function Code static audit and execution rules
`function-code-python-whitelist.md`	Whitelist of the Python subset allowed by the audit
`python-function-executor.md`	Python Executor internals: greenlet runtime, SDK bridge, UDS event loop
`python-executor-process-metrics.md`	How process metrics in Executor heartbeats are sampled
`worker-executor-connection-and-python-sdk-hook.md`	Worker↔Executor UDS connection protocol and SDK hook
`executor-sandbox-isolation.md`	Executor containerd sandbox isolation
`sync-invoker.md`	Technical design of the sync invocation service
`sync-invoker-failure-origin.md`	sync-invoker error classification
`noderpc-semantic-batching.md`	Transparent NodeRPC semantic batching
`substrait_ast.md`	Substrait-style `Plan` for row-level filtering and deduplication (`internal/plugin/callbuilder/types/operator.go`)
`client-id-propagation.md`	Propagation of client IDs across gRPC metadata, HTTP headers, and in-process
`logging.md`	Structured logging contract (Go `slog` and Python `logging`)
`blockx-log-types.md`	Key log types from the user’s perspective and how to search them
`tracing.md`	OpenTelemetry distributed tracing
`system-e2e-testing.md`	Design of end-to-end verification on a dev machine
`worker-test-organization.md`	Worker Go test organization standard
`python-test-organization.md`	Python unit test organization standard
`perf-methodology.md`	Performance troubleshooting methodology; the basis for the `e2e/perf/` matrix
`perf-test-how-to-v2.md`, `perf-test-report-v2.md`, `perf-test-report.md`, `perf-test-report-appendix.md`	Performance test reproduction guide and historical reports
`perf-capability-backend-report.md`	Cost report for the capability backend framework layer

Incremental designs and changes (date prefix)

File	Topic
`2026-07-13-blockx-usage-collection.md`	Current implementation for writing Worker usage data to Kafka
`2026-07-14-dbscan-in-memory-operator.md`	DBScan reads by table+block, with filtering/deduplication moved to in-memory operators
`2026-07-16-task-owner-lease-and-cancellation.md`	Reuses the `WatchTasks` stream for task disconnect reclamation (watch grace)
`2026-07-21-block-bundle-clusters.md`	Splitting deployments into block and bundle sets
`2026-07-23-bundle-coordinator-api.md`	Standalone gRPC service for the Bundle Coordinator
`2026-07-23-execute-call-function-code-reference.md`	ExecuteCall carries only the source digest; the Executor fetches source on demand
`2026-07-23-grpc-client-balancing.md`	gRPC multi-connection load balancing behind an NLB (`internal/sdk/grpcclient`)
`2026-07-28-registry-prefix-migration.md`	Backward-compatible migration of the Worker etcd registry prefix
`2026-07-30-bundle-write-batch-api.md`	BundleWrite/TableUpserts switched to BlockDB BatchWrite Jobs
`2026-07-30-ec2-worker-profiling.md`	pprof / py-spy sampling of EC2 Workers without host dependencies
`2026-07-30-python-executor-cpu-optimization.md`	Python Executor CPU optimization design and baseline
`2026-08-06-noderpc-binary-sidecar.md`	NodeRPC bridge binary passthrough

”I want to change X, where should I look?”

What you want to change	Start here	Change together / reference
Add a Call Builder	`internal/plugin/callbuilder/<name>/`, implement `types.CallBuilder`; add a `CallBuilderName` in `internal/plugin/callbuilder/types/types.go`	The `newBuilderRegistry` switch in `internal/worker/app/app.go`, the `Builders` manifest in `cmd/worker/main.go` / `cmd/bundle_worker/main.go`; `docs/specs/plugin-system.md`
Add a Writer Plugin	`internal/plugin/event/<name>/`, implement `types.WriterPlugin`; add a `PluginName` in `internal/plugin/event/types/types.go`	`newPluginRegistry` in `internal/worker/app/app.go`, the `Plugins` manifest in the entry point; `docs/specs/plugin-system.md`
Change the slot / task state machine, TTL, result retention	`internal/worker/core/worker.go`, `worker_slots.go`, `types.go`	Timers and side effects are in `internal/worker/adapters/orchestrator*.go`; `docs/specs/worker.md`
Change call scheduling, batching, retries, subcalls	`internal/worker/core/dispatcher*.go`	`internal/worker/adapters/orchestrator_dispatch.go`, `orchestrator_subcall.go`; `docs/specs/call-execution-subsystem.md`
Change Worker ↔ Executor UDS messages	`api/uds/types.go`, `api/uds/codec.go`	`python/blockx_executor/messages.py`, `wire_keys.py`, `uds_codec.py`; `docs/specs/worker-executor-connection-and-python-sdk-hook.md`
Change a gRPC protocol	`api/grpc/<service>/*.proto`, then run `make proto`	The corresponding adapter: `internal/worker/adapters/grpc_server.go`, `wire.go` or `internal/coordinator/adapters/grpc_server.go`; update the spec in the same change
Add an IO / capability backend	`internal/sdk/<kind>/` (`proto/`, `service.go`, `adapter.go`), implement `iocore.BackendAdapter`	Add an `assembly.Module` to `backendModules` in `internal/worker/app/app.go`; `cmd/syncinvoker/io.go`; `python/blockx_audit/tables.py`; `docs/capability-backend-guide.md`
Change IO quota / cache / singleflight semantics	`internal/io/core/task_scope*.go`, `worker_scope.go`	`internal/io/{cache,quota,sflight}/`; `docs/specs/io-subsystem.md`
Change backend admission (AIMD) or timeouts	`internal/io/adaptive/`	Each `internal/sdk/<kind>/adaptive.go`; the corresponding AIMD fields in `WorkerFullConfig`
Add metrics / log fields / spans	`internal/obs/metrics*.go`, `logger.go`, `tracing.go`	Instrument the corresponding adapter; on the Python side `python/blockx_executor/metrics.py`, `logging_setup.py`, `tracing_setup.py`; `docs/specs/logging.md`, `tracing.md`
Change a Worker config option	`WorkerFullConfig` in `internal/worker/app/config.go`	Entry-point defaults go through `Profile.TuneDefaults`; `deploy/env/worker.env.example`
Change Coordinator placement / red lines / circuit breaking	`internal/coordinator/core/coordinator.go`, `worker_view.go`	`internal/coordinator/adapters/etcd_watcher.go`; `docs/specs/task-resource-coordinator.md`
Change Function Code View sync or audit	`internal/functioncode/core/`, `adapters/{redis,blockdb}/`, `audit/`	Audit rules are in `python/blockx_audit/`; `docs/specs/function-code-view.md`, `function-code-audit-design.md`
Change the Python runtime or SDK bridge	`python/blockx_executor/runtime.py`, `sdk_bridge.py`, `context.py`	`python/blockx_sdk/`; `docs/specs/python-function-executor.md`
Change bundle scan / DuckDB reads	`internal/plugin/callbuilder/bundlescan/`	The generic binding layer `internal/duckdb/borrowed/`; `internal/sdk/iceberg/`
Change sync-invoker	`internal/syncinvoker/core/`, `adapters/service.go`, `cmd/syncinvoker/`	`api/grpc/syncinvoker/sync_invoker.proto`; `docs/specs/sync-invoker.md`
Change deployment	`deploy/scripts/`, `deploy/systemd/`, `deploy/env/`, then run `deploy/tests/*.sh`	`Dockerfile`, `.github/workflows/`; `docs/deploy.md`, `docs/deploy/*.md`
Add an E2E test	Single process: `cmd/worker/worker_process_*_test.go`; cross-component: `e2e/contract/`, `e2e/system/`; performance: `e2e/perf/`	Scaffolding in `internal/testutil/`; `docs/specs/system-e2e-testing.md`, `worker-test-organization.md`

AGENTS.md in the blockx repository: directory skeleton, commands, commit conventions.
docs/specs/code-style.md in the blockx repository: implementation constraints for core/adapters/api/scope.
docs/specs/architecture.md in the blockx repository: system overview.
docs/capability-backend-guide.md in the blockx repository: file-by-file walkthrough for adding a capability backend.
On this site: Architecture overview, Design principles and code conventions, Protocols and interfaces, Local development environment, Testing, Contributing.

Get started

Architecture

Components

Development guide

Repository layout and code layering

Layering conventions

Module index

`cmd/`

`internal/`

`api/`, `python/`, `e2e/`, and others

docs/specs index

”I want to change X, where should I look?”

​Layering conventions

​Module index

​cmd/

​internal/

​api/, python/, e2e/, and others

​docs/specs index

​”I want to change X, where should I look?”

​Related docs

Layering conventions

Module index

`cmd/`

`internal/`

`api/`, `python/`, `e2e/`, and others

docs/specs index

”I want to change X, where should I look?”

Related docs