x

docs/PLATFORM_OVERVIEW.md

@@ -0,0 +1,52 @@
+# DBK Platform Overview
+
+## Purpose
+
+DBK Platform is a multi-tenant, white-label commerce platform. It provides the
+shared capabilities required to operate branded commerce experiences across web,
+social-commerce, administrative, and marketplace channels. It is not limited to
+one product vertical.
+
+## Product model
+
+| Term | Meaning |
+| --- | --- |
+| **DBK Platform** | The shared product, architecture, applications, and operational capabilities in this repository. |
+| **Tenant** | A separately branded commerce implementation using the platform. A tenant owns its brand, catalog, content, domains, integrations, and configuration. |
+| **Reference tenant** | A concrete tenant retained as an implementation and content reference. |
+| **HomAroma** | The reference tenant for aroma, essential-oil, and home-fragrance commerce. It is not the platform's product category. |
+| **Legacy identifier** | Existing repository names, hosts, PM2 processes, domains, storage keys, and deployment paths that contain `homaroma`. These are operational identifiers until explicitly migrated. |
+
+## Shared applications
+
+- `apps/backend`: API, commerce domain logic, persistence, tenant-aware configuration, and integrations.
+- `apps/admin`: back-office operations and content/commerce management.
+- `apps/website`: server-rendered public storefront with SEO support.
+- `apps/spa`: mobile and social-commerce storefront, including LINE LIFF where enabled by a tenant.
+- `apps/mcp-server`: MCP interface for supported content and administration workflows.
+- `packages/types`: shared TypeScript contracts.
+
+## Documentation rules
+
+1. Platform documents must describe capabilities in vertical-neutral language.
+2. Tenant documents must name the tenant and may use vertical-specific products,
+   copy, images, routes, domains, or integrations.
+3. Examples must identify their tenant; they must not imply that their catalog is
+   a platform requirement.
+4. Historical records retain their original names and claims, but must carry a
+   short historical-context note when they could be mistaken for current platform
+   documentation.
+5. A legacy infrastructure identifier is not evidence of current product branding.
+
+## Current tenants and examples
+
+HomAroma is the reference tenant. The repository also contains tenant or showcase
+material for wellness, beauty, fashion, motorcycle parts, and other deployments.
+Their presence demonstrates that DBK Platform supports multiple verticals; it does
+not guarantee that every documented integration is enabled for every tenant.
+
+## Migration boundary
+
+This documentation migration does not rename runtime identifiers or alter code,
+database schemas, deployment paths, domains, environment variables, or external
+contracts. Such changes require a separately planned infrastructure migration.