Skip to content

docs: add SDK package boundary and dependency direction map - #328

Merged
El-swaggerito merged 1 commit into
Axionvera:mainfrom
jd5073356-max:docs/285-sdk-package-boundary-map
Jul 27, 2026
Merged

docs: add SDK package boundary and dependency direction map#328
El-swaggerito merged 1 commit into
Axionvera:mainfrom
jd5073356-max:docs/285-sdk-package-boundary-map

Conversation

@jd5073356-max

Copy link
Copy Markdown
Contributor

Summary

docs/dependency_direction_map.md existed only as a 4-line stub — a title and one sentence referencing "core, utils, and contract clients," none of which match any real module in this SDK. This replaces it with a real map, verified directly against src/'s actual imports rather than inferred from module names or copied from architecture.md's existing (partially stale) diagram.

Per the acceptance criteria in #285:

  • Architecture boundary map added: full per-module ownership/dependency table covering all 12 real src/ directories. architecture.md's existing layer diagram only documented 9 of them — account, errors, and vault exist in src/ with real, substantial implementations and were undocumented anywhere in the repo.
  • Module responsibilities explained: added the three missing module sections to architecture.md in its existing format, plus the full ownership table in the new map.
  • Dependency direction documented: account is correctly placed in the infrastructure layer (it's an identity/signing abstraction with a pluggable Signer + hardware/mobile-signer extension point), not a peer feature module — even though only transactions has adopted it so far. vault is documented as a pure re-export facade over soroban with no implementation of its own. And the configdiagnostics mutual reference — which looks exactly like the cycle the layer rule forbids — is explained precisely: diagnostics/hooks.ts (a leaf config depends on) and diagnostics/report.ts (which depends on config) never import each other, so npm run check:circular reports zero cycles despite the module-level mutual reference. Worth knowing before adding a new import between the two, since the circular-dependency checker operates on individual files, not directories.
  • Security-sensitive modules highlighted: account/wallet are the only modules that ever touch secret key material, errors owns redaction, diagnostics has its own independent redaction layer.
  • Cross-module integration examples included: correct vs. incorrect examples for config resolution, deep imports, and adopting the account abstraction.
  • README links added: neither new doc was linked from README.md's Documentation section before this PR — architecture.md (already large and useful) was effectively undiscoverable.

Pre-existing, out-of-scope finding

While verifying the repo before touching docs, npm run verify reported 46 pre-existing test failures across 5 files (retry-policy.test.ts, types/asset.test.ts, and others) — functional bugs in retry classification and asset validation, unrelated to module structure. npm run lint (tsc --noEmit) and npm run check:circular both pass cleanly, which is what this doc's claims actually depend on, so these failures don't block anything in this PR. Flagging for visibility rather than expanding this PR's scope into unrelated bug fixes.

Test plan

  • npm run lint (tsc --noEmit) — passes
  • npm run check:circular — passes, 46 modules, 0 cycles
  • Every dependency edge in the new map was verified with grep -rhoE "from '\.\./[a-z]+" src/<module> per module, not assumed
  • Every relative link in the new/edited docs resolves to a real file
  • README links to both architecture.md and the new dependency map

Closes #285

docs/dependency_direction_map.md was a 4-line stub referencing "core,
utils, and contract clients" — none of which match the SDK's actual module
names. Replaced it with a real map, verified against src/'s actual imports
(grep -rhoE "from '\.\./[a-z]+" per module, not inferred from names):

- Full per-module ownership/dependency table for all 12 real src/
  directories. architecture.md's existing layer diagram only covered 9 of
  them - account, errors, and vault existed in src/ with no documentation
  at all anywhere in the repo.
- account is Layer 1 infrastructure (an identity/signing abstraction with
  a pluggable Signer + hardware/mobile signer extension point), not a peer
  feature module, even though only transactions has adopted it so far -
  that's the intended migration direction, not a violation of the "features
  don't cross-import" rule.
- vault has zero implementation of its own: it's a pure re-export facade
  over soroban, existing only for a more discoverable public import path.
- config and diagnostics reference each other, which looks like exactly
  the cycle the layer rule forbids. It isn't one: diagnostics/hooks.ts (a
  leaf config depends on) and diagnostics/report.ts (which depends on
  config) never import each other, so npm run check:circular reports zero
  cycles despite the module-level mutual reference. Documented precisely
  since the circular-dependency checker operates on individual files, not
  directories, and a future import into the wrong file could create a real
  cycle it wouldn't catch as clearly.
- Security-sensitive boundaries called out explicitly: account/wallet are
  the only modules touching secret key material, errors owns redaction,
  diagnostics has its own independent redaction layer.
- Correct vs. incorrect cross-module and package-root import examples.

Also added the account, errors, and vault module sections to
architecture.md (present in src/, undocumented there) and pointed its
now-superseded hand-drawn layer diagram at the new, verified map instead of
maintaining two potentially-drifting versions of the same DAG.

Neither new-doc file previously existed as real content and neither is
linked from README.md before this commit - added both.

Closes Axionvera#285
@El-swaggerito
El-swaggerito merged commit 9428aa9 into Axionvera:main Jul 27, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add SDK package boundary and dependency direction map

2 participants