learning_ai_invt_trdg/docs/CONVENTIONS.md

Repository Conventions

Purpose

This document defines naming conventions, directory structure rules, and import boundaries for learning_ai_invt_trdg. It is the authoritative reference for where code lives and what each package is allowed to import.

---

Package Names

Package	Name in package.json	pnpm --filter alias
Backend	@bytelyst/trading-backend	trading-backend
Web	@bytelyst/trading-web	trading-web
Mobile	@bytelyst/trading-mobile	trading-mobile
Shared	@bytelyst/trading-shared (internal — not published)	—

---

Directory Structure

learning_ai_invt_trdg/
├── backend/
│   ├── src/
│   │   ├── backtest/       # Backtesting engine and guards
│   │   ├── config/         # Environment config loader (config/index.ts is the only place process.env is read)
│   │   ├── connectors/     # Exchange connectors (Alpaca, CCXT) + factory
│   │   ├── domain/         # Trading domain enums, value types, and pure domain logic
│   │   ├── repositories/   # Cosmos DB data-access layer (one file per entity)
│   │   ├── scripts/        # Internal one-time scripts and verification contracts (not imported by src/)
│   │   ├── services/       # Application services (apiServer, TradeExecutor, aiClient, etc.)
│   │   ├── strategies/     # 7-rule ProStrategyEngine and individual rule implementations
│   │   └── utils/          # Generic utilities (logger, symbolMapper, etc.)
│   ├── *.ts                # Root-level verification / reconciliation scripts (not part of the runtime)
│   └── package.json
├── web/
│   └── src/
│       ├── backtest/       # Backtest feature: hook, flags, UI components
│       ├── components/     # Shared React components (AuthContext, Login, ChatControl, etc.)
│       ├── hooks/          # React hooks (useWebSocket, useTabFeatureFlags, etc.)
│       ├── lib/            # Utility modules: authSession, runtime, profileApi, etc.
│       ├── tabs/           # Top-level tab components (one file per tab)
│       ├── test/           # Vitest test setup and fixtures
│       ├── App.tsx         # Root component: tab routing, auth gate, feature flags
│       └── main.tsx        # Vite entry point
├── mobile/
│   ├── app/                # Expo Router file-based routes
│   │   ├── (tabs)/         # Tab screens: index, positions, history, strategies, settings
│   │   ├── _layout.tsx     # Root layout (auth gate, kill-switch)
│   │   ├── chat.tsx        # AI chat surface
│   │   └── marketplace.tsx # Marketplace surface
│   ├── components/         # React Native shared components
│   ├── hooks/              # React Native hooks
│   ├── lib/                # runtime, telemetry, authSession equivalents
│   ├── providers/          # MobileAuthProvider, TradingDataProvider
│   └── utils/              # Utility functions
├── shared/                 # Cross-surface constants and TypeScript interfaces
│   ├── feature-flags.ts    # TradingFeatureFlagsResponse, TabFeatureFlags, BacktestFeatureFlags
│   ├── realtime.ts         # SOCKET_NAMESPACES, buildTradingSocketOptions, isUnauthorizedSocketError
│   ├── request-id.ts       # createRequestId()
│   ├── runtime.ts          # getRuntimeEnvironment()
│   ├── product.ts          # productConfig — canonical product identity
│   ├── control-plane.ts    # Control-plane state types
│   ├── platform-web.ts     # Web-specific platform helpers
│   └── platform-mobile.ts  # Mobile-specific platform helpers
├── docs/                   # All project documentation
├── scripts/                # Root-level build/verify scripts
└── vendor/                 # Local vendored @bytelyst/* packages (symlinked or copied)

---

Import Boundary Rules

Rule 1 — shared/ is the only cross-surface code

No surface may import directly from another surface's src/.

