Skip to content

IMPLEMENTATION_PLAN.md

Latest commit

 

History

History
224 lines (181 loc) · 9.83 KB

IMPLEMENTATION_PLAN.md

File metadata and controls

224 lines (181 loc) · 9.83 KB

🗓️ Implementation Plan: BackLogAI

Phased Roadmap, Key Milestones & Estimated Timelines

This document tracks the development progress of the BackLogAI project.

Current Phase: Phase 8 (Windows Client) 🚧 In Progress

🏗️ Phase 1: Project Initialization & Architecture Setup

Goal: Establish the monorepo structure, development environment, and core backend infrastructure. Status: Status

  • Repository Setup (Monorepo)
    • Initialize Git repository.
    • Structure: /backend, /shared, /composeApp, /infra.
  • Backend Infrastructure (Dockerized)
    • Database: Setup PostgreSQL container.
    • Backend: Setup Python 3.11+ container with FastAPI and Uvicorn.
    • ORM: Configure Tortoise-ORM/SQLAlchemy (Async).
    • Migrations: Initialize Aerich or Alembic.
  • Authentication (SSO/OAuth)
    • Implement OAuth2 flow (Google/GitHub) with authlib.
    • Create User model.
    • Secure API endpoints (JWT).

🧠 Phase 2: Core Backend Logic (The "Brain")

Goal: Implement the pillars, story generation, and prioritization engines. Status: Status

  • Input Module & Data Models
    • Define Pydantic models for the 5 Key Pillars.
    • Create API endpoints to validate project context.
  • Story Generation Engine (AI-Powered)
    • Integration: Connect to OpenAI API / Claude 3.5.
    • Prompt Engineering: Enforce "Why now? Why this? Why us?".
    • Logic: Implement Epics → Stories → Tasks decomposition.
  • Prioritization Engine
    • Implement RICE algorithm.
    • Implement WSJF algorithm.
    • Implement MoSCoW logic.
  • Quality Validation Engine
    • Implement INVEST criteria checks.
    • Return warnings for vague stories.

🔌 Phase 3: JIRA Integration & API

Goal: Connect the generated backlog to the real world. Status: Status

  • JIRA Connector
    • Implement Atlassian Python API wrapper.
    • Map internal Story models to JIRA Issue types.
    • Push Logic: Create/Update issues, link Epics to Stories.
    • Pull Logic: Sync status updates.
  • API Polish
    • Finalize REST API documentation (Swagger/OpenAPI).
    • Ensure all endpoints are async.

🔄 Phase 4: Kotlin Multiplatform (KMP) Shared Logic

Goal: Write business logic once, run everywhere. Status: Status

  • Shared Module Setup
    • Configure KMP for Android, iOS, JVM (Desktop), and Wasm (Web).
  • Networking & Data
    • Ktor Client: Implement API client.
    • Serialization: kotlinx.serialization (JSON).
    • Repositories: Auth, Backlog, Settings.
  • View Models
    • Implement shared ViewModels (MVVM).

📱 Phase 5: Compose Multiplatform UI

Goal: Build a beautiful, responsive interface for all targets. Status: Status

  • Design System
    • Implement Material 3 theme.
    • Components: PillarInputCard, StoryCard, PriorityBadge, KanbanBoard.
  • Screens Implementation
    • Login Screen: SSO handling.
    • Dashboard: High-level metrics.
    • Wizard/Input: Multi-step form for 5 Pillars.
    • Backlog View: List/Kanban, Edit Mode.
    • JIRA Sync: Status dashboard.
  • Platform Specifics
    • Desktop: Window management.
    • Mobile: Touch interactions.
    • Web: Responsive layout.

✅ Phase 6: Testing & Quality Assurance

Goal: Ensure reliability and correctness. Status: Status

  • Backend Testing
    • Unit tests (pytest).
    • Integration tests.
  • Frontend Testing
    • UI tests (Compose).
    • Unit tests (Shared KMP).
  • Performance
    • Verify "under 60 seconds" generation requirement.

💬 Phase 7: Slack Client Integration

