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 --- .../source/architecture/data-and-auth.rst | 72 ++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 Documentation/source/architecture/data-and-auth.rst (limited to 'Documentation/source/architecture/data-and-auth.rst') diff --git a/Documentation/source/architecture/data-and-auth.rst b/Documentation/source/architecture/data-and-auth.rst new file mode 100644 index 0000000..44736bd --- /dev/null +++ b/Documentation/source/architecture/data-and-auth.rst @@ -0,0 +1,72 @@ +Data, Auth, and Comments +======================== + +Database Ownership +------------------ + +The repository uses PostgreSQL for both CMS data and application-owned data. +The separation is logical: + +* Payload stores CMS data in the ``payload`` schema. +* Application auth and comments use Drizzle schema objects and ``blog_*`` + tables. + +This keeps CMS-managed structures separate from reader interaction data and +allows application migrations to evolve without coupling every change to +Payload internals. + +Authentication +-------------- + +Authentication is configured in ``src/server/auth/index.ts`` with better-auth +and the Drizzle adapter. Current providers: + +* Google OAuth; +* GitHub OAuth. + +The user model includes an additional ``role`` field with a default value of +``user``. Session lookup is wrapped by ``getSession`` so route and component +code does not need to call the better-auth API directly. + +Comments +-------- + +Comments are configured in ``src/server/comments/config.ts``. The Fuma Comments +storage adapter receives the Drizzle database connection and these schemas: + +* ``comments``; +* ``rates``; +* ``roles``; +* ``users``. + +The comment API route is mounted under ``/api/comments/[...comment]``. Frontend +comment rendering belongs on post detail pages, while moderation and role +policy should remain server-controlled. + +Migration Commands +------------------ + +.. list-table:: + :header-rows: 1 + :widths: 26 50 + + * - Command + - Use + * - ``pnpm db:generate`` + - Generate Drizzle migration files after schema changes. + * - ``pnpm db:migrate`` + - Apply Drizzle migrations. + * - ``pnpm db:push`` + - Push schema changes directly during local development. + * - ``pnpm payload:migrate`` + - Run Payload migrations. + * - ``pnpm payload:migrate:create`` + - Create a new Payload migration. + +Implementation Rule +------------------- + +When adding data-backed features, decide first whether the data is editorial or +application-owned. Editorial content should be modeled in Payload collections. +Account, interaction, moderation, and operational records should be modeled in +Drizzle. -- cgit v1.2.3