mtkell
/
kell_creations
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kell_creations/docs/development/master_development_brief.md

28 KiB
Raw Blame History

Kell Creations Operations Platform — Master Development Brief

Recommended repo location

Place this document in the repository at:

docs/development/master_development_brief.md

Why this location:

  • keeps it versioned with the code
  • makes it easy for Cline to read and update
  • separates implementation planning from feature code
  • works for both web and Android roadmap tracking

If docs/development/ does not exist yet, create it.

Purpose

This document is the master implementation brief for continuing development of the Kell Creations Flutter operations platform across web and Android. It is intended for use by Cline in Windows 11 VS Code.

This brief should be treated as the working source of truth for planned development after the current completed slices already landed on main.

Working model

Development must proceed in small, reviewable vertical slices.

Rules:

  • Branch from current main for each stage or sub-slice.
  • Implement on a feature branch.
  • Validate locally.
  • Open a PR into main.
  • Merge only after tests/analyze are clean.
  • Do not stack broad unfinished work directly on main.
  • After each merged slice, update this brief so it remains aligned to main.

Current confirmed baseline on main

Platform structure

  • apps/kell_web exists — active, wired to shared packages.
  • apps/kell_mobile exists — scaffolded as default Flutter template, not yet integrated with shared packages.
  • Shared packages include:
    • core — shared domain/application abstractions
    • design_system — theme (colors, spacing, theme) and shared widgets (KcCard, KcStatusChip)
    • feature_inventory — domain, application, data (fake), and presentation layers
    • feature_wordpress — domain, application, data (fake + WooCommerce), and presentation layers (most mature feature)
    • feature_orders — domain, application, data (fake), and presentation layers
    • feature_policy — domain, application, data (fake), and presentation layers
  • Scaffolded but empty stub packages (created, no implementation yet):
    • auth — authentication/authorization (stub only)
    • data — shared data layer (stub only)
    • integrations — shared integration abstractions (stub only)
    • feature_finance — financial analysis feature (stub only)
    • feature_mrp — craft manufacturing/MRP feature (stub only)
    • feature_social — social media management feature (stub only)
  • tools/ directory exists but is empty.
  • App shell, routing, dashboard, reusable shell widgets, AppServices, and AppScope are implemented.
  • Dashboard uses app-composed repository data.
  • Vertical slices exist for Inventory, Products/Publishing, Orders, and Policy/Governance.
  • Cross-feature navigation handoffs and shared filtering/search/selection persistence are implemented.
  • Runtime bootstrap uses:
    • KC_ENV
    • KC_WC_SITE_URL
    • KC_WC_CONSUMER_KEY
    • KC_WC_CONSUMER_SECRET
  • App supports FAKE and WP modes with visible shell badge.

Product publishing workflow already landed on main

  • Controlled WooCommerce publish action landed.
  • ProductDraft.copyWith landed.
  • unpublished -> draft UI exposure landed.
  • pendingReview -> draft UI exposure landed.
  • unpublished semantics clarified as a read-only abstraction.
  • Status action success/failure feedback landed.
  • Publishing page polish landed.
  • Richer read-side detail preview landed.
  • Price-only product edit landed.
  • Search/filter/sort refinement landed.
  • Name-only product edit landed.
  • ✅ Description-only product edit landed (Stage 1A complete — merged feat/description-only-edit → main at cebac4c, 2026-04-11).
  • ✅ Category-only product edit landed (Stage 1B complete — merged feat/category-only-edit → main at 8e7e4cb, 2026-04-11). Stage 1 complete.
  • ✅ Post-write consistency hardening landed (Stage 2A complete — merged feat/post-write-consistency → main at 7acff83, 2026-04-11).
  • ✅ Publishing workflow UX hardening landed (Stage 2B complete — merged feat/publishing-ux-hardening → main at b81016d, 2026-04-11). Stage 2 complete.
  • ✅ Multi-select groundwork landed (Stage 3A complete — merged feat/multi-select-groundwork → main, 2026-05-22).
  • ✅ List efficiency improvements landed (Stage 3B complete — merged feat/list-efficiency-improvements → main, 2026-05-22). Stage 3 complete.
  • ✅ Design system expansion and shared widget migration landed (Stage 4A complete — merged feat/design-system-shared-widgets → main, 2026-05-22).
  • ✅ Cross-platform shell composition strategy landed (Stage 4B complete — merged feat/shared-composition-pattern → main, 2026-05-22).

