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.