diff options
Diffstat (limited to 'Documentation/source/reference')
| -rw-r--r-- | Documentation/source/reference/api.rst | 53 | ||||
| -rw-r--r-- | Documentation/source/reference/commands.rst | 96 | ||||
| -rw-r--r-- | Documentation/source/reference/glossary.rst | 32 | ||||
| -rw-r--r-- | Documentation/source/reference/index.rst | 13 | ||||
| -rw-r--r-- | Documentation/source/reference/routes.rst | 50 |
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. |