Historical Repository Notes

Historical Repository Documentation Notes

These records describe earlier documentation and task-tracking states. They are preserved for provenance, not current work selection. GitHub Issues, the current Wiki, and AGENTS.md govern present work.

See also the Historical Architecture Map, which predates the current AGPL and self-hosted decisions.

The historical ADR-0001 conversation domain model records an unadopted migration proposal; it is not a current architecture contract.

Project Documentation Report — 365 WeCom Archive

Historical QA artifact from the 2026-07-10 documentation refresh review. This report captures a point-in-time assessment before subsequent fixes and is not a current-source claim. Use AGENTS.md and Architecture Overview as the current documentation entry point.

Generated: 2026-07-10

---

Overall Documentation Health Score

88 / 100

Score Breakdown

Category	Weight	Score	Rationale
Accuracy (matches current code)	40%	35/40	README, ARCHITECTURE, DATA_MODEL outdated on initial review; now updated
Completeness (missing docs)	25%	22/25	AI context docs (docs/ai/) were missing; now created
Consistency (no contradictions)	15%	14/15	Minor duplication in DATA_MODEL (duplicate media_files row) fixed
Clarity (AI/human readability)	10%	9/10	Most docs clear; some had stale phase references
Maintainability (style/last-updated)	10%	8/10	Last-updated timestamps now refreshed; doc catalog added to README

Total: 88 / 100

---

Documentation Audit Summary

A (Current — no changes needed)

Document	Reason
AGENTS.md	Single source of truth for working rules + agent roles (v6, merged 2026-08-28)
docs/CONVERSATION_REVIEW_CONSOLE_PRD.md	Spec document — historical reference; still accurate as product vision
docs/wecom_archive_worker_runbook.md	Accurate, covers production deployment
docs/wecom_archive_media_download_runbook.md	Accurate, covers production deployment
docs/research/wecom_employee_login_tenant_saas_foundation.md	Historical research doc — accurate record of decisions
docs/research/rnd_185_media_storage_abstraction.md	Recent (RND-185); accurate
.env.example	Well-maintained with comments; accurate
DESIGN-linear.app.md	External design system reference; not project-specific

B (Partially outdated — updated)

Document	Problems Found	Update
README.md	Project structure incomplete; Stack line "UI not implemented" wrong; missing capabilities table; stale architecture diagram; no doc index	Rewritten: accurate structure, implemented capabilities table, updated architecture diagram, documentation catalog
docs/ARCHITECTURE.md	"Admin UI Phase 2" statement; missing tenant model; component status showing "stub" / "not implemented" for already-shipped features; storage section old; missing conversation model	Rewritten: all component statuses current; tenant model section added; conversation model section added; deployment section updated; non-goals trimmed
docs/DATA_MODEL.md	Duplicate media_files row in overview table; old migrations list (3 and 4 missing); stale "Phase 2 RND-110 not shipped" text in Tenant Scoping note	Cleaned: removed duplicate; added migrations 0003/0004; updated tenant scoping section

C (Fully outdated — none found)

No documents were fully outdated. All described features still exist.

D (Duplicate — fixed)

Issue	Resolution
media_files appeared twice in DATA_MODEL.md overview table	Removed the duplicate row

---

Updated Files

File	Type of Update	Priority
README.md	Full rewrite	Tier 1
docs/ARCHITECTURE.md	Full rewrite	Tier 1
docs/DATA_MODEL.md	Medium edits (duplicate removal, migration list, stale text)	Tier 2

New Files

File	Purpose
docs/ai/project-overview.md	One-paragraph project summary for AI agents
docs/ai/architecture-summary.md	Concise architecture overview (module map, call flow, DB relations, worker pipeline)
docs/ai/business-terms.md	Domain terminology reference (Tenant, Corp, Archive, Conversation, etc.)
docs/ai/current-status.md	What's implemented, pending, deprecated, technical debt
docs/ai/onboarding.md	Recommended reading order for new AI agents
docs/ai/known-pitfalls.md	Common traps, mistakes, and fragile areas

