mtkell
/
kell_creations
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kell_creations/docs/development/master_development_brief.md

1349 lines
71 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Kell Creations Operations Platform — Master Development Brief
## Recommended repo location
Place this document in the repository at:
`docs/development/master_development_brief.md`
Why this location:
- keeps it versioned with the code
- makes it easy for Cline to read and update
- separates implementation planning from feature code
- works for both web and Android roadmap tracking
If `docs/development/` does not exist yet, create it.
---
## Purpose
This document is the master implementation brief for continuing development of the Kell Creations Flutter operations platform across **web** and **Android**. It is intended for use by Cline in Windows 11 VS Code.
This brief should be treated as the working source of truth for planned development after the current completed slices already landed on `main`.
---
## Platform Vision
The Kell Creations platform is a **multi-channel commerce operations system** for managing an online product catalog, conducting in-person market sales via a mobile app, taking custom orders, and tracking supplies and inventory — all synchronized across **WooCommerce** (online storefront) and **Square** (point-of-sale and payments).
### Core business workflows
1. **Online Catalog Management** — Create, edit, publish, and manage products on the WooCommerce store from both web and mobile.
2. **Market Sales (Mobile POS)** — Use the Android app at craft markets/shows to browse the catalog, process sales via Square, and capture customer information.
3. **Custom Orders** — Accept and track custom/made-to-order requests from both online and in-person channels, with specifications, deposits, and fulfillment tracking.
4. **Supplies & Inventory** — Track raw materials (supplies) and finished goods (inventory), with stock levels synchronized bidirectionally across WooCommerce and Square.
5. **Multi-Channel Sync** — Keep product catalog, inventory quantities, pricing, and order data consistent between WooCommerce and Square as the two sales channels.
---
## Working model
Development must proceed in **small, reviewable vertical slices**.
Rules:
- Branch from current `main` for each stage or sub-slice.
- Implement on a feature branch.
- Validate locally.
- Open a PR into `main`.
- Merge only after tests/analyze are clean.
- Do not stack broad unfinished work directly on `main`.
- After each merged slice, update this brief so it remains aligned to `main`.
---
## Current confirmed baseline on `main`
### Platform structure
- `apps/kell_web` exists — active, wired to shared packages.
- `apps/kell_mobile` exists — integrated with shared packages, mobile-optimized shell with bottom navigation, dashboard, and placeholder pages for all features.
- Shared packages include:
- `core` — shared domain/application abstractions and cross-platform composition pattern (`KcAppConfig`, `KcAppServices`, `KcBootstrap`, `KcAppScope`)
- `design_system` — theme (`KcColors`, `KcSpacing`, `KcTheme`), typography (`KcTypography`), layout (`KcBreakpoints`), and 7 shared widgets (`KcCard`, `KcStatusChip`, `KcEmptyState`, `KcSectionHeader`, `KcSummaryCard`, `KcLoadingState`, `KcErrorState`)
- `feature_inventory` — domain, application, data (fake), and presentation layers
- `feature_wordpress` — domain, application, data (fake + WooCommerce), and presentation layers (most mature feature)
- `feature_orders` — domain, application, data (fake), and presentation layers
- `feature_policy` — domain, application, data (fake), and presentation layers
- Scaffolded but **empty stub** packages (created, no implementation yet):
- `auth` — authentication/authorization (stub only)
- `data` — shared data layer (stub only)
- `integrations` — shared integration abstractions (stub only)
- `feature_finance` — financial analysis feature (stub only)
- `feature_mrp` — craft manufacturing/MRP feature (stub only)
- `feature_social` — social media management feature (stub only)
- `tools/` directory contains CI helper scripts (`run_all_tests.sh`, `collect_coverage.sh`, `README.md`).
- App shell, routing, dashboard, reusable shell widgets, `AppServices`, and `AppScope` are implemented.
- Dashboard uses app-composed repository data.
- Vertical slices exist for Inventory, Products/Publishing, Orders, and Policy/Governance.
- Cross-feature navigation handoffs and shared filtering/search/selection persistence are implemented.
- Runtime bootstrap uses:
- `KC_ENV`
- `KC_WC_SITE_URL`
- `KC_WC_CONSUMER_KEY`
- `KC_WC_CONSUMER_SECRET`
- App supports `FAKE` and `WP` modes with visible shell badge.
### Product publishing workflow already landed on `main`
- Controlled WooCommerce publish action landed.
- `ProductDraft.copyWith` landed.
- `unpublished -> draft` UI exposure landed.
- `pendingReview -> draft` UI exposure landed.
- `unpublished` semantics clarified as a read-only abstraction.
- Status action success/failure feedback landed.
- Publishing page polish landed.
- Richer read-side detail preview landed.
- Price-only product edit landed.
- Search/filter/sort refinement landed.
- Name-only product edit landed.
- ✅ Description-only product edit landed (Stage 1A complete — merged `feat/description-only-edit` → `main` at `cebac4c`, 2026-04-11).
- ✅ Category-only product edit landed (Stage 1B complete — merged `feat/category-only-edit` → `main` at `8e7e4cb`, 2026-04-11). Stage 1 complete.
- ✅ Post-write consistency hardening landed (Stage 2A complete — merged `feat/post-write-consistency` → `main` at `7acff83`, 2026-04-11).
- ✅ Publishing workflow UX hardening landed (Stage 2B complete — merged `feat/publishing-ux-hardening` → `main` at `b81016d`, 2026-04-11). Stage 2 complete.
- ✅ Multi-select groundwork landed (Stage 3A complete — merged `feat/multi-select-groundwork` → `main`, 2026-05-22).
- ✅ List efficiency improvements landed (Stage 3B complete — merged `feat/list-efficiency-improvements` → `main`, 2026-05-22). Stage 3 complete.
- ✅ Design system expansion and shared widget migration landed (Stage 4A complete — merged `feat/design-system-shared-widgets` → `main`, 2026-05-22).
- ✅ Cross-platform shell composition strategy landed (Stage 4B complete — merged `feat/shared-composition-pattern` → `main`, 2026-05-22).
- ✅ Flutter CI/CD pipeline landed (Stage 4C complete — merged `feat/flutter-cicd` → `main`, 2026-05-22).
- ✅ Test coverage visibility landed (Stage 4D complete — merged `feat/test-coverage-visibility` → `main`, 2026-05-22).
- ✅ Bulk move-to-draft action landed (Stage 7A complete — merged `feat/bulk-status-actions` → `main`, 2026-05-30).
### Current narrow edit capabilities on `main`
- update product status through controlled workflow
- update product price only
- update product name only
- update product description only
- update product category only
### Latest known validation state on `main`
- `dart analyze` clean
- `core` tests passing
- `design_system` tests passing
- `feature_wordpress` tests passing
- `kell_web` tests passing
- `kell_mobile` tests passing
- latest reported count for `core`: `20/20 passed`
- latest reported count for `design_system`: `41/41 passed`
- latest reported count for `feature_wordpress`: `311/311 passed`
- latest reported count for `kell_web`: `24/24 passed`
- latest reported count for `kell_mobile`: `14/14 passed`
- baseline commit: merge of `feat/android-mobile-ux-hardening` (2026-05-30)
#### Baseline test coverage (established 2026-05-22)
| Package | Tests | Lines Hit | Lines Found | Coverage |
| ------------------- | ------- | --------- | ----------- | --------- |
| `core` | 20 | 42 | 49 | 85.7% |
| `design_system` | 41 | 88 | 88 | 100.0% |
| `feature_wordpress` | 294 | 857 | 1012 | 84.7% |
| `kell_web` | 24 | 191 | 353 | 54.1% |
| **Total** | **379** | **1178** | **1502** | **78.4%** |
No minimum thresholds are enforced — this is visibility-only tracking. Coverage is measured via `flutter test --coverage` (generates `lcov.info`) and reported in the CI workflow summary table.
### Next recommended branch
**`feat/bulk-status-actions`** — Stage 7: Controlled bulk actions.
Branch from latest `main`. All entry criteria met: single-item edit/status flows stable, multi-select groundwork complete, post-write consistency hardened, Android core publishing surface exists. Stage 6 (Android operational maturity) is complete.
---
## Senior Audit Report (2026-05-30)
### Audit scope
Full structural, feature, and build plan review conducted against the target platform vision: multi-channel commerce operations with online catalog management, mobile market sales, custom orders, supplies/inventory tracking, and WooCommerce + Square integration.
### Audit summary — strengths
| Area | Assessment |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Architecture** | Excellent C4 coverage (19 diagrams), clean package boundaries, well-documented composition pattern. The monorepo structure with shared domain/application layers is sound and extensible. |
| **Code quality** | 393 tests across 5 packages, 78.4% line coverage, `dart analyze` clean. Strict vertical-slice discipline with thorough PR tracking. |
| **WooCommerce integration** | Production-ready product publishing via REST API v3. Clean `WooCommerceApiClient` abstraction with Basic Auth, pagination, and error handling. |
| **Cross-platform** | Shared composition pattern (`KcAppServices`, `KcBootstrap`, `KcAppScope`) enables both web and mobile to reuse identical business logic. Zero logic forking for Android. |
| **Design system** | Foundation-ready with 7 shared widgets, typography, breakpoints, and 100% test coverage. |
| **CI/CD** | Forgejo Actions for analyze + test with per-package coverage reporting. |
| **Mobile app** | Android shell with 5-tab navigation, mobile-optimized publishing surface, haptic feedback, confirmation dialogs. |
### Audit summary — critical gaps for target vision
#### Gap 1: No product creation capability
The platform can only **edit existing** WooCommerce products. There is no workflow to **create new products** — neither in the domain model, repository contract, nor UI. The `ProductPublishingRepository` has no `createProduct()` method. This is a blocker for online catalog management.
**Impact:** Cannot manage a catalog without the ability to add products.
#### Gap 2: No image/media management
The `ProductDraft` model has an `imageUrl` field but it is read-only. No upload, selection, or gallery management exists. The `WooCommerceApiClient` has no media endpoints. Product images cannot be added or changed.
**Impact:** Catalog products without images have severely reduced sales conversion.
#### Gap 3: Orders are read-only with fake data
The `OrdersRepository` contract has only `getOrders()`. There is no `createOrder()`, `updateOrderStatus()`, or any write operation. The `Order` domain model lacks custom order fields (notes, customizations, deposit tracking). The repository has no real backend — only `FakeOrdersRepository`.
**Impact:** Cannot take custom orders or sync orders from WooCommerce.
#### Gap 4: Inventory is read-only with fake data
The `InventoryRepository` contract has only `getInventoryItems()`. No write operations (adjust quantity, add item, record usage). No concept of raw materials vs. finished goods. No real backend. No WooCommerce stock sync.
**Impact:** Cannot track supplies or update inventory levels. No stock accuracy across channels.
#### Gap 5: Square integration is completely absent
No Square API client, no Square SDK references, no Square-related domain models, no payment processing, no POS capability. The `integrations` package is an empty stub containing only a placeholder `Calculator` class.
**Impact:** Cannot process payments at markets. Cannot sync catalog or inventory with Square.
#### Gap 6: No multi-channel sync engine
No mechanism to synchronize products, inventory, or orders between WooCommerce and Square. No unified product ID mapping, no conflict resolution strategy, no webhook handling for external change detection.
**Impact:** Running two sales channels without sync leads to overselling and data inconsistency.
#### Gap 7: No authentication
The `auth` package is a stub. All access is uncontrolled. No user identity, no role-based access, no secure credential storage beyond `--dart-define`.
**Impact:** Cannot deploy to multiple users or secure API credentials on-device.
#### Gap 8: No offline capability
The mobile app requires network connectivity for all operations. Markets frequently have poor or no cellular coverage. No local data caching, no offline queue, no sync-on-reconnect.
**Impact:** Mobile app is unusable at markets without reliable network.
#### Gap 9: WooCommerce integration is products-only
The `WooCommerceApiClient` supports only the Products endpoint (`GET /products`, `PUT /products/{id}`). Missing: Orders API, Customers API, Categories API (CRUD), Product Images/Media API, Stock/Inventory API, Webhooks, Coupons.
**Impact:** Cannot pull orders from the online store or sync inventory levels with WooCommerce.
#### Gap 10: No financial/reporting capability
`feature_finance` is a stub. No sales reports, inventory valuation, cost tracking, or revenue analytics. No data aggregation from orders across channels.
**Impact:** No business intelligence for decision-making.
### Audit recommendations
The gaps above are addressed in the revised development roadmap below (Stages 8–16). The roadmap is ordered to deliver the highest-value capabilities first while respecting architectural dependencies.
---
## Non-negotiable architectural constraints
These must be preserved in all future work:
- Preserve **strict package boundaries**.
- Fake repositories remain in feature packages.
- Real integrations are incremental alongside fake ones.
- Runtime selection stays via `--dart-define`, not a settings UI.
- No credentials hardcoded or committed.
- Do **not** broaden into generic product editing prematurely.
- Keep WooCommerce details inside the WP repository layer.
- Keep Square details inside a dedicated Square integration layer.
- Keep diffs small and reviewable.
- Prefer inspection-first development.
- Android support should reuse shared feature/domain/application layers rather than fork logic.
- Multi-channel sync must be abstraction-first: define channel-agnostic contracts before platform-specific implementations.
---
## Development stages
### Stage 1 — Web application completion: controlled product editing
#### Objective
Extend the publishing workflow with additional **single-field** edit capabilities using the same narrow pattern already established by price-only and name-only update.
#### Branching model
Use one branch per edit slice:
- `feat/description-only-edit`
- `feat/category-only-edit`
#### ~~Stage 1A — Description-only product edit~~ ✅ COMPLETE
> Merged `feat/description-only-edit` → `main` at `cebac4c` (2026-04-11).
> All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline description edit UI, and targeted tests (212 total `feature_wordpress` tests passing).
#### ~~Stage 1B — Category-only product edit~~ ✅ COMPLETE
> Merged `feat/category-only-edit` → `main` at `8e7e4cb` (2026-04-11).
> All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline category edit UI, snack bar feedback, and targeted tests (223 total `feature_wordpress` tests passing). Stage 1 complete.
---
### Stage 2 — Web application operational hardening
#### Objective
Improve operator consistency, predictability, and usability after writes.
#### Branches
- `feat/post-write-consistency`
- `feat/publishing-ux-hardening`
#### ~~Stage 2A — Post-write consistency hardening~~ ✅ COMPLETE
> Merged `feat/post-write-consistency` → `main` at `7acff83` (2026-04-11).
> Added `_refreshSelection()` to `ProductPublishingController` to preserve/refresh selection after all write-triggered reloads. 11 new post-write consistency tests added (234 total `feature_wordpress` tests passing).
#### ~~Stage 2B — Publishing workflow UX hardening~~ ✅ COMPLETE
> Merged `feat/publishing-ux-hardening` → `main` at `b81016d` (2026-04-11).
> Added inline validation error messages for all four single-field edits (name, price, description, category), disabled text fields and save buttons during `isUpdating`, and appended error detail to failure snack bars. 13 new tests added (247 total `feature_wordpress` tests passing). Stage 2 complete.
---
### Stage 3 — Web application operator efficiency
#### Objective
Increase throughput for product triage and management using existing data.
#### Branches
- `feat/multi-select-groundwork`
- `feat/list-efficiency-improvements`
#### ~~Stage 3A — Multi-select groundwork (read/state only first)~~ ✅ COMPLETE
> Merged `feat/multi-select-groundwork` → `main` (2026-05-22).
> Added multi-selection state to `ProductPublishingController` (`toggleMultiSelect`, `clearMultiSelection`, `selectAllVisible`, `isMultiSelected`, `multiSelectedIds`, `multiSelectedCount`). Updated `ProductDraftCard` with optional leading checkbox for multi-select mode. Added `_MultiSelectBar` to `ProductPublishingPage` with selected-count display, Select All, and Clear actions. Single-item preview selection preserved independently. 15 new multi-select tests added (262 total `feature_wordpress` tests passing). No bulk writes introduced.
#### ~~Stage 3B — List efficiency improvements~~ ✅ COMPLETE
> Merged `feat/list-efficiency-improvements` → `main` (2026-05-22).
> Added compact/standard view toggle (`ListDensity` enum), staleness detection (`isStale()`, `staleCount()` with 30-day threshold), keyboard navigation (`selectNextDraft`/`selectPreviousDraft` with wrapping), description snippet in standard card, and stale indicator icon. Updated `ProductDraftCard` with compact two-row layout variant and `Flexible` overflow handling. Page wires up `Focus`+`onKeyEvent` for arrow keys and density toggle button. 32 new tests added (294 total `feature_wordpress` tests passing). Stage 3 complete.
---
### Stage 4 — Platform foundations and cross-platform readiness
#### Objective
Strengthen the shared platform infrastructure before expanding to Android. This stage implements the key recommendations from the codebase analysis to reduce technical debt, prevent duplication, and establish quality gates.
#### Key principle
Invest in shared foundations now so that the Android expansion (Stage 5) and all future feature work benefits from a mature design system, shared composition patterns, automated CI/CD, and proper test coverage tracking.
#### Branches
- `feat/design-system-shared-widgets`
- `feat/flutter-cicd`
- `feat/shared-composition-pattern`
#### ~~Stage 4A — Design system expansion and shared widget migration~~ ✅ COMPLETE
> Merged `feat/design-system-shared-widgets` → `main` (2026-05-22).
> Migrated `EmptyStatePanel`, `SectionHeader`, and `SummaryCard` from `kell_web/lib/shell/widgets/` into `design_system` as `KcEmptyState`, `KcSectionHeader`, and `KcSummaryCard`. Added `KcTypography` shared typography scale, `KcBreakpoints` responsive layout breakpoint utilities, `KcLoadingState` and `KcErrorState` shared state widgets. Updated `kell_web` dashboard to use design_system widgets directly; shell widget files now contain backward-compatible typedefs. Theme updated to use `KcTypography.applyKcTypography()`. 41 new design_system tests added (41 total `design_system` tests, 294 `feature_wordpress` tests, 24 `kell_web` tests — all passing). Analyze clean.
#### ~~Stage 4B — Cross-platform shell composition strategy~~ ✅ COMPLETE
> Merged `feat/shared-composition-pattern` → `main` at `0a0abc2` (2026-05-22).
> Extracted shared composition abstractions into `core` package: `KcAppConfig`, `KcAppEnvironment`, `KcAppServices` (abstract), `KcServiceFactory<T>`, `KcBootstrap`, `KcAppScope<T>`. Updated `kell_web` to delegate to shared types via backward-compatible typedefs (`AppConfig`, `AppEnvironment`, `AppServices`, `AppScope`, `Bootstrap`). Contract for new app targets documented in `kell_creations_apps/docs/composition-strategy.md`. `kell_web` runtime behavior unchanged. 20 core tests added covering all composition abstractions (20/20 core, 41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web — all passing). Analyze clean.
#### ~~Stage 4C — Flutter CI/CD pipeline~~ ✅ COMPLETE
> Merged `feat/flutter-cicd` → `main` (2026-05-22).
> Added Forgejo Actions workflows: `flutter-analyze.yml` (runs `dart analyze --fatal-infos` on all 8 packages/apps) and `flutter-test.yml` (runs `flutter test` per package with per-package pass/fail count and aggregate summary table). Workflows trigger on PRs to main and all non-main branch pushes using `ghcr.io/cirruslabs/flutter:stable` container. Populated `tools/` directory with `run_all_tests.sh` (local test runner with optional `--analyze` flag) and `README.md` documenting scripts and CI workflow inventory. All existing tests passing (20 core, 41 design_system, 294 feature_wordpress, 24 kell_web — 379 total). Analyze clean.
#### ~~Stage 4D — Test coverage visibility~~ ✅ COMPLETE
> Merged `feat/test-coverage-visibility` → `main` (2026-05-22).
> Enhanced `flutter-test.yml` CI workflow to run `flutter test --coverage` and parse `lcov.info` files, producing an aggregate summary table with per-package pass/fail counts and line coverage percentages. Added `collect_coverage.sh` local coverage helper script and updated `tools/README.md`. Established baseline coverage: core 85.7% (42/49), design_system 100.0% (88/88), feature_wordpress 84.7% (857/1012), kell_web 54.1% (191/353) — overall 78.4% (1178/1502). No minimum thresholds enforced — visibility first. All 379 tests passing. Analyze clean. Stage 4 complete.
---
### Stage 5 — Android application foundation
#### Objective
Bring the current operations platform capabilities to Android using shared packages first and platform-specific UI only where required.
#### Key principle
Business logic, domain logic, repositories, and feature application logic should remain shared. Android should primarily add a dedicated app shell and mobile-optimized presentation.
#### Branches
- `feat/android-app-shell`
- `feat/android-publishing-surface`
#### ~~Stage 5A — Android app shell and bootstrap~~ ✅ COMPLETE
> Merged `feat/android-app-shell` → `main` (2026-05-28).
> Replaced the default Flutter counter template with a fully integrated mobile app shell. Created `MobileAppServices` extending `KcAppServices` with shared composition pattern, `KellMobileApp` with `KcAppScope<MobileAppServices>` and `KcBootstrap`, `MobileShell` with 5-tab `NavigationBar` (Dashboard, Inventory, Orders, Publishing, More). Dashboard reuses shared `DashboardSummary`/`DashboardController` with mobile-optimized `GridView` layout and design system widgets. Placeholder pages for Finance, Integrations, and feature tab content. `pubspec.yaml` references all shared packages (`core`, `design_system`, `feature_inventory`, `feature_orders`, `feature_policy`, `feature_wordpress`). Environment badge shows runtime mode. SDK constraint corrected to `^3.11.0` across all 14 pubspec files. 6 new `kell_mobile` widget tests added (6/6 kell_mobile, 24/24 kell_web, 294/294 feature_wordpress — all passing).
#### ~~Stage 5B — Android publishing surface~~ ✅ COMPLETE
> Merged `feat/android-publishing-surface` → `main` (2026-05-29).
> Created mobile-optimized publishing workspace: `MobilePublishingPage` with search bar, horizontal filter chips, sort dropdown with ascending/descending toggle, product count display, compact card list with pull-to-refresh, and push navigation to detail page. `MobileProductDetailPage` wraps the shared `ProductPreviewPanel` with all narrow edit callbacks (status, price, name, description, category). Products tab in `MobileShell` switched from web `ProductPublishingPage` to `MobilePublishingPage`. Expanded `feature_wordpress` barrel exports for mobile consumption (`ProductPublishingController`, `ProductSortField`, `ProductDraftCard`, `ProductPreviewPanel`, all 5 use cases, snack bar helpers). Zero business logic forked — all shared layers reused. 4 new mobile publishing surface tests added (10 total `kell_mobile` tests passing). Analyze clean. Stage 5 complete.
---
### Stage 6 — Android operational maturity
#### Objective
Harden Android UX after the core feature surface works.
#### Branches
- `feat/android-feedback-polish`
- `feat/android-mobile-ux-hardening`
#### ~~Stage 6A — Android feedback and action polish~~ ✅ COMPLETE
> Merged `feat/android-feedback-polish` → `main` (2026-05-29).
> Converted `MobileProductDetailPage` to StatefulWidget with its own controller listener for local SnackBar feedback. Added confirmation dialogs for publish/move-to-draft status changes. Added haptic feedback (mediumImpact for status, lightImpact for field edits) on successful actions. Guarded list page SnackBars with `_detailPageActive` flag to prevent invisible behind-route feedback. 4 new tests added (14 total kell_mobile tests passing).
#### ~~Stage 6B — Android mobile workflow hardening~~ ✅ COMPLETE
> Merged `feat/android-mobile-ux-hardening` → `main` (2026-05-30).
> Restored Material Design 48×48dp minimum touch targets on 12 `IconButton`s in `ProductPreviewPanel` by removing `constraints: BoxConstraints()` and `padding: EdgeInsets.zero` overrides. Replaced fixed-width `SizedBox(width: 80)` on price edit `TextField` with `Expanded` for flexible layout on narrow mobile screens. Added `tooltip: 'Edit price'` for consistency. Wrapped `ProductPreviewPanel` in `SafeArea` in `MobileProductDetailPage` to prevent content clipping under system UI on devices with notches/gesture bars. 6 new touch target rendered-size tests added (300 total `feature_wordpress` tests passing, 14 `kell_mobile`, 24 `kell_web`, 41 `design_system` — 379 total). Stage 6 complete.
---
### Stage 7 — Controlled bulk actions (only after groundwork)
#### Objective
Add carefully scoped bulk operations once single-item workflows are stable across web and Android.
#### Branches
- `feat/bulk-status-actions`
- `feat/bulk-operator-workflows`
#### Entry criteria ✅ ALL MET
- ✅ single-item edit/status flows are stable
- ✅ multi-select groundwork is complete
- ✅ post-write consistency is hardened
- ✅ Android core publishing surface exists
#### ~~Stage 7A — Bulk move-to-draft (web)~~ ✅ COMPLETE
> Merged `feat/bulk-status-actions` → `main` (2026-05-30).
> Added `BulkActionResult` value class, `bulkUpdateStatus()` controller method (sequential processing with per-row updating state, single reload after completion, auto-clear multi-selection), `showBulkActionSnackBar()` with success/partial-failure/total-failure messaging. Updated `_MultiSelectBar` with "Move to Draft" button and confirmation dialog. 11 new bulk action tests added (311 total `feature_wordpress` tests passing, 24 `kell_web` tests passing).
#### Stage 7B — Bulk operator workflows (future)
Candidate additional bulk actions (implement one per slice):
- bulk publish
- bulk move to pending review
#### Explicitly defer
- bulk generic edit
- bulk category management
- destructive bulk deletion unless separately justified
---
### Stage 8 — Infrastructure package activation
#### Objective
Activate the three infrastructure stub packages (`auth`, `data`, `integrations`) to provide shared foundations required by all subsequent feature work — especially multi-channel commerce, custom orders, and inventory management.
#### Key principle
These packages define **contracts and abstractions** first, with concrete implementations added incrementally. Do not build full implementations in one pass.
#### Branches
- `feat/integrations-contracts`
- `feat/data-layer-contracts`
- `feat/auth-foundation`
#### Stage 8A — Integration abstractions (`integrations` package)
##### Goal
Replace the placeholder `Calculator` class in `integrations` with shared integration contracts that formalize the API client pattern already proven in `feature_wordpress`.
##### Requirements
- Define `ApiClient` abstract class (lifecycle, auth, error handling, dispose)
- Define `ApiException` base class with status code, message, body
- Define `RetryPolicy` and `RateLimiter` abstractions
- Define `IntegrationHealthCheck` contract
- Define `WebhookHandler` contract for incoming webhook processing
- Define `ChannelAdapter` contract — the abstraction for a sales channel (WooCommerce, Square, future channels) with standard operations: products, orders, inventory, customers
- Refactor `WooCommerceApiClient` and `WooCommerceApiException` to implement the shared contracts
- Tests for all contracts
#### Stage 8B — Shared data layer (`data` package)
##### Goal
Provide shared data abstractions for local caching, offline storage, and cross-feature data patterns.
##### Requirements
- Define `LocalCache<T>` contract for in-memory and persistent caching
- Define `SyncQueue` abstraction for offline operation queuing
- Define `ConflictResolver<T>` contract for multi-channel sync conflicts
- Define `ChangeTracker<T>` for tracking local modifications pending sync
- Define `DataMapper<TLocal, TRemote>` for local ↔ remote model mapping
- Implement SQLite-backed persistent cache (using `sqflite` or `drift`)
- Tests for all abstractions
#### Stage 8C — Authentication foundation (`auth` package)
##### Goal
Provide basic authentication and secure credential storage so the app can be deployed beyond a single operator.
##### Requirements
- Define `AuthService` contract (login, logout, current user, token refresh)
- Define `CredentialStore` contract for secure storage of API keys (WooCommerce, Square)
- Implement `SecureCredentialStore` using `flutter_secure_storage`
- Define `User` and `AuthState` domain models
- Add `KC_ENV` extension: support `SQUARE` mode alongside `FAKE` and `WP`
- Update `KcAppEnvironment` enum and `KcBootstrap` to support the new mode
- Tests for auth contracts and credential store
---
### Stage 9 — WooCommerce integration expansion
#### Objective
Extend the WooCommerce integration from products-only to full commerce coverage: orders, inventory/stock, categories, images, and customers.
#### Key principle
Each API surface is added as a separate sub-stage with its own repository contract, implementation, and tests. The `WooCommerceApiClient` gains new endpoint methods; feature packages gain new repository methods.
#### Branches
- `feat/wc-orders-integration`
- `feat/wc-inventory-sync`
- `feat/wc-catalog-expansion`
#### Stage 9A — WooCommerce Orders API integration
##### Goal
Connect the orders feature to WooCommerce so orders placed online appear in the app and order status can be updated.
##### Requirements
- Add `getOrders()`, `getOrder(id)`, `updateOrderStatus()`, `createOrder()` to `WooCommerceApiClient`
- Extend `Order` domain model: add `orderNotes`, `paymentMethod`, `source` (online vs. market), `customFields` map for custom order specifications
- Extend `OrderItem` domain model: add `productId`, `variationId`, `customizations` (map for custom order specs like color, size, material)
- Add `OrderStatus` values: `onHold`, `refunded`, `failed` (WooCommerce standard statuses)
- Extend `OrdersRepository` contract: `getOrders()`, `getOrder(id)`, `createOrder()`, `updateOrderStatus()`, `addOrderNote()`
- Implement `WooCommerceOrdersRepository`
- Update `FakeOrdersRepository` with matching methods
- Add order mapper for WooCommerce JSON ↔ domain
- Tests for repository, mapper, and API client extensions
#### Stage 9B — WooCommerce stock/inventory sync
##### Goal
Enable bidirectional stock quantity synchronization between the app's inventory and WooCommerce product stock levels.
##### Requirements
- Add `getProductStock(id)`, `updateProductStock(id, quantity)`, `batchUpdateStock(updates)` to `WooCommerceApiClient`
- Extend `InventoryItem` domain model: add `wooCommerceProductId` (nullable — not all inventory items are WooCommerce products), `lastSyncedAt`, `syncStatus`
- Extend `InventoryRepository` contract: `updateQuantity()`, `adjustQuantity()`, `getItemBySku()`, `syncWithRemote()`
- Add `InventorySyncService` in application layer — orchestrates comparing local vs. remote stock and resolving differences
- Implement `WooCommerceInventoryRepository`
- Update `FakeInventoryRepository` with matching write methods
- Tests for sync service, repository, and stock update flows
#### Stage 9C — WooCommerce catalog expansion
##### Goal
Add product creation, image management, and category CRUD to complete full catalog management via WooCommerce.
##### Requirements
- Add `createProduct(data)`, `deleteProduct(id)` to `WooCommerceApiClient`
- Add `getCategories()`, `createCategory()`, `updateCategory()`, `deleteCategory()` to `WooCommerceApiClient`
- Add `uploadMedia(file)`, `getMedia(productId)`, `setProductImages(productId, mediaIds)` to `WooCommerceApiClient`
- Extend `ProductPublishingRepository`: `createProduct()`, `deleteProduct()`, `updateProductImages()`, `getCategories()`, `createCategory()`
- Add `ProductCategory` domain model (id, name, slug, parent, count)
- Add `ProductImage` domain model (id, url, alt, position)
- Add product creation UI — form with name, description, price, category, SKU, images
- Add image picker/upload UI for mobile and web
- Add category management page
- Tests for all new repository methods, use cases, and UI
---
### Stage 10 — Square integration foundation
#### Objective
Introduce Square as a second sales channel, enabling in-person payment processing and catalog/inventory synchronization.
#### Key principle
Square integration must follow the same architectural pattern as WooCommerce: API client in a data layer, repository contracts in domain layer, and runtime selection via `--dart-define`. The `integrations` package `ChannelAdapter` contract (Stage 8A) provides the abstraction both channels implement.
#### Branches
- `feat/square-api-client`
- `feat/square-catalog-sync`
- `feat/square-payments`
#### Stage 10A — Square API client and authentication
##### Goal
Create the foundational Square API client with OAuth 2.0 authentication.
##### Requirements
- Add `KC_SQUARE_ACCESS_TOKEN`, `KC_SQUARE_LOCATION_ID`, `KC_SQUARE_ENVIRONMENT` to `--dart-define` keys
- Create `SquareApiClient` implementing shared `ApiClient` contract from `integrations` package
- Implement Square OAuth 2.0 flow (or access token injection for initial development)
- Implement Square Catalog API: `listCatalogItems()`, `upsertCatalogItem()`, `deleteCatalogItem()`
- Implement Square Inventory API: `getInventoryCount()`, `batchChangeInventory()`
- Implement Square Orders API: `createOrder()`, `listOrders()`, `getOrder()`
- Implement Square Payments API: `createPayment()`, `getPayment()`
- Add `SquareApiException` extending shared `ApiException`
- Update `KcAppEnvironment` to support `square` and `multi` (both channels) modes
- Tests for API client, auth flow, and all endpoints
#### Stage 10B — Square catalog and inventory sync
##### Goal
Synchronize the product catalog and inventory levels between the app and Square.
##### Requirements
- Create `SquareProductMapper` for Square CatalogObject ↔ `ProductDraft` mapping
- Create `SquareInventoryMapper` for Square InventoryCount ↔ `InventoryItem` mapping
- Create `SquareCatalogRepository` implementing `ProductPublishingRepository` (or a shared catalog contract)
- Create `SquareInventoryRepository` implementing `InventoryRepository`
- Create `ProductIdMapping` domain model — maps product IDs across WooCommerce and Square
- Create `ProductIdMappingRepository` for persisting cross-channel ID mappings
- Update `FakeProductPublishingRepository` and `FakeInventoryRepository` with matching operations
- Tests for mappers, repositories, and ID mapping
#### Stage 10C — Square payment processing (mobile POS)
##### Goal
Enable the Android app to accept payments via Square at craft markets.
##### Requirements
- Integrate Square Mobile Payments SDK (or Square Reader SDK) for Android
- Create `PaymentService` abstraction in application layer
- Create `PaymentResult` domain model (amount, method, transactionId, receiptUrl)
- Create `MobileCheckoutPage` — product selection → cart → payment flow
- Support cash recording (manual entry, no Square hardware needed)
- Support card payment via Square Reader
- Generate digital receipt (or link to Square receipt)
- After payment: create order record, deduct inventory
- Add `Sales` tab to mobile navigation (replaces or supplements current Products tab for market mode)
- Tests for payment service, checkout flow, and order creation
---
### Stage 11 — Custom orders workflow
#### Objective
Enable operators to accept custom/made-to-order requests from both online and in-person channels, track specifications, manage deposits, and fulfill orders.
#### Key principle
Custom orders extend the existing `Order` domain model with additional fields rather than creating a parallel system. Custom orders flow through the same order management pipeline.
#### Branches
- `feat/custom-order-domain`
- `feat/custom-order-ui`
- `feat/custom-order-tracking`
#### Stage 11A — Custom order domain and data
##### Goal
Extend the order domain model and repository to support custom order creation with specifications.
##### Requirements
- Add `OrderType` enum: `standard`, `custom`
- Add `CustomOrderSpec` value object: material, color, dimensions, special instructions, reference images, estimated completion date
- Add `DepositInfo` value object: depositAmount, depositPaid, depositDate, balanceDue
- Extend `Order` model: `orderType`, `customSpec` (nullable), `depositInfo` (nullable), `estimatedCompletionDate`, `internalNotes`
- Extend `OrdersRepository`: `createCustomOrder()`, `updateCustomOrderSpec()`, `recordDeposit()`, `updateEstimatedCompletion()`
- Implement in both `FakeOrdersRepository` and `WooCommerceOrdersRepository` (WooCommerce custom orders use order meta fields)
- Tests for domain models and repository methods
#### Stage 11B — Custom order creation UI
##### Goal
Provide mobile and web interfaces for creating custom orders, especially at markets.
##### Requirements
- Create `CustomOrderFormPage` (shared or platform-specific presentation)
- Customer information capture (name, email, phone)
- Product base selection (from catalog) or free-text description
- Customization fields: material, color, size/dimensions, special instructions
- Reference image capture (camera on mobile, file picker on web)
- Pricing: estimated price, deposit amount, deposit payment method
- Estimated completion date picker
- Create `CustomOrderConfirmationPage` — summary with digital receipt for deposit
- Wire into mobile shell navigation and web routing
- Tests for form validation, order creation flow
#### Stage 11C — Custom order tracking and fulfillment
##### Goal
Provide order tracking dashboard and status management for custom orders.
##### Requirements
- Create `CustomOrderTrackingPage` — filtered view of custom orders by status
- Add status progression: `quoted` → `depositReceived` → `inProduction` → `qualityCheck` → `readyForPickup` → `completed`
- Add notification triggers (future: email/SMS when status changes)
- Add order history/timeline view showing all status changes with timestamps
- Link custom order completion to inventory deduction (materials used)
- Tests for tracking UI and status progression
---
### Stage 12 — Inventory and supplies management
#### Objective
Transform the inventory feature from a read-only fake-data display into a full supplies and inventory management system with write operations, supply tracking, and multi-channel stock sync.
#### Key principle
Distinguish between **raw materials/supplies** (inputs to production) and **finished goods** (products for sale). Both are tracked in the inventory system but have different lifecycles.
#### Branches
- `feat/inventory-write-ops`
- `feat/supplies-tracking`
- `feat/inventory-sync-engine`
#### Stage 12A — Inventory write operations and domain expansion
##### Goal
Add write operations to inventory and expand the domain model for real-world tracking.
##### Requirements
- Add `ItemType` enum: `rawMaterial`, `finishedGood`, `packaging`, `tool`
- Extend `InventoryItem`: `itemType`, `reorderPoint`, `reorderQuantity`, `supplier`, `costPerUnit`, `location`, `lastCountDate`, `notes`
- Add `InventoryAdjustment` value object: `itemId`, `adjustmentType` (received, used, damaged, returned, counted), `quantity`, `reason`, `timestamp`, `operator`
- Extend `InventoryRepository`: `addItem()`, `updateItem()`, `adjustQuantity()`, `getAdjustmentHistory()`, `getLowStockItems()`, `getItemsByType()`
- Implement write operations in `FakeInventoryRepository`
- Add `InventoryController` (ChangeNotifier) for state management — mirrors the pattern from `ProductPublishingController`
- Tests for all new domain models, repository methods, and controller
#### Stage 12B — Supplies tracking
##### Goal
Add supply-specific workflows: receiving shipments, recording material usage in production, and reorder alerts.
##### Requirements
- Add `Supplier` domain model: name, contact, leadTime, minimumOrder
- Add `PurchaseOrder` domain model: supplier, items, orderDate, expectedDelivery, status, totalCost
- Add `SupplierRepository` contract and fake implementation
- Add `PurchaseOrderRepository` contract and fake implementation
- Create supply receiving workflow: record incoming shipments → auto-adjust inventory
- Create material usage workflow: when fulfilling orders (standard or custom) → deduct raw materials
- Add low-stock alert system: surface items below reorder point on dashboard
- Create `SuppliesPage` UI (list, filter by type, quick-adjust, reorder alerts)
- Tests for supply workflows, reorder logic, and UI
#### Stage 12C — Multi-channel inventory sync engine
##### Goal
Keep inventory quantities consistent across the local app, WooCommerce, and Square.
##### Requirements
- Create `InventorySyncEngine` in application layer:
- Poll or webhook-triggered sync from WooCommerce and Square
- Conflict resolution: last-write-wins with operator override option
- Sync status tracking per item (synced, pending, conflict, error)
- Batch sync support for efficiency
- Create `ChannelStockMapping` — maps inventory item IDs to WooCommerce product IDs and Square catalog item IDs
- Implement `WooCommerceStockSync` using Stage 9B foundations
- Implement `SquareStockSync` using Stage 10B foundations
- Add sync status indicators to inventory UI
- Add manual sync trigger and conflict resolution UI
- Tests for sync engine, conflict resolution, and channel adapters
---
### Stage 13 — Multi-channel sync and unified operations
#### Objective
Provide a unified view across WooCommerce and Square as two sales channels, with consistent product catalog, pricing, and order visibility.
#### Key principle
The sync engine is event-driven where possible (webhooks) and poll-based as fallback. The app is the source of truth for catalog data; channels are synchronized outward.
#### Branches
- `feat/unified-catalog-sync`
- `feat/unified-order-view`
- `feat/webhook-integration`
#### Stage 13A — Unified catalog sync
##### Goal
Synchronize the product catalog bidirectionally between WooCommerce and Square, with the app as the authoritative source.
##### Requirements
- Create `CatalogSyncService` orchestrating WooCommerce ↔ app ↔ Square product sync
- Product changes in the app push to both channels
- Product changes detected from channels pull into the app (with conflict detection)
- Handle field mapping differences between platforms (e.g., WooCommerce categories vs. Square categories)
- Handle price sync across channels (same price or channel-specific pricing)
- Create `SyncDashboard` widget showing last sync time, pending changes, errors per channel
- Tests for sync service, conflict detection, and field mapping
#### Stage 13B — Unified order view
##### Goal
Aggregate orders from all channels (WooCommerce online, Square in-person, custom orders) into a single order management interface.
##### Requirements
- Add `OrderChannel` enum: `woocommerce`, `square`, `manual`
- Extend `Order` model with `channel` field
- Create `UnifiedOrdersController` that merges orders from all repositories
- Create unified orders page showing all orders with channel indicator and filters
- Order detail page shows channel-specific information
- Tests for unified controller and merged order display
#### Stage 13C — Webhook integration (stretch)
##### Goal
Set up real-time change detection from WooCommerce and Square via webhooks.
##### Requirements
- Define `WebhookHandler` endpoints for WooCommerce webhooks (order created, product updated, stock changed)
- Define `WebhookHandler` endpoints for Square webhooks (payment completed, inventory changed)
- Requires a lightweight backend/proxy (n8n workflow or serverless function) to receive webhooks and forward to the app
- Alternatively: implement polling with configurable intervals as interim solution
- Tests for webhook payload parsing and event routing
---
### Stage 14 — Offline capability and field operations
#### Objective
Make the mobile app usable at markets with poor or no network connectivity.
#### Key principle
Offline-first for critical market operations (viewing catalog, recording sales, capturing custom orders). Sync when connectivity is available.
#### Branches
- `feat/offline-data-cache`
- `feat/offline-sales-queue`
- `feat/barcode-scanning`
#### Stage 14A — Offline data cache
##### Goal
Cache product catalog and inventory data locally so the mobile app can display products and check stock without network.
##### Requirements
- Implement `LocalCache<T>` from `data` package (Stage 8B) using SQLite
- Cache product catalog, inventory items, and categories on successful fetch
- Detect offline state and serve from cache with "offline" indicator
- Cache invalidation strategy: time-based + manual refresh
- Pre-market sync: "Prepare for Market" action that forces a full cache refresh
- Tests for cache storage, retrieval, offline detection, and invalidation
#### Stage 14B — Offline sales queue
##### Goal
Queue sales transactions made offline and sync them when connectivity returns.
##### Requirements
- Implement `SyncQueue` from `data` package (Stage 8B)
- Queue offline sales with all order details (items, quantities, payment method, customer)
- Queue offline inventory adjustments
- Queue offline custom order captures
- Auto-sync on connectivity restoration with progress indicator
- Handle sync conflicts (e.g., item sold out in both channels during offline period)
- Manual sync trigger with error reporting
- Tests for queue operations, sync flow, and conflict handling
#### Stage 14C — Barcode/SKU scanning (stretch)
##### Goal
Enable quick product lookup via barcode scanning on the mobile app.
##### Requirements
- Integrate camera-based barcode scanning (using `mobile_scanner` or similar package)
- Scan → product lookup by SKU → add to cart or view details
- Support standard product barcodes and QR codes
- SKU label printing integration (stretch)
- Tests for scan → lookup flow
---
### Stage 15 — Reporting and business intelligence
#### Objective
Activate the `feature_finance` package to provide sales reporting, inventory valuation, and basic business analytics.
#### Key principle
Reports aggregate data from orders, inventory, and product repositories across all channels. Start with simple aggregations before adding charts or advanced analytics.
#### Branches
- `feat/sales-reporting`
- `feat/inventory-reporting`
- `feat/financial-dashboard`
#### Stage 15A — Sales reporting
##### Goal
Provide daily, weekly, and monthly sales summaries across all channels.
##### Requirements
- Sales by channel (WooCommerce, Square, custom orders)
- Sales by product/category
- Sales by time period with comparison to previous period
- Top-selling products
- Average order value
- Revenue tracking
- Exportable reports (CSV)
- Tests for aggregation logic
#### Stage 15B — Inventory valuation and reporting
##### Goal
Provide inventory value, turnover, and supply usage reports.
##### Requirements
- Current inventory value (cost and retail)
- Inventory turnover rate
- Low stock alerts summary
- Supply usage history
- Reorder recommendations based on usage trends
- Tests for valuation calculations
#### Stage 15C — Financial dashboard
##### Goal
Create a unified financial dashboard combining sales, costs, and margins.
##### Requirements
- Revenue vs. cost of goods
- Gross margin by product and category
- Market event profitability (sales at specific markets)
- Period-over-period trends
- Wire into existing dashboard page as additional summary cards
- Tests for dashboard aggregations
---
### Stage 16 — Production readiness
#### Objective
Harden the platform for production deployment beyond a single operator.
#### Branches
- `feat/error-tracking`
- `feat/secure-deployment`
#### Stage 16A — Error tracking and observability
##### Goal
Add crash reporting, error tracking, and basic usage analytics.
##### Requirements
- Integrate lightweight crash reporting (e.g., Sentry)
- Add structured logging for API calls, sync operations, and errors
- Add basic usage analytics (feature usage frequency, sync success rates)
- Add health check dashboard showing integration status per channel
#### Stage 16B — Secure deployment configuration
##### Goal
Move beyond `--dart-define` for credential management in production.
##### Requirements
- Secure credential storage on device (via `auth` package Stage 8C)
- First-run setup wizard for entering API credentials
- Connection testing UI (verify WooCommerce and Square connectivity)
- Environment-specific configuration (dev/staging/production)
---
## Suggested improvements (identified from codebase analysis)
This section captures structural improvements, coverage gaps, and maturity enhancements identified through codebase analysis against the architecture documentation and current implementation state. Items here are candidates for future stages or can be woven into existing stages as appropriate.
### 1. Stub package activation roadmap
The following packages exist as scaffolded stubs with no implementation. Each needs an activation plan aligned to architecture documentation:
| Package | Architecture Reference | Priority | Notes |
| ----------------- | --------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `auth` | Enterprise Identity & Access Architecture | High | No auth layer exists; all access is currently uncontrolled. Required before any multi-user or production deployment. |
| `data` | Enterprise Data Architecture | Medium | Shared data abstractions/caching could reduce duplication across feature repositories. |
| `integrations` | Enterprise Integration & Orchestration Architecture | Medium | Shared integration contracts could formalize API client patterns currently embedded in `feature_wordpress`. |
| `feature_finance` | Financial Analysis Components | Low | Architecture docs exist but no implementation. Defer until core WordPress/Inventory workflows mature. |
| `feature_mrp` | Craft Manufacturing / MRP Components | Low | Architecture docs exist but no implementation. Defer until inventory workflows mature. |
| `feature_social` | Social Media Management Components | Low | Architecture docs exist but no implementation. Defer until core platform stabilizes. |
**Recommendation:** Addressed in **Stage 8 — Infrastructure package activation**. Auth, data, and integrations are activated before expanding into new feature domains.
### ~~2. Design system expansion~~ ✅ RESOLVED
> Addressed in **Stage 4A** (Design system expansion and shared widget migration), merged 2026-05-22.
> All previously identified gaps have been resolved:
>
> - ✅ Shared typography scale → `KcTypography` with full Material 3 hierarchy and `applyKcTypography()` helper
> - ✅ Responsive layout utilities → `KcBreakpoints` with compact/medium/expanded/large queries and grid column helper
> - ✅ Shared empty state, loading state, error state patterns → `KcEmptyState`, `KcLoadingState`, `KcErrorState`
> - ✅ Shell widgets migrated → `EmptyStatePanel`, `SectionHeader`, `SummaryCard` moved from `kell_web` to `design_system` as `KcEmptyState`, `KcSectionHeader`, `KcSummaryCard`; backward-compatible typedefs retained in `kell_web`
>
> The `design_system` package now contains: theme (`KcColors`, `KcSpacing`, `KcTheme`), typography (`KcTypography`), layout (`KcBreakpoints`), and 7 widgets (`KcCard`, `KcStatusChip`, `KcEmptyState`, `KcSectionHeader`, `KcSummaryCard`, `KcLoadingState`, `KcErrorState`). 41 tests, 100% line coverage.
>
> **Remaining gap:** No shared button/action component library. This can be addressed in a future stage as needed.
### ~~3. Cross-platform shell composition strategy~~ ✅ RESOLVED
> Addressed in **Stage 4B** (Cross-platform shell composition strategy), merged `feat/shared-composition-pattern` → `main` at `0a0abc2` (2026-05-22).
> Shared composition abstractions extracted into `core` package: `KcAppConfig`, `KcAppEnvironment`, `KcAppServices` (abstract), `KcServiceFactory<T>`, `KcBootstrap`, `KcAppScope<T>`. `kell_web` updated to delegate to shared types via backward-compatible typedefs. Contract for new app targets (including `kell_mobile`) documented in `kell_creations_apps/docs/composition-strategy.md`. 20 core tests passing. Analyze clean.
### ~~4. CI/CD for Flutter applications~~ ✅ RESOLVED
> Addressed in **Stage 4C** (Flutter CI/CD pipeline), merged `feat/flutter-cicd` → `main` at `6a6323e` (2026-05-22).
> Two Forgejo Actions workflows established: `flutter-analyze.yml` (runs `dart analyze --fatal-infos` on all 8 packages/apps) and `flutter-test.yml` (runs `flutter test` per package with aggregate summary table). Workflows trigger on PRs to main and all non-main branch pushes. Local CI helper scripts added to `tools/`.
>
> **Remaining gap:** Flutter build validation (web + Android) is not yet automated in CI. This can be added as Android work progresses in Stage 5.
### 5. ~~Test coverage visibility and quality gates~~ ✅ PARTIALLY RESOLVED
> Automated test count reporting and line coverage measurement now addressed in Stage 4D (test coverage visibility). CI workflow produces per-package pass/fail counts and coverage percentages. Baseline documented. Minimum threshold enforcement and trend tracking remain future enhancements.
### ~~6. Build execution tracker synchronization~~ ✅ RESOLVED
> The `build_execution_tracker.md` has been fully updated through Stage 6A. All 13 merged branches are tracked with status, dates, files changed, test counts, and analysis results. Current status correctly reflects Stage 6A complete and next branch as `feat/android-mobile-ux-hardening` (Stage 6B). Last synchronized 2026-05-30.
### 7. Image and media management
Architecture documentation (`traceability-index.md` coverage gaps) identifies "Product image / media synchronization workflow" as a gap. The current publishing workflow handles text fields only.
**Recommendation:** Addressed in **Stage 9C — WooCommerce catalog expansion** which includes image upload, gallery management, and product image assignment via the WooCommerce Media API.
### 8. Error tracking and observability
No monitoring, error tracking, or analytics strategy exists for the Flutter applications. In production use:
- Runtime errors are invisible unless the operator sees them
- No crash reporting
- No usage analytics to guide prioritization
**Recommendation:** Addressed in **Stage 16A — Error tracking and observability**.
### 9. ~~Empty tools directory~~ ✅ RESOLVED
> Now populated with `run_all_tests.sh` and `README.md` as part of Stage 4C (Flutter CI/CD pipeline).
### ~~10. Missing feature parity documentation~~ ✅ PARTIALLY RESOLVED
> A **feature maturity matrix** has been added to this brief (see **Appendix: Feature maturity matrix** at the end of this document). It maps all 12 packages across domain, application, data (fake/real), presentation, test count, and maturity level. Added 2026-05-22 during full project analysis.
>
> **Remaining gap:** The matrix does not yet map architecture documentation aspirations to implementation status per feature (e.g., which architecture-described capabilities exist vs. are missing within each feature package). This can be expanded as feature packages mature.
### 11. Policy register CSVs are empty
The policy repository has 2 active governance documents (`KC-POL-GOV-001`, `KC-PRO-GOV-001`), but the register CSVs (`policy-register.csv`, `document-control-log.csv`, `review-calendar.csv`) contain headers only with no data rows. This means the controlled document lifecycle described in the Document Control Policy is not being followed for the governance documents themselves.
**Recommendation:** Populate the register CSVs with entries for the 2 active governance documents. This should be done before any additional policies are created.
### 12. `feature_orders` package missing standard scaffolding
The `feature_orders` package is missing standard scaffolding files (`.gitignore`, `.metadata`, `CHANGELOG.md`, `LICENSE`, `README.md`) that are present in all other packages. This creates inconsistency across the monorepo.
**Recommendation:** Add the missing files to `feature_orders` to match the structure of other packages. This is a low-effort, high-consistency improvement.
### 13. Architecture documentation shows wrong diagram
The Enterprise Data Architecture documentation page (`docs/architecture/containers/enterprise-data-architecture.md`) was referencing the wrong SVG image (showing the enterprise services diagram instead of the data architecture diagram).
**Resolution:** ✅ Fixed 2026-05-22 during full project analysis. Image reference corrected to `enterprise-data-architecture.svg`.
### 14. Missing diagram source references in architecture docs
Three architecture documentation pages were missing the standard "Diagram Source" section pointing to their PlantUML file:
- `docs/architecture/system-landscape.md`
- `docs/architecture/containers/platform-containers.md`
- `docs/architecture/components/inventory.md`
**Resolution:** ✅ Fixed 2026-05-22 during full project analysis. Diagram source references added for consistency.
### 15. Empty documentation sections need initial content
The Standards, Integrations, and Brand documentation sections had placeholder-only index pages with no substantive content.
**Resolution:** ✅ Populated 2026-05-22 during full project analysis. Each section now includes current state assessment, recommendations, and actionable next steps.
### 16. ADR index needs retroactive entries
The Architecture Decision Record (ADR) index exists but contained no entries. Seven significant architecture decisions are already in effect across the platform.
**Resolution:** ✅ Populated 2026-05-22 during full project analysis. Seven candidate ADRs documented with status, context, decision, and consequences.
### 17. Square integration not represented in architecture
The architecture documentation (system landscape, integration architecture, deployment architecture) makes no mention of Square. Square needs to be added as an external system in the system landscape and as an integration target in the enterprise integration architecture.
**Recommendation:** Update architecture diagrams before or during Stage 10 (Square integration foundation):
- Add Square to `system-landscape.puml` as an external system
- Add Square to `enterprise-integration-orchestration-architecture.puml`
- Add Square to `context-kellcreations-platform.puml`
- Create a new dynamic workflow: `dynamic-market-sale-checkout.puml`
### 18. No multi-channel data model in architecture
The current architecture documents describe a single-channel model (WordPress/WooCommerce). The multi-channel reality (WooCommerce + Square) requires:
- A unified product ID mapping concept
- Cross-channel inventory reconciliation
- Multi-source order aggregation
- Channel-specific vs. channel-agnostic data separation
**Recommendation:** Add `enterprise-multi-channel-architecture.puml` capturing the channel adapter pattern, product ID mapping, sync engine, and conflict resolution strategy. This should be created during Stage 13 planning.
### 19. `feature_mrp` activation alignment
The `feature_mrp` (Craft Manufacturing/MRP) package is architecturally described but stubbed. Custom orders (Stage 11) and supplies tracking (Stage 12B) together provide the foundation for basic manufacturing planning. The MRP package should be evaluated for activation after Stage 12 to determine if its scope is already covered by custom orders + inventory or if it adds distinct value (e.g., production scheduling, work orders, bill of materials).
**Recommendation:** Re-evaluate `feature_mrp` scope after Stage 12 completion. It may be partially or fully absorbed by custom order fulfillment and supplies tracking.
---
## Required development workflow for every slice
For every branch/stage:
1. Start from latest `main`.
2. Inspect first.
3. Write a brief inspection report.
4. Propose the smallest implementation plan.
5. Implement only the current slice.
6. Run targeted tests.
7. Run `flutter analyze` or `dart analyze` as appropriate.
8. Summarize changed files and validation results.
9. Open PR into `main`.
10. Merge only after clean review and validation.
11. **Update this brief and the build execution tracker** after merge.
---
## Standard Cline operating prompt
Use this at the start of any new slice:
```text
Continue the Kell Creations Flutter operations platform workstream from current main.
Read docs/development/master_development_brief.md first and follow it as the authoritative planning document.
Constraints:
- Preserve strict package boundaries.
- Fake repositories remain in feature packages.
- Real integrations are incremental alongside fake ones.
- Runtime selection stays via --dart-define, not settings UI.
- No credentials hardcoded or committed.
- Do not broaden into generic product editing prematurely.
- Keep WooCommerce details inside the WP repository layer.
- Keep Square details inside a dedicated Square integration layer.
- Multi-channel sync contracts before implementations.
- Use small, reviewable steps only.
- Work is being driven through Cline in Windows 11 VS Code.
Working rules:
1. Inspect first. Do not edit immediately.
2. Summarize current relevant state from main.
3. Propose the smallest implementation plan for the requested slice.
4. Implement only that slice.
5. Add/update focused tests.
6. Run validation.
7. Report changed files and validation results.
8. Update master_development_brief.md and build_execution_tracker.md after merge.
```
---
## Appendix A: Feature maturity matrix
| Package | Domain Layer | Application Layer | Data (Fake) | Data (Real) | Presentation | Tests | Maturity |
| ------------------- | ------------ | ----------------- | ------------ | -------------- | -------------------------------------------------- | ------- | -------------------- |
| `feature_wordpress` | ✅ Complete | ✅ Complete | ✅ Complete | ✅ WooCommerce | ✅ Complete | 294 | **Production-ready** |
| `feature_inventory` | ⚠️ Read-only | ⚠️ Read-only | ⚠️ Read-only | ❌ None | ⚠️ Read-only | Minimal | **Fake-only MVP** |
| `feature_orders` | ⚠️ Read-only | ⚠️ Read-only | ⚠️ Read-only | ❌ None | ⚠️ Read-only | Some | **Fake-only MVP** |
| `feature_policy` | ✅ Complete | ✅ Complete | ✅ Complete | ❌ None | ✅ Complete | Minimal | **Fake-only MVP** |
| `feature_finance` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** |
| `feature_mrp` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** |
| `feature_social` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** |
| `auth` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | N/A | None | **Scaffolded only** |
| `data` | ❌ Stub | N/A | N/A | ❌ None | N/A | None | **Scaffolded only** |
| `integrations` | ❌ Stub | N/A | N/A | ❌ None | N/A | None | **Scaffolded only** |
| `design_system` | N/A | N/A | N/A | N/A | ✅ Expanded (theme, typography, layout, 7 widgets) | 41 | **Foundation ready** |
| `core` | ✅ Partial | ✅ Composition | N/A | N/A | N/A | 20 | **Foundation ready** |
### Key changes from previous matrix
- `feature_inventory` and `feature_orders` downgraded from "Complete" to "⚠️ Read-only" in domain/application/data/presentation to reflect that they have no write operations — a critical gap for the target platform vision.
- Feature maturity labels clarified: "Fake-only MVP" packages that are also read-only now carry the ⚠️ indicator.
---
## Appendix B: Integration landscape
| Integration | Package/Location | Protocol | Current Status | Target Stage |
| -------------------- | ------------------- | ------------- | ------------------- | ------------ |
| WooCommerce Products | `feature_wordpress` | REST API v3 | ✅ Production-ready | — |
| WooCommerce Orders | `feature_wordpress` | REST API v3 | ❌ Not implemented | Stage 9A |
| WooCommerce Stock | `feature_wordpress` | REST API v3 | ❌ Not implemented | Stage 9B |
| WooCommerce Catalog | `feature_wordpress` | REST API v3 | ⚠️ Read + edit only | Stage 9C |
| WooCommerce Media | `feature_wordpress` | REST API v3 | ❌ Not implemented | Stage 9C |
| Square Catalog | (new) | Square API v2 | ❌ Not implemented | Stage 10A/B |
| Square Inventory | (new) | Square API v2 | ❌ Not implemented | Stage 10B |
| Square Payments | (new) | Mobile SDK | ❌ Not implemented | Stage 10C |
| Square Orders | (new) | Square API v2 | ❌ Not implemented | Stage 10A |
| Facebook API | `feature_social` | Graph API | ❌ Stub only | Deferred |
| Instagram API | `feature_social` | Graph API | ❌ Stub only | Deferred |
| X (Twitter) API | `feature_social` | REST API v2 | ❌ Stub only | Deferred |
| n8n Workflows | (external) | Webhooks/REST | ❌ Not implemented | Stage 13C |
| Mail Server | (external) | SMTP | ❌ Not implemented | Deferred |
---
## Appendix C: Runtime configuration keys
### Current
| Key | Description | Default | Used By |
| ----------------------- | ------------------------------------ | ------- | ------- |
| `KC_ENV` | `fake`, `wordpress` | `fake` | All |
| `KC_WC_SITE_URL` | WordPress site URL | (empty) | WP mode |
| `KC_WC_CONSUMER_KEY` | WooCommerce REST API consumer key | (empty) | WP mode |
| `KC_WC_CONSUMER_SECRET` | WooCommerce REST API consumer secret | (empty) | WP mode |
### Planned (Stage 8+)
| Key | Description | Default | Target Stage |
| ------------------------ | ------------------------- | --------- | ------------ |
| `KC_SQUARE_ACCESS_TOKEN` | Square API access token | (empty) | Stage 10A |
| `KC_SQUARE_LOCATION_ID` | Square location ID | (empty) | Stage 10A |
| `KC_SQUARE_ENVIRONMENT` | `sandbox` or `production` | `sandbox` | Stage 10A |
### Planned `KC_ENV` values
| Value | Description | Target Stage |
| ----------- | -------------------------------- | ------------ |
| `fake` | All fake repositories (current) | — |
| `wordpress` | WooCommerce real + others fake | — |
| `square` | Square real + others fake | Stage 10A |
| `multi` | Both WooCommerce and Square real | Stage 13A |
---
## Appendix D: Stage dependency graph
```
Stages 1–6 (COMPLETE/IN PROGRESS) — Foundation
│
├── Stage 7 — Bulk actions (independent, can proceed in parallel)
│
└── Stage 8 — Infrastructure activation (PREREQUISITE for 9–16)
│
├── Stage 9 — WooCommerce expansion
│ │
│ ├── Stage 11 — Custom orders (depends on 9A orders API)
│ │
│ └── Stage 12 — Inventory management (depends on 9B stock sync)
│ │
│ └── Stage 12C — Multi-channel inventory sync (depends on 10B)
│
├── Stage 10 — Square integration
│ │
│ └── Stage 10C — Mobile POS (depends on 10A + 10B)
│
├── Stage 13 — Multi-channel sync (depends on 9 + 10 + 12C)
│
├── Stage 14 — Offline capability (depends on 8B data layer)
│
├── Stage 15 — Reporting (depends on 9A + 10 + 12)
│
└── Stage 16 — Production readiness (depends on 8C auth)
```
Reference in New Issue View Git Blame Copy Permalink