@chidchanun/bcp 0.1.17 → 0.1.19

package/docs/README.md

@@ -0,0 +1,350 @@
+# BCP Framework Documentation Source
+
+This directory is the documentation source of truth for the BCP Framework documentation website.
+
+The recommended documentation website project name is `bcp-docs`.
+
+> Documentation target: BCP Framework `0.1.19`
+
+## Purpose
+
+The `bcp-docs` website should turn the Markdown files in this directory into a structured developer documentation experience without duplicating framework behavior in a separate source of truth.
+
+When framework behavior changes:
+
+1. update the framework source and tests,
+2. update the relevant file in `docs/`,
+3. update the release note in `docs/releases/`,
+4. then publish or synchronize the content to `bcp-docs`.
+
+The website should not invent API behavior that is not documented or tested in the framework repository.
+
+## Recommended website navigation
+
+### Getting Started
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/getting-started` | `getting-started.md` | Create and run a BCP application |
+| `/docs/configuration` | `configuration.md` | Framework configuration |
+| `/docs/application-modules` | `application-modules.md` | Client/server module boundaries |
+| `/docs/deployment` | `deployment.md` | Production and deployment guidance |
+| `/docs/updating` | `updating.md` | Upgrade an existing BCP project |
+
+### Routing and Data
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/routing` | `routing.md` | File-based routing |
+| `/docs/server-data-loaders` | `server-data-loaders.md` | Server-side page data |
+| `/docs/route-guards` | `route-guards.md` | Scoped page authorization |
+| `/docs/form-actions` | `form-actions.md` | Server mutations and forms |
+| `/docs/server-request-apis` | `server-request-apis.md` | Request, cookie, redirect and response APIs |
+| `/docs/validation` | `validation.md` | Typed form/API validation and field errors |
+
+### Authentication
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/authentication` | `authentication.md` | Authentication Core and `bcp/auth` |
+| `/docs/auth-route-guards` | `auth-route-guards.md` | `requireAuth`, `requireRole` and guard integration |
+| `/docs/session-auth` | `session-auth.md` | Low-level JWT cookie sessions |
+
+### Database
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/database` | `database.md` | `bcp/database`, MySQL and transactions |
+| `/docs/database-migrations` | `database-migrations.md` | Migration CLI and migration files |
+
+### Runtime and Infrastructure
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/middleware` | `middleware.md` | Middleware System v2 and v1 compatibility |
+| `/docs/caching` | `caching.md` | Cache and revalidation |
+| `/docs/security` | `security.md` | Framework security defaults |
+| `/docs/development-logging` | `development-logging.md` | Development request logging |
+
+### Releases
+
+Use the files under `docs/releases/` for release pages.
+
+Recommended route format:
+
+```text
+/releases/0.1.17
+/releases/0.1.18
+/releases/0.1.19
+```
+
+The newest release should also be available from `/releases`.
+
+## Homepage content for bcp-docs
+
+The documentation homepage should describe BCP as a React full-stack framework and highlight the currently implemented capabilities.
+
+Recommended feature groups:
+
+### Application
+
+- File-based routing
+- React SSR
+- SPA navigation
+- Persistent layouts
+- Loading and error UI
+- API routes
+- Client islands / partial hydration
+
+### Server data and mutations
+
+- Server data loaders
+- Route guards
+- Form actions
+- Request-scoped server APIs
+- Cookies and redirects
+- `bcp/validation`
+- Typed form/API validation
+- Field and form error output
+
+### Database
+
+- `bcp/database`
+- Lazy MySQL connection pool
+- Queries and prepared execution
+- Transactions
+- Database migrations
+- Migration status and rollback
+
+### Authentication
+
+- `bcp/auth`
+- JWT cookie sessions
+- Typed users and session data
+- Session rotation
+- `requireAuth()`
+- `requireRole()`
+- Auth-aware route guards
+
+### Middleware
+
+- Middleware System v2
+- Middleware chains
+- Real `await next()` downstream execution
+- Before/after response interception
+- Shared request context state
+- Matchers
+- Rewrite and redirect
+- Backward-compatible Middleware v1 handlers
+
+### Production and DX
+
+- `create-bcp-app`
+- Interactive project setup
+- Tailwind preset
+- Database/auth presets
+- `bcp update`
+- Standalone production builds
+- Critical CSS
+- Cache/revalidation
+- Security defaults
+- Unit/integration/E2E/package smoke testing in the framework repository
+
+## Suggested homepage hero
+
+Suggested content, not a required exact copy:
+
+```text
+BCP Framework
+A React full-stack framework for building server-rendered applications with routing,
+data loading, server mutations, authentication, databases, validation, middleware and production tooling.
+```
+
+Primary actions:
+
+```text
+Get Started
+Read the Docs
+View on GitHub
+```
+
+The website may display the current release version from project metadata instead of hard-coding it in multiple UI files.
+
+## Suggested documentation sidebar
+
+```text
+Getting Started
+  Introduction
+  Installation
+  Project Structure
+  Configuration
+  Updating
+
+Core
+  Routing
+  Application Modules
+  Server Request APIs
+  Server Data Loaders
+  Route Guards
+  Form Actions
+  Validation
+
+Authentication
+  Authentication Core
+  Auth Route Guards
+  JWT Sessions
+
+Database
+  Database
+  Migrations
+
+Runtime
+  Middleware
+  Caching
+  Security
+
+Production
+  Deployment
+  Development Logging
+
+Releases
+  0.1.19
+  0.1.18
+  0.1.17
+```
+
+## Suggested documentation page layout
+
+Each documentation page should support:
+
+- title
+- short summary
+- previous/next page navigation
+- table of contents generated from headings
+- syntax-highlighted code blocks
+- copy-code button
+- deep links to headings
+- responsive sidebar
+- mobile navigation
+- light/dark appearance
+- framework version label
+- link to the corresponding source Markdown file in GitHub
+
+Optional later additions:
+
+- documentation search
+- version selector
+- API symbol index
+- interactive examples
+- edit-on-GitHub links
+
+## Code examples
+
+Examples should use the public package entrypoints that application developers actually install.
+
+Preferred:
+
+```ts
+import {
+    auth,
+    requireAuth,
+} from "bcp/auth";
+
+import {
+    db,
+} from "bcp/database";
+
+import {
+    v,
+    validateFormData,
+} from "bcp/validation";
+
+import {
+    type MiddlewarePipelineHandler,
+} from "bcp/middleware";
+```
+
+Avoid documenting internal monorepo imports such as:
+
+```text
+packages/server/src/...
+packages/client/src/...
+```
+
+unless a page is explicitly explaining framework internals.
+
+## Version labels
+
+The website should distinguish:
+
+- current stable npm version
+- documentation target version
+- unreleased/main documentation if it is shown
+
+Do not label unreleased `main` behavior as already available from npm until the corresponding package has been published.
+
+## Framework commands to document
+
+```bash
+bcp dev
+bcp routes
+bcp build
+bcp start
+bcp update
+bcp version
+
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
+
+Project creation:
+
+```bash
+npx create-bcp-app@latest my-app
+```
+
+## Middleware v2 documentation priority
+
+BCP 0.1.18 introduced a meaningful middleware architecture change, so the `bcp-docs` website should make the distinction between v1 and v2 clear.
+
+The middleware page should prominently explain:
+
+```text
+v1 next()        = return a pass-through instruction
+v2 await next()  = execute downstream middleware/application and receive Response
+```
+
+Existing v1 code remains supported, so migration documentation should describe v2 as an additive upgrade rather than a mandatory rewrite.
+
+See `middleware.md` for the full API and examples.
+
+## Validation documentation priority
+
+BCP 0.1.19 introduces the public `bcp/validation` entrypoint. The docs website should show validation in both form-action and API-route examples.
+
+Important concepts to surface:
+
+- `v.object`, `v.string`, `v.number`, `v.boolean`, `v.array`
+- FormData coercion with `validateFormData()`
+- `success/data` versus `issues/fieldErrors/formErrors`
+- object fields are stripped unless `allowUnknown: true`
+- `refine()` for custom application rules
+- no external validation dependency is required
+
+See `validation.md` for the complete API and examples.
+
+## Release workflow for documentation
+
+Before publishing a new BCP release:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run rc:check
+```
+
+After npm publication, the docs website can update its displayed stable version.
+
+The framework repository remains authoritative for API correctness; `bcp-docs` is the presentation layer for that content.