QuantDinger Backend Module Boundaries

This document defines target ownership for the backend. It does not require an immediate rewrite. It is the contract to follow as existing code is decomposed.

Layer Model

Layer	Owns	Must Not Own
routes	HTTP parsing, auth checks, status codes, request/response mapping	trading loops, exchange-specific rules, long-running jobs
openapi	schema registration, OpenAPI export, operation metadata	business logic
services	business workflows and use-case orchestration	raw Flask request objects except at route boundary
services/live_trading	exchange and broker adapters, order API normalization	strategy lifecycle, user auth, HTTP responses
services/grid	grid engine, cell state, fill normalization, reconciliation	route parsing, frontend-specific formatting
data_sources	market data adapters and fetch policy	strategy execution or account mutation
data_providers	dashboard/global-market aggregation and cache policy	trading decisions or order placement
utils	low-level auth, db, cache, logging, time, crypto helpers	feature workflows
config	environment and settings resolution	runtime mutation side effects
migrations	schema and seed data	Python runtime behavior

Current Hotspots

These files mix multiple responsibilities and should be decomposed gradually:

File	Current Risk	Target Split
app/__init__.py	app factory plus core Flask wiring	keep app factory only
app/startup.py	worker boot, strategy restore, process-local singletons	distributed worker ownership guards
app/routes/strategy.py	lifecycle, templates, AI generation	route modules per subdomain
app/routes/strategy_account_routes.py	account snapshot and account position mirror	account service facade
app/routes/backtest_center.py	unified V2 backtest endpoint facade	one request schema and one simulation service facade
app/routes/strategy_deviation_routes.py	dry-run deviation endpoint	deviation service facade
app/routes/strategy_grid_routes.py	grid resting order endpoint	grid route facade
app/routes/strategy_ledger_routes.py	trades, equity curve, performance endpoints	ledger/read-model service facade
app/routes/strategy_positions_routes.py	strategy live position read model	position query service facade
app/routes/strategy_review_routes.py	AI strategy review endpoints	review request schema and service facade
app/routes/strategy_logs_routes.py	runtime log query endpoint	observability route facade
app/routes/strategy_notifications.py	strategy notification endpoints	notification service facade
app/routes/quick_trade.py	HTTP, credential handling, exchange selection, order formatting	route facade plus quick-trade service
app/routes/ai_chat.py	memory, skills, tools, chat, streaming	separate AI route modules
app/routes/settings.py	schema, config values, brand, connection testing	settings service plus config schemas
app/services/trading_executor.py	signal loops, order placement, sync, persistence	executor core, order intents, locks, recorders
app/services/backtest.py	data loading, strategy execution, simulation, metrics	backtest pipeline components
app/services/pending_order_worker.py	worker loop plus dispatch and sync details	worker shell, dispatcher, reconciliation

Route Layer Rules

• Routes may validate input, call services, and shape HTTP responses.
• Routes must not start background threads directly.
• Routes must not contain exchange-specific order sizing logic.
• Routes must not perform multi-step database transactions inline unless the logic is being migrated and covered by tests.
• Streaming routes must define timeout, heartbeat, and cancellation behavior.

Service Layer Rules

• Services own use-case flow and can coordinate repositories/adapters.
• Services should accept plain Python values, not Flask request objects.
• Services should return plain dicts/dataclasses or typed result objects.
• Services should define idempotency behavior when they mutate state.
• Long-running service work should be runnable as a job or worker task.

Adapter Rules

• Exchange and broker adapters normalize external APIs into internal contracts.
• Adapters should not know about Flask, users, or frontend response shapes.
• Adapter methods should accept explicit client_order_id when the venue supports it.
• Adapter-specific rate limits and retry rules should be isolated from business logic.

Startup Boundary

Target structure:

• create_app() creates Flask, configures JSON/CORS, registers routes.
• startup.py owns worker startup and process-local service singletons.
• Worker startup is disabled for OpenAPI export, tests, and one-off scripts.
• Multi-process deployments must have an explicit owner for each background worker.

Documentation Boundary

• Root README.md: user-facing quick start and product overview.
• docs/: architecture, API, operations, integration guides.
• docs/agent/: agent-facing docs only, English only.
• Generated API files must say how they were generated.
• Deprecated docs must be moved to an archive or marked with a date and replacement.

Language Boundary

• Code comments, docstrings, log messages, internal error details, module names, function names, variables, and engineering documentation should be English by default.
• Chinese is allowed only for user-facing localized text, prompts, translation dictionaries, examples that intentionally demonstrate Chinese output, exchange or market terminology that is inherently Chinese, and backward-compatible API fields that already expose localized content.
• Do not mix Chinese comments into core trading, concurrency, API, database, or deployment code. If localized text is needed, keep it behind an explicit language selector or i18n structure.
• When replacing legacy Chinese comments, preserve the technical meaning and avoid changing runtime behavior in the same edit.

Compatibility Rule

When moving code, keep the old import path or route path until all callers are verified. If compatibility cannot be preserved, document the break and update frontend/API tests in the same change.