Current narrow edit capabilities on main

  • update product status through controlled workflow
  • update product price only
  • update product name only
  • update product description only
  • update product category only

Latest known validation state on main

  • dart analyze clean
  • core tests passing
  • design_system tests passing
  • feature_wordpress tests passing
  • kell_web tests passing
  • latest reported count for core: 20/20 passed
  • latest reported count for design_system: 41/41 passed
  • latest reported count for feature_wordpress: 294/294 passed
  • latest reported count for kell_web: 24/24 passed
  • baseline commit: merge of feat/shared-composition-pattern (2026-05-22)

Next recommended branch

feat/flutter-cicd — Stage 4C: Flutter CI/CD pipeline. Branch from latest main. Stage 4B (cross-platform shell composition) is complete.

Non-negotiable architectural constraints

These must be preserved in all future work:

  • Preserve strict package boundaries.
  • Fake repositories remain in feature packages.
  • Real integrations are incremental alongside fake ones.
  • Runtime selection stays via --dart-define, not a settings UI.
  • No credentials hardcoded or committed.
  • Do not broaden into generic product editing prematurely.
  • Keep WooCommerce details inside the WP repository layer.
  • Keep diffs small and reviewable.
  • Prefer inspection-first development.
  • Android support should reuse shared feature/domain/application layers rather than fork logic.

Development stages

Stage 1 — Web application completion: controlled product editing

Objective

Extend the publishing workflow with additional single-field edit capabilities using the same narrow pattern already established by price-only and name-only update.

Branching model

Use one branch per edit slice:

  • feat/description-only-edit
  • feat/category-only-edit

Stage 1A — Description-only product edit ✅ COMPLETE

Merged feat/description-only-edit → main at cebac4c (2026-04-11). All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline description edit UI, and targeted tests (212 total feature_wordpress tests passing).

Stage 1B — Category-only product edit ✅ COMPLETE

Merged feat/category-only-edit → main at 8e7e4cb (2026-04-11). All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline category edit UI, snack bar feedback, and targeted tests (223 total feature_wordpress tests passing). Stage 1 complete.

Stage 2 — Web application operational hardening

Objective

Improve operator consistency, predictability, and usability after writes.

Branches

  • feat/post-write-consistency
  • feat/publishing-ux-hardening

Stage 2A — Post-write consistency hardening ✅ COMPLETE

Merged feat/post-write-consistency → main at 7acff83 (2026-04-11). Added _refreshSelection() to ProductPublishingController to preserve/refresh selection after all write-triggered reloads. 11 new post-write consistency tests added (234 total feature_wordpress tests passing).

Stage 2B — Publishing workflow UX hardening ✅ COMPLETE

Merged feat/publishing-ux-hardening → main at b81016d (2026-04-11). Added inline validation error messages for all four single-field edits (name, price, description, category), disabled text fields and save buttons during isUpdating, and appended error detail to failure snack bars. 13 new tests added (247 total feature_wordpress tests passing). Stage 2 complete.

Stage 3 — Web application operator efficiency

Objective

Increase throughput for product triage and management using existing data.

Branches

  • feat/multi-select-groundwork
  • feat/list-efficiency-improvements

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

Merged feat/multi-select-groundwork → main (2026-05-22). Added multi-selection state to ProductPublishingController (toggleMultiSelect, clearMultiSelection, selectAllVisible, isMultiSelected, multiSelectedIds, multiSelectedCount). Updated ProductDraftCard with optional leading checkbox for multi-select mode. Added _MultiSelectBar to ProductPublishingPage with selected-count display, Select All, and Clear actions. Single-item preview selection preserved independently. 15 new multi-select tests added (262 total feature_wordpress tests passing). No bulk writes introduced.

Stage 3B — List efficiency improvements ✅ COMPLETE

Merged feat/list-efficiency-improvements → main (2026-05-22). Added compact/standard view toggle (ListDensity enum), staleness detection (isStale(), staleCount() with 30-day threshold), keyboard navigation (selectNextDraft/selectPreviousDraft with wrapping), description snippet in standard card, and stale indicator icon. Updated ProductDraftCard with compact two-row layout variant and Flexible overflow handling. Page wires up Focus+onKeyEvent for arrow keys and density toggle button. 32 new tests added (294 total feature_wordpress tests passing). Stage 3 complete.

Stage 4 — Platform foundations and cross-platform readiness

Objective

Strengthen the shared platform infrastructure before expanding to Android. This stage implements the key recommendations from the codebase analysis to reduce technical debt, prevent duplication, and establish quality gates.

Key principle

