Vaultro Internal Engineering Handbook

Single entry-point for new and current developers: architecture, standards, execution workflow and operational guardrails.

Current program decision: internal re-architecture first (DI, engines, boundaries, tests, onboarding). Public SDK expansion is parked for the final stage.

Quickstart (Internal Dev)

Minimal path to start contributing with quality gates enabled.

bash

pnpm setup:dev
pnpm matrix:validate
pnpm workers:type-check:all
pnpm lint && pnpm type-check
pnpm test:all
pnpm verify:migration:parity

Architecture (Target)

Internal structure target for onboarding, maintainability and strong ownership boundaries.

Layer	Purpose	Rule
`apps/*`	Wallet and product UIs	Consume packages only, never service internals
`@vaultro/core`	Contracts and shared types	Single source for cross-service contracts
`@vaultro/engine`	Business orchestration	Framework-agnostic and DI-first
`WORKERS/*`	Edge services and API frontdoor	Use stable contracts from core

Internal Packages

Planned and active package boundaries for internal team integration:

@vaultro/core: shared contracts, types, status models
@vaultro/engine: orchestrated use-cases (swap, transfer, bridge, invest, recovery)
@vaultro/crypto: signing, key handling, auth primitives
@vaultro/ui: reusable internal components and design patterns

Workers Platform

Current frontdoor and services topology used by internal apps and services.

Frontdoor: api.vaultro.space (and final domain when DNS stable)
Core workers: relayer, rpc, aggregator, price, token, registry, download, docs, status
Cross-cutting: correlation-id propagation and strict auth matrix per endpoint

Endpoint Auth Matrix

Official source is generated from worker routes and published automatically.

Matrix source: /data/endpoint-auth-matrix.json | Validation: pnpm matrix:validate

Loading endpoint matrix...

DI Standard

All critical engines must receive adapters instead of importing global state directly.

typescript

type EngineAdapters = {
  rpc: RpcAdapter;
  signer: SignerAdapter;
  wallet: WalletAdapter;
  storage: StorageAdapter;
  featureFlags: FeatureFlagsAdapter;
};

export function createSwapEngine(adapters: EngineAdapters) {
  // no direct imports from UI or runtime globals
}

Testing and Quality Gates

Quality gates are mandatory for all internal deliveries.

Command	Purpose
`pnpm test:unit`	fast isolated checks
`pnpm test:contract`	SDK/worker contract safety
`pnpm test:integration`	cross-service integration
`pnpm ci:gates`	full quality and build gates
`pnpm verify:migration:parity:full`	critical migration parity + UX smoke

Release and Change Management

Use semver validation per package in CI.
Generate changelog artifacts on every gate run.
Follow deploy checklist and rollback-safe sequence.
No merge to production path without green gates.

Security and Access

Client-facing routes use signed requests; internal key is service-to-service only.
No secrets in frontend or extension bundles.
All new endpoints must be classified in auth matrix before deploy.
Long-term target is repo-level isolation for sensitive domains.

Current Priority

Execution order approved for current cycle:

Consolidate internal package architecture and strict boundaries.
Standardize DI for critical engines and remove residual coupling.
Increase test coverage and internal onboarding reliability.
Strengthen governance: CODEOWNERS, ADR cadence, contribution flow.

Public SDK Status

Parked track: Public SDK expansion is intentionally deferred until internal architecture stabilization is complete.

The existing public SDK surface remains available but is under maintenance-only mode in this phase.