Aurox Intelligence

Simulation-first financial intelligence platform — market data · explainable signals · deterministic simulation trading

---

Table of Contents

• System Purpose
• Current Product Surfaces
• Monorepo Structure
• Non-Negotiable Architecture Boundaries
• Read and Write Patterns
• Prerequisites
• Quick Start
• Environment Variables
• Development Commands
• Testing and Validation Workflow
• Simulation and Execution Safety
• Performance and Debugging Tips
• Docs Map
• Known Baseline Issue
• Contribution Checklist
• Troubleshooting

---

System Purpose

Aurox Intelligence is designed to:

• aggregate provider-backed market context
• compute deterministic signals and forecast context
• run auditable simulation trading across stocks, ETFs, and crypto
• expose route-driven, typed read models for workstation UI flows

Safety and correctness take priority over convenience:

1. Safety
2. Correctness
3. Determinism
4. Observability
5. Performance

---

Current Product Surfaces

Web routes include:

• /dashboard
• /market
• /markets/rankings
• /stocks, /stocks/[symbol]
• /fx, /fx/[pair]
• /signals
• /forecasts
• /portfolio
• /invest
• /invest/overview
• /invest/simulation
• /invest/portfolio
• /invest/orders
• /invest/live-readiness
• /invest/accounts
• /invest/broker-health
• /invest/broker-modes
• /invest/stocks, /invest/etfs, /invest/crypto
• /admin, /admin/monitoring
• /account, /account/profile, /account/settings, /account/activity
• /login, /signup

---

Simulation and Lane Configuration

Simulation is the default execution target. Lanes define capital limits, asset scope, and execution policy per strategy. Live execution is gated behind a readiness check.

---

Monorepo Structure

apps/
  web/                         # Next.js App Router UI + server orchestration
  worker/                      # Background worker runtime

packages/
  api-contracts/               # Zod schemas and shared contracts
  db/                          # SQL repositories, migrations, read models
  ingestion/                   # Canonicalization + ingestion lifecycle
  providers/                   # External data provider adapters
  signals/                     # Pure signal logic (no I/O)
  forecasting/                 # Pure forecast logic (no I/O)
  agents/                      # Execution and orchestration workflows
  ai-market-intelligence/      # Explainable market intelligence helpers
  observability/               # Logging/telemetry scaffolding
  design-tokens/               # Shared tokens/CSS themes

---

Knowledge Architecture

Aurox is backed by a structured knowledge base that maps financial domains, signal frameworks, and system architecture into a connected graph. The knowledge engine powers explainability across signals, recommendations, and risk decisions.

---

Localization

The platform is localized across multiple languages. All financial UI labels, risk copy, and signal explanations are translation-ready.

---

Non-Negotiable Architecture Boundaries

• packages/providers owns all external provider calls.
• packages/db is the only SQL/persistence boundary.
• packages/api-contracts is the contract source of truth.
• packages/signals and packages/forecasting stay pure.
• apps/web orchestrates routes/services/mappers/UI only.

Forbidden:

• provider calls in UI components
• direct SQL in routes/components
• duplicated contract schemas in app layer
• execution or risk logic in presentation components

---

Read and Write Patterns

Canonical read path:

Query -> Mapper -> Service -> Route -> UI

Canonical write path:

UI -> Server Action -> Zod Validation -> Domain Service -> Repository Transaction -> Revalidation

Keep these seams explicit when adding or changing features.

---

Prerequisites

• Node.js 20+ recommended
• pnpm (repo uses pnpm@10)
• PostgreSQL for full repository-backed behavior

---

Quick Start

1. Install dependencies

pnpm install

2. Create local env

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

The repository-root .env is the single source of truth for shared runtime config and secrets. Both apps/web and apps/worker read from it during development — you do not need per-app .env files. .env is git-ignored and must never be committed.

3. Generate a strong AUTH_SECRET

AUTH_SECRET signs session tokens and is required for the web app to boot. The placeholder in .env.example is intentionally too short. Generate a real one:

openssl rand -base64 32

Set it in the root .env:

