Field Manual / 2026

Repository Architecture Field Manual

How to read, design and reason about mature software systems. Package boundaries, plugins, local/cloud authority, persistence, sync, RPC/gRPC, CAD, multiplayer, native runtimes and IDE/CLI UX.

Files are syntax. Directories are responsibility. Packages are contracts. Processes are failure boundaries. Protocols are promises across boundaries.

Four-pass method

Pass	Question
Cartography	What are the top-level responsibilities?
Authority	Who is allowed to decide truth?
Contracts	Where are schemas, APIs, manifests and migrations?
Motion	Trace one operation end-to-end.

repo/
├─ apps/        deployable products
├─ packages/    reusable capabilities
├─ schemas/     wire/data contracts
├─ migrations/  executable data history
├─ tooling/     build/release/codegen
└─ examples/    executable documentation

Boundaries

Packages, layers and plugins

Dependency direction is the invisible architecture. High-level product code may depend on stable lower-level capabilities; the reverse dependency usually signals a leak.

UI / CLI / HTTP
      │
      ▼
application commands
      │
      ▼
domain / core
      │ interfaces
  ┌───┼────┐
 DB  net   fs
 adapters

Plugin contract checklist

Discovery and stable identity
Frontend/backend/native entry points
Capability grants rather than entire host internals
Activation/disposal lifecycle
Process/WASM/worker isolation
Host API and protocol compatibility
Scoped persistence and observability

Dynamic import is not a plugin architecture. The architecture is the constrained, versioned contract around the imported code.

Authority

Local vs cloud

“Local” and “cloud” describe placement. Authority describes who is allowed to decide. A robust design can have cloud-owned identity, locally owned live execution, and separately durable operation receipts.

Plane	Owns
Control	identity, policy, enrollment, configuration
Data	latency-sensitive payload and execution
Observability	logs, traces, metrics, receipts
Build/release	trusted artifacts, signing, SBOM, publishing

cloud policy ── authorizes ──▶ local runtime
                                  │
                            live session/data
                                  │
                         durable receipt/event

Protocols

RPC, gRPC, generated contracts

A process boundary turns ordinary calls into distributed-systems calls: they can time out, be retried, arrive twice, arrive late, or fail after the remote side committed work.

foo.proto ── protoc ──▶ foo.pb.go
                     ├▶ foo_grpc.pb.go
                     ├▶ Python/TS/Rust bindings
                     └▶ descriptors

.proto, .capnp, GraphQL schemas, OpenAPI documents, JSON-RPC methods and WIT interfaces are all ways of turning assumptions into inspectable contracts.

State

Persistence and migrations

A database is not one thing. Relational truth, local working state, immutable artifacts, event history, caches and search indexes need different guarantees.

001_create.sql
002_add_nullable_owner.sql
003_backfill_owner.sql
004_enforce_owner.sql

The staged sequence above is architecture: it allows mixed-version software and existing data to survive change.

Synchronization

Conflict policy over a network

Model	Core idea
Optimistic concurrency	Version check then retry/rebase
CRDT	Replicas merge by datatype rules and converge
Server authoritative	Clients send intent; server validates simulation truth
Event sourcing	Ordered events are durable history; projections derive state

client intent ──▶ authority ──▶ accepted state/event ──▶ clients
                     │
              validate + simulate

WebSocket is transport. It does not answer who wins a conflict.

Creative systems

CAD / 3D / scene representations

Learn representation before format. STL is usually triangle mesh; STEP commonly carries precise CAD geometry; OpenSCAD is source code that produces geometry; USD is scene description/composition; IFC carries BIM semantics.

Representation	Preserves
Mesh	renderable surface
B-rep	precise topology + surfaces
Parametric	feature history + constraints
Scene graph	hierarchy, transforms, references, materials, time
BIM	building semantics + geometry + relationships

“4D” usually means 3D plus time: animation, simulation, or BIM scheduling—not one magic fourth-dimensional file format.

Developer experience

IDE / CLI as systems architecture

keyboard / palette / CLI / agent
              │
        command registry
              │
       application handler
              │
   filesystem / terminal / git / RPC
              │
       structured receipt

