92 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

Online Catalog Management — Create, edit, publish, and manage products on the WooCommerce store from both web and mobile.
Market Sales (Mobile POS) — Use the Android app at craft markets/shows to browse the catalog, process sales via Square, and capture customer information.
Custom Orders — Accept and track custom/made-to-order requests from both online and in-person channels, with specifications, deposits, and fulfillment tracking.
Supplies & Inventory — Track raw materials (supplies) and finished goods (inventory), with stock levels synchronized bidirectionally across WooCommerce and Square.
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 foundation activated (Stage 8C complete); KcUser/KcUserRole domain models, AuthState sealed hierarchy, AuthService contract, AuthException, CredentialStore/CredentialKeys contract, InMemoryCredentialStore, FakeAuthService implemented; KcAppEnvironment.square added to core
- integrations — ✅ integration contracts activated (Stage 8A complete); ApiClient, ApiException, RetryPolicy, RateLimiter, IntegrationHealthCheck, WebhookHandler, ChannelAdapter contracts defined; WooCommerceApiClient and WooCommerceApiException refactored to implement shared contracts
- data — ✅ shared data layer contracts activated (Stage 8B complete); LocalCache<T>, SyncQueue, ConflictResolver<T>, ChangeTracker<T>, DataMapper<TLocal, TRemote> contracts defined with in-memory implementations
- 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).
✅ Android app shell and bootstrap landed (Stage 5A complete — merged feat/android-app-shell → main, 2026-05-28).
✅ Android publishing surface landed (Stage 5B complete — merged feat/android-publishing-surface → main, 2026-05-29). Stage 5 complete.
✅ Android feedback and action polish landed (Stage 6A complete — merged feat/android-feedback-polish → main, 2026-05-29).
✅ Android mobile workflow hardening landed (Stage 6B complete — merged feat/android-mobile-ux-hardening → main, 2026-05-30).
✅ Bulk move-to-draft action landed (Stage 7A complete — merged feat/bulk-status-actions → main, 2026-05-30).
✅ Inventory domain expansion landed (Stage 5A-inv complete — merged feat/inventory-domain-expansion → main, 2026-07-10).
✅ Inventory page UI landed (Stage 5B-inv complete — merged feat/inventory-page-ui → main, 2026-07-10).
✅ Orders domain expansion landed (Stage 5C complete — merged feat/orders-domain → main, 2026-07-10).
✅ Orders page UI landed (Stage 5D complete — merged feat/orders-page-ui → main, 2026-07-10).
✅ Orders mobile surface landed (Stage 6B-orders complete — merged feat/orders-mobile-surface → main, 2026-07-10).
✅ Inventory mobile surface landed (Stage 6C complete — merged feat/inventory-mobile-surface → main, 2026-07-10). Stage 6 complete.
✅ Bulk publish and bulk submit-for-review actions landed (Stage 7B complete — merged feat/bulk-operator-workflows → main, 2026-07-11). Stage 7 complete.
✅ Integration abstractions activated (Stage 8A complete — merged feat/integrations-contracts → main, 2026-07-11).
✅ Shared data layer contracts activated (Stage 8B complete — merged feat/data-layer-contracts → main, 2026-07-11).
✅ Authentication foundation activated (Stage 8C complete — merged feat/auth-foundation → main, 2026-07-11). Stage 8 complete.
✅ Square API client and authentication activated (Stage 10A complete — merged feat/square-api-client → main, 2026-07-19).
✅ Square catalog and inventory sync mappers + ProductIdMapping domain landed (Stage 10B complete — merged feat/square-catalog-sync → main, 2026-07-25).
✅ SquareCatalogRepository and SquareInventoryRepository landed (Stage 10C complete — merged feat/square-catalog-sync-repositories → main, 2026-07-25).
✅ SquareSyncController, AppServices.square()/multi(), MobileAppServices.square()/multi(), ID conflation fix, and KcBootstrap credential validation landed (Stage 10E complete — branch feat/square-catalog-sync-service-controller ready for merge, 2026-07-25).
✅ SquareSyncStatusPanel, IntegrationsPage, MobileIntegrationsPage, and squareSyncController wired into both shells landed (Stage 10F complete — branch feat/square-sync-ui ready for merge, 2026-07-25).

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`

Last verified: 2026-07-25 — Comprehensive State Audit (chore/audit-state-sync)

dart analyze --fatal-infos clean across all 11 packages/apps
All packages passing
latest reported count for core: 24/24 passed
latest reported count for design_system: 41/41 passed
latest reported count for feature_inventory: 167/167 passed ← +35 new (Stage 10C)
latest reported count for feature_orders: 234/234 passed ← +36 new (Stage 10C POS)
latest reported count for feature_wordpress: 545/545 passed
latest reported count for kell_web: 52/52 passed
latest reported count for integrations: 123/123 passed
latest reported count for data: 63/63 passed
latest reported count for auth: 42/42 passed
latest reported count for kell_mobile: 72/72 passed ← +18 new (Stage 10C POS)
total: 1,373/1,373 passed (+45 new from Stage 10C POS branch feat/square-mobile-pos)
active branch: feat/square-mobile-pos (Stage 10C) — ready for merge

Note: Stage 10D (feat/square-catalog-sync-service) is complete and ready for merge. The feature_wordpress count of 506/506 reflects the post-merge state. The main baseline currently shows 475/475 for feature_wordpress until Stage 10D is merged.

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.

Stage 10D — complete (2026-07-25)

feat/square-catalog-sync-service — SquareCatalogSyncService + SquareSyncResult + SyncError + InventorySyncAdapter

Delivered:

SquareCatalogSyncService in feature_wordpress/lib/src/application/square_catalog_sync_service.dart
SyncError value object (itemId, message, ==/hashCode/toString())
SquareSyncResult value object (catalogSynced, inventorySynced, catalogFailed, inventoryFailed, errors, totalProcessed, allSucceeded, merge())
InventorySyncAdapter abstract contract (syncItem(itemId, remoteQuantity) → Future<bool>)
syncCatalog() — fetches products via ProductPublishingRepository, reconciles ProductIdMappingRepository, per-item error capture
syncInventory() — iterates mappings with squareVariationId, delegates to InventorySyncAdapter, per-item error capture
syncAll() — runs catalog then inventory, merges results
Exported from feature_wordpress.dart barrel
31 new tests (506/506 feature_wordpress total, 167/167 feature_inventory — all passing, analyze clean)

Stage 10E — complete (2026-07-25)

feat/square-catalog-sync-service-controller — SquareSyncController + AppServices.square()/multi() + ID conflation fix + KcBootstrap credential validation

Delivered:

SquareSyncController ChangeNotifier in feature_wordpress/lib/src/application/square_sync_controller.dart
AppServices.square() and AppServices.multi() factory constructors (P1.1)
MobileAppServices.square() and MobileAppServices.multi() factory constructors (P1.1)
KcBootstrap Square credential validation with fallback to fake mode (P1.5)
ProductDraft.squareCatalogObjectId nullable field; ID conflation bug fixed in syncCatalog() (P1.2)
18 new SquareSyncController tests + 10 new composition tests per app (834 total across tested packages)
Analyze clean

Stage 10F — complete (2026-07-25)

feat/square-sync-ui — SquareSyncStatusPanel + IntegrationsPage + MobileIntegrationsPage

Delivered:

SquareSyncStatusPanel StatefulWidget in feature_wordpress/lib/src/presentation/widgets/square_sync_status_panel.dart
IntegrationsPage in kell_web/lib/pages/integrations_page.dart — shows panel when squareSyncController is non-null, placeholder otherwise
MobileIntegrationsPage in kell_mobile/lib/pages/mobile_integrations_page.dart — mirrors web layout for mobile
AppRoute.integrations wired in kell_web routing
More tab in kell_mobile shell switched from placeholder to MobileIntegrationsPage
8 new panel tests + 4 integrations page tests per app + 5 composition tests per app (651 total across tested packages)
Analyze clean

Stage 10C — complete (2026-07-25)

feat/square-mobile-pos — Square Mobile POS / Checkout

Delivered:

PaymentMethod enum (cash, card) with label and iconHint extensions in feature_orders
PaymentResult immutable value object (transactionId, amountCents, method, completedAt, receiptUrl, amountFormatted) in feature_orders
PaymentService abstract contract + PaymentException in feature_orders
CheckoutController (ChangeNotifier) with sealed CheckoutState hierarchy (idle/processing/success/error) and CartEntry in feature_orders
FakePaymentService (always succeeds, counter-based IDs) in feature_orders
MobileCheckoutPage — product selection → cart → payment → receipt flow; Cash + Card buttons; confirmation dialog; haptic feedback in kell_mobile
Sales tab (index 4) added to MobileShell bottom navigation (6 tabs total)
paymentService + checkoutCatalogue fields wired into all MobileAppServices factory constructors
45 new tests (36 feature_orders + 18 kell_mobile − 9 pre-existing kell_mobile); 1373 total across all packages
Analyze clean

Next recommended branch

feat/custom-order-domain — Stage 11A: Custom order domain and data

Add OrderType enum, CustomOrderSpec, DepositInfo value objects
Extend Order model and OrdersRepository contract
Implement in FakeOrdersRepository and WooCommerceOrdersRepository
Tests for all new domain models and repository methods

Comprehensive State Audit (2026-07-25)

Audit reference: PROJECT_STATE_AUDIT.md — Kell Creations Operations Platform Comprehensive Code Audit
Audit date: 2026-07-25
Baseline: Stage 10C complete (feat/square-catalog-sync-repositories → main)
Total tests verified: 1,015 / 1,015 passing; dart analyze --fatal-infos clean across all 11 packages/apps

Platform scorecard (as of 2026-07-25)

Subsystem	Status	Completeness	Blocking Issues
`core`	✅ COMPLETE	95%	Square/multi bootstrap validation missing
`design_system`	✅ COMPLETE	100%	None
`auth`	⚠️ PARTIAL	40%	No production impl, not wired into app
`data`	⚠️ PARTIAL	35%	No SQLite impl, not wired into any feature
`integrations`	⚠️ PARTIAL	70%	RetryPolicy/RateLimiter not wired; ChannelAdapter not implemented
`feature_wordpress`	✅ COMPLETE	95%	SquareSyncController (Stage 10E) pending
`feature_inventory`	⚠️ PARTIAL	65%	No unified sync engine; ItemType/Supplier/PurchaseOrder missing
`feature_orders`	⚠️ PARTIAL	70%	Custom orders missing; WC/Square repos not wired into AppServices
`feature_policy`	⚠️ PARTIAL	50%	Fake-only; minimal tests; policy register empty
`feature_finance`	❌ MISSING	0%	Pure stub
`feature_mrp`	❌ MISSING	0%	Pure stub
`feature_social`	❌ MISSING	0%	Pure stub
`kell_web`	⚠️ PARTIAL	75%	Finance/Integrations placeholder; no square/multi factory
`kell_mobile`	⚠️ PARTIAL	70%	No POS/checkout; no square/multi factory
Architecture docs	⚠️ PARTIAL	80%	Square not represented; multi-channel model missing
Policy register	❌ MISSING	10%	All CSVs empty
CI/CD	✅ COMPLETE	85%	No coverage thresholds enforced

Audit engineering backlog

The full backlog is captured in PROJECT_STATE_AUDIT.md §4. The prioritized summary follows.

Phase 1 — High-priority / blocking (core fixes and missing execution paths)

These items block correct runtime behavior or represent data integrity risks. All Phase 1 items should be addressed in feat/square-catalog-sync-service-controller (Stage 10E) or immediately after.

ID	Item	Branch
P1.1	Wire `square` and `multi` factory constructors into `AppServices`/`MobileAppServices`	`feat/square-catalog-sync-service-controller`
P1.2	Fix `SquareCatalogSyncService.syncCatalog()` ID conflation (`product.id` vs Square ID)	`feat/square-catalog-sync-service-controller`
P1.3	Merge Stage 10D (`feat/square-catalog-sync-service`) → `main`	Immediate — prerequisite for Stage 10E
P1.4	`SquareSyncController` (Stage 10E) — UI trigger for `SquareCatalogSyncService`	`feat/square-catalog-sync-service-controller`
P1.5	Add `hasSquareConfig` credential check in `KcBootstrap` for `square`/`multi` modes	`feat/square-catalog-sync-service-controller`

Phase 2 — Feature completion and integration

These items complete planned stages and wire existing contracts into production paths.

ID	Item	Target Stage
P2.1	Square Mobile POS / Checkout (`MobileCheckoutPage`, Square Reader SDK)	Stage 10C
P2.2	Custom Orders Workflow (`OrderType`, `CustomOrderSpec`, `DepositInfo`, UI)	Stage 11
P2.3	Inventory Write Ops & Supplies Tracking (`ItemType`, `Supplier`, `PurchaseOrder`)	Stage 12A/B
P2.4	Multi-Channel Inventory Sync Engine (`InventorySyncEngine`, `ChannelStockMapping`)	Stage 12C
P2.5	Wire `WooCommerceOrdersRepository` into `AppServices.wordpress()`	Stage 10E or standalone
P2.6	Wire `WooCommerceInventoryRepository` into `AppServices.wordpress()`	Stage 10E or standalone
P2.7	Unified Order View (`OrderChannel`, `UnifiedOrdersController`)	Stage 13B
P2.8	Offline Data Cache & Sales Queue (SQLite `LocalCache`, `SyncQueue`)	Stage 14
P2.9	`feature_finance` Activation (sales reporting, inventory valuation)	Stage 15
P2.10	Populate Policy Register CSVs (2 active governance documents)	Immediate — no dependencies

Phase 3 — Defensive engineering, logging, and test harness expansion

These items harden the platform for production deployment.

ID	Item	Target Stage
P3.1	Wire `RetryPolicy` and `RateLimiter` into `SquareApiClient` and `WooCommerceApiClient`	Stage 16A
P3.2	Implement `SecureCredentialStore` (`flutter_secure_storage`)	Stage 16B
P3.3	Auth guard wired into app shell (login screen, route guard)	Stage 16B
P3.4	Structured logging infrastructure (`package:logging`, replace silent `catch (_) {}`)	Stage 16A
P3.5	Crash reporting integration (Sentry or Firebase Crashlytics)	Stage 16A
P3.6	Expand `feature_policy` test coverage (controller, widget tests; target >80%)	Standalone
P3.7	Expand `kell_web` test coverage from 54.1% (routing, shell, factory tests; target >75%)	Standalone
P3.8	Add `feature_orders` standard scaffolding files (`.gitignore`, `CHANGELOG.md`, etc.)	Standalone
P3.9	Update architecture diagrams for Square and multi-channel	Stage 13 planning
P3.10	Implement `ChannelAdapter` for WooCommerce and Square	Stage 13A
P3.11	Enforce minimum test coverage thresholds in CI (e.g., 75% floor)	Standalone
P3.12	Evaluate and activate `feature_mrp` after Stage 12 completion	Post-Stage 12

Key technical debt findings

AppServices/MobileAppServices have no square() or multi() factory — KC_ENV=square silently falls to fake mode (CRITICAL)
SquareCatalogSyncService ID conflation — product.id used as Square catalog object ID; incorrect in mixed-source scenarios (HIGH)
RetryPolicy/RateLimiter defined but not wired — all API calls are single-attempt with no retry or rate limiting (HIGH)
auth package not imported by any app or feature — app is completely unguarded (HIGH)
data package not imported by any feature — all data is in-memory only; no persistence path (MEDIUM)
InventoryController not wired to InventorySyncService — sync cannot be triggered from UI (MEDIUM)
feature_policy has only a smoke test — no controller or widget tests (MEDIUM)
kell_web at 54.1% line coverage — routing, shell, and navigation largely untested (MEDIUM)

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

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 ✅ COMPLETE

Merged feat/bulk-operator-workflows → main (2026-05-30). Enabled pendingReview status in WordPressProductMapper.toWooCommerceStatus() (maps to WooCommerce 'pending'). Added "Publish" and "Submit for Review" bulk action buttons to _MultiSelectBar with confirmation dialogs. Refactored bar layout from Row to Wrap for responsive overflow. 8 new tests added across mapper, controller, page, and repository test suites (319 total feature_wordpress tests passing). Stage 7 complete.

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 ✅ COMPLETE

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 getProductImages(productId), setProductImages(productId, mediaIds) to WooCommerceApiClient
✅ Extend ProductPublishingRepository: createProduct(), deleteProduct(), updateProductImages(), getCategories(), createCategory(), updateCategory(), deleteCategory(), getProductImages()
✅ Add ProductCategory domain model (id, name, slug, parentId, count) with copyWith, equality, toString
✅ Add ProductImage domain model (id, url, alt, position) with copyWith, equality
✅ Implement all new methods in FakeProductPublishingRepository (with seed categories)
✅ Implement all new methods in WordPressProductPublishingRepository
✅ Add use cases: CreateProduct, DeleteProduct, GetCategories, CreateCategory, UpdateProductImages
✅ Update barrel exports in feature_wordpress.dart
✅ Update test stubs in dashboard_controller_test.dart and product_publishing_page_test.dart
✅ 69 new tests in wc_catalog_expansion_test.dart covering domain models, fake repo, API client, real repo, and use cases
✅ Product creation UI — CreateProductDialog (web) and MobileCreateProductPage (mobile) with name, price, SKU, category dropdown, description, initial status (Stage 9D)
✅ Image management scaffolding — UpdateProductImages use case wired; full image picker UI deferred to Stage 10+
✅ Category management page — CategoryManagementPage with list, add, rename, delete, empty/loading/error states (Stage 9D)

Branch

feat/wc-catalog-expansion — merged to main

Stage 9D — Product creation UI and category management ✅ COMPLETE

Merged feat/wc-catalog-expansion-ui → main (2026-07-11). Added CreateProductDialog (web) — StatefulWidget with name (required), price (required), SKU, category dropdown, description, and initial-status SegmentedButton (Draft / Review); inline validation errors; CreateProductDialogResult value object; showCreateProductDialog() helper. Added CategoryManagementPage with category list, add-category FAB, inline rename, delete with confirmation dialog, empty/loading/error states. Extended ProductPublishingController with CreateProductResult sealed class, createNewProduct() (calls CreateProduct use case, auto-selects new product, reloads), and fetchCategories(). Wired "New Product" button and "Manage Categories" link into ProductPublishingPage toolbar. Added MobileCreateProductPage full-screen form for mobile. Added "New Product" FAB to MobilePublishingPage. Expanded barrel exports. 34 new tests added (13 dialog, 14 category page, 7 controller) — 424 total feature_wordpress tests passing. Analyze clean.

Branch

feat/wc-catalog-expansion-ui — merged to main

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 ✅ COMPLETE

Merged feat/square-api-client → main (2026-07-19). Added SquareApiClient in integrations package implementing ApiClient contract; sandbox() and production() factory constructors; full lifecycle (initialize(), dispose(), isReady, execute<T>()); Catalog API (listCatalogItems() with cursor pagination, getCatalogItem(), upsertCatalogItem(), deleteCatalogItem()); Inventory API (getInventoryCount(), batchChangeInventory()); Orders API (createOrder(), listOrders(), getOrder()); Payments API (createPayment(), getPayment()); Bearer token + Square-Version headers on all requests. Added SquareApiException extending ApiException. Added KC_SQUARE_ACCESS_TOKEN, KC_SQUARE_LOCATION_ID, KC_SQUARE_ENVIRONMENT dart-define key constants to KcAppConfig. Added KcAppEnvironment.multi value. 50 new tests in square_api_client_test.dart — 88 total integrations tests. 24 total core tests. Analyze clean across all 11 packages/apps.

Branch

feat/square-api-client — merged to main

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:

Start from latest main.
Inspect first.
Write a brief inspection report.
Propose the smallest implementation plan.
Implement only the current slice.
Run targeted tests.
Run flutter analyze or dart analyze as appropriate.
Summarize changed files and validation results.
Open PR into main.
Merge only after clean review and validation.
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

Last updated: 2026-07-25 — Comprehensive State Audit

Package	Domain Layer	Application Layer	Data (Fake)	Data (Real)	Presentation	Tests	Maturity
`feature_wordpress`	✅ Complete	✅ Complete	✅ Complete	✅ WooCommerce + Square	✅ Complete	506	Production-ready (95%)
`feature_inventory`	✅ Complete	✅ Write ops	✅ Complete	✅ WooCommerce + Square	✅ Complete	167	Partial (65%)
`feature_orders`	✅ Complete	✅ Write ops	✅ Complete	✅ WooCommerce	✅ Complete	198	Partial (70%)
`feature_policy`	✅ Complete	✅ Complete	✅ Complete	❌ None	✅ Complete	~5	Fake-only (50%)
`feature_finance`	❌ Stub	❌ Stub	❌ Stub	❌ None	❌ Stub	1	Scaffolded only (0%)
`feature_mrp`	❌ Stub	❌ Stub	❌ Stub	❌ None	❌ Stub	1	Scaffolded only (0%)
`feature_social`	❌ Stub	❌ Stub	❌ Stub	❌ None	❌ Stub	1	Scaffolded only (0%)
`auth`	✅ Complete	✅ FakeAuthService	✅ InMemory	❌ None (SecureStore TBD)	N/A	42	Foundation ready (40%)
`data`	✅ Contracts	N/A	✅ InMemory	❌ None (SQLite TBD)	N/A	63	Foundation ready (35%)
`integrations`	✅ Contracts	N/A	N/A	✅ WooCommerce + Square	N/A	123	Partial (70%)
`design_system`	N/A	N/A	N/A	N/A	✅ Expanded (theme, typography, layout, 7 widgets)	41	Complete (100%)
`core`	✅ Complete	✅ Composition	N/A	N/A	N/A	24	Complete (95%)
`kell_web`	N/A	✅ AppServices (wp only)	N/A	N/A	✅ 7 routes (2 placeholder)	24	Partial (75%)
`kell_mobile`	N/A	✅ MobileAppServices	N/A	N/A	✅ 5-tab shell (no POS)	26	Partial (70%)

Key changes from previous matrix (updated 2026-07-25)

feature_wordpress test count updated to 506 (Stage 10D, pending merge); real data layer now includes Square repositories.
feature_inventory and feature_orders upgraded from "Read-only" — write operations, real WooCommerce/Square repositories now complete.
integrations test count updated to 123; Square API client and mappers complete.
core test count updated to 24; kell_web and kell_mobile rows added.
Completeness percentages sourced from PROJECT_STATE_AUDIT.md §5 scorecard (2026-07-25).

Appendix B: Integration landscape

Last updated: 2026-07-25 — Comprehensive State Audit

Integration	Package/Location	Protocol	Current Status	Target Stage
WooCommerce Products	`feature_wordpress`	REST API v3	✅ Production-ready (full CRUD + categories + images)	—
WooCommerce Orders	`feature_orders`	REST API v3	✅ Repository complete; not wired into AppServices	Stage 9A ✅
WooCommerce Stock	`feature_inventory`	REST API v3	✅ Repository complete; not wired into AppServices	Stage 9B ✅
WooCommerce Catalog	`feature_wordpress`	REST API v3	✅ Full CRUD + categories + images	Stage 9C ✅
WooCommerce Media	`feature_wordpress`	REST API v3	⚠️ Use case wired; image picker UI deferred	Stage 10+
Square Catalog	`feature_wordpress`	Square API v2	✅ Repository complete; no UI trigger (Stage 10E next)	Stage 10B ✅
Square Inventory	`feature_inventory`	Square API v2	✅ Repository complete; not wired into AppServices	Stage 10B ✅
Square Payments	`kell_mobile`	Mobile SDK	❌ Not implemented	Stage 10C (P2.1)
Square Orders	`feature_orders`	Square API v2	❌ No SquareOrdersRepository exists	Stage 13B (P2.7)
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

Active Square keys (Stage 10A — live on `main`)

Key	Description	Default	Used By
`KC_SQUARE_ACCESS_TOKEN`	Square API access token	(empty)	Square mode
`KC_SQUARE_LOCATION_ID`	Square location ID	(empty)	Square mode
`KC_SQUARE_ENVIRONMENT`	`sandbox` or `production`	`sandbox`	Square mode

`KC_ENV` values

Value	Description	Status
`fake`	All fake repositories	✅ Active
`wordpress`	WooCommerce real + others fake	✅ Active
`square`	Square real + others fake	⚠️ Keys defined (Stage 10A); factory constructors missing (P1.1)
`multi`	Both WooCommerce and Square real	⚠️ Enum value defined; factory constructors missing (P1.1)

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)

92 KiB Raw Blame History Unescape Escape

Kell Creations Operations Platform — Master Development Brief

Recommended repo location

Purpose

Platform Vision

Core business workflows

Working model

Current confirmed baseline on main

Platform structure

Product publishing workflow already landed on main

Current narrow edit capabilities on main

Latest known validation state on main

Baseline test coverage (established 2026-05-22)

Stage 10D — complete (2026-07-25)

Stage 10E — complete (2026-07-25)

Stage 10F — complete (2026-07-25)

Stage 10C — complete (2026-07-25)

Next recommended branch

Comprehensive State Audit (2026-07-25)

Platform scorecard (as of 2026-07-25)

Audit engineering backlog

Phase 1 — High-priority / blocking (core fixes and missing execution paths)

Phase 2 — Feature completion and integration

Phase 3 — Defensive engineering, logging, and test harness expansion

Key technical debt findings

Senior Audit Report (2026-05-30)

Audit scope

Audit summary — strengths

Audit summary — critical gaps for target vision

Gap 1: No product creation capability

Gap 2: No image/media management

Gap 3: Orders are read-only with fake data

Gap 4: Inventory is read-only with fake data

Gap 5: Square integration is completely absent

Gap 6: No multi-channel sync engine

Gap 7: No authentication

Gap 8: No offline capability

Gap 9: WooCommerce integration is products-only

Gap 10: No financial/reporting capability

Audit recommendations

Non-negotiable architectural constraints

Development stages

Stage 1 — Web application completion: controlled product editing

Objective

Branching model

Stage 1A — Description-only product edit ✅ COMPLETE

Stage 1B — Category-only product edit ✅ COMPLETE

Stage 2 — Web application operational hardening

Objective

Branches

Stage 2A — Post-write consistency hardening ✅ COMPLETE

Stage 2B — Publishing workflow UX hardening ✅ COMPLETE

Stage 3 — Web application operator efficiency

Objective

Branches

Stage 3A — Multi-select groundwork (read/state only first) ✅ COMPLETE

Stage 3B — List efficiency improvements ✅ COMPLETE

Stage 4 — Platform foundations and cross-platform readiness

Objective

Key principle

Branches

Stage 4A — Design system expansion and shared widget migration ✅ COMPLETE

Stage 4B — Cross-platform shell composition strategy ✅ COMPLETE

Stage 4C — Flutter CI/CD pipeline ✅ COMPLETE

Stage 4D — Test coverage visibility ✅ COMPLETE

Stage 5 — Android application foundation

Objective

Key principle

Branches

Stage 5A — Android app shell and bootstrap ✅ COMPLETE

Stage 5B — Android publishing surface ✅ COMPLETE

Stage 6 — Android operational maturity

Objective

Branches

Stage 6A — Android feedback and action polish ✅ COMPLETE

Stage 6B — Android mobile workflow hardening ✅ COMPLETE

Stage 7 — Controlled bulk actions (only after groundwork)

Objective

Branches

Entry criteria ✅ ALL MET

92 KiB

Raw Blame History

Current confirmed baseline on `main`

Product publishing workflow already landed on `main`

Current narrow edit capabilities on `main`

Latest known validation state on `main`

Stage 8A — Integration abstractions (`integrations` package)

Stage 8B — Shared data layer (`data` package)

Stage 8C — Authentication foundation (`auth` package)