AUTH_SECRET=<paste-the-generated-value>

4. Verify the environment is loaded

pnpm env:check

This prints which env files were found and confirms AUTH_SECRET presence (yes/no only — it never prints secret values). It exits non-zero if a required variable is missing.

5. Run DB migrations

node packages/db/scripts/migrate.mjs

6. Start development

pnpm dev

7. Open the app

• http://localhost:3000

How env loading works in development

• pnpm dev runs Turborepo, which first builds the internal @repo/* packages that the web app consumes as compiled dist/, then starts the persistent dev servers.
• The web dev/build/start scripts use dotenv-cli to inject the root .env (and an optional root .env.local override) into the process. Next.js then propagates those real env vars to its render workers — which is why a config-file loader is not sufficient here.
• NODE_ENV is forced per command (dev → development, build/start → production) via cross-env, so a NODE_ENV value accidentally left in .env cannot corrupt a production build. Do not set NODE_ENV in .env.
• The worker loads the root .env itself (via @next/env) and consumes the @repo/* packages directly from their TypeScript source through tsx, so it does not depend on prebuilt dist/ during development.

---

Environment Variables

See .env.example for complete list. Key groups:

• Core app/runtime:
  • NODE_ENV
  • APP_BASE_URL
  • NEXT_PUBLIC_APP_URL
  • AUTH_SECRET
• Database:
  • DATABASE_URL
  • DATABASE_URL_UNPOOLED
  • DIRECT_URL
• Providers:
  • MARKET_DATA_PROVIDER
  • MARKET_HISTORY_FALLBACK_PROVIDERS
  • MARKET_QUOTE_FALLBACK_PROVIDERS
  • Provider API keys (POLYGON_API_KEY, FINNHUB_API_KEY, etc.)
• Broker execution safety:
  • BROKER_EXECUTION_PROVIDER (defaults to simulation)
  • BROKER_DRY_RUN
  • BROKER_SANDBOX_MODE
  • BROKER_ALLOWED_LIVE_MODE_IDS

Important:

• Never commit secrets or .env files.
• Keep simulation defaults unless live readiness is explicitly approved.

---

Development Commands

Root:

pnpm dev
pnpm build
pnpm typecheck
pnpm test
pnpm lint
pnpm clean

Targeted:

pnpm dev:web
pnpm build:web
pnpm typecheck:web

pnpm dev:worker
pnpm build:worker
pnpm typecheck:worker

Package-level examples:

pnpm --filter @repo/api-contracts typecheck
pnpm --filter @repo/db typecheck
pnpm --filter @repo/ingestion typecheck
pnpm --filter @repo/providers test

---

Testing and Validation Workflow

When changing code, prefer smallest meaningful validation first.

Typical flow:

1. Run targeted package checks for touched areas.
2. Run pnpm build:web for route/UI/server changes.
3. Escalate to broader checks only when needed.

Suggested minimums by change type:

• Contracts changed:
  • pnpm --filter @repo/api-contracts typecheck
• DB/repository changed:
  • node packages/db/scripts/migrate.mjs
  • pnpm --filter @repo/db typecheck
• Provider logic changed:
  • pnpm --filter @repo/providers typecheck
  • pnpm --filter @repo/providers test
• Dashboard/web route changed:
  • pnpm build:web

---

Simulation and Execution Safety

Simulation is the default execution mode.

Key expectations:

• deterministic accounting and order lifecycle
• transaction and snapshot auditability
• explicit risk and policy gates before any execution
• safe fallback behavior when provider or data paths degrade

Do not:

• bypass risk checks
• fake provider data
• enable autonomous live execution without readiness gates

Simulation persistence tables include:

• app.simulation_accounts
• app.simulation_portfolios
• app.simulation_positions
• app.simulation_orders
• app.simulation_transactions
• app.simulation_snapshots

---

Performance and Debugging Tips

• Prefer targeted query/service timings in development (NODE_ENV=development).
• Avoid adding expensive calls to broad routes (/dashboard) unless needed for initial shell.
• Use streaming boundaries and request-scoped dedupe for heavy sections.
• Cache only non-user-specific data globally; keep user-specific reads request-scoped.
• Watch .next/dev/logs/next-development.log for route timing and warning context.

For bottleneck analysis on dashboard-like pages:

1. instrument loader/query/service timing
2. identify dominant path (provider breadth, DB read model, history)
3. apply one focused optimization
4. re-measure and compare

---

Docs Map

Primary entry points:

• System Docs Master
• Current State Summary
• Architecture Overview
• Architecture Current State
• Architecture Best Practices
• Simulation Test Plan

Domain docs:

• Finance System Overview
• Signal Framework
• Risk Management
• Execution Layer
• Portfolio Construction
• Reporting Framework
• Broker Infrastructure
• AI in Finance

Live microtrading docs:

• Overview
• Readiness Checklist
• Risk Policy and Guards
• Incident Response and Kill Switch

---

Known Baseline Issue

As of 2026-04-25, pnpm --filter @repo/web typecheck currently fails with existing issues in:

• apps/web/components/signals/signal-score-badge.tsx
• apps/web/server/auth/service.test.ts
• packages/agents/src/execution/execution-mode-registry.ts

Treat these as baseline unless your change directly touches those areas. Verified passing on the same date:

• pnpm --filter @repo/api-contracts typecheck
• pnpm --filter @repo/db typecheck

---

Contribution Checklist

Before opening a PR:

• confirm boundaries are preserved (providers, db, api-contracts, etc.)
• keep changes scoped and reversible
• run targeted validation commands
• include any migration/risk implications in notes
• call out residual risks and follow-up tasks

PR summary should include:

• what changed
• why it changed
• commands run
• known unrelated failures
• rollback approach (if relevant)

---

Troubleshooting

AUTH_SECRET undefined / "Invalid or missing authentication environment configuration"

The web app reads AUTH_SECRET from the repository-root .env. If it is missing or shorter than 32 characters the app fails fast with an actionable message.

1. Confirm the value is present and visible:

   pnpm env:check

2. If missing, generate one and add it to the root .env:

   echo "AUTH_SECRET=$(openssl rand -base64 32)" >> .env

3. Start fresh — next dev caches env at process start:

   pnpm dev

Notes:

• The value must live in the root .env (preferred) or apps/web/.env.local.
• Never prefix it with NEXT_PUBLIC_ — that would expose the signing key to the browser bundle.
• There is intentionally no insecure development fallback for AUTH_SECRET.

Cannot find module @repo/db/dist/index.js (worker)

This means a workspace package has not been built where a consumer expected compiled output. The web app consumes @repo/* as built dist/; pnpm dev builds those packages first via Turborepo (dev depends on ^build). The worker consumes the same packages from source through tsx, so it does not need dist/ in development.

If you still hit this:

pnpm build            # builds all internal package dist/ once
# or just the one package:
pnpm --filter @repo/db build

Then re-run pnpm dev.

Node version mismatch

This repo targets the Node version used in CI (Node 24.x at time of writing). If you see syntax or ESM resolution errors that nobody else hits, check:

node -v

and switch with your version manager (e.g. nvm use) to match.

Turborepo --parallel warning about task dependencies

pnpm dev runs turbo run dev (no --parallel). In Turborepo 2.x, --parallel ignores task dependencies, which would skip the ^build step the web app needs. The default turbo run dev already runs the dev tasks concurrently and respects dependsOn, so do not re-add --parallel.

EPERM / sandbox / path errors when running scripts

If command execution fails with filesystem permission errors, rerun outside restrictive sandbox or from a shell with proper workspace permissions.

Port already in use (Next dev)

If you see "another next dev server is already running":

• stop the existing process or choose another port
• on Windows: taskkill /PID <pid> /F

Slow dashboard route

Start by measuring loaders in development logs, then optimize the single slowest path. Typical hotspots:

• broad quote universe fetches
• expensive provider history reads
• DB read model cold path latency

Favicon/logo not updating

Browser favicon caches aggressively:

• hard refresh
• clear site data
• verify file in apps/web/public/ and metadata icon config