57 KiB
PROJECT_STATE_AUDIT.md
Kell Creations Operations Platform — Comprehensive Code Audit
Audit Date: 2026-07-25
Last Reconciled: 2026-09-25 (chore/state-reconciliation-flutter-347)
Auditor: Senior Software Engineering Review Board (Automated)
Baseline Commit: feat/square-catalog-sync-repositories → main (Stage 10C complete)
Current Branch Work: Stage 10D (SquareCatalogSyncService) — complete, pending merge
Total Tests (baseline): 1,015 / 1,015 passing
Static Analysis: dart analyze --fatal-infos — clean across all 11 packages/apps
Reconciliation notice (2026-09-25). Sections 1–4 below are preserved as the historical 2026-07-25 audit record and are not rewritten in place. Since that date Stages 10C (POS), 10D, 10E, 10F, 11A, and 16A have all merged to
main, so many "❌ Missing" findings in those sections are now closed. §5 has been re-baselined againstmainas of 2026-09-25 and is the authoritative scorecard. A duplicated copy of §5 (a bad append in an earlier edit) was removed on the same date.
1. Repository Architecture Overview
Monorepo Structure
kell_creations/
├── kell_creations_apps/
│ ├── apps/
│ │ ├── kell_web/ # Flutter Web app (Windows Desktop / Browser)
│ │ └── kell_mobile/ # Flutter Android app
│ ├── packages/
│ │ ├── core/ # Shared composition abstractions
│ │ ├── design_system/ # Shared UI components and theme
│ │ ├── auth/ # Authentication contracts + fake impl
│ │ ├── data/ # Data layer contracts + in-memory impls
│ │ ├── integrations/ # API client contracts + Square/WC clients
│ │ ├── feature_wordpress/ # Product catalog management (most mature)
│ │ ├── feature_inventory/ # Inventory management
│ │ ├── feature_orders/ # Order management
│ │ ├── feature_policy/ # Policy/governance compliance
│ │ ├── feature_finance/ # Financial reporting [STUB]
│ │ ├── feature_mrp/ # Manufacturing/MRP [STUB]
│ │ └── feature_social/ # Social media management [STUB]
│ └── tools/ # CI helper scripts
├── docs/ # MkDocs documentation site
├── architecture/ # PlantUML C4 diagrams (19 diagrams)
└── policies/ # Controlled policy document repository
Architectural Pattern
- Domain-Driven Design with strict package boundaries
- Repository pattern with fake/real runtime selection via
--dart-define - ChangeNotifier controllers for unidirectional state flow (no Riverpod yet)
- Shared composition pattern (
KcAppConfig,KcBootstrap,KcAppScope) across both app targets - Vertical slice discipline — each feature has domain → application → data → presentation layers
2. Audit Matrix — Built vs. Remaining
2.1 Infrastructure Packages
core — [COMPLETE]
| Artifact | Status |
|---|---|
KcAppConfig / KcAppEnvironment (fake, wp, square, multi) |
✅ Complete |
KcAppServices abstract base |
✅ Complete |
KcServiceFactory<T> |
✅ Complete |
KcBootstrap |
✅ Complete |
KcAppScope<T> InheritedWidget |
✅ Complete |
| Tests | ✅ 24/24 passing |
Notes: KcBootstrap only validates WooCommerce credentials. Square/multi mode credential validation is not yet wired into the bootstrap guard logic — AppServices and MobileAppServices have no square or multi factory constructors, meaning KC_ENV=square silently falls through to fake mode at runtime.
design_system — [COMPLETE]
| Artifact | Status |
|---|---|
KcColors, KcSpacing, KcTheme |
✅ Complete |
KcTypography (full Material 3 scale) |
✅ Complete |
KcBreakpoints (responsive layout utilities) |
✅ Complete |
7 shared widgets (KcCard, KcStatusChip, KcEmptyState, KcSectionHeader, KcSummaryCard, KcLoadingState, KcErrorState) |
✅ Complete |
| Tests | ✅ 41/41 passing, 100% line coverage |
Notes: No shared button/action component library exists. All action chips and buttons are defined inline per-page. This is a low-priority gap.
auth — [PARTIAL]
| Artifact | Status |
|---|---|
KcUser / KcUserRole domain models |
✅ Complete |
AuthState sealed hierarchy |
✅ Complete |
AuthService abstract contract |
✅ Complete |
AuthException |
✅ Complete |
CredentialStore / CredentialKeys contract |
✅ Complete |
InMemoryCredentialStore |
✅ Complete |
FakeAuthService |
✅ Complete |
SecureCredentialStore (flutter_secure_storage) |
❌ Missing |
Real AuthService implementation (login/session) |
❌ Missing |
| Auth guard / login screen wired into app shell | ❌ Missing |
| Tests | ✅ 42/42 passing |
Notes: The auth package provides contracts and fakes only. No production implementation exists. The app is currently unguarded — any user can access all features without authentication. auth is not imported by either AppServices or MobileAppServices.
data — [PARTIAL]
| Artifact | Status |
|---|---|
LocalCache<T> contract + InMemoryCache<T> |
✅ Complete |
SyncQueue contract + InMemorySyncQueue |
✅ Complete |
ConflictResolver<T> + 3 concrete implementations |
✅ Complete |
ChangeTracker<T> + InMemoryChangeTracker<T> |
✅ Complete |
DataMapper<TLocal, TRemote> contract |
✅ Complete |
SQLite-backed LocalCache<T> implementation |
❌ Missing |
SQLite-backed SyncQueue implementation |
❌ Missing |
| Integration with any feature package | ❌ Missing |
| Tests | ✅ 63/63 passing |
Notes: All implementations are in-memory only. The data package is not imported by any feature package or app. It is a well-designed contract layer with zero production wiring. SQLite persistence (required for offline capability, Stage 14) is not implemented.
integrations — [PARTIAL]
| Artifact | Status |
|---|---|
ApiClient / ApiException contracts |
✅ Complete |
RetryPolicy + NoRetryPolicy + ExponentialBackoffRetryPolicy |
✅ Complete |
RateLimiter + NoRateLimiter + TokenBucketRateLimiter |
✅ Complete |
IntegrationHealthCheck contract |
✅ Complete |
WebhookHandler contract |
✅ Complete |
ChannelAdapter contract |
✅ Complete |
SquareApiClient (full lifecycle, Catalog/Inventory/Orders/Payments APIs) |
✅ Complete |
SquareApiException |
✅ Complete |
SquareProductMapper (Square CatalogObject ↔ ChannelProduct) |
✅ Complete |
SquareInventoryMapper (Square InventoryCount ↔ ChannelInventoryCount) |
✅ Complete |
WooCommerceApiClient (refactored to implement ApiClient) |
✅ Complete (lives in feature_wordpress) |
RetryPolicy / RateLimiter wired into any real client |
❌ Missing |
IntegrationHealthCheck concrete implementation |
❌ Missing |
WebhookHandler concrete implementation |
❌ Missing |
ChannelAdapter concrete implementation for WooCommerce or Square |
❌ Missing |
| Tests | ✅ 123/123 passing |
Notes: RetryPolicy and RateLimiter are defined but not wired into SquareApiClient or WooCommerceApiClient. All API calls are single-attempt with no retry or rate limiting in production paths. ChannelAdapter is a contract with no concrete implementation — the WooCommerce and Square clients do not implement it.
2.2 Feature Packages
feature_wordpress — [COMPLETE] (most mature)
| Artifact | Status |
|---|---|
ProductDraft domain model (full fields, copyWith) |
✅ Complete |
PublishStatus enum (draft, published, pendingReview, unpublished) |
✅ Complete |
ProductCategory domain model |
✅ Complete |
ProductImage domain model |
✅ Complete |
ProductIdMapping domain model |
✅ Complete |
ProductPublishingRepository contract (full CRUD + categories + images) |
✅ Complete |
ProductIdMappingRepository contract |
✅ Complete |
FakeProductPublishingRepository (seeded, all methods) |
✅ Complete |
FakeProductIdMappingRepository (seeded, 6 mappings) |
✅ Complete |
WordPressProductPublishingRepository (WooCommerce REST API v3) |
✅ Complete |
SquareCatalogRepository (Square API, in-memory cache) |
✅ Complete |
WooCommerceApiClient (Products, Orders, Stock, Categories, Images) |
✅ Complete |
WordPressProductMapper |
✅ Complete |
| All use cases (GetProductDrafts, PublishProduct, UpdateProduct*, CreateProduct, DeleteProduct, GetCategories, CreateCategory, UpdateProductImages) | ✅ Complete |
ProductPublishingController (full state: multi-select, bulk actions, create, categories) |
✅ Complete |
SquareCatalogSyncService + SquareSyncResult + SyncError + InventorySyncAdapter |
✅ Complete (Stage 10D, pending merge) |
ProductPublishingPage (web, full feature surface) |
✅ Complete |
CategoryManagementPage |
✅ Complete |
ProductPreviewPanel (all inline edits, touch targets) |
✅ Complete |
ProductDraftCard (compact/standard, multi-select, stale indicator) |
✅ Complete |
CreateProductDialog (web) |
✅ Complete |
SquareSyncController (Riverpod/ChangeNotifier wrapping SquareCatalogSyncService) |
❌ Missing (Stage 10E — next branch) |
| Image picker / gallery management UI | ❌ Missing (deferred post-Stage 10) |
| Tests | ✅ 506/506 passing (Stage 10D) |
Notes: The SquareCatalogRepository throws UnsupportedError for all category and image operations — this is intentional and documented, but callers must handle these exceptions. The SquareSyncController (Stage 10E) is the immediate next deliverable.
feature_inventory — [PARTIAL]
| Artifact | Status |
|---|---|
InventoryItem domain model (full fields including squareVariationId, wooCommerceProductId, syncStatus) |
✅ Complete |
InventoryStatus enum |
✅ Complete |
InventorySyncStatus enum |
✅ Complete |
InventoryAdjustmentResult value object |
✅ Complete |
InventoryRepository contract (read + write + sync) |
✅ Complete |
FakeInventoryRepository (seeded, all write methods) |
✅ Complete |
WooCommerceInventoryRepository |
✅ Complete |
SquareInventoryRepository |
✅ Complete |
InventorySyncService (WooCommerce pull/push sync) |
✅ Complete |
| All use cases (GetInventoryItems, AdjustInventoryQuantity, CreateInventoryItem, UpdateInventoryItem) | ✅ Complete |
InventoryController (read + write actions) |
✅ Complete |
InventoryPage (web, full filter/search/detail panel) |
✅ Complete |
InventoryDetailPanel, AdjustQuantityDialog, InventoryStatusChip |
✅ Complete |
ItemType enum (rawMaterial, finishedGood, packaging, tool) |
❌ Missing (Stage 12A) |
InventoryAdjustment audit log value object |
❌ Missing (Stage 12A) |
Supplier domain model |
❌ Missing (Stage 12B) |
PurchaseOrder domain model |
❌ Missing (Stage 12B) |
| Supply receiving / material usage workflows | ❌ Missing (Stage 12B) |
Multi-channel inventory sync engine (InventorySyncEngine) |
❌ Missing (Stage 12C) |
ChannelStockMapping |
❌ Missing (Stage 12C) |
| Sync status indicators in inventory UI | ❌ Missing |
| Tests | ✅ 167/167 passing |
Notes: The inventory feature has a solid domain and data layer. The InventorySyncService is WooCommerce-only. Square inventory sync is handled separately via SquareInventoryRepository but there is no unified sync engine that coordinates both channels. The InventoryController is not wired to InventorySyncService — sync must be triggered manually.
feature_orders — [PARTIAL]
| Artifact | Status |
|---|---|
Order domain model (full fields: customerPhone, notes, orderNotes, paymentMethod, source, customFields) |
✅ Complete |
OrderItem domain model (productId, variationId, customizations) |
✅ Complete |
OrderStatus enum (including onHold, refunded, failed) |
✅ Complete |
OrderSource enum (online, market, manual) |
✅ Complete |
OrderActionResult value object |
✅ Complete |
OrdersRepository contract (getOrders, getOrder, createOrder, updateOrderStatus, addOrderNote) |
✅ Complete |
FakeOrdersRepository (seeded, all write methods) |
✅ Complete |
WooCommerceOrdersRepository |
✅ Complete |
WooCommerceOrderMapper |
✅ Complete |
| All use cases (GetOrders, UpdateOrderStatus, AddOrderNote, CreateOrder) | ✅ Complete |
OrdersController (read + write, filter/search persistence) |
✅ Complete |
OrdersPage (web, master-detail, status filter, cross-feature callbacks) |
✅ Complete |
OrderDetailPanel, OrderCard, AddNoteDialog, OrderStatusChip |
✅ Complete |
OrderType enum (standard, custom) |
❌ Missing (Stage 11A) |
CustomOrderSpec value object |
❌ Missing (Stage 11A) |
DepositInfo value object |
❌ Missing (Stage 11A) |
| Custom order fulfillment status pipeline | ❌ Missing (Stage 11C) |
CustomOrderFormPage |
✅ Delivered (11B) |
CustomOrderTrackingPage |
❌ Missing (Stage 11C) |
OrderChannel enum (woocommerce, square, manual) |
❌ Missing (Stage 13B) |
UnifiedOrdersController (multi-channel aggregation) |
❌ Missing (Stage 13B) |
Standard scaffolding files (.gitignore, .metadata, CHANGELOG.md, LICENSE, README.md) |
❌ Missing |
| Tests | ✅ 198/198 passing |
Notes: The feature_orders package is missing standard monorepo scaffolding files present in all other packages. The WooCommerce orders integration is production-ready. Square orders are not yet integrated into the orders feature (Square API client has createOrder/listOrders/getOrder but no SquareOrdersRepository exists).
feature_policy — [PARTIAL]
| Artifact | Status |
|---|---|
PolicyCheckResult domain model |
✅ Complete |
GovernanceStatus enum |
✅ Complete |
PolicyRepository contract |
✅ Complete |
FakePolicyRepository |
✅ Complete |
GetPolicyChecks use case |
✅ Complete |
PolicyController |
✅ Complete |
PolicyPage (master-detail, filter, search, cross-feature callbacks) |
✅ Complete |
PolicyCheckCard, PolicyDetailPanel |
✅ Complete |
| Real backend (e.g., reading from policy register CSVs) | ❌ Missing |
| Tests | ⚠️ Minimal (only smoke test in feature_policy_test.dart) |
Notes: The policy feature is fake-data only. The policy register CSVs in policies/register/ contain headers only with no data rows — the controlled document lifecycle is not being followed for the governance documents themselves.
feature_finance — [MISSING/PENDING]
| Artifact | Status |
|---|---|
| Package scaffolding | ✅ Exists |
| Any domain model | ❌ Missing |
| Any application logic | ❌ Missing |
| Any data layer | ❌ Missing |
| Any presentation | ❌ Missing |
| Tests | ❌ Placeholder Calculator test only |
Notes: The barrel file (feature_finance.dart) contains only the Flutter template Calculator class. The Finance route in kell_web renders FinancePlaceholderPage. This is a pure stub.
feature_mrp — [MISSING/PENDING]
| Artifact | Status |
|---|---|
| Package scaffolding | ✅ Exists |
| Any domain model | ❌ Missing |
| Any application logic | ❌ Missing |
| Any data layer | ❌ Missing |
| Any presentation | ❌ Missing |
| Tests | ❌ Placeholder Calculator test only |
Notes: Pure stub. Scope should be re-evaluated after Stage 12 (supplies tracking) to determine if MRP adds distinct value beyond custom orders + inventory.
feature_social — [MISSING/PENDING]
| Artifact | Status |
|---|---|
| Package scaffolding | ✅ Exists |
| Any domain model | ❌ Missing |
| Any application logic | ❌ Missing |
| Any data layer | ❌ Missing |
| Any presentation | ❌ Missing |
| Tests | ❌ Placeholder Calculator test only |
Notes: Pure stub. Deferred until core platform stabilizes. Facebook, Instagram, and X (Twitter) API integrations are all listed as "Stub only" in the integration landscape.
2.3 Application Targets
kell_web — [COMPLETE] (for current feature scope)
| Artifact | Status |
|---|---|
AppServices (fake + wordpress factories) |
✅ Complete |
KcBootstrap / KcAppScope wiring |
✅ Complete |
AppShell with sidebar navigation (7 routes) |
✅ Complete |
AppRoutes (dashboard, inventory, products, orders, finance, policy, integrations) |
✅ Complete |
DashboardPage (8 KPI cards, quick actions, cross-feature navigation) |
✅ Complete |
ProductPublishingPage (full feature surface) |
✅ Complete |
InventoryPage (full feature surface) |
✅ Complete |
OrdersPage (full feature surface) |
✅ Complete |
PolicyPage (full feature surface) |
✅ Complete |
FinancePlaceholderPage |
⚠️ Placeholder only |
IntegrationsPlaceholderPage |
⚠️ Placeholder only |
square / multi factory constructors in AppServices |
❌ Missing |
| Tests | ✅ 24/24 passing |
Notes: AppServices has no square() or multi() factory. Setting KC_ENV=square or KC_ENV=multi at runtime will fall through to fake mode silently because KcServiceFactory only has createFake and createWordPress callbacks. This is a critical gap for Square integration testing.
kell_mobile — [COMPLETE] (for current feature scope)
| Artifact | Status |
|---|---|
MobileAppServices (fake + wordpress factories) |
✅ Complete |
KcBootstrap / KcAppScope wiring |
✅ Complete |
MobileShell (5-tab NavigationBar: Dashboard, Inventory, Orders, Publishing, More) |
✅ Complete |
DashboardPage (mobile GridView layout) |
✅ Complete |
MobilePublishingPage + MobileProductDetailPage |
✅ Complete |
MobileCreateProductPage |
✅ Complete |
MobileInventoryPage + MobileInventoryDetailPage |
✅ Complete |
MobileOrdersPage + MobileOrderDetailPage |
✅ Complete |
| Haptic feedback, confirmation dialogs, SafeArea, 48dp touch targets | ✅ Complete |
FinancePlaceholderPage |
⚠️ Placeholder only |
IntegrationsPlaceholderPage |
⚠️ Placeholder only |
square / multi factory constructors in MobileAppServices |
❌ Missing |
| Square POS / checkout flow | ❌ Missing (Stage 10C) |
MobileCheckoutPage |
❌ Missing (Stage 10C) |
| Tests | ✅ 26/26 passing |
2.4 Architecture & Documentation
Architecture Documentation — [COMPLETE]
| Artifact | Status |
|---|---|
| 19 PlantUML C4 diagrams (context, containers, components, deployment, dynamic) | ✅ Complete |
MkDocs documentation site (mkdocs.yml) |
✅ Complete |
| ADR index (7 retroactive entries) | ✅ Complete |
| Traceability index | ✅ Complete |
| Square not represented in architecture diagrams | ❌ Missing (noted in brief §17) |
| Multi-channel data model architecture | ❌ Missing (noted in brief §18) |
Policy Repository — [PARTIAL]
| Artifact | Status |
|---|---|
| Policy templates (policy, procedure, standard, form, exception) | ✅ Complete |
| Active governance documents (KC-POL-GOV-001, KC-PRO-GOV-001) | ✅ Complete |
| Policy register CSVs (policy-register, document-control-log, review-calendar) | ❌ Empty (headers only, no data rows) |
| Exception register | ❌ Empty |
3. Technical Debt & Code Hygiene Assessment
3.1 Dead Code / Placeholder Stubs
| Location | Issue | Severity |
|---|---|---|
feature_finance/lib/feature_finance.dart |
Flutter template Calculator class — entire package is a stub |
HIGH |
feature_mrp/lib/feature_mrp.dart |
Flutter template Calculator class — entire package is a stub |
HIGH |
feature_social/lib/feature_social.dart |
Flutter template Calculator class — entire package is a stub |
HIGH |
kell_web/lib/pages/finance_placeholder_page.dart |
Placeholder page with no content | MEDIUM |
kell_web/lib/pages/integrations_placeholder_page.dart |
Placeholder page with no content | MEDIUM |
kell_mobile/lib/pages/finance_placeholder_page.dart |
Placeholder page with no content | MEDIUM |
kell_mobile/lib/pages/integrations_placeholder_page.dart |
Placeholder page with no content | MEDIUM |
kell_web/lib/pages/dashboard_page.dart (Recent Activity section) |
KcEmptyState hardcoded — no real activity feed |
LOW |
3.2 Missing Error Handling / Defensive Gaps
| Location | Issue | Severity |
|---|---|---|
AppServices / MobileAppServices |
No square() or multi() factory — KC_ENV=square silently falls to fake |
CRITICAL |
KcBootstrap |
Only validates WooCommerce credentials; Square credential validation absent | HIGH |
SquareCatalogRepository |
6 methods throw UnsupportedError (categories, images) — callers must handle |
HIGH |
integrations — RetryPolicy / RateLimiter |
Defined but not wired into SquareApiClient or WooCommerceApiClient |
HIGH |
auth package |
Not imported or used by any app or feature package | HIGH |
data package |
Not imported or used by any app or feature package | MEDIUM |
InventoryController |
Not wired to InventorySyncService — sync cannot be triggered from UI |
MEDIUM |
SquareCatalogSyncService |
No Riverpod/ChangeNotifier controller wrapper — cannot be triggered from UI | MEDIUM |
WooCommerceApiClient |
No retry logic on transient failures (5xx, network timeouts) | MEDIUM |
feature_policy tests |
Only a smoke test exists — no domain, controller, or widget tests | MEDIUM |
3.3 Hardcoded Values / Antipatterns
| Location | Issue | Severity |
|---|---|---|
SquareCatalogSyncService.syncCatalog() |
Uses product.id as both localId and squareCatalogObjectId — conflates Square catalog IDs with local product IDs |
HIGH |
InventorySyncService._syncItem() |
pushLocalStock silently swallows push failures with catch (_) {} — no logging |
MEDIUM |
kell_web/lib/pages/dashboard_page.dart |
Revenue card navigates to Finance route which is a placeholder | LOW |
policies/register/*.csv |
All register CSVs contain headers only — no data rows | MEDIUM |
feature_orders package |
Missing .gitignore, .metadata, CHANGELOG.md, LICENSE, README.md |
LOW |
3.4 Test Coverage Assessment
Test counts re-verified 2026-09-25 by a full local run — 1,898 / 1,898 passing. Coverage percentages are from the original 2026-07-25 audit and have not been re-measured; treat them as indicative only.
| Package | Tests | Coverage | Assessment |
|---|---|---|---|
core |
90 | ~85.7% | Good — composition + observability well covered |
design_system |
51 | 100% | Excellent |
feature_wordpress |
545 | ~84.7% | Good — broad coverage across all layers |
feature_inventory |
167 | Unknown | Adequate — domain, data, and widget tests present |
feature_orders |
657 | Unknown | Excellent — custom order domain exhaustively tested |
feature_policy |
17 | Very low | Gap — thin; no controller/widget tests |
auth |
42 | Unknown | Good for contracts and fakes |
data |
63 | Unknown | Good for contracts and in-memory impls |
integrations |
123 | Unknown | Good — API client and mapper tests present |
kell_web |
62 | ~54.1% | Gap — low coverage; routing and shell untested |
kell_mobile |
81 | Unknown | Adequate — shell, page, and checkout tests |
feature_finance |
1 (placeholder) | ~0% | Critical gap — stub only |
feature_mrp |
1 (placeholder) | ~0% | Critical gap — stub only |
feature_social |
1 (placeholder) | ~0% | Critical gap — stub only |
Key gaps:
kell_webat 54.1% line coverage — routing, shell, and navigation are largely untestedfeature_policyhas no meaningful tests beyond a barrel smoke test- No integration tests exist across any package boundary
- No end-to-end tests exist for any user workflow
- CI enforces no minimum coverage thresholds (visibility-only)
3.5 Architectural Antipatterns
Status column added 2026-09-25. Three findings below were closed by Stages 10E and 16A.
| Issue | Description | Severity | Status |
|---|---|---|---|
| No state management framework | All state uses ChangeNotifier + AnimatedBuilder. As complexity grows (sync engine, multi-channel, offline queue), this pattern will become difficult to compose. No Riverpod, BLoC, or equivalent. |
MEDIUM | Open |
| No dependency injection | Services are constructed directly in factory methods. No DI container. Makes testing harder as the app grows. | MEDIUM | Open |
SquareCatalogSyncService ID conflation |
syncCatalog() used product.id as the Square catalog object ID when it is really the local/WooCommerce ID. |
HIGH | ✅ Resolved (10E) |
AppServices / MobileAppServices duplication |
Both files are nearly identical. A shared base class or factory could eliminate the duplication. | LOW | Open |
| No logging infrastructure | Structured logging landed in core: KcLogger, KcLogLevel, KcLogRecord, KcLogSink, KcRedactor. Repositories log failures with redacted context instead of swallowing them. |
MEDIUM | ✅ Resolved (16A) |
| No crash reporting | KcErrorReporter, KcObservability, KcBugReport, and KcBugReportService capture crashes and user-submitted bug reports. No third-party SaaS dependency was introduced. |
MEDIUM | ✅ Resolved (16A) |
4. Actionable Engineering Backlog
Phase 1 — High-Priority / Blocking (Core Fixes & Missing Execution Paths)
These items block correct runtime behavior or represent data integrity risks.
P1.1 — Wire square and multi factory constructors into AppServices and MobileAppServices
Why blocking: Setting KC_ENV=square currently silently falls to fake mode. Square integration cannot be tested end-to-end without this.
Scope: Add AppServices.square() and AppServices.multi() factories using SquareCatalogRepository and SquareInventoryRepository. Mirror in MobileAppServices. Update KcServiceFactory to accept createSquare and createMulti callbacks. Update KcBootstrap to validate Square credentials.
Branch: feat/square-catalog-sync-service-controller (Stage 10E) should include this.
P1.2 — Fix SquareCatalogSyncService.syncCatalog() ID conflation
Why blocking: The current implementation uses product.id (a local/WooCommerce ID) as the squareCatalogObjectId. When SquareCatalogRepository is the source, product.id is the Square catalog object ID — but when FakeProductPublishingRepository or WordPressProductPublishingRepository is the source, product.id is a WooCommerce ID. The mapping will be incorrect in mixed-source scenarios.
Scope: The sync service needs to know which repository type it is talking to, or the ProductDraft model needs a squareCatalogObjectId field, or the sync service should accept the Square catalog object ID separately.
P1.3 — Merge Stage 10D (feat/square-catalog-sync-service)
Why blocking: The build tracker shows Stage 10D as "ready for merge" but not yet merged. The master brief baseline is Stage 10C. Stage 10E depends on 10D being on main.
Action: Merge feat/square-catalog-sync-service → main before starting Stage 10E.
P1.4 — SquareSyncController (Stage 10E)
Why blocking: SquareCatalogSyncService exists but has no UI trigger. Without a controller, sync cannot be initiated from the app.
Scope: ChangeNotifier wrapping SquareCatalogSyncService, exposing syncAll(), syncCatalog(), syncInventory(), isSyncing, lastSyncedAt, lastResult. Wire into AppServices / MobileAppServices.
Branch: feat/square-catalog-sync-service-controller
P1.5 — Add square / multi mode to KcBootstrap credential validation
Why blocking: KcBootstrap currently only validates WooCommerce credentials. Square mode will silently proceed with empty tokens.
Scope: Add hasSquareConfig check in bootstrap for square and multi environments.
Phase 2 — Feature Completion & Integration
These items complete planned stages and wire existing contracts into production paths.
P2.1 — Square Mobile POS / Checkout (Stage 10C)
Scope: PaymentService abstraction, PaymentResult domain model, MobileCheckoutPage (product selection → cart → payment), Square Reader SDK integration for Android, cash recording, digital receipt, post-payment order creation and inventory deduction, Sales tab in mobile navigation.
Dependencies: Stage 10A ✅, Stage 10B ✅, Stage 10D ✅, P1.1, P1.4
P2.2 — Custom Orders Workflow (Stage 11) — ⚠️ PARTIALLY RESOLVED
Domain and data layers delivered on
feat/custom-order-domain(Stage 11A, 2026-08-29). Intake UI delivered onfeat/custom-order-ui(Stage 11B, 2026-09-25).
Delivered (11A): OrderType enum, CustomOrderSpec value object, DepositInfo value object (money as integer cents), FulfillmentStatus pipeline with domain-enforced legal transitions (quoted → depositReceived → inProduction → qualityCheck → readyForPickup → completed, plus cancelled and a qualityCheck → inProduction rework path), extended Order model, createCustomOrder() / updateCustomOrderSpec() / recordDeposit() / advanceFulfillmentStatus() on OrdersRepository, implemented in both FakeOrdersRepository (seeded across every stage) and WooCommerceOrdersRepository (_kc_-prefixed order meta-data). 423 new tests.
Delivered (11B): CreateCustomOrder / RecordDeposit use cases, CustomOrderFormController (field-keyed validation, integer-cent money parsing, injectable clock and ID generator), CustomOrderFormPage, CustomOrderConfirmationPage with a deposit receipt that carries no payment identifier, FulfillmentStatusChip, showReferenceImageDialog(), an optional onCreateCustomOrder action on OrdersPage, the /orders/custom web route, and MobileCustomOrderPage behind an orders FAB. 146 new tests.
Still open: CustomOrderTrackingPage, the status-change timeline, catalogue product-base selection, platform camera / file-picker image capture, and inventory deduction on completion (Stage 11C).
Dependencies: Stage 9A ✅, Stage 11A ✅, Stage 11B ✅
P2.3 — Inventory Write Operations & Supplies Tracking (Stage 12A/12B)
Scope: ItemType enum, InventoryAdjustment audit log, Supplier domain model, PurchaseOrder domain model, supply receiving workflow, material usage workflow, low-stock alert system, SuppliesPage UI.
Dependencies: Stage 9B ✅
P2.4 — Multi-Channel Inventory Sync Engine (Stage 12C)
Scope: InventorySyncEngine (poll/webhook-triggered, conflict resolution, batch sync), ChannelStockMapping, WooCommerceStockSync, SquareStockSync, sync status indicators in inventory UI, manual sync trigger.
Dependencies: P2.3, Stage 10B ✅
P2.5 — WooCommerce Orders Integration wired into AppServices
Current state: WooCommerceOrdersRepository exists but AppServices.wordpress() still uses FakeOrdersRepository.
Scope: Wire WooCommerceOrdersRepository into AppServices.wordpress() and MobileAppServices.wordpress().
P2.6 — WooCommerce Inventory Integration wired into AppServices
Current state: WooCommerceInventoryRepository exists but AppServices.wordpress() still uses FakeInventoryRepository.
Scope: Wire WooCommerceInventoryRepository into AppServices.wordpress() and MobileAppServices.wordpress().
P2.7 — Unified Order View (Stage 13B)
Scope: OrderChannel enum, UnifiedOrdersController aggregating WooCommerce + Square + manual orders, unified orders page with channel indicator.
Dependencies: P2.1, Stage 9A ✅
P2.8 — Offline Data Cache & Sales Queue (Stage 14)
Scope: SQLite-backed LocalCache<T> implementation (using sqflite or drift), SQLite-backed SyncQueue, offline detection, "Prepare for Market" pre-sync action, auto-sync on reconnect, conflict handling.
Dependencies: data package contracts ✅
P2.9 — feature_finance Activation (Stage 15)
Scope: Sales reporting (by channel, product, time period), inventory valuation, financial dashboard (revenue vs. COGS, gross margin, market event profitability).
Dependencies: P2.1, Stage 9A ✅, P2.3
P2.10 — Populate Policy Register CSVs
Scope: Add data rows to policies/register/policy-register.csv, document-control-log.csv, review-calendar.csv, and exception-register.csv for the 2 active governance documents.
Dependencies: None — can be done immediately.
Phase 3 — Defensive Engineering, Logging & Test Harness Expansion
These items harden the platform for production deployment.
P3.1 — Wire RetryPolicy and RateLimiter into API clients
Scope: Apply ExponentialBackoffRetryPolicy to SquareApiClient and WooCommerceApiClient for 5xx and network errors. Apply TokenBucketRateLimiter to Square API calls (Square enforces rate limits).
P3.2 — Implement SecureCredentialStore (Stage 8C remainder)
Scope: flutter_secure_storage-backed CredentialStore implementation. First-run setup wizard for entering API credentials. Connection testing UI.
P3.3 — Auth guard wired into app shell
Scope: Login screen, AuthService wired into AppServices, route guard preventing unauthenticated access.
Dependencies: P3.2
P3.4 — Structured logging infrastructure
Scope: Add a logging abstraction (e.g., package:logging) with structured output. Log all API calls, sync operations, errors, and state transitions. Replace silent catch (_) {} blocks with logged failures.
P3.5 — Crash reporting integration (Stage 16A)
Scope: Sentry or Firebase Crashlytics integration. Health check dashboard showing integration status per channel.
P3.6 — Expand feature_policy test coverage
Scope: Add controller tests, widget tests for PolicyPage, PolicyCheckCard, PolicyDetailPanel. Target >80% line coverage.
P3.7 — Expand kell_web test coverage from 54.1%
Scope: Add routing tests, shell navigation tests, AppServices factory tests. Target >75% line coverage.
P3.8 — Add feature_orders standard scaffolding files ✅ RESOLVED
feature_orders standard scaffolding filesDelivered on
feat/custom-order-domain(Stage 11A, 2026-08-29).
Scope: Add .gitignore, .metadata, CHANGELOG.md, LICENSE, README.md to feature_orders to match all other packages.
.gitignore already existed; .metadata, CHANGELOG.md, LICENSE, and README.md were added. The README documents the fulfillment pipeline, the WooCommerce meta mapping, and the observability/privacy rules rather than carrying the default template placeholders.
P3.9 — Update architecture diagrams for Square and multi-channel
Scope: Add Square to system-landscape.puml, enterprise-integration-orchestration-architecture.puml, context-kellcreations-platform.puml. Create dynamic-market-sale-checkout.puml. Create enterprise-multi-channel-architecture.puml.
P3.10 — Implement ChannelAdapter for WooCommerce and Square
Scope: Concrete WooCommerceChannelAdapter and SquareChannelAdapter implementing the ChannelAdapter contract from integrations. This enables the multi-channel sync engine (Stage 13A) to operate against a channel-agnostic interface.
P3.11 — Enforce minimum test coverage thresholds in CI
Scope: Update flutter-test.yml to fail the build if any package drops below a defined threshold (e.g., 75% line coverage). Currently coverage is visibility-only.
P3.12 — Evaluate and activate feature_mrp
Scope: After Stage 12 completion, assess whether MRP adds distinct value (production scheduling, work orders, bill of materials) beyond custom orders + inventory. Activate or formally retire the package.
5. Summary Scorecard
Re-baselined 2026-09-25 against
mainafter Stages 10C–10F, 11A, and 16A merged. Test counts are the verified per-package totals from a full local run (1,898 / 1,898 passing);dart analyze --fatal-infosis clean across all 11 packages and apps.
| Subsystem | Status | Completeness | Tests | Blocking Issues |
|---|---|---|---|---|
core |
✅ COMPLETE | 100% | 90 | None — square/multi bootstrap validation landed (Stage 10E) |
design_system |
✅ COMPLETE | 100% | 51 | None |
auth |
⚠️ PARTIAL | 40% | 42 | No production impl; SecureCredentialStore TBD; not wired into shell |
data |
⚠️ PARTIAL | 35% | 63 | No SQLite impl; not wired into any feature |
integrations |
⚠️ PARTIAL | 70% | 123 | RetryPolicy/RateLimiter not wired; ChannelAdapter not implemented |
feature_wordpress |
✅ COMPLETE | 100% | 545 | None — SquareSyncController landed (Stage 10E) |
feature_inventory |
⚠️ PARTIAL | 65% | 167 | No unified sync engine; ItemType/Supplier/PurchaseOrder missing |
feature_orders |
⚠️ PARTIAL | 85% | 657 | Custom order domain+data landed (11A); custom order UI open |
feature_policy |
⚠️ PARTIAL | 50% | 17 | Fake-only; minimal tests; policy register empty |
feature_finance |
❌ MISSING | 0% | 1 | Pure stub |
feature_mrp |
❌ MISSING | 0% | 1 | Pure stub |
feature_social |
❌ MISSING | 0% | 1 | Pure stub |
kell_web |
⚠️ PARTIAL | 85% | 62 | Finance placeholder remains; Integrations page now real |
kell_mobile |
⚠️ PARTIAL | 85% | 81 | Finance placeholder remains; POS/checkout landed (Stage 10C) |
| 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 |
Overall Platform Readiness
| Dimension | Assessment |
|---|---|
| WooCommerce catalog management | ✅ Production-ready |
| WooCommerce orders | ✅ Repository complete; not wired into AppServices |
| WooCommerce inventory sync | ✅ Repository complete; not wired into AppServices |
| Square catalog sync | ✅ Service + controller + UI panel; ID bug fixed (10E/10F) |
| Square inventory sync | ✅ Repository wired via square() / multi() factories |
| Square payments / POS | ✅ Mobile checkout flow implemented (Stage 10C) |
| Custom orders | ⚠️ Domain, data, and intake UI done (11A/11B); tracking open |
| Observability / error logging | ✅ KcLogger, KcErrorReporter, bug reports (Stage 16A) |
| Supplies tracking | ❌ Not implemented |
| Multi-channel sync engine | ❌ Not implemented |
| Offline capability | ❌ Not implemented |
| Authentication | ❌ Contracts only; not wired |
| Financial reporting | ❌ Not implemented |
| Social media management | ❌ Not implemented |
Generated by automated repository audit. All findings are based on source code inspection, documentation review, and test suite analysis as of 2026-07-25.