> ## Documentation Index > Fetch the complete documentation index at: https://docs.blockx.chaintable.com/llms.txt > Use this file to discover all available pages before exploring further. # Repository layout and code layering > What lives where in the BlockX repository, why it is laid out that way, and which directory to go to when you want to change a feature 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](/en/architecture/overview). ```text theme={null} 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//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//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//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](/en/components/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](/en/components/bundle) | `2026-07-21-block-bundle-clusters.md` | | `cmd/coordinator/` | Entry point for the block Coordinator; watches the legacy block registry prefix | [Coordinator](/en/components/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](/en/components/bundle) | `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](/en/components/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](/en/development/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](/en/components/bundle) | `2026-07-30-ec2-worker-profiling.md` | | `cmd/blockdb_grpc_stub/` | Benchmark-only BlockDB gRPC stub service with an endpoint probe | [Backend Adapter](/en/components/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](/en/components/worker), [Call execution](/en/components/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](/en/components/worker) | `worker.md` | | `internal/worker/adapters/executor/` | Python executor process pool, UDS send/receive, bare and sandbox spawners | [Call execution](/en/components/call-execution), [Python Executor](/en/components/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](/en/components/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](/en/development/testing) | `system-e2e-testing.md` | | `internal/coordinator/core/` | `CoordinatorCore`: worker view, candidate selection, red lines and circuit breaking | [Coordinator](/en/components/coordinator) | `task-resource-coordinator.md` | | `internal/coordinator/adapters/` | etcd watcher, `CoordinatorServer`/`BundleCoordinatorServer` gRPC, `WorkerRPCClient` | [Coordinator](/en/components/coordinator) | `task-resource-coordinator.md` | | `internal/coordinator/app/` | `Profile` (`WorkerRegistryPrefixes`) and `Run` | [Coordinator](/en/components/coordinator) | `2026-07-28-registry-prefix-migration.md` | | `internal/syncinvoker/core/` | sync-call state machine, executor registry, admission selection | [Sync Invoker](/en/components/sync-invoker) | `sync-invoker.md` | | `internal/syncinvoker/adapters/` | `Service` (Invoke/DebugInvoke/Precheck), gRPC server, exec adapter | [Sync Invoker](/en/components/sync-invoker) | `sync-invoker.md`, `sync-invoker-failure-origin.md` | | `internal/functioncode/core/` | `SnapshotStore`, `TaskFunctionView`, source digests | [Function Code](/en/components/function-code) | `function-code-view.md` | | `internal/functioncode/adapters/{redis,blockdb}/` | Syncs function code from Redis snapshots or BlockDB scan/subscribe | [Function Code](/en/components/function-code) | `function-code-view.md` | | `internal/functioncode/audit/` | Go-side auditor: `blockx_audit` daemon subprocess pool, digest cache, `RejectionError` | [Function Code](/en/components/function-code) | `function-code-audit-design.md` | | `internal/io/core/` | `WorkerIOScope`/`TaskIOScope`, `model/` (`BackendAdapter`, `BackendKind`, `ReadReq`), `stats/` | [IO subsystem](/en/components/io-subsystem) | `io-subsystem.md` | | `internal/io/assembly/` | `assembly.Build`: turns the `Module` manifest into backend registrations wrapped with adaptive admission | [IO subsystem](/en/components/io-subsystem) | `io-backend-module-design.md` (in `docs/`) | | `internal/io/{cache,quota,sflight}/` | Bounded LRU cache, channel semaphore, singleflight table | [IO subsystem](/en/components/io-subsystem) | `io-subsystem.md` | | `internal/io/adaptive/` | Transport-agnostic AIMD concurrency control and the `observed/` metrics wrapper | [IO subsystem](/en/components/io-subsystem) | `io-subsystem.md` | | `internal/io/capabilitywire/` | Decodes the binary request envelope of gRPC-style capability backends | [IO subsystem](/en/components/io-subsystem) | `capability-backend-guide.md` (in `docs/`) | | `internal/plugin/callbuilder/` | `BuilderRegistry`, `types/` (`CallBuilder` interface, `Call`, Substrait-style `Plan`), `dbscan/`, `call_list/`, `bundlescan/` | [Plugins](/en/components/plugins) | `plugin-system.md`, `substrait_ast.md` | | `internal/plugin/event/` | `PluginRegistry`, `types/` (`WriterPlugin`, `TaskIO`), `blockdbwrite/`, `returnvalue/`, `bundlewrite/`, `tableupserts/`, `batchwrite/` | [Plugins](/en/components/plugins) | `plugin-system.md`, `2026-07-30-bundle-write-batch-api.md` | | `internal/plugin/schema/` | Helper for reading table schemas through IO (`ReadColumns`) | [Plugins](/en/components/plugins) | `plugin-system.md` | | `internal/sdk/blockdb/` | BlockDB gRPC `Adapter`, the `BridgeAdapter` used by the executor, BatchWrite, stub, `proto/` and `gen/` | [Backend Adapter](/en/components/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](/en/components/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](/en/components/backend-adapter) | `io-subsystem.md` | | `internal/sdk/iceberg/` | Read-only Glue/Iceberg `Planner` used by bundle scan to resolve data files | [Backend Adapter](/en/components/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](/en/components/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](/en/components/backend-adapter) | `capability-backend-guide.md` (in `docs/`) | | `internal/sdk/grpcclient/` | Multi-connection strategies and protobuf wire helpers | [Backend Adapter](/en/components/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](/en/components/bundle) | 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](/en/components/observability) | `logging.md`, `tracing.md`, `blockx-log-types.md` | | `internal/usage/` | Usage aggregation and Kafka sink (`NewKafkaCollector` is fail-closed) | [Observability](/en/components/observability) | `2026-07-13-blockx-usage-collection.md` | | `internal/common/` | `types/` (`TaskID`, `Stage`, `TaskCtx`), `clientid/`, `argspool/`, `unsafebytes/` | [Design principles](/en/architecture/design-principles) | `client-id-propagation.md` | | `internal/testutil/` | Spawns etcd/worker/coordinator subprocesses, build binary cache, `RunTestMain` | [Testing](/en/development/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](/en/architecture/protocols) | `worker.md`, `task-resource-coordinator.md`, `sync-invoker.md` | | `api/uds/` | `MessageEnvelope` and the individual payloads, frame codec | [Protocols and interfaces](/en/architecture/protocols) | `worker-executor-connection-and-python-sdk-hook.md` | | `api/etcd/` | `WorkerHeartbeat`, registry prefix constants and parsing | [Protocols and interfaces](/en/architecture/protocols) | `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](/en/components/python-executor) | `python-function-executor.md` | | `python/blockx_sdk/` | SDK that function code can import: `db`, `rpc`, `sleep`, `call_subfunc`, `get_provider` | [Python Executor](/en/components/python-executor) | `worker-executor-connection-and-python-sdk-hook.md` | | `python/blockx_audit/` | Pure-stdlib static auditor and stdin/stdout framed daemon | [Function Code](/en/components/function-code) | `function-code-audit-design.md`, `function-code-python-whitelist.md` | | `python/tests/` | `unittest` unit tests | [Testing](/en/development/testing) | `python-test-organization.md` | | `e2e/contract/` | coordinator↔etcd and coordinator↔worker contract E2E (slot TTL, timeouts, restarts, failover) | [Testing](/en/development/testing) | `system-e2e-testing.md` | | `e2e/system/` | smoke/routing/recovery/logical\_type end-to-end E2E | [Testing](/en/development/testing) | `system-e2e-testing.md` | | `e2e/perf/` | Performance tests organized by the S0–S5 matrix; artifacts land in `_artifacts/` | [Testing](/en/development/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](/en/development/getting-started) | `capability-backend-guide.md` (in `docs/`) | | `deploy/` | `systemd/` units, `scripts/` install/start/health/cleanup scripts, `env/` examples, `tests/` bash tests | [Deployment](/en/development/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](/en/development/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](/en/development/getting-started) | — | | `Dockerfile` | Builds two coordinators, two workers, and syncinvoker, and packs them into a `python:3.12-slim` runtime | [Deployment](/en/development/deployment) | — | | `test.sh` | Runs `./e2e/perf/...` under `systemd-run --scope` with CPUQuota/MemoryMax | [Testing](/en/development/testing) | `perf-methodology.md` | | `analyze_spans.py` | Aggregates span files such as `/tmp/blockx_spans.jsonl` into a trace tree | [Observability](/en/components/observability) | `tracing.md` | To build a single binary, use `go build ./cmd/`; 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`. | 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 | | 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//`, 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//`, 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//*.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//` (`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//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` | ## Related docs * `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](/en/architecture/overview), [Design principles and code conventions](/en/architecture/design-principles), [Protocols and interfaces](/en/architecture/protocols), [Local development environment](/en/development/getting-started), [Testing](/en/development/testing), [Contributing](/en/development/contributing).