From dbb5e791f0c228369605d126dd590962ebe1eddc Mon Sep 17 00:00:00 2001
From: Bertrand Yuan <me@bertyuan.com>
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 <github@bertyuan.com>
---
 .../source/architecture/system-overview.rst        | 61 ++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 Documentation/source/architecture/system-overview.rst

(limited to 'Documentation/source/architecture/system-overview.rst')

diff --git a/Documentation/source/architecture/system-overview.rst b/Documentation/source/architecture/system-overview.rst
new file mode 100644
index 0000000..c876096
--- /dev/null
+++ b/Documentation/source/architecture/system-overview.rst
@@ -0,0 +1,61 @@
+System Overview
+===============
+
+Layered View
+------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 34 44
+
+   * - Layer
+     - Main Files
+     - Responsibility
+   * - Presentation
+     - ``src/app/(main)``, ``src/components``
+     - Render public pages, route handlers, shared UI, rich text, and layout.
+   * - Content access
+     - ``src/lib/payload-posts.ts``
+     - Query Payload and normalize CMS documents into frontend-friendly types.
+   * - CMS admin
+     - ``payload.config.ts``, ``src/payload``, ``src/app/(payload)``
+     - Define editorial collections and expose the admin experience.
+   * - Auth and comments
+     - ``src/server/auth``, ``src/server/comments``
+     - Authenticate users and persist comment data.
+   * - Data
+     - ``src/server/db``, ``src/migrations``
+     - Own Drizzle schema, connection setup, and application migrations.
+   * - Content pipeline
+     - ``content``, ``source.config.ts``
+     - Build local MDX content through Fumadocs.
+
+Request Flow: Reading a Post
+----------------------------
+
+1. A route under ``src/app/(main)/(home)/posts/[slug]`` receives a slug.
+2. The server component calls ``getPostBySlug``.
+3. ``src/lib/payload-posts.ts`` obtains a Payload client and queries
+   ``posts`` where ``status`` is ``published``.
+4. The raw Payload document is transformed into ``BlogPost``.
+5. The page renders rich text content and mounts client-side interactions such
+   as sharing and comments.
+
+Request Flow: Writing a Comment
+-------------------------------
+
+1. The post detail page renders the Fuma Comments client component.
+2. The client calls ``/api/comments/[...comment]``.
+3. The route delegates to the Fuma Comments Next.js handler.
+4. better-auth validates the session.
+5. The Drizzle adapter writes comment, rate, and role data to application-owned
+   tables.
+
+Boundaries
+----------
+
+Payload owns editorial content and media metadata. The application owns auth,
+comments, UI state, route behavior, and integration logic. Keep that boundary
+clear when adding features: editorial fields belong in Payload collections;
+reader interaction and account behavior belong in ``src/server`` and the app
+routes.
-- 
cgit v1.2.3