> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/engineering-guide/13-repository-atlas.md). # Repository atlas [← Production operations](/nytshift-docs/engineering-guide/12-production-operations.md) · [Documentation home](/nytshift-docs/start-here/readme.md) · Next: [Glossary →](/nytshift-docs/engineering-guide/14-glossary.md) This map is for finding the state owner before editing a symptom. ## Top level ``` apps/ user-facing runtimes packages/ shared contracts, adapters and client kit services/ pure domains and isolated execution service scripts/ supervisors, audits, backup and release tooling docs/ guide, architecture, ADRs, runbooks and tickets pnpm-workspace.yaml workspace membership and dependency overrides turbo.json task graph .env.example documented safe defaults and private configuration taxonomy AGENTS.md repository-wide engineering/safety instructions START_HERE.md current release boundary and operator map ``` ## `apps/web` The Next.js app is both product and BFF. | Area | Look here for | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `app/terminal` | Terminal state, charts, market microstructure, PAPER, authority modes and responsive UI | | `app/nightshift` | Robinhood Chain coverage/radar and asset dossiers | | `app/(customer)` and `app/components/customer-*` | Customer route workspaces for markets, trade, portfolio, activity, funds, orders, agents, research and settings | | `app/(operator)` and `app/components/operator-*` | Session-gated operator workspaces and privacy-safe observability | | `app/(trust)` | Public status, docs, security, help, token and legal routes | | `app/auth` | Privy provider, customer identity and session presentation | | `app/api/market` | Public venue market/book/candle/trade/funding/liquidation routes | | `app/api/rhc` | Canonical RHC price, portfolio, activity, provider and bridge routes | | `app/api/profile` | Verified customer portfolio/activity/funding views | | `app/api/mcp` | MCP transport gateway | | `app/api/agent*` | Proposal and DPoP automation APIs | | `app/api/execution` | Hyperliquid review/submit/cancel/reconcile/dead-man/time-machine | | `app/api/arcus` | Arcus account, preflight, signer, funding and withdrawal routes | | `app/api/health` | Release, readiness and fail-closed aggregate health | | `app/styles.css` | Reviewed CSS source inventory used by the deterministic route splitter | | `app/styles/*` | Independently loaded base, landing, command-deck, terminal and identity CSS outputs | Route files should be thin: authentication, parsing, domain call, response-contract validation and fixed error mapping. Shared domain logic belongs outside route handlers. The `/terminal` compatibility route is composition, not a state owner. Its reviewed module boundaries are: | Module | Ownership | | ---------------------------------- | ------------------------------------------------------------------------------------------- | | `terminal-client.tsx` | Nine-line client composition wrapper | | `terminal-controller.tsx` | Cross-domain composition and derived presentation state | | `terminal-workspace-state.ts` | Bounded market, draft, execution, operator, agent and presentation state hooks | | `terminal-data-controller.ts` | Read/load orchestration and late-response guards | | `terminal-lifecycle-controller.ts` | Polling, context invalidation, subscriptions and preference lifecycle | | `terminal-execution-actions.ts` | Arcus/Hyperliquid review, confirmation, submission, cancellation and reconciliation actions | | `terminal-operator-actions.ts` | Session, proposal, agent, automation and commercial operator actions | | `terminal-workspace-view.tsx` | Presentational workspace only; no hooks or raw transport | | `terminal-domain-clients.ts` | Same-origin, bounded, abortable transport plus registered response-contract validation | `terminal-architecture-budget.test.ts` prevents the compatibility route from returning to one giant component, caps each state-domain hook at 30 React hooks and forbids raw `fetch` in the composed terminal modules. ## `packages/contracts` Owns canonical Zod definitions and deterministic artifacts under `generated/`. Change the registry before producer/consumer code. Generated JSON Schema/OpenAPI files are committed and must not be hand-edited. The high-fan-out registry is split into `core.ts`, `strategy.ts`, `execution.ts` and `platform.ts`, with public/customer documents in their existing named modules. `index.ts` is a compatibility re-export only; workspace consumers import domain subpaths. `domain-boundaries.test.ts` enforces that ownership and the extracted-domain dependency DAG. Key contract domains include: * development API; * signer requests; * public market; * public account; * public RHC readiness/data; * customer portfolio/funding/activity; * agent proposal and automation; * MCP/agent connection and paper state. ## `packages/venues` Owns read-only adapter contracts, official-origin behavior, strict normalization and Robinhood Chain identity/provenance. It is the first stop for provider schema or network semantics—not React components. ## `packages/agent-client` No-secret Node client/CLI helpers for external P-256 identity, DPoP proofs and strict loopback testnet automation requests. It exposes no cancel, retry, funding, wallet, signer or mainnet operation. ## Pure services | Service | State/authority | | ---------------------- | ---------------------------------------------------- | | `services/risk` | Pure AEGIS verdicts; no I/O or signing | | `services/ai` | Proposal validation and abstention; no execution | | `services/market-data` | Hyperliquid streams/Info normalization | | `services/portfolio` | Idempotent portfolio materialization and convergence | | `services/paper` | Deterministic simulation/replay | ## `services/execution-py` The only signer/reconciler domain. Inspect: * `app.py` for application composition, dependency wiring and health only; * `execution_domain.py` for canonical request normalization and reconciliation helpers; * `store.py` for the durable idempotency/audit store; * `dead_man_routes.py`, `hyperliquid_routes.py`, `arcus_routes.py` and `audit_routes.py` for bounded route families; * request models and exact decimal parsing; * loopback authentication; * account/network/scope checks; * SQLite schema/migrations/WAL health; * idempotency and action claims; * Arcus Ed25519 adapter; * Hyperliquid official SDK adapter; * order/bracket/fill/fee/dead-man reconciliation; * secret-free alert outbox; * health and backup integration. Any change here requires Python tests, TypeScript/Python contract parity, signer integration and store-recovery gates. ## `scripts` Scripts are production code. Major families: | Family | Examples | | ---------------------------- | -------------------------------------------------------------- | | Safe local runtime | `local-runtime.mjs` | | Signer supervisors | `signer-runtime.mjs`, `hyperliquid-signer-runtime.mjs` | | Backups | `backup.mjs`, `signer-store-backup.mjs` | | Contract/license/eligibility | `agent-license.mjs`, `execution-eligibility.mjs` | | Canonical evidence audits | RHC registry/bridge/oracle and Arcus funding/withdrawal audits | | Production activation | Privy/charts/provider evidence and activation audit | | Public release | `public-release.mjs`, preflight, smoke and handoff checks | | Soak/operations | live-feed soak, capacity and local health | ## Documentation corpus | Location | Role | | ------------------------- | ------------------------------------------------- | | `docs/guide` | Coherent system narrative | | `docs/*.md` | Normative architecture/product/security documents | | `docs/adr` | Stable design decisions | | `docs/runbooks` | Operator procedures and incident response | | `docs/tickets` | Implementation slices and acceptance criteria | | `docs/assets/screenshots` | Hash-recorded public UI evidence | ## Where to start by symptom | Symptom/change | Start | | -------------------------- | ----------------------------------------------------------------------------------------------- | | Wrong/missing market value | adapter → reference classifier → consumer projection → route → UI | | Chart race or stale bars | exact context key → request sequence → REST/WS merge → renderer lifecycle | | PAPER unexpected fill | book observation ID → risk checkpoint → exact depth walk → ledger reducer | | Agent tool rejected | connection digest/expiry → mode/tool/symbol/account scopes → quota → protocol parser | | Review unavailable | operator session → portfolio convergence → market metadata/book → AEGIS reasons → signer health | | Unknown order | signer action claim → CLOID/client ID → exact status/fill coverage → reconciliation runbook | | Build badge missing | public `/api/health` → release receipt → capacity → strict browser projection | | RHC readiness false | provider topology → archive attestation → WSS head/divergence → stabilization | Use `rg` to search for contract/type names before file names; the same concept often crosses producer, consumer and parity tests. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://nytshift.gitbook.io/nytshift-docs/engineering-guide/13-repository-atlas.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.