xiaobaifupan/ARCHITECTURE.md

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.