# Architecture

The normative governance contract is documented in
`docs/governance/architecture-standard.md`. This file describes the currently deployed
shape; the standard defines the target boundaries and the rules applied during migration.

The application intentionally keeps a small deployment footprint: one Python process, one
SQLite database, and a build-free browser client. The internal boundaries are nevertheless
explicit so new features do not bypass account isolation or data-quality rules.

## Backend boundaries

- `server.py`: application services and HTTP request/response wiring.
- `api_access.py`: the single authorization policy for authenticated, member, and admin APIs.
- `app_config.py`: runtime paths, local environment loading, and shared input validation.
- `database.py`: SQLite schema, migrations, and persistence operations.
- `tushare_client.py` and `realtime_aggregator.py`: external market-data adapters.
- `sentiment_engine.py`, `screener.py`, and `heaven_engine.py`: deterministic domain logic.
- `mentor_agent.py`, `heaven_agent.py`, and `llm_strategy.py`: bounded LLM adapters.

## Data ownership

Public market snapshots, stock factors, built-in strategies, limit-up reasons, seat aliases,
and sector-element mappings are shared. Only administrators can modify shared knowledge.

Watchlists, review notes, custom strategies, screener runs, mentor conversations, birth data,
alerts, trading journals, and assistant conversations are owned by a user ID and must be
queried with that ID. LLM features additionally require active membership.

## Data integrity

Production reads never synthesize market prices. A failed live request may use the latest real
snapshot at or before the requested date. When no real snapshot exists, the API reports that
the data is unavailable. Demo builders remain test fixtures only.

## Change contract

New endpoints must be added to `api_access.required_role` when they need member or admin
access. New user-owned tables must include `user_id`, an ownership index, and cross-account
tests. API payload compatibility is protected by the Python and Playwright suites.