Removed Files

None.

---

Remaining Gaps (Future Work)

Gap	Priority	Notes
API specification (OpenAPI) export	Medium	FastAPI auto-generates OpenAPI; consider adding a rendered version to docs/
Testing guide	Medium	No single doc explaining how to run tests (pytest backend/tests/)
Deployment guide	Medium	scripts/deploy_server.sh and runbooks exist but no consolidated deployment doc
Environment variable reference	Low	.env.example has good comments; could be extracted to docs/env-vars.md
Database migration guide	Low	Alembic is straightforward; consider documenting the migration workflow
Debug guide	Low	Most debug info is in known-pitfalls.md now

---

AI Readiness Evaluation

Score: ★★★★☆ (4.5 / 5)

Explanation:

A new AI agent entering this repository for the first time can understand the project with minimal overhead:

1. Good: The docs/ai/ directory now provides a structured onboarding path — project overview → architecture → terminology → current status → working rules.
2. Good: The README has a capabilities table showing exactly what's implemented.
3. Good: The README provides a documentation catalog with audience/purpose for each doc.
4. Good: ARCHITECTURE.md and DATA_MODEL.md are now current with the codebase.
5. Minor gaps remaining (reducing from 5 to 4.5):
   • No consolidated, rendered API reference (though FastAPI /docs serves this).
   • No explicit "how to run the tests" doc.
   • No formal architecture decision log beyond research docs.

For comparison, before this refresh the score would have been ~3/5, because:

• README said "Admin UI not implemented" when it is.
• ARCHITECTURE.md showed "Phase 2" items that are shipped.
• No AI onboarding directory existed.
• DATA_MODEL.md had duplicate rows and stale migration info.

---

Generated as part of Project Documentation Refresh. For current onboarding, see Developer Onboarding.

Historical Task Tracking Fragment