Importer	May import from
backend/src/	shared/, vendor/bytelyst/*, npm packages
web/src/	shared/, vendor/bytelyst/*, npm packages
mobile/	shared/, vendor/bytelyst/*, npm packages
shared/	npm packages only — never from backend, web, or mobile

Violation example (never do this):

// In web/src — WRONG
import { TradeExecutor } from '../../../backend/src/services/TradeExecutor.js';

Rule 2 — config/index.ts is the only process.env reader in the backend

All environment variable access in backend/src/ goes through config/index.ts. No other file calls process.env directly. This makes the config surface auditable and testable in isolation.

Rule 3 — domain/ contains no I/O

backend/src/domain/ is pure TypeScript: enums, value types, and functions with no database calls, no HTTP, and no filesystem access. It may be imported by any other backend module.

Rule 4 — repositories/ only talk to Cosmos

backend/src/repositories/ (or services/*Repository.ts) are the only files that import @azure/cosmos or call Cosmos client methods. Services and strategies call repositories; they do not call Cosmos directly.

Rule 5 — scripts/ are not imported at runtime

backend/src/scripts/ contains verification contracts (e.g., verifyWebsocketContract.ts) that run as standalone processes. They are never import-ed by backend/src/index.ts or any other runtime module. Root-level backend/*.ts scripts follow the same rule.

Rule 6 — shared/ exports must be serialisable

Everything exported from shared/ must be importable in all three environments: Node.js (backend), browser (web), and React Native (mobile). No Node.js built-ins, no DOM APIs, no React Native-specific APIs.

Rule 7 — Trading domain logic stays in the backend

No trading strategy logic, risk rules, capital guard calculations, or execution logic may be moved into shared/, web/, or mobile/. Backend is authoritative.

---

Naming Conventions

Files

Context	Convention	Example
TypeScript source	camelCase.ts	apiServer.ts, healthTracker.ts
React components	PascalCase.tsx	OverviewTab.tsx, AuthContext.tsx
React hooks	use prefix, camelCase.ts	useWebSocket.ts, useTabFeatureFlags.ts
Test files	.test.ts / .test.tsx	App.dom.test.tsx
Verification scripts	verify*.ts / test*.ts	verifyApiContract.ts
Docs	SCREAMING_SNAKE.md	CONVENTIONS.md, OPERATIONS.md

Identifiers

Context	Convention	Example
Classes	PascalCase	ApiServer, TradeExecutor
Interfaces / types	PascalCase	TradingFeatureFlagsResponse, BotState
Constants (module-level)	SCREAMING_SNAKE_CASE	SOCKET_NAMESPACES, BACKTEST_FLAG_KEYS
Functions	camelCase	buildTradingSocketOptions, createRequestId
React components	PascalCase	OverviewTab, LivePulseTicker
Environment variables	SCREAMING_SNAKE_CASE	COSMOS_ENDPOINT, TAB_MARKETPLACE_ENABLED

API Endpoints

Scope	Prefix	Auth
Public product API	/api/	requireAuth (platform JWT)
Internal operator tooling	/internal/	requireAuth — firewall-restrict in prod
Admin-only mutations	/api/admin/	requireAuth + requireAdmin
Health / observability	/health, /metrics	None — firewall-restrict in prod

Socket.IO Events (backend → client)

Event	Payload type	Notes
state	BotState	Full state on connect
symbol_update	{ symbol, data }	Per-symbol signal/indicator update
positions_update	Position[]	Full position list replacement
orders_update	Order[]	Full order list replacement
history_update	HistoryRow	Single new closed trade
new_alert	Alert	Single new alert
health_update	HealthSnapshot	Loop health and trading control state
account_snapshot	AccountSnapshot	Exchange account balance snapshot
order_failure	OrderFailureRecord	Single order failure notification
operational_event	OperationalEvent	Structured operational log entry
operational_event_cleared	—	Signals log has been cleared

---

Feature Flag Conventions

• Feature flags are defined in shared/feature-flags.ts as TypeScript interfaces.
• Flag key constants (BACKTEST_FLAG_KEYS, TAB_FLAG_KEYS) are the single source of truth for env var names — never hardcode the string elsewhere.
• Backend reads env vars via config/index.ts; web/mobile read via GET /api/feature-flags.
• Admin accounts bypass all feature flags — they always see everything.
• New flags default to enabled (opt-out model) unless gating a genuinely unreleased feature.

---

Request Tracing Convention

Every HTTP request from web or mobile must include:

x-request-id: <createRequestId('surface-context')>
Authorization: Bearer <accessToken>

Backend echoes x-request-id in all responses. Use this header as the primary correlation key when tracing a request across client logs and backend logs.

---

Test / Verification Script Convention

Backend verification scripts follow this pattern:

// verify*.ts or test*.ts at backend/ root or backend/src/scripts/
import assert from 'node:assert/strict';

function main() {
    // ... assertions ...
    console.log('[PASS] Description of what passed.');
}

main();

• Exit with a non-zero code on AssertionError (Node.js default behaviour).
• Print [PASS] ... on success; never console.log progress in the happy path.
• Never connect to real infrastructure — use in-memory fixtures only.
• Wire into package.json scripts as check:* and into npm run test or npm run lint.