Architecture, Code Map & Migrations
AI Translation Notice
This page is synced from the primary Chinese guide (原理与源码导览(含决策迁移)). The repository's authoritative walkthrough and evidence audit under repo-docs/ are written in Chinese; see the Chinese docs page for the full embedded walkthrough.
System Layering & Storage Topology
- Static Workbench (
web/):dashboard.html+app.jsimplement the dual-pane master-detail workspace, focus review mode, and draft preservation.markdown.jsstrips raw HTML and checks link schemes;diagrams.jswraps vendored Mermaid 12.1.0 (strict mode, 50k chars / 500 edges max);agent-question.jsactivates only valid latest-round fences. - Loopback Gateway & Process Lock (
core/server.py,core/locking.py): PythonThreadingHTTPServervalidates loopback origin/host rules and request size/timeout bounds; mutations serialize via an in-process reentrant lock keyed by normalizeddatabase_path. - Orchestration & Authoritative Markdown (
core/decision_service.py,core/markdown_parser.py): Before atomically replacingdecisions/<id>.md,_validate_documentperforms a parse-and-reserialize round-trip check so broken Markdown fences never corrupt a topic file. - Snapshots, Consistency & Isolated Git (
core/db.py,core/recovery.py,core/git_engine.py):decisions.dbstores fullrevisionssnapshots, monotonictopic_version_seq(ABA prevention), and SHA-256-keyedidempotency_keys.metadata.jsonis export-only, andGitEngineaborts cleanly (skipped_unrelated_staged) if unrelated staged changes exist.
Decision Lifecycle Interactive Diagram
End-to-End Write & Replay Walkthrough
A single POST /api/topic/<id>/save follows five sequential guarantees (detailed step-by-step in repository file repo-docs/walkthroughs/one-real-run.md):
- Read & Verify Target: Confirm service data paths via
GET /api/status(oragent_hooks preflight) and read currentversionfromGET /api/topic/<id>. - Persist Request Identity: Generate a unique
request_idper logical operation, bindexpected_version, and storerequest.jsonbefore POSTing. - Lock, Deduplicate & Validate: Inside
ledger_lock, match(request_id, req_hash)inidempotency_keys(replaying completed responses or resuming unfinished metadata/Git phases without appending duplicate rounds), verifyexpected_versionagainsttopic_version_seq, and run_validate_documentround-trip check. - Persist & Report Staged Receipts: Atomically update
decisions/<id>.md, update SQLitetopics+revisions, exportmetadata.json, optionally run path-isolated Git commit, and return independentsave_status,export_status, andgit_statusfields. - Read-Only Post Check: Run
core.agent_hooks after-write --topic <id> --receipt receipt.jsonto confirm version parity and ledger consistency.
Code Map and Key Migrations
Repository Structure (core/, web/, tests/)
| Path | Responsibility | Key Symbols / Assets |
|---|---|---|
core/config.py | Config loading, env precedence, relative path resolution, topic_scope | load_config, Config.topic_is_active |
core/contracts.py | Portable ID regex/reserved-name check & orthogonal 3-axis enum mapping | validate_portable_id, decision_axes |
core/server.py | Loopback HTTP handler, origin/size/timeout guards & CLI modes | is_loopback_host, make_handler, main |
core/decision_service.py | Save, create, amend latest round, verify, archive delete & restore/rollback | save_topic, edit_latest_round, delete_topic, restore_single_topic, rollback_full |
core/db.py | SQLite schema/migrations, topic_version_seq, idempotency_keys, hot backup | upsert_topic, check_idempotency, commit_revision, backup_database |
core/markdown_parser.py | schema_version: "2.0" frontmatter & fence-aware round parser | parse_markdown_text, amend_round, serialize_markdown |
core/recovery.py | Digest check, index rebuild from Markdown & summary export | check_consistency, rebuild_index_from_markdown, sync_metadata_json |
core/git_engine.py | Clean-index guard, 30s timeout & path-isolated commits | commit_decision, get_commit_history |
core/agent_context.py & core/agent_hooks.py | 5-bucket governance context query & read-only pre/post hooks | query_context, before_task, after_write |
web/ & web/vendor/ | Dual-pane workbench, safe Markdown/Mermaid rendering, bundled vendor libs | app.js, agent-question.js, markdown.js, diagrams.js |
tests/ | Python unittest suite (227 tests) & Node frontend tests (12 tests) | tests/test_*.py, tests/*.test.js |
Key Migrations & Breaking/Behavioral Changes
- Orthogonal 3-Axis Promotion: Legacy topics placing
"deferred"or"superseded"indecision_outcomeare transparently interpreted in memory underworkflow_state(LEGACY_PROGRESS_OUTCOMES) without silently rewriting disk files until the next explicit save or restore toschema_version: "2.0". - Safe Archive Delete (
delete_topic): Deleting a topic movesdecisions/<id>.mdtodecisions/.archived_rollback/with a random suffix and records aTOPIC_REMOVErevision linkingprior_rev_id, enabling single-topic undo or full rollback. - Scoped Topic Filtering (
topic_scope.active_topic_ids): Long-lived ledgers can configure an array of active topic IDs to declutter lists andGET /api/agent/contextwithout removing archived Markdown or breaking direct/api/topic/<id>links. doc_data_json_pathCompatibility Key: Retained inDEFAULT_CONFIGfor legacy config compatibility only; authoritative persistence remains exclusivelydecisions_dir/*.md+database_path, with summary exports tometadata_json_path.
Contributor Verification Commands
Run all checks against isolated temporary directories (never against a live ledger's decisions.db):
sh
python3 -m unittest discover tests
node --test tests/*.test.js
node --check web/app.js && node --check web/markdown.js && node --check web/diagrams.js
git diff --check
pnpm --dir docs-site run docs:buildFor full evidence claims, falsification criteria, and remaining risks (including single-process bounds and manual UI testing scope), refer to repo-docs/references/source-evidence.md and repo-docs/references/quality-review.md in the repository.