# PROJECT_STATE_AUDIT.md ## Kell Creations Operations Platform — Comprehensive Code Audit **Audit Date:** 2026-07-25 **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 --- ## 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` | ✅ Complete | | `KcBootstrap` | ✅ Complete | | `KcAppScope` 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` contract + `InMemoryCache` | ✅ Complete | | `SyncQueue` contract + `InMemorySyncQueue` | ✅ Complete | | `ConflictResolver` + 3 concrete implementations | ✅ Complete | | `ChangeTracker` + `InMemoryChangeTracker` | ✅ Complete | | `DataMapper` contract | ✅ Complete | | SQLite-backed `LocalCache` 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` | ❌ Missing (Stage 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 | Package | Tests | Coverage | Assessment | | ------------------- | --------------- | -------- | ----------------------------------------------------- | | `core` | 24 | ~85.7% | Good — composition abstractions well covered | | `design_system` | 41 | 100% | Excellent | | `feature_wordpress` | 506 | ~84.7% | Good — broad coverage across all layers | | `feature_inventory` | 167 | Unknown | Adequate — domain, data, and widget tests present | | `feature_orders` | 198 | Unknown | Good — domain, data, mapper, and widget tests present | | `feature_policy` | ~5 | Very low | **Gap** — only smoke test; 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` | 24 | ~54.1% | **Gap** — low coverage; routing and shell untested | | `kell_mobile` | 26 | Unknown | Adequate — shell and page smoke 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_web` at 54.1% line coverage — routing, shell, and navigation are largely untested - `feature_policy` has 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 | Issue | Description | Severity | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | **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 | | **No dependency injection** | Services are constructed directly in factory methods. No DI container. Makes testing harder as the app grows. | MEDIUM | | **`SquareCatalogSyncService` ID conflation** | `syncCatalog()` uses `product.id` as the Square catalog object ID, but `product.id` is the local/WooCommerce ID. This will produce incorrect mappings when Square is the source. | HIGH | | **`AppServices` / `MobileAppServices` duplication** | Both files are nearly identical. A shared base class or factory could eliminate the duplication. | LOW | | **No logging infrastructure** | No structured logging anywhere in the codebase. Errors are caught and surfaced via SnackBars or swallowed silently. | MEDIUM | | **No crash reporting** | No Sentry, Firebase Crashlytics, or equivalent. Runtime errors are invisible in production. | MEDIUM | --- ## 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) **Scope:** `OrderType` enum, `CustomOrderSpec` value object, `DepositInfo` value object, extended `Order` model, `createCustomOrder()` / `updateCustomOrderSpec()` / `recordDeposit()` repository methods, `CustomOrderFormPage`, `CustomOrderConfirmationPage`, `CustomOrderTrackingPage`, fulfillment status pipeline. **Dependencies:** Stage 9A ✅ #### 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` 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 **Scope:** Add `.gitignore`, `.metadata`, `CHANGELOG.md`, `LICENSE`, `README.md` to `feature_orders` to match all other packages. #### 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 | 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 | ### 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 layer complete; no UI trigger; ID conflation bug | | **Square inventory sync** | ⚠️ Repository complete; not wired into AppServices | | **Square payments / POS** | ❌ Not implemented | | **Custom orders** | ❌ Not implemented | | **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._ --- ## 5. Summary Scorecard | 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 | ### 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 layer complete; no UI trigger; ID conflation bug | | **Square inventory sync** | ⚠️ Repository complete; not wired into AppServices | | **Square payments / POS** | ❌ Not implemented | | **Custom orders** | ❌ Not implemented | | **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.*