A PTY, terminal emulator, shell, transport, session manager and UI are distinct layers. LSP and DAP show how deliberately boring protocols can create rich tooling ecosystems.

File atlas

Read unfamiliar extensions by lifecycle

Ask: who writes it, who consumes it, can it be regenerated, and what contract does it encode?

File	Family	Interpretation
`.ts / .tsx`	TypeScript / TS+JSX	Web/server/CLI packages; .tsx usually contains JSX syntax.
`.js / .mjs / .cjs`	JavaScript module variants	ES module vs CommonJS boundaries; package.json `type` also matters.
`.jsx`	JavaScript + JSX	React-style UI source.
`.rs`	Rust	Crates, native runtimes, CLIs, WASM, systems code.
`.go`	Go	Services, CLIs, networking, generated protobuf stubs.
`.swift`	Swift	Apple-platform apps, services, packages, native tooling.
`.m / .mm`	Objective-C / Objective-C++	Apple-native bridges and older platform code.
`.c`	C	Portable low-level code and stable FFI surfaces.
`.cc / .cpp / .cxx`	C++	CAD kernels, engines, runtimes, high-performance native systems.
`.h / .hpp / .hxx`	Headers	Declarations, templates and public native interfaces.
`.py`	Python	Automation, ML, data tooling, SDKs, plugins.
`.rb`	Ruby	Automation/server ecosystems.
`.kt / .kts`	Kotlin / script	Android, JVM, Gradle Kotlin build scripts.
`.java`	Java	JVM services/Android/libraries.
`.cs`	C#	Unity, .NET services/tools, CAD connectors.
`.lua`	Lua	Embedded scripting; common in games and configurable runtimes.
`.zig`	Zig	Systems code, C interoperability, build tooling.
`.ex / .exs`	Elixir	Concurrent/network services; mix project scripts.
`.erl / .hrl`	Erlang	BEAM/OTP systems.
`.scala`	Scala	JVM functional/data systems.
`.dart`	Dart	Flutter applications and tooling.
`.gd`	GDScript	Godot game/application scripting.
`.shader / .glsl / .vert / .frag`	Shader sources	GPU programs; vertex/fragment stages and variants.
`.metal`	Metal Shading Language	Apple GPU shader source.
`.hlsl`	High-Level Shader Language	DirectX-style GPU shader source.
`.wgsl`	WebGPU Shading Language	WebGPU shader source.
`.proto`	Protobuf / gRPC IDL	messages, enums, services, field numbers.
`.capnp`	Cap’n Proto schema	RPC/data layout and generated bindings.
`.graphql / .gql`	GraphQL schema/query	types, operations, fragments.
`.avsc`	Avro schema	Data serialization / streaming ecosystems.
`.fbs`	FlatBuffers schema	Zero-copy-ish serialized data/codegen.
`.thrift`	Thrift IDL	Cross-language service/data contracts.
`.wit`	WASM component interface	Typed host/guest interfaces.
`.jsonschema / schema.json`	JSON Schema	Validation and config/data contracts.
`openapi.yaml`	OpenAPI contract	HTTP operations, request/response schemas.
`.d.ts`	TypeScript declarations	Public type shape without implementation.
`.swiftinterface`	Swift textual module interface	Stable-ish compiler-visible public API representation.
`.def`	Windows module definition	DLL exports/imports.
`.idl`	Generic interface definition language	COM or other RPC/interface systems depending on ecosystem.
`.sql`	SQL source	Migrations, queries, schema, seeds.
`.sqlite / .db / .sqlite3`	SQLite database	Binary embedded relational database.
`.wal / .shm`	SQLite write-ahead log/shared memory	Live database sidecar files; not source assets.
`.csv / .tsv`	Delimited tables	Simple interchange; weak types.
`.json`	Structured text	Config/data/API payloads; no comments in strict JSON.
`.jsonc`	JSON with comments	Config files such as modern Wrangler.
`.jsonl / .ndjson`	One JSON object per line	Streaming/log/data pipelines.
`.yaml / .yml`	Human-oriented structured data	CI, manifests, deployment and API contracts.
`.toml`	Config/package manifests	Rust Cargo, Python, tool configs.
`.xml`	Structured markup	Build files, interchange formats, legacy APIs.
`.parquet`	Columnar analytics	Efficient typed analytical datasets.
`.arrow / .feather`	Apache Arrow ecosystem	Columnar in-memory/interchange data.
`.orc`	Columnar data	Big-data analytics.
`.duckdb`	DuckDB database file	Embedded analytical database.
`.pbf`	Protocol Buffer binary	Serialized protobuf data; also used by OpenStreetMap PBF conventions.
`.msgpack`	MessagePack binary	Compact JSON-like binary serialization.
`.cbor`	CBOR binary	Compact typed binary data, common in protocols/embedded systems.
`Info.plist`	Property list	Bundle metadata, capabilities and application configuration.
`.plist`	Apple property list	XML/binary structured settings/data.
`.entitlements`	Code-signing entitlements	Capabilities such as keychain groups, sandbox permissions.
`.xcassets`	Asset catalog bundle	App icons, images, colors, symbol assets.
`.storyboard`	Interface Builder UI document	XML UI graph; common in UIKit-era apps.
`.xib`	Interface Builder UI file	Reusable UI view/window definition.
`.strings`	Localization strings	Localized key/value resources.
`.stringsdict`	Plural/localization rules	Structured localized variations.
`.mobileprovision`	Provisioning profile	Signing/device/team entitlement material.
`.xcconfig`	Xcode build configuration	Composable build setting files.
`.swiftmodule`	Compiled Swift module	Compiler artifact; platform/toolchain specific.
`.ipa`	iOS application archive	Packaged signed app payload.
`.app`	Application bundle	Directory bundle containing executable + resources.
`.framework / .xcframework`	Apple binary framework bundles	Libraries/resources for one or many platforms/architectures.
`.onnx`	Open Neural Network Exchange	Portable model graph/weights across runtimes.
`.safetensors`	Tensor weights	Safer/simple tensor storage common in ML ecosystems.
`.gguf`	Quantized LLM model container	Local inference ecosystems such as llama.cpp family.
`.tflite`	TensorFlow Lite model	Mobile/embedded inference.
`.mlmodel / .mlpackage`	Core ML model	Apple ML deployment formats.

