Documentation Guidelines

How to read, write, and contribute to the Ecommercen business flow documentation.

Purpose & Audience

These docs exist so that frontend Vue developers, new team members, and business analysts can understand what the platform does and how it does it -- tracing business logic through actual code paths.

What these docs are: Step-by-step traces of business logic flows through the codebase, with file paths, database schemas, configuration keys, and extension points.

What these docs are not: API reference or endpoint specifications. The docs site has three distinct layers:

Layer	Location	Content
API Reference	/operations/	Auto-generated from OpenAPI spec. Endpoint signatures, request/response schemas.
API Usage Guides	/api-guides/	How to authenticate, paginate, filter, sort, handle errors.
Business Flows	/flows/	How features work end-to-end through the codebase. You are here.

Flow Categories

Every flow belongs to one of four categories, identified by a two-letter prefix:

Prefix	Category	Scope	Examples
CF	Customer-Facing	Storefront user experiences -- what the shopper sees and does	Cart, checkout, search, product pages
AD	Admin	Dashboard and back-office operations -- what store managers do	Product CRUD, order management, settings
SY	System	Background jobs, cron tasks, infrastructure processes -- no UI	Order cleanup, sitemap generation, Solr indexing
IN	Integration	External service connectors -- data flowing in or out	Skroutz, Google Merchant, ERP sync, courier APIs

Document Structure

Every flow doc follows this section order. Not all sections are required -- omit any that don't apply.

#	Section	Required	Content
1	Title + metadata	Yes	H1 title. Blockquote with Flow ID, Module(s), Complexity, Last Updated.
2	Business Overview	Yes	BA-friendly summary. No code. What it does, who uses it, why it exists.
3	API Reference	If endpoints exist	REST endpoint table (Method, Path, Auth, Description). Legacy routes table if applicable.
4	Code Flow	Yes	Step-by-step trace through actual files. Include file paths. Legacy (ecommercen/) first, then modern (src/).
5	Domain Layer	If modern DDD exists	Entity, Repository, Service, ListRequest, RepositoryConfigurator components.
6	Architecture	Recommended	Component table (Component, Path, Purpose). Class hierarchy. Key integration points.
7	Data Model	Yes	Database tables with column-level detail, types, indexes, foreign keys.
8	Configuration	If configurable	Registry keys, config files, .env variables, feature flags.
9	Client Extension Points	Recommended	How client repos (application/, custom/) can override behavior. DI aliases, model overrides, hook points.
10	Business Rules	Yes	Numbered or tabled list of validations, conditions, edge cases. Include file references.
11	Related Flows	Recommended	Cross-references to other flow docs using VitePress links.

Metadata Block Format

> **Flow ID**: CF-05 | **Module(s)**: eshop, Cart domain | **Complexity**: High

Or multi-line for longer module lists:

> **Flow ID**: AD-02
> **Module(s)**: eshop, variations, attributes, coupons, badges
> **Complexity**: Very High
> **Last Updated**: 2026-04-04

Writing Guidelines

1. Business Overview comes first. Lead with "what" and "why" before "how." A BA should understand the first section without reading code.
2. Every code path reference must include the actual file path. Use ecommercen/ paths for legacy code, src/ for modern code, application/ for client-layer overrides.
3. Tables over prose for structured data -- endpoints, database columns, config keys, component inventories.
4. Link between flows using relative VitePress paths:

   [CF-05 Cart Management](/flows/customer/CF-05-cart-management)

5. Flow IDs are permanent. Never renumber. If a flow is removed, retire the ID.
6. One flow per file. Never bundle multiple flows into a single document.
7. Use code blocks for SQL, file paths, and config examples. Inline backticks for table names, column names, class names, and method names.
8. Keep dual-layer coverage. Most features have both legacy and modern implementations. Document both, clearly separated.

Complexity Rating

Rating	Criteria
Low	Single controller, fewer than 3 tables, no external services
Medium	Multiple controllers/models, 3--8 tables, simple integrations
High	Multi-layer (legacy + modern), 8+ tables, external APIs, complex business rules
Very High	10+ models, multiple external integrations, parallel implementations, extensive batch operations

Naming Conventions

Element	Pattern	Example
File name	{ID}-{slug}.md	CF-05-cart-management.md
Flow ID	{Category}-{NN} (zero-padded)	CF-05, AD-02, SY-03, IN-02
Slug	Lowercase, hyphenated, descriptive	cart-management, incomplete-order-cancellation
Directory	Category folder under flows/	flows/customer/, flows/admin/, flows/system/, flows/integration/

Adding a New Flow

1. Pick the category (CF, AD, SY, IN) based on who or what triggers the flow.
2. Assign the next available ID in that category. Check the sidebar in config.mts for the current highest number.
3. Create the file at docs/flows/{category}/{ID}-{slug}.md.
4. Write the metadata block with Flow ID, Module(s), and Complexity.
5. Write the Business Overview first -- get the "what" and "why" right before diving into code.
6. Trace the code paths through the actual codebase. Include file paths for every component referenced.
7. Document the data model with column-level detail.
8. Add the sidebar entry in docs-gen/.vitepress/config.mts under the appropriate category group.
9. Cross-reference related flows in the Related Flows section.
10. Update the index page stats at docs/flows/index.md if adding a new flow.

Architecture Context

Ecommercen has a dual-layer architecture, which is why flow docs frequently reference two parallel implementations:

Legacy layer (ecommercen/, application/): CodeIgniter 3.x HMVC with ~49 modules. Controllers extend Adv_admin_controller or Adv_front_controller. Models extend Adv_base_model. Session-based state, server-rendered views. This layer handles the full admin panel and the traditional storefront.

Modern layer (src/): PSR-4 namespaced DDD code under the Advisable\ namespace. Entities, Repositories (Specification pattern), Services, and REST controllers with JWT auth. Resource transformers handle API responses. This layer powers the REST API and headless/SPA frontends.

Both layers share the same database and often the same business rules. When documenting a flow, cover both layers where they exist, clearly labeling which is which. The modern layer does not yet cover every feature -- many flows are legacy-only.

Client repos extend the platform via application/ (legacy overrides) and custom/ (modern PSR-4 overrides under the Custom\ namespace). The Client Extension Points section in each flow doc should explain what can be overridden and where.

Development Conventions

Non-obvious rules from the project's development standards (.claude/rules/) that affect how new code is written and reviewed:

Convention	Rationale
Entity files must NOT have declare(strict_types=1)	Avoids type coercion errors during database hydration, where all values arrive as strings.
REST update uses POST, not PUT	PHP does not populate $_FILES for PUT requests, so file uploads require POST. All update endpoints follow this pattern.
HandlesWriteActions vs HandlesUploadActions are mutually exclusive	A REST controller uses one or the other, never both. HandlesUploadActions extends write behavior with file handling.
MuiRepository requires explicit NullRelationConfigurator arg in DI	When a MUI repository has no relations of its own, the DI container must pass NullRelationConfigurator as the configurator argument.
Domain containers must load before REST containers in modules.php	The application container registry (application/config/container/modules.php) must list domain container.php files before their corresponding REST container.php files, since REST services depend on domain services.
Migrations use raw SQL via $this->execute() in HEREDOC -- never Phinx fluent API	All database migrations use raw SQL strings passed to $this->execute() in PHP HEREDOC blocks. The Phinx table-builder / fluent API is not used.