跳转至

Shadow Assembly

shadow-assembly is the current product workspace for the Shadow stack.

它取代旧 shadow 作为用户可见的工作台入口：frontend renders the application, backend owns the app-facing API contract, and other Shadow projects remain behind explicit adapters.

Repository Shape

The repository uses a simple root-level frontend/backend layout.

Workspace Role
frontend Next.js app, package name @shadow-assembly/client
backend FastAPI service, Python module site_api, owner of the /api/* contract

The frontend may render pages and proxy requests. It does not own auth, admin, inbox, fundamentals, news, research, fund product data, document evidence, or agent execution semantics.

Backend Owns The Contract

backend/ is the source of truth for:

  • auth and RBAC
  • admin user/fund operations
  • inbox
  • fundamentals
  • news
  • document evidence and PDF materials
  • research workspaces
  • fund products
  • monitoring
  • agent run/stream APIs

Current local backend:

cd backend
uv sync --locked
uv run uvicorn site_api.main:app --reload --host 127.0.0.1 --port 18000

The frontend defaults server-side /api/* proxying to:

http://127.0.0.1:18000

Set SHADOW_ASSEMBLY_SITE_API_BASE_URL only when the backend runs elsewhere.

Frontend

Run from the repository root:

pnpm install
pnpm dev

Or target the workspace explicitly:

pnpm --filter @shadow-assembly/client dev

Open:

http://localhost:3000

Main Routes

The product shell currently includes surfaces such as:

  • /documents
  • /evidence
  • /fundamentals
  • /funds
  • /news
  • /stocks/[symbol]
  • /agent
  • /research/codex
  • /monitoring
  • /admin/users

These routes should depend on same-origin /api/* proxy routes and backend-documented response shapes, not on internal package layouts or storage paths.

Relationship To Other Projects

Dependency How Assembly Uses It
shadow-lighthouse document search, evidence lookup, readable materials
shadow-ingest market and reference data through stable APIs
shadow-factor factor panels and factor metadata through public APIs
shadow-backtest execution simulation through package APIs when a workflow needs it
mail-tracker read-only fund product materialized payloads
shadow-octopus indirectly through Lighthouse read models, not raw writes

Legacy Replacement

旧文档中的 shadow composition layer 不再是当前主入口。

  • Product workspace: shadow-assembly
  • Backtest execution package: shadow-backtest
  • Factor engine: shadow-factor
  • Dataframe access: shadow-ingest

When writing new docs, prefer these concrete project names instead of using shadow as a catch-all owner.