Merge pull request #21 from bertyuan/Documentationv1.2

docs: add comprehensive documentation for operations

5 files changed, 239 insertions, 0 deletions

diff --git a/Documentation/source/operations/database.rst b/Documentation/source/operations/database.rst
new file mode 100644
index 0000000..37c0cba
--- /dev/null
+++ b/Documentation/source/operations/database.rst
@@ -0,0 +1,59 @@
+Database
+========
+
+Local Bootstrap
+---------------
+
+Use the included helper when developing locally:
+
+.. code-block:: bash
+
+   ./start-database.sh
+
+The script is designed for local development and should not be used as a
+production database management tool.
+
+Schema Areas
+------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 50
+
+   * - Area
+     - Ownership
+   * - Payload schema
+     - CMS collections, admin content, media metadata, and Payload-managed
+       structures.
+   * - Drizzle ``blog_*`` tables
+     - better-auth users, sessions, accounts, verifications, comments, rates,
+       and roles.
+
+Migration Workflow
+------------------
+
+For Payload collection changes:
+
+.. code-block:: bash
+
+   pnpm payload:migrate:create
+   pnpm payload:migrate
+   pnpm payload:generate
+
+For application schema changes:
+
+.. code-block:: bash
+
+   pnpm db:generate
+   pnpm db:migrate
+
+During local iteration, ``pnpm db:push`` can be useful, but committed schema
+changes should still have a deliberate migration story.
+
+Operational Cautions
+--------------------
+
+* Keep Payload and application-owned tables conceptually separate.
+* Regenerate Payload types after collection changes.
+* Keep ``drizzle.config.ts`` filters aligned with application-owned tables.
+* Do not commit local database data directories or generated build artifacts.
diff --git a/Documentation/source/operations/documentation.rst b/Documentation/source/operations/documentation.rst
new file mode 100644
index 0000000..b7fcb71
--- /dev/null
+++ b/Documentation/source/operations/documentation.rst
@@ -0,0 +1,51 @@
+Documentation
+=============
+
+Source Layout
+-------------
+
+Sphinx source files live in ``Documentation/source``. Use reStructuredText for
+all Sphinx pages.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 26 50
+
+   * - Directory
+     - Purpose
+   * - ``architecture``
+     - System design, data model, auth, comments, feeds, and risk register.
+   * - ``frontend``
+     - Routes, UI conventions, components, and accessibility.
+   * - ``operations``
+     - Setup, environment, database, quality, and documentation workflow.
+   * - ``contributing``
+     - Commit, review, and code integrity practices.
+   * - ``reference``
+     - Stable route, command, glossary, and API references.
+
+Build Commands
+--------------
+
+Build HTML:
+
+.. code-block:: bash
+
+   make -C Documentation html
+
+Clean generated output:
+
+.. code-block:: bash
+
+   make -C Documentation clean
+
+Authoring Rules
+---------------
+
+* Write durable documentation in ``.rst`` files under ``Documentation/source``.
+* Keep raw notes in ``docs/`` only when they are not yet ready for the formal
+  documentation tree.
+* Prefer small pages with focused toctrees over long mixed-topic pages.
+* Use literal paths and commands with double backticks.
+* Add new pages to the nearest ``index.rst`` toctree.
+* Do not commit ``Documentation/build`` output.
diff --git a/Documentation/source/operations/environment.rst b/Documentation/source/operations/environment.rst
new file mode 100644
index 0000000..64e5c8e
--- /dev/null
+++ b/Documentation/source/operations/environment.rst
@@ -0,0 +1,60 @@
+Environment
+===========
+
+Validation Source
+-----------------
+
+Environment validation is defined in ``src/env.js`` with
+``@t3-oss/env-nextjs`` and ``zod``. Empty strings are treated as undefined.
+
+Server Variables
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 44
+
+   * - Variable
+     - Purpose
+   * - ``DATABASE_URL``
+     - PostgreSQL connection string.
+   * - ``RESEND_API_KEY``
+     - Resend API key. Must start with ``re_``.
+   * - ``RESEND_AUDIENCE_ID``
+     - Resend audience identifier.
+   * - ``EMAIL_FROM``
+     - Sender email address.
+   * - ``BETTER_AUTH_SECRET``
+     - better-auth secret. Required in production.
+   * - ``BETTER_AUTH_URL``
+     - Optional explicit auth base URL.
+   * - ``GOOGLE_CLIENT_ID`` / ``GOOGLE_CLIENT_SECRET``
+     - Google OAuth credentials.
+   * - ``GITHUB_CLIENT_ID`` / ``GITHUB_CLIENT_SECRET``
+     - GitHub OAuth credentials.
+
+Client Variables
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 44
+
+   * - Variable
+     - Purpose
+   * - ``NEXT_PUBLIC_UMAMI_URL``
+     - Optional Umami analytics script URL.
+   * - ``NEXT_PUBLIC_UMAMI_WEBSITE_ID``
+     - Optional Umami site identifier.
+
+Skipping Validation
+-------------------
+
+``SKIP_ENV_VALIDATION=1`` can be used for limited local or container workflows.
+Do not rely on it for production builds.
+
+Production Notes
+----------------
+
+Production should use explicit, non-default secrets for Payload and better-auth
+and an explicit public site URL for canonical links and generated metadata.
diff --git a/Documentation/source/operations/index.rst b/Documentation/source/operations/index.rst
new file mode 100644
index 0000000..41b6431
--- /dev/null
+++ b/Documentation/source/operations/index.rst
@@ -0,0 +1,13 @@
+Operations
+==========
+
+This section covers runtime configuration, database workflows, testing,
+documentation builds, and release-oriented tasks.
+
+.. toctree::
+   :maxdepth: 2
+
+   environment
+   database
+   quality
+   documentation
diff --git a/Documentation/source/operations/quality.rst b/Documentation/source/operations/quality.rst
new file mode 100644
index 0000000..4be1cfd
--- /dev/null
+++ b/Documentation/source/operations/quality.rst
@@ -0,0 +1,56 @@
+Quality
+=======
+
+Tooling
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 54
+
+   * - Tool
+     - Role
+   * - Vitest
+     - Unit and component tests.
+   * - Testing Library
+     - DOM-oriented component assertions.
+   * - Biome
+     - Linting and formatting checks.
+   * - ``scripts/lint.mts``
+     - Project-specific content and link validation.
+   * - TypeScript
+     - Static type checking through project build and editor tooling.
+
+Common Checks
+-------------
+
+.. code-block:: bash
+
+   pnpm lint
+   pnpm check
+   pnpm test
+   pnpm build
+
+Testing Guidance
+----------------
+
+Add tests when a change affects:
+
+* shared UI components;
+* route-visible behavior;
+* metadata generation;
+* validation logic;
+* content transformation;
+* pagination;
+* authentication or comment policy boundaries.
+
+Keep tests focused on observable behavior. Avoid locking tests to incidental
+implementation details unless the implementation itself is the contract.
+
+CI Direction
+------------
+
+A complete CI gate should run lint, tests, type-sensitive build checks, and
+documentation build checks. If a command requires external secrets, provide a
+mocked or validation-skipped CI mode rather than weakening production
+validation.