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

71 KiB
Raw Blame History

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 IconButtons 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:

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)