Invest in shared foundations now so that the Android expansion (Stage 5) and all future feature work benefits from a mature design system, shared composition patterns, automated CI/CD, and proper test coverage tracking.

Branches

  • feat/design-system-shared-widgets
  • feat/flutter-cicd
  • feat/shared-composition-pattern

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

Merged feat/design-system-shared-widgets → main (2026-05-22). Migrated EmptyStatePanel, SectionHeader, and SummaryCard from kell_web/lib/shell/widgets/ into design_system as KcEmptyState, KcSectionHeader, and KcSummaryCard. Added KcTypography shared typography scale, KcBreakpoints responsive layout breakpoint utilities, KcLoadingState and KcErrorState shared state widgets. Updated kell_web dashboard to use design_system widgets directly; shell widget files now contain backward-compatible typedefs. Theme updated to use KcTypography.applyKcTypography(). 41 new design_system tests added (41 total design_system tests, 294 feature_wordpress tests, 24 kell_web tests — all passing). Analyze clean.

Stage 4B — Cross-platform shell composition strategy

Goal

Extract or document a shared app composition pattern so kell_mobile can mirror the kell_web architecture without forking logic.

Requirements
  • evaluate whether AppServices, AppScope, AppConfig, and Bootstrap should move to a shared package (e.g., core or new app_shell) or remain duplicated with a documented contract
  • if extracting: create shared composition abstractions in the chosen package
  • if duplicating: document the contract explicitly so kell_mobile follows the same pattern
  • do not change runtime behavior of kell_web
Definition of done
  • composition strategy is decided and documented
  • shared abstractions extracted or duplication contract documented
  • kell_web still works identically
  • analyze clean, existing tests passing

Stage 4C — Flutter CI/CD pipeline

Goal

Establish automated validation for Flutter applications in Forgejo Actions.

Requirements
  • add Forgejo Actions workflow for dart analyze on PRs
  • add Forgejo Actions workflow for flutter test execution on PRs (per package)
  • add basic test result reporting (pass/fail count per package)
  • ensure workflows work for both web and Android targets
  • populate tools/ directory with any CI helper scripts if needed
Definition of done
  • PRs trigger automated analyze and test runs
  • test counts are reported in workflow output
  • workflow files committed under .forgejo/workflows/
  • tools/ directory populated or removed if not needed

Stage 4D — Test coverage visibility

Goal

Introduce lightweight test coverage tracking across packages.

Requirements
  • add coverage measurement to CI pipeline (at minimum: total tests and pass rate per package)
  • document current baseline coverage in this brief or a companion document
  • do not enforce minimum thresholds yet — visibility first
Definition of done
  • coverage data is generated and visible in CI output
  • baseline coverage documented
  • no regressions in existing tests

Stage 5 — Android application foundation

Objective

Bring the current operations platform capabilities to Android using shared packages first and platform-specific UI only where required.

Key principle

Business logic, domain logic, repositories, and feature application logic should remain shared. Android should primarily add a dedicated app shell and mobile-optimized presentation.

Branches

  • feat/android-app-shell
  • feat/android-publishing-surface

Stage 5A — Android app shell and bootstrap

Goal

Create the Android app entry and shell for the existing platform.

Requirements
  • add or adapt app target for Android
  • reuse shared packages and feature modules
  • preserve runtime environment selection model
  • ensure FAKE mode works cleanly on Android first
  • mobile shell/navigation should stay simple and consistent with shared app structure
Current state note

kell_mobile exists as a default Flutter counter template. It does not yet reference any shared packages (core, design_system, feature_*). This stage must replace the template with a proper app shell that mirrors the kell_web composition pattern (AppServices, AppScope, routing, shell).

Definition of done
  • app runs on Android emulator/device in FAKE mode
  • shell, navigation, and core screens render
  • analyze/tests remain clean
  • kell_mobile/pubspec.yaml references shared packages

Stage 5B — Android publishing surface

Goal

Adapt the publishing workflow for mobile form factor.

Requirements
  • reuse shared controller/use case/repository layers
  • optimize preview/edit interactions for smaller screens
  • keep feature parity for current publishing workflow where feasible
  • do not fork business rules for Android
Definition of done
  • Android supports browsing, filtering, status changes, and existing narrow edits
  • mobile presentation is usable and tested where practical

Stage 6 — Android operational maturity

Objective

Harden Android UX after the core feature surface works.

Branches

  • feat/android-feedback-polish
  • feat/android-mobile-ux-hardening

Stage 6A — Android feedback and action polish