The DOCX edition contains the expanded CAD, native-binary, build-system, media, archive and package-format tables.

Repository observatory

Public codebases worth reading

Cloudflare workers-sdk — Wrangler, Miniflare, C3, Vite integration; developer tooling monorepo.
Cloudflare workerd — Native Workers runtime; Cap’n Proto/native/runtime rabbit holes.
Microsoft VS Code — Layered editor/workbench core and extension host.
Eclipse Theia — Framework for custom browser/desktop IDEs.
Zed — Rust workspace, native editor, collaboration and agent subsystems.
OpenAI Codex — Coding-agent CLI/runtime and app-server protocol surfaces.
Directus — Headless data platform and extension SDK.
Payload — TypeScript/Next app framework + CMS monorepo.
Automerge — CRDT core in Rust, JS/WASM surface, binary/sync protocol.
Nakama — Go realtime game backend and runtime extensions.
Colyseus — TypeScript multiplayer rooms and synchronized authoritative state.
Godot — C++ game engine with unusually educational root boundaries.
Bevy — Rust ECS engine and plugin architecture.
FreeCAD — Parametric CAD application and workbench ecosystem.
OpenSCAD — Programmatic geometry / CAD compiler mental model.
OpenUSD — Scene description, composition, C++ and asset system.
Speckle — AEC collaboration server/viewer/connectors/SDK ecosystem.
Swift Package Manager — Swift package/build graph and large modular Swift codebase.
gRPC — Cross-language RPC implementation; native build systems.
gRPC Go — Go RPC stack and protobuf/gRPC code generation.

Choose a question and compare two repositories. Do not wander through ten giant repos without a hypothesis.

Engineering practice

What mature teams optimize

Explicit ownership and small blast radius
Compatibility during rolling change
Structured observability and correlation IDs
Data migration discipline
Cancellation, deadlines, retries and idempotency
Least-privilege capabilities and trust boundaries
Tests aligned with architectural boundaries
Reproducible builds and generated artifacts
Deletion of old shims and duplicate authority

identity ≠ permission ≠ capability ≠ possession of every secret