Historical reference only (reclassified by GitHub #92). This unchecked RND-198 implementation checklist is not an active work queue and must not be used to select, scope, or close work.

GitHub Issues are the active issue-management system. Follow AGENTS.md for ticket claiming, delivery, and validation. The original checklist remains in Git history for provenance.

Historical F0 Account-System Verification Snapshot

Historical QA record (2026-07-28; reclassified by GitHub #92). This document predates current tenant lifecycle, login identity, PlatformAdmin, and GitHub-Issue workflow. It is not an architecture, deployment, or work tracking source.

Use AGENTS.md, Architecture Overview, and current GitHub Issues instead. Historical RND/Linear references remain provenance only.

The original point-in-time account-system verification remains available in Git history if needed for forensic comparison.

---

Historical Development Guide

Superseded: This internal guide predates the AGPL-3.0 and self-hosted decisions. Its hosted-only and “no external contribution process” statements are historical, not current. See CONTRIBUTING.md for today's contributor workflow and ADR-0008 for the current runtime policy.

This page remains for historical engineering notes; do not use its old product-boundary statements as current policy.

Setting up

Python 3.11+ and PostgreSQL 14+ are the supported baseline. PostgreSQL is required to run the application, but not to run most of the test suite.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r backend/requirements.txt -r backend/requirements-dev.txt
cp .env.example backend/.env      # never commit this file

See the README's Local console section for the database and startup steps.

The WeCom SDK

Archive synchronization, message decryption, and media download all go through Tencent's proprietary WeCom C SDK, which is not in this repository and cannot be redistributed. You do not need it for most work: the console, the API, and nearly the entire test suite run against a fake SDK and sample data. You only need the real SDK to work on the live sync path itself.

Making a change

Every change runs in an assigned non-main delivery worktree and branch, based on an up-to-date origin/main. Never develop on, commit to, or push directly to main. Each GitHub Issue keeps its own implementation conversation and exactly one final commit. A worktree/branch/pull request may group several related issue commits, normally from the same Epic. Those issues must be implemented serially so uncommitted changes from different tickets never coexist. Agents must verify git branch --show-current before editing and stop if it reports main.

Run the acceptance chain before opening a pull request:

make verify        # lint on your diff, type/import check, build, tests

make test alone runs the suite. Tests that need a live PostgreSQL skip themselves when DATABASE_URL is unset, so a run reporting skips is the expected local result.

Pull requests run the same gates in CI via .github/workflows/ci.yml. A red CI is a red pull request; do not merge until it is green and human review is complete. When Merge Queue is enabled, the same CI also runs for the merge-group candidate. A multi-ticket PR must list its issue-to-commit mapping and use a merge strategy that preserves the individual ticket commits; do not squash it into one commit.

Merging deployable paths to main triggers the CD-only production workflow (.github/workflows/deploy.yml). CD deploys the exact merged main SHA and retains migration, readiness, serialization, and rollback gates, but it does not repeat the complete CI suite. Require a pull request and green CI, keep the branch up to date, and never push directly to main. Branch-protection settings are managed in GitHub, outside this repository; verify them against the binding repository rules before changing merge policy or maintainers. Documentation/task-only merges still pass PR CI but are excluded from CD by the workflow's paths-ignore list.

What makes a change easy to review

• One coherent delivery per pull request. A PR may contain several related same-Epic ticket commits, but unrelated fixes or refactors belong in another delivery branch and PR.
• A test that fails before your change and passes after it. For a bug fix this is the single most useful thing you can include.
• Comments that explain why, not what. This codebase leans heavily on explaining the reasoning behind non-obvious decisions; match that.
• No new lint findings in your diff. make lint-diff checks exactly this. The repository carries a pre-existing whole-repo lint baseline that you are not expected to fix.

Things to know

• Decrypted message envelopes are never persisted. The archive_messages.decrypted_payload column is always NULL by design — the worker extracts the fields it needs and stores those. This is a data minimization contract, not an oversight; do not "fix" it.
• The console is server-rendered with no template engine. Follow the existing patterns in backend/app/web/ rather than introducing one.
• User-facing strings are localized across three locales in backend/app/assets/i18n.js. A new string needs all three.
• Database changes need an Alembic migration, and CI runs alembic check to catch a model that has drifted from its migrations.
• Archive private keys are the highest-severity asset in this system. The application handles tenant decryption keys. Never let key material reach logs, backups, error payloads, or plaintext database columns. See key-hosting-and-tenant-isolation.md.

Reporting bugs

Include the version or commit, what you expected, what happened, and the minimal steps to reproduce it. Never paste real credentials, private keys, conversation content, or personal data into an issue — this is an archive product handling other companies' conversations.

Security issues follow SECURITY.md instead.

---

DEV_AGENT_RULES — merged into AGENTS.md

This file is a tombstone. As of 2026-08-28 (v6) all binding working rules live in the repository-root AGENTS.md, together with the agent roster that used to live in docs/AGENTS.md.

Historical ticket prompts under tasks/ instruct agents to "read DEV_AGENT_RULES.md". Read AGENTS.md instead — it is the same rule set, de-duplicated, with roles named by function (dev / qa / ops / research) and GitHub Issues in place of Linear.

Section anchors moved as follows:

Old	New
#core-philosophy	#core-invariants
#standard-workflow, #git-workflow	#workflow, #git-workflow
#agent-responsibilities, #default-agent-selection	#roles
#main-direct-commit-exception	#main-direct-commit-exception
#git-operation-boundaries	#git-operation-boundaries
#commit-rules	#commit-rules
#qa-rules	#validation-and-qa
#architecture-boundaries	#architecture-boundaries
#secrets-sensitive-data-and-untrusted-input	#secrets-sensitive-data-and-untrusted-input
#out-of-scope-without-explicit-approval	#out-of-scope-without-explicit-approval
#decision-priority	#decision-priority