Goal

Ensure action feedback patterns translate cleanly to Android.

Requirements
  • reuse shared action result model where possible
  • adapt SnackBar/feedback timing and presentation appropriately
  • validate status/edit workflows on mobile

Stage 6B — Android mobile workflow hardening

Goal

Improve ergonomics on smaller screens.

Requirements
  • verify scrolling/selection/edit flows
  • ensure touch targets and inline edit behavior are mobile-friendly
  • refine layout without changing shared domain/application contracts

Stage 7 — Controlled bulk actions (only after groundwork)

Objective

Add carefully scoped bulk operations once single-item workflows are stable across web and Android.

Branches

  • feat/bulk-status-actions
  • feat/bulk-operator-workflows

Entry criteria

Do not begin until:

  • single-item edit/status flows are stable
  • multi-select groundwork is complete
  • post-write consistency is hardened
  • Android core publishing surface exists

Candidate first bulk action

  • bulk move to draft

Explicitly defer

  • bulk generic edit
  • bulk category management
  • destructive bulk deletion unless separately justified

Suggested improvements (identified from codebase analysis)

This section captures structural improvements, coverage gaps, and maturity enhancements identified through codebase analysis against the architecture documentation and current implementation state. Items here are candidates for future stages or can be woven into existing stages as appropriate.

1. Stub package activation roadmap

The following packages exist as scaffolded stubs with no implementation. Each needs an activation plan aligned to architecture documentation:

Package Architecture Reference Priority Notes
auth Enterprise Identity & Access Architecture High No auth layer exists; all access is currently uncontrolled. Required before any multi-user or production deployment.
data Enterprise Data Architecture Medium Shared data abstractions/caching could reduce duplication across feature repositories.
integrations Enterprise Integration & Orchestration Architecture Medium Shared integration contracts could formalize API client patterns currently embedded in feature_wordpress.
feature_finance Financial Analysis Components Low Architecture docs exist but no implementation. Defer until core WordPress/Inventory workflows mature.
feature_mrp Craft Manufacturing / MRP Components Low Architecture docs exist but no implementation. Defer until inventory workflows mature.
feature_social Social Media Management Components Low Architecture docs exist but no implementation. Defer until core platform stabilizes.

Recommendation: Add a Stage 8 — Infrastructure package activation to the roadmap covering auth, data, and integrations before expanding into new feature domains.

2. Design system expansion

The design_system package currently contains:

  • Theme: KcColors, KcSpacing, KcTheme
  • Widgets: KcCard, KcStatusChip

Gaps identified:

  • No shared typography scale
  • No shared button/action component library
  • No responsive layout utilities for cross-platform (web + mobile)
  • No shared empty state, loading state, or error state patterns
  • Shell widgets (EmptyStatePanel, SectionHeader, SummaryCard) live in kell_web app rather than design_system

Recommendation: Now addressed in Stage 4A (Design system expansion and shared widget migration). Migrate reusable shell widgets into design_system and add responsive layout primitives before the Android expansion in Stage 5.

3. Cross-platform shell composition strategy

kell_web uses a well-structured composition pattern (AppServices, AppScope, AppConfig, Bootstrap). kell_mobile has none of this — it's a default counter app.

Recommendation: Extract a shared shell composition pattern or at minimum define a documented convention so that kell_mobile mirrors the kell_web architecture. Consider whether AppServices, AppScope, and bootstrap logic should move to a shared core or app_shell package, or remain duplicated with a documented contract.

4. CI/CD for Flutter applications

Currently, CI/CD exists only for MkDocs documentation publishing. There is no automated pipeline for:

  • Flutter dart analyze on PRs
  • Flutter test execution on PRs
  • Flutter build validation (web + Android)
  • Test result reporting or quality gates

Recommendation: Now addressed in Stage 4C (Flutter CI/CD pipeline). Establish Flutter CI/CD in Forgejo Actions before the Android expansion in Stage 5 adds more surfaces to validate.

5. Test coverage visibility and quality gates

Test counts are tracked manually in this brief (e.g., 294/294 passed). There is no:

  • Automated test count reporting
  • Coverage measurement
  • Minimum coverage threshold enforcement
  • Test trend tracking across slices

Recommendation: Introduce coverage tooling and reporting as part of CI/CD establishment. Even lightweight coverage tracking (total tests, pass rate per package) would improve confidence during the Android expansion.

6. Build execution tracker synchronization

