Merge pull request #21 from bertyuan/Documentationv1.2

docs: add comprehensive documentation for operations

5 files changed, 244 insertions, 0 deletions

diff --git a/Documentation/source/reference/api.rst b/Documentation/source/reference/api.rst
new file mode 100644
index 0000000..85081aa
--- /dev/null
+++ b/Documentation/source/reference/api.rst
@@ -0,0 +1,53 @@
+API Reference
+=============
+
+Search Index
+------------
+
+Path
+   ``/api/search``
+
+Purpose
+   Provides search data for the frontend search experience.
+
+Rules
+   Return public published content only. Keep the response shape stable for the
+   search client.
+
+Comments
+--------
+
+Path
+   ``/api/comments/[...comment]``
+
+Purpose
+   Handles Fuma Comments operations.
+
+Rules
+   Authentication and authorization belong on the server side. Client code
+   should not decide comment privileges.
+
+Auth
+----
+
+Path
+   ``/api/auth/[...all]``
+
+Purpose
+   Handles better-auth routes for OAuth and session behavior.
+
+Rules
+   Keep provider configuration in ``src/server/auth`` and environment
+   validation in ``src/env.js``.
+
+Feed
+----
+
+Path
+   ``/rss.xml``
+
+Purpose
+   Publishes feed output for readers and feed clients.
+
+Rules
+   Include published content only and keep route references canonical.
diff --git a/Documentation/source/reference/commands.rst b/Documentation/source/reference/commands.rst
new file mode 100644
index 0000000..8268400
--- /dev/null
+++ b/Documentation/source/reference/commands.rst
@@ -0,0 +1,96 @@
+Command Reference
+=================
+
+Application
+-----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 52
+
+   * - Command
+     - Description
+   * - ``pnpm dev``
+     - Start the Next.js development server.
+   * - ``pnpm build``
+     - Build the production application.
+   * - ``pnpm start``
+     - Start a built production server.
+   * - ``pnpm preview``
+     - Build and start the production server.
+
+Quality
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 52
+
+   * - Command
+     - Description
+   * - ``pnpm lint``
+     - Run project link validation and Biome linting.
+   * - ``pnpm check``
+     - Run Biome checks.
+   * - ``pnpm format``
+     - Format files with Biome.
+   * - ``pnpm test``
+     - Run Vitest once.
+   * - ``pnpm test:watch``
+     - Run Vitest in watch mode.
+   * - ``pnpm test:coverage``
+     - Run tests with coverage.
+
+Data and CMS
+------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 48
+
+   * - Command
+     - Description
+   * - ``pnpm db:generate``
+     - Generate Drizzle migration files.
+   * - ``pnpm db:migrate``
+     - Apply Drizzle migrations.
+   * - ``pnpm db:push``
+     - Push Drizzle schema changes directly.
+   * - ``pnpm db:studio``
+     - Open Drizzle Studio.
+   * - ``pnpm payload:generate``
+     - Generate Payload TypeScript types.
+   * - ``pnpm payload:migrate``
+     - Run Payload migrations.
+   * - ``pnpm payload:migrate:create``
+     - Create a Payload migration.
+
+Email
+-----
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 52
+
+   * - Command
+     - Description
+   * - ``pnpm email:dev``
+     - Start React Email preview server on port 3001.
+   * - ``pnpm email:build``
+     - Build email templates.
+   * - ``pnpm email:export``
+     - Export email templates.
+
+Documentation
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 48
+
+   * - Command
+     - Description
+   * - ``make -C Documentation html``
+     - Build Sphinx HTML documentation.
+   * - ``make -C Documentation clean``
+     - Remove generated Sphinx build output.
diff --git a/Documentation/source/reference/glossary.rst b/Documentation/source/reference/glossary.rst
new file mode 100644
index 0000000..d2d648b
--- /dev/null
+++ b/Documentation/source/reference/glossary.rst
@@ -0,0 +1,32 @@
+Glossary
+========
+
+App Router
+   Next.js routing model used by this project under ``src/app``.
+
+better-auth
+   Authentication library used for OAuth and sessions.
+
+BlogPost
+   Normalized frontend post shape returned by ``src/lib/payload-posts.ts``.
+
+Drizzle
+   TypeScript ORM used for application-owned database tables.
+
+Fuma Comments
+   Comment UI and server package used for post discussions.
+
+Fumadocs
+   MDX content and UI tooling used by the site.
+
+Lexical
+   Rich text editor used by Payload CMS.
+
+Payload
+   CMS used for posts, users, media, and the admin interface.
+
+Sphinx
+   Documentation generator used for ``Documentation/source``.
+
+Tag
+   Topic label stored on posts and used for tag index and filtered post pages.
diff --git a/Documentation/source/reference/index.rst b/Documentation/source/reference/index.rst
new file mode 100644
index 0000000..1f52bcf
--- /dev/null
+++ b/Documentation/source/reference/index.rst
@@ -0,0 +1,13 @@
+Reference
+=========
+
+Reference pages collect stable facts that are useful during implementation and
+review.
+
+.. toctree::
+   :maxdepth: 2
+
+   commands
+   routes
+   api
+   glossary
diff --git a/Documentation/source/reference/routes.rst b/Documentation/source/reference/routes.rst
new file mode 100644
index 0000000..93bcfd3
--- /dev/null
+++ b/Documentation/source/reference/routes.rst
@@ -0,0 +1,50 @@
+Route Reference
+===============
+
+Public Pages
+------------
+
+.. code-block:: text
+
+   /
+   /posts
+   /posts/[slug]
+   /tags
+   /tags/[tag]
+   /about
+   /login
+
+Admin and Payload
+-----------------
+
+.. code-block:: text
+
+   /admin
+   /api/[...slug]
+   /api/graphql
+   /api/graphql-playground
+
+Application APIs
+----------------
+
+.. code-block:: text
+
+   /api/auth/[...all]
+   /api/comments/[...comment]
+   /api/search
+
+Generated Assets
+----------------
+
+.. code-block:: text
+
+   /rss.xml
+   /banner.png
+   /og/[...slug]
+
+Route Ownership
+---------------
+
+Routes under ``src/app/(main)`` belong to the public application. Routes under
+``src/app/(payload)`` belong to Payload CMS integration and should be changed
+with care because they affect the admin and CMS API surface.