695 lines
56 KiB
Markdown
695 lines
56 KiB
Markdown
# 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<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` | ❌ 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<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
|
|
|
|
**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.*
|