From dbb5e791f0c228369605d126dd590962ebe1eddc Mon Sep 17 00:00:00 2001 From: Bertrand Yuan Date: Mon, 27 Apr 2026 20:52:54 +0800 Subject: docs: add comprehensive documentation for operations This commit introduces a complete set of documentation files covering various aspects of the project, including environment setup, quality checks, command references, and architecture. The documentation is structured to assist developers and contributors in understanding the project's configuration, workflow, and best practices. Additionally, translations for Simplified and Traditional Chinese have been added to ensure accessibility for a wider audience. This enhances the overall usability and maintainability of the project. Signed-off-by: Bertrand Yuan --- Documentation/source/architecture/risks.rst | 55 +++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 Documentation/source/architecture/risks.rst (limited to 'Documentation/source/architecture/risks.rst') diff --git a/Documentation/source/architecture/risks.rst b/Documentation/source/architecture/risks.rst new file mode 100644 index 0000000..604bc78 --- /dev/null +++ b/Documentation/source/architecture/risks.rst @@ -0,0 +1,55 @@ +Risks and Technical Debt +======================== + +This page tracks known architectural risks and follow-up work. Keep entries +short, actionable, and tied to repository evidence. + +Current Risk Register +--------------------- + +.. list-table:: + :header-rows: 1 + :widths: 10 26 28 30 + + * - Priority + - Finding + - Evidence + - Recommendation + * - P0 + - Email utility type dependency should be verified. + - ``src/lib/resend.ts`` imports project-local types. + - Keep type sources explicit and covered by type checks. + * - P0 + - Payload secret fallback is unsafe for production. + - ``payload.config.ts`` falls back to ``your-secret-key``. + - Fail fast in production when ``PAYLOAD_SECRET`` is missing. + * - P1 + - RSS canonical path must stay consistent. + - Route is ``/rss.xml``. + - Use the same path in metadata, README, docs, and sitemap config. + * - P1 + - In-memory aggregation can become expensive. + - Search, RSS, and tag counts read batches of posts. + - Add caching or database-side aggregation when content volume grows. + * - P1 + - Canonical URL configuration needs production hardening. + - Deployment URL handling depends on environment conventions. + - Prefer an explicit public site URL for production. + * - P2 + - Comment role governance needs policy tests. + - Comment storage includes roles. + - Define moderation behavior before adding privileged comment actions. + +Roadmap +------- + +Phase 1: correctness and configuration hardening + Fix production secret handling, verify email types, and align feed paths. + +Phase 2: scalability + Cache expensive public indexes, move tag aggregation closer to storage, and + add clear revalidation boundaries. + +Phase 3: governance + Add architecture decision records, route-level integration tests, and CI + checks for type safety, tests, linting, and documentation links. -- cgit v1.2.3