The build_execution_tracker.md is stale:

  • Shows feat/multi-select-groundwork as "queued" when it was merged 2026-05-22
  • Does not include feat/list-efficiency-improvements at all
  • current status section references Stage 3 as current when Stage 3 is complete

Recommendation: Update the tracker immediately and consider whether the tracker should be auto-generated or at minimum updated as part of the standard slice completion checklist.

7. Image and media management

Architecture documentation (traceability-index.md coverage gaps) identifies "Product image / media synchronization workflow" as a gap. The current publishing workflow handles text fields only.

Recommendation: Plan a future stage for image/media management once existing narrow edits are stable on both platforms. This aligns with the architecture gap analysis.

8. Error tracking and observability

No monitoring, error tracking, or analytics strategy exists for the Flutter applications. In production use:

  • Runtime errors are invisible unless the operator sees them
  • No crash reporting
  • No usage analytics to guide prioritization

Recommendation: Add lightweight error reporting and observability as a future stage, particularly important before any production WP-mode deployment beyond a single operator.

9. Empty tools directory

The tools/ directory under kell_creations_apps exists but contains nothing.

Recommendation: Either populate with development tooling (code generation scripts, analysis helpers, CI scripts) or remove to avoid confusion. If CI/CD scripts are planned, this is a natural home.

10. Missing feature parity documentation

The architecture documentation describes rich capabilities across all domains (Inventory, MRP, WordPress, Social Media, Financial Analysis), but actual implementation maturity varies dramatically. Only feature_wordpress has substantial implementation.

Recommendation: Add a feature maturity matrix to this brief or a companion document that maps architecture aspirations to actual implementation status per feature package. This would make prioritization conversations clearer.

Required development workflow for every slice

For every branch/stage:

  1. Start from latest main.
  2. Inspect first.
  3. Write a brief inspection report.
  4. Propose the smallest implementation plan.
  5. Implement only the current slice.
  6. Run targeted tests.
  7. Run flutter analyze or dart analyze as appropriate.
  8. Summarize changed files and validation results.
  9. Open PR into main.
  10. Merge only after clean review and validation.
  11. Update this brief and the build execution tracker after merge.

Standard Cline operating prompt

Use this at the start of any new slice:

Continue the Kell Creations Flutter operations platform workstream from current main.

Read docs/development/master_development_brief.md first and follow it as the authoritative planning document.

Constraints:
- Preserve strict package boundaries.
- Fake repositories remain in feature packages.
- Real integrations are incremental alongside fake ones.
- Runtime selection stays via --dart-define, not settings UI.
- No credentials hardcoded or committed.
- Do not broaden into generic product editing prematurely.
- Keep WooCommerce details inside the WP repository layer.
- Use small, reviewable steps only.
- Work is being driven through Cline in Windows 11 VS Code.

Working rules:
1. Inspect first. Do not edit immediately.
2. Summarize current relevant state from main.
3. Propose the smallest implementation plan for the requested slice.
4. Implement only that slice.
5. Add/update focused tests.
6. Run validation.
7. Report changed files and validation results.
8. Update master_development_brief.md and build_execution_tracker.md after merge.

Appendix: Feature maturity matrix

Package Domain Layer Application Layer Data (Fake) Data (Real) Presentation Tests Maturity
feature_wordpress ✅ Complete ✅ Complete ✅ Complete ✅ WooCommerce ✅ Complete 294 Production-ready
feature_inventory ✅ Complete ✅ Complete ✅ Complete ❌ None ✅ Complete Minimal Fake-only MVP
feature_orders ✅ Complete ✅ Complete ✅ Complete ❌ None ✅ Complete Some Fake-only MVP
feature_policy ✅ Complete ✅ Complete ✅ Complete ❌ None ✅ Complete Minimal Fake-only MVP
feature_finance ❌ Stub ❌ Stub ❌ Stub ❌ None ❌ Stub None Scaffolded only
feature_mrp ❌ Stub ❌ Stub ❌ Stub ❌ None ❌ Stub None Scaffolded only
feature_social ❌ Stub ❌ Stub ❌ Stub ❌ None ❌ Stub None Scaffolded only
auth ❌ Stub ❌ Stub ❌ Stub ❌ None N/A None Scaffolded only
data ❌ Stub N/A N/A ❌ None N/A None Scaffolded only
integrations ❌ Stub N/A N/A ❌ None N/A None Scaffolded only
design_system N/A N/A N/A N/A ✅ Expanded (theme, typography, layout, 7 widgets) 41 Foundation ready
core ✅ Partial N/A N/A N/A N/A 20 Foundation ready