Thank you for helping improve PanWatch. This guide describes the current repository layout, development workflow, extension points, and pull-request expectations.
- Search existing issues and pull requests before starting duplicate work.
- For large features, architecture changes, new dependencies, or breaking behavior, open an issue first and describe the user problem and proposed boundary.
- Never commit API keys, tokens, cookies, personal portfolio data, local databases, generated reports, or logs containing private data.
- Keep a pull request focused. Separate unrelated cleanup from the behavior being changed.
| Path | Responsibility |
|---|---|
src/modules/ |
Product modules and their API routes, services, and workflows |
src/modules/automation/ |
Scheduled and on-demand agents, catalog, scheduler, and TradingAgents integration |
src/platform/ |
Shared AI, persistence, market-data, notification, observability, and runtime infrastructure |
packages/marketdata/ |
Standalone typed market-data package with vendor failover |
packages/pan-agent-* |
Reusable agent runtime, metering, and tool-research packages |
frontend/src/ |
React application, pages, components, hooks, and locale resources |
frontend/packages/ |
Shared frontend API, business UI, and base UI packages |
prompts/ |
Prompt templates used by analysis workflows |
tests/ |
Backend, integration, architecture, and evaluation tests |
frontend/tests/ |
Vitest and Testing Library tests |
docs/ |
Public documentation, diagrams, screenshots, and donation assets |
Respect module ownership: product code may depend on platform services, while standalone packages must not import the PanWatch application or database. Architecture tests enforce important boundaries.
- Python 3.10 or newer; the Docker runtime uses Python 3.11.
- Node.js 24.14.0.
- pnpm 9.15.9.
# Terminal 1: create .venv, install backend dependencies, and start :8000
make dev-api
# Terminal 2: install frontend dependencies and start :5183
make dev-webThe frontend development server proxies /api to 127.0.0.1:8000.
Manual setup is also supported:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py
cd frontend
pnpm install
pnpm devCopy .env.example to .env when local configuration is needed. Use disposable test credentials and keep .env untracked.
To install the repository's pre-push test hook:
make install-hooks- Create a branch from the latest default branch.
- Add or update a focused test before or alongside the implementation.
- Keep network calls mocked in unit tests; tests must not require paid APIs or send real notifications.
- Update both language resources and public documentation when user-visible behavior changes.
- Run checks proportional to the affected area, followed by
git diff --check. - Open a pull request using the template and scope and acceptance policy.
Run the smallest focused test while iterating, then the relevant suite before opening a pull request.
# Backend suite
.venv/bin/python -m pytest -q
# Frontend suite, translation guard, type/build verification
pnpm --dir frontend exec vitest run
pnpm --dir frontend run check:i18n
pnpm --dir frontend run check:ui
pnpm --dir frontend run build
# Whitespace and conflict-marker check
git diff --checkPackage-specific changes should also run their own tests, for example:
.venv/bin/python -m pytest packages/marketdata/tests -q
.venv/bin/python -m pytest packages/pan-agent-runtime/tests -qDo not describe a check as passing unless you actually ran it. If an environment prevents a required check, explain the limitation in the pull request.
Before creating an agent, decide whether it is:
- a workflow agent: user-visible and eligible for scheduling; or
- a capability agent: invoked by another workflow or UI action and not independently scheduled.
Use these integration points:
- Implement the agent under
src/modules/automation/, normally by extendingBaseAgentand separatingcollect()frombuild_prompt(). - Reuse
AgentContextfor AI, portfolio, watchlist, notification, and report-language state. Do not create parallel AI clients or notification pipelines. - Put substantial prompts in
prompts/. Preserve required machine-readable output structures when adding language instructions. - Add the user-facing seed definition to
AGENT_SEED_SPECSinsrc/modules/automation/agent_catalog.py, including kind, visibility, schedule, execution mode, and safe defaults. - Add the implementation class to
AGENT_REGISTRYinserver.pywhen it can be executed directly. - Add English and Chinese catalog labels under
agentsPage.catalogin the frontend locale resources when the agent is visible in the UI. - Add focused tests for collection, parsing, notification policy, scheduling, idempotency, failure states, and English report output as applicable.
Prefer existing scheduler, persistence, tracing, cost metering, deduplication, and failover behavior. New workflows must end in an observable success or failure state and must not silently swallow exceptions.
Choose the correct layer first:
- Typed quote, K-line, fundamentals, flow, event, or discovery vendors belong in
packages/marketdata/. - PanWatch-specific orchestration, caching, screenshots, or adapters belong in
src/platform/marketdata/collectors/.
For a vendor in the standalone package:
- Implement the appropriate vendor interface under
packages/marketdata/src/marketdata/vendors/. - Normalize responses into the shared dataclasses; do not expose provider-specific dictionaries to callers.
- Use the package HTTP helper so timeouts, proxy behavior, throttling, retries, and metrics remain consistent.
- Register the vendor in
VENDOR_CLASSES_BY_TYPEinpackages/marketdata/src/marketdata/registry.py. - If PanWatch should expose it in the data-source admin UI, add a conservative entry to
DATA_SOURCE_SEEDSinserver.py. Lower priority numbers run first; providers requiring credentials or a proxy should normally start disabled. - Add mocked parser and routing tests, including malformed/empty responses, supported markets, and failover behavior.
Document attribution, authentication requirements, rate limits, market coverage, symbol format, and known data-quality limitations. Avoid destructive seed reconciliation and never overwrite user credentials or priorities during startup.
- Put user-visible text in
frontend/src/i18n/locales/zh-CN/andfrontend/src/i18n/locales/en-US/using semantic keys. - Keep both locale shapes in sync and run
pnpm --dir frontend run check:i18n. - A locale changes interface and generated-report language; it must not implicitly change market, currency, timezone, stock symbols, or source excerpts.
- Use the existing format helpers for dates, numbers, percentages, currencies, and market labels.
- Prefer shared components from
frontend/packages/over page-local duplicates. - Render API failures from stable
error_codevalues. Treat server error messages as diagnostics, not translation keys or control-flow contracts. - Add Testing Library coverage for user-visible state changes and locale-sensitive behavior.
- Keep migrations and startup reconciliation backward compatible with existing self-hosted data.
- Prefer additive schema changes and explicit defaults. Do not silently delete or replace user configuration.
- Keep API error codes stable and document new request or response fields.
- Test upgrade paths, missing legacy fields, authorization boundaries, and repeated/idempotent requests where relevant.
README.mdis the default English project introduction.README.zh-CN.mdis the complete Simplified Chinese version.- Update both when installation, configuration, screenshots, or user-visible features change.
- Keep historical compatibility files such as
README.en.mdandCONTRIBUTING.en.mdworking when paths move. - Do not present prototypes, local-only files, or unverified behavior as released functionality.
Commit messages must be written in English and use Conventional Commits:
<type>(<scope>): <subject>
Common types are feat, fix, refactor, perf, test, docs, chore, build, and ci. Use the affected module as the scope, such as assistant, marketdata, frontend, or i18n. Keep the subject concise, imperative, and without a trailing period.
Examples:
feat(automation): add a pre-market risk digest
fix(marketdata): handle empty quote volume
docs(readme): clarify Docker startup behavior
Pull-request titles and descriptions must be written in English. Titles should also use Conventional Commits. The body must include:
- Background — the problem and user impact.
- Changes — implementation and behavior changes grouped by module.
- Scope — one independently usable outcome, exclusions, and the agreed proposal where applicable.
- Validation — current tested commit, exact commands and actual results.
- Acceptance evidence — reproducible steps, expected/observed behavior and accessible evidence.
- Boundaries and risks — compatibility, untested paths, and known limitations.
- Follow-up — only concrete work intentionally left for later.
Use <type>/<short-english-kebab-case> branches, for example fix/report-symbol or feature/market-enablement. The repository normally uses squash merge.
The initial scope budget is 20 production files and 800 added + deleted production lines, excluding tests, Markdown docs and known lockfiles. Maintainers can approve a current-head exception. See the complete policy for evidence proportional to risk, read-only rollout, 7-day reminders, 14-day closure notices, and hold/exception labels. Existing PRs receive a full notice period; compliant PRs waiting for maintainer review are not automatically closed.
For ordinary bugs, open an issue with reproduction steps, expected and actual behavior, version information, and sanitized logs. Remove tokens, cookies, account identifiers, positions, and other private financial data.
For a security-sensitive issue, do not publish exploit details or credentials in a public issue. Follow the private reporting instructions in SECURITY.md.
Read the UI guide (简体中文) before changing controls or scrolling panels. Run pnpm --dir frontend check:ui to catch native selects, browser dialogs, and unstyled scroll regions; verify desktop/mobile and light/dark rendering as well.
Published annual closures and half-days live in src/platform/scheduling/exchange_calendar_data.py (currently 2026). Runtime warmup materializes only the previous 30 and upcoming 90 days without fetching historical calendars. Unpublished weekdays are unknown and cannot authorize automatic execution. Update the bundled annual data from exchange publications before the next year; preserve market-local dates, daylight-saving offsets, and half-day regression coverage. Configured Agent Cron/interval cycles remain unchanged; execution and preview share calendar gates.