# Stage 02: Architecture Inventory

Date: 2026-07-29

The machine-readable inventory is `architecture-inventory.json`. Regenerate it with:

```shell
python tools/build_architecture_inventory.py
python tools/build_architecture_inventory.py --check
```

## Current Shape

- The product is a single-container modular monolith with one Python process and SQLite WAL.
- The browser is a build-free single-page application served by the same process.
- The primary navigation exposes 16 workspaces.
- The current database bootstrap defines 34 tables.
- HTTP routing and service orchestration are concentrated in `server.py`.
- Schema creation, inline migrations, and all persistence methods are concentrated in
  `database.py`.
- The frontend loads six ordered CSS layers and one global application script.
- Background refresh and automatic screener work execute as daemon threads in the HTTP
  process.

## Ownership Inventory

### Shared market and system data

Dashboard snapshots, synchronization runs, stock master data, daily bars, benchmark bars,
daily indicators, fundamental indicators, money flow, auction factors, earnings events,
popularity factors, institutional list data, public screener strategies, reason overrides,
seat aliases, sector phase overrides, and encrypted system settings are shared.

### User-owned data

Sessions, personal credentials, birth profiles, watchlists, review notes, custom strategies,
private screener runs, mentor messages and preferences, saved queries, tracking entries,
alerts, trades, assistant messages, and heaven readings are user-scoped. Every repository
extracted in later stages must preserve this boundary explicitly.

## Runtime Entrypoints

- HTTP and application bootstrap: `server.py`
- Persistence and migrations: `database.py`
- Access policy: `api_access.py`
- Market providers: `tushare_client.py`, `ifind_client.py`, `chart_data_provider.py`,
  `realtime_aggregator.py`
- Deterministic computation: `sentiment_engine.py`, `screener.py`, `advanced_strategies.py`,
  `market_insights.py`, `heaven_engine.py`
- LLM calls: `mentor_agent.py`, `heaven_agent.py`, `assistant_agent.py`, `llm_strategy.py`
- Browser shell and pages: `static/index.html`, `static/app.js`, and the ordered CSS files

## Primary Structural Risks

1. Request routing, use cases, scheduling, provider selection, serialization, and account
   context coexist in one service module.
2. Database migrations cannot be reviewed independently from repository behavior.
3. Several business paths instantiate provider clients directly, so source policy is not
   centrally enforceable.
4. LLM authorization, quota accounting, model selection, streaming, and error handling are
   distributed across multiple adapters.
5. Global DOM state and page behavior share one JavaScript file, increasing cross-page
   regression risk.
6. CSS correctness depends on load order and late overrides rather than explicit layer
   ownership.
7. In-process daemon jobs have no durable queue and some failure paths are not observable.

## Inventory Limits

The JSON inventory records source-level declarations and references. It does not claim that
every declared endpoint is exercised or every table is populated. Runtime coverage and data
quality are separate contracts introduced in later governance stages.