Goal: Add Slack as a new client channel for story generation and Jira sync without impacting Android/iOS/macOS behavior. Status: Status

  • Slack App & Connectivity

    • Create Slack app with scopes (chat:write, commands, interactivity).
    • Configure command and interaction callback URLs.
    • Setup secure tunnel (Cloudflare Tunnel) to local backend endpoint.
    • Validate Slack request signature verification and timestamp replay checks.

  • Secure Connectivity (Quick Tunnel for Live Local Demo)

    • Install cloudflared on host machine.
    • Start quick tunnel for BacklogAI callback host.
    • Start quick tunnel for Jira host access.
    • Validate callback behavior (405 on GET, 401 on unsigned POST).
    • Document URL rotation procedure in SLACK_QUICK_TUNNEL_CHECKLIST.md.

  • Production Hardening (Deferred)

    • Migrate from quick tunnels to named tunnel + stable DNS.
    • Create Cloudflare Access self-hosted app for Jira public hostname.
    • Add primary allow policy (team email domain allow-list).
    • Confirm authenticated users can access Jira through protected URL.

  • Slack Bypass Policy for Jira Endpoints (Deferred)

    • Add bypass policy for Jira Slack integration path: /rest/slack/latest/*.
    • Add Slack source IP ranges:
      • 3.23.0.0/14
      • 3.120.0.0/14
      • 35.154.0.0/15
      • 44.192.0.0/11
      • 52.64.0.0/13
      • 54.64.0.0/13
    • Ensure bypass policy priority is above team access allow policy.

  • Jira + Slack Finalization (Local Runtime)

    • Keep Jira on local runtime and validate issue creation through Slack flow.
    • Add Jira URL host fallback for local non-Docker backend runtime.
    • Confirm repeated Slack sync clicks do not create duplicate Jira issues.

  • Backend Slack Adapter Layer

    • Implement POST /slack/commands (launch input modal).
    • Implement POST /slack/interactions (modal submit + action buttons).
    • Add modal key/value parser mapped to BacklogItemGenerateV2Request.
    • Build Slack Block Kit responses for Story Preview and actions.
    • Add non-blocking command ACK path to avoid Slack dispatch_unknown_error.

  • Story Preview & Jira Sync Flow

    • Generate Story Preview using existing v2 generation pipeline.
    • Post preview message back to Slack channel.
    • Implement "Sync to JIRA" action path reusing existing Jira sync service.
    • Post Jira ticket key and URL back to Slack after successful sync.

  • State, Idempotency & Reliability

    • Persist Slack session state (input payload, preview payload, sync status).
    • Prevent duplicate Jira tickets on repeated sync actions.
    • Return existing Jira key/URL for repeated sync clicks.

  • Validation & Regression

    • Validate end-to-end Slack flow: input -> preview -> sync -> Jira response.
    • Add tests for signature validation, payload mapping, and idempotency.
    • Re-verify Android/iOS/macOS flows remain unchanged.

  • Scope Note

    • Existing clients remain active: Android, iOS, macOS Desktop.
    • Windows client rollout is tracked separately in Phase 8.

  • Documentation & Demos

    • Publish Slack live setup guide and quick tunnel checklist.
    • Update implementation and architecture docs for Slack runtime behavior.
    • Add v3 demo assets for Slack and client app flows under demo/.

🪟 Phase 8: Windows Client (Compose Desktop)

Goal: Deliver a modern Windows desktop client with end-to-end story generation and Jira sync using Kotlin Multiplatform + Compose. Status: Status

  • Planning & Scope Baseline

    • Confirm architecture path: reuse desktopMain Compose codebase.
    • Define distribution strategy: MSI installer + portable ZIP.
    • Document Phase 8 plan in project roadmap.

  • Windows Runtime UX Modernization

    • Improve desktop window defaults (initial size, minimum size, usability baseline).
    • Refine desktop-friendly spacing and readability in Input/Result screens.
    • Add clear desktop interaction feedback for generate/sync states.

  • Windows Packaging & Distribution

    • Build Windows installer artifact (.msi) using Compose Desktop distribution tasks.
    • Build portable Windows ZIP package for no-installation usage.
    • Publish Windows binaries under demo/binaries-v3/windows/.

  • Windows End-to-End Validation

    • Validate flow on Windows runtime: health -> generate v2 -> sync v2.
    • Verify error handling UX (API unavailable, sync failures, retry behavior).
    • Capture Windows demo assets under demo/windows-e2e-v3/.

  • Cross-Platform Regression

    • Re-verify Android, iOS, and macOS behaviors remain unchanged.
    • Re-verify Slack client flow remains stable after desktop updates.

  • Documentation Track (Initial)

    • Update README support matrix to reflect Windows in-progress status.
    • Add Windows setup and release checklist docs.
    • Add architecture notes for shared desktop path (macOS + Windows).

  • Documentation Track (Completion)

    • Mark Windows client as live after successful E2E validation.
    • Link final Windows demos and binaries in README.