41 lines
2.1 KiB
Markdown
41 lines
2.1 KiB
Markdown
# 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.
|