sepehr/GitPulse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: GitPulse project scaffold

Browse Source 
Next.js dashboard with git statistics, AI-powered summaries via Ollama,
and research documents for project planning.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
sepehr
2026-04-25 16:53:39 +02:00
commit 4f7e808855
459 changed files with 75418 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

705
_bmad-output/planning-artifacts/architecture.md Normal file
View File

@@ -0,0 +1,705 @@
---
stepsCompleted: [step-01-init, step-02-context, step-03-starter, step-04-decisions, step-05-patterns, step-06-structure, step-07-validation, step-08-complete]
inputDocuments:
- "prd.md"
- "product-brief-gitpulse.md"
- "product-brief-gitpulse-distillate.md"
- "research/market-git-dashboard-ia-research-2026-04-24.md"
workflowType: 'architecture'
project_name: 'GitPulse'
user_name: 'Ramez'
date: '2025-04-25'
lastStep: 8
status: 'complete'
completedAt: '2025-04-25'
---
# Architecture Decision Document
_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._
## Project Context Analysis
### Requirements Overview
**Functional Requirements (46 FRs across 7 capability areas):**
| Area | FRs | Architectural Implication |
|------|-----|--------------------------|
| Repository Discovery | FR1-FR7 | Filesystem scanner, `.gitpulseignore` parser, local cache |
| Dashboard & Visualization | FR8-FR14 | React component library, virtualized rendering, state management |
| Batch Operations | FR15-FR21 | Git process spawner, async execution engine, per-repo error aggregation |
| Smart Status (AI) | FR22-FR30 | AI provider abstraction layer, per-task routing, prompt engineering |
| System Tray & Notifications | FR31-FR35 | Platform abstraction, native OS bindings, background monitoring |
| Settings & Configuration | FR36-FR41 | Local persistence layer, settings schema, OS keychain integration |
| Onboarding & Distribution | FR42-FR46 | Build/packaging pipeline, cross-platform CI, code signing |
**Non-Functional Requirements (27 NFRs driving architecture):**
- **Performance (NFR1-8):** Tauri + Rust answers binary size, RAM, startup time, and scan speed targets. Virtualized rendering for 100+ repos. Async AI loading prevents UI blocking.
- **Security (NFR9-15):** OS keychain for API keys, git process isolation, privacy-by-default, zero telemetry.
- **Integration (NFR16-20):** Provider abstraction with graceful fallback, Git >= 2.20 compatibility, native OS APIs.
- **Reliability (NFR21-24):** Fault-tolerant scan/batch engines, crash recovery via persisted state, settings survival across updates.
- **Accessibility (NFR25-27):** Keyboard navigation, ARIA markup, high contrast support.
**Scale & Complexity:**
- Primary domain: Cross-platform desktop application (Rust backend + React frontend + native OS integrations)
- Complexity level: Medium — no regulatory compliance, but significant cross-platform surface area, multi-provider AI integration, and native system integration requirements
- Estimated architectural components: 8-10 major modules
### Technical Constraints & Dependencies
- **Tauri v2** — defines the IPC boundary (Rust ↔ React), binary packaging format, and system integration APIs
- **Rust backend** — handles all filesystem I/O, git process execution, AI API calls, and native OS interactions
- **React frontend** — runs in platform-native webview (WebView2/WebKit/WebKitGTK); no server-side rendering
- **Git CLI dependency** — requires Git >= 2.20 installed; GitPulse shells out to git commands
- **Ollama dependency (optional)** — local AI via Ollama API v1; auto-detection of running instance
- **Cloud API dependencies (optional)** — user-provided API keys for Gemini, DeepSeek, OpenAI, Anthropic
- **No database** — file-based storage (JSON/TOML) for settings and scan cache
- **No server component** — fully local; only outbound requests are AI API calls and update checks
- **Single binary distribution** — ~15MB target; no installer wizard
- **Solo developer** — architecture must be maintainable by one person; avoid over-engineering
### Cross-Cutting Concerns Identified
1. **IPC Boundary Design** — Every React ↔ Rust interaction crosses the Tauri IPC bridge. Command/event API design determines modularity and testability.
2. **Error Handling Strategy** — Partial success pattern (FR20, NFR22) applies to batch ops, AI calls, and scanning. Unified error handling prevents inconsistency.
3. **State Management** — Scan results, repo status, AI responses, settings, and tray state need coordinated management. Rust-side = source of truth; React-side = presentation cache.
4. **Platform Abstraction** — System tray (FR31), notifications (FR32), auto-launch (FR34), keychain (NFR9) all need platform-specific implementations behind common interfaces.
5. **Privacy & Data Flow** — Privacy indicator (FR27) requires knowing whether data is local or cloud-bound at all times. Must permeate AI provider layer and UI.
6. **Offline Resilience** — Every feature works without network. AI degrades gracefully, updates are manual, no cloud dependencies. Architecture never assumes connectivity.
## Starter Template Evaluation
### Primary Technology Domain
Desktop Application — Tauri v2 + Rust backend + React frontend
### Selected Starter: create-tauri-app (react-ts)
**Rationale:** Official scaffold, minimal opinion, Tauri v2 native, actively maintained (90k+ GitHub stars), fits solo developer context.
**Initialization Command:**
```bash
npm create tauri-app@latest -- --template react-ts --manager npm gitpulse
```
**Architectural Decisions Provided by Starter:**
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Build tool | Vite | Default Tauri v2 bundler, fast HMR, optimized builds |
| Frontend language | TypeScript | Type safety for IPC boundary with Rust |
| Frontend framework | React 18+ | Specified by PRD |
| Package manager | npm | Standard, no friction |
| Rust toolchain | Cargo (via Tauri) | Standard Rust |
| IPC system | Tauri commands/events | Official v2 pattern |
| Permissions | Capabilities system (v2) | Replaces v1 allowlist |
**Stack Additions (post-scaffold):**
| Concern | Recommendation | Why |
|---------|---------------|-----|
| State management | Zustand | Lightweight, no boilerplate, fits solo dev |
| Styling | Tailwind CSS | Rapid prototyping, utility-first |
| Testing (unit) | Vitest | Native Vite, fast, TypeScript compatible |
| Testing (e2e) | Playwright (webview) | Cross-platform, real UI testing |
| Linting | ESLint + Prettier | Standard React/Rust |
| Tauri plugins | `tauri-plugin-store`, `tauri-plugin-shell`, `tauri-plugin-fs` | Settings persistence, git execution, filesystem access |
**Note:** Project initialization using this command should be the first implementation story.
## Core Architectural Decisions
### Decision Priority Analysis
**Already Decided (from PRD + Starter):**
- Framework: Tauri v2 + Rust + React TypeScript
- Build: Vite | Package manager: npm
- State: Zustand | Styling: Tailwind CSS
- Testing: Vitest (unit) + Playwright (e2e)
- No database, no authentication, no cloud hosting
**Critical Decisions (made in this step):**
- Data storage strategy (file-based)
- Security implementation (keyring, process isolation)
- IPC boundary design (commands vs events)
- Frontend module structure
- Cross-platform build pipeline
**Deferred Decisions (Post-MVP):**
- File watcher architecture (Phase 2)
- MCP integration design (Phase 3)
- Auto-update mechanism (Phase 1.5)
- CLI companion architecture (Phase 2)
### Data Architecture
**Storage Strategy: File-based, no database.**
| Data Type | Format | Storage | Rationale |
|-----------|--------|---------|-----------|
| User settings (scan roots, AI config, notification thresholds) | TOML | `tauri-plugin-store` (OS app data dir) | Human-readable, Rust-native, editable by power users |
| Scan cache (repo list, git status results) | JSON | `tauri-plugin-store` (OS app data dir) | Machine-to-machine, fast parse, no manual editing needed |
| API keys | Encrypted | OS keychain via Rust `keyring` crate | NFR9: not plaintext, native security |
| `.gitpulseignore` rules | Glob | Per-directory `.gitpulseignore` files | .gitignore syntax, user-controlled |
**Persistence approach:** `tauri-plugin-store` handles all file I/O, platform-specific paths, and atomic writes. No manual file management needed.
### Security Architecture
**API Key Storage:**
- Crate: `keyring` (Rust) — wraps Windows Credential Manager, macOS Keychain, Linux secret-service/kerberos
- Keys never transit to frontend — only a "configured/not configured" boolean crosses IPC
- Cloud API keys stored per-provider with service name `gitpulse:{provider_name}`
**Git Process Isolation:**
- All git commands executed via `tokio::process::Command` — async, isolated child processes
- Each git invocation runs in its own process with timeout (configurable, default 60s)
- stdout/stderr captured per-repo, never mixed across batch operations
- No shell expansion — arguments passed as `Vec<String>`, preventing injection
**Privacy Architecture:**
- Default mode: all processing local. No outbound network requests except manual update check
- AI provider layer tracks "active provider type" (local/cloud) in Rust state
- Frontend queries privacy status via IPC command — drives PrivacyBadge component (FR27)
- When cloud provider is active, all prompts include metadata that data will transit externally
### API & Communication (Tauri IPC)
**Dual IPC pattern: Commands (request/response) + Events (pub/sub)**
| Operation Type | IPC Pattern | Flow |
|---------------|-------------|------|
| Scan trigger | Command → Events | `start_scan` → `scan:progress` + `scan:complete` |
| Batch operations | Command → Events | `batch_pull` → `batch:repo_result` (streaming per-repo) |
| AI queries | Command → Events | `smart_status` → `ai:result` (async, non-blocking) |
| Settings CRUD | Command only | `get_settings` / `update_settings` (synchronous) |
| Tray actions | Command only | `tray_pull` / `tray_status` (quick operations) |
**Error handling across IPC:**
- All Tauri commands return `Result<T, AppError>` where `AppError` is a structured error type
- Frontend receives typed errors — no string matching
- Batch operations emit per-repo events with `Result<RepoResult, RepoError>` — partial success pattern
### Rust Backend Module Structure
```
src-tauri/src/
├── commands/
│ ├── mod.rs # Module registration
│ ├── scanner.rs # FR1-FR7: scan commands
│ ├── dashboard.rs # FR8-FR14: query/filter/sort
│ ├── batch.rs # FR15-FR21: batch git ops
│ ├── ai.rs # FR22-FR30: Smart Status
│ ├── tray.rs # FR31-FR35: system tray
│ └── settings.rs # FR36-FR41: configuration
├── providers/
│ ├── mod.rs # AI provider trait definition
│ ├── ollama.rs # Ollama API v1 implementation
│ ├── gemini.rs # Google Gemini implementation
│ ├── deepseek.rs # DeepSeek implementation
│ ├── openai.rs # OpenAI implementation
│ └── anthropic.rs # Anthropic implementation
├── git.rs # Git process execution engine
├── ignore.rs # .gitpulseignore glob parser
├── scanner.rs # Recursive disk scanner logic
├── state.rs # Shared application state (Tauri managed)
└── lib.rs # Tauri builder, plugin registration, command registration
```
**AI Provider Abstraction:**
```rust
// providers/mod.rs
#[async_trait]
pub trait AiProvider {
async fn health_summary(&self, repo_context: &RepoContext) -> Result<String, AiError>;
async fn suggest_commit_message(&self, diff: &str) -> Result<String, AiError>;
async fn cross_repo_analysis(&self, repos: &[RepoContext]) -> Result<String, AiError>;
fn provider_type(&self) -> ProviderType;
fn is_local(&self) -> bool;
}
```
Each provider implements this trait. The `is_local()` method drives the privacy indicator.
### Frontend Architecture
```
src/
├── components/
│ ├── ui/ # Primitives: Button, Badge, Card, Input, Dialog
│ ├── dashboard/
│ │ ├── CardGrid.tsx # FR8: card grid view
│ │ ├── RepoCard.tsx # FR8, FR13: individual repo tile
│ │ ├── ListView.tsx # FR9: sortable/filterable list
│ │ ├── RepoRow.tsx # FR9: individual repo row
│ │ └── ViewToggle.tsx # FR10: grid/list toggle
│ ├── batch/
│ │ ├── BatchPanel.tsx # FR15-FR18: batch operation controls
│ │ └── BatchResults.tsx # FR19-FR21: per-repo results display
│ ├── ai/
│ │ ├── SmartStatus.tsx # FR24-FR26: AI summaries display
│ │ ├── PrivacyBadge.tsx # FR27: local/cloud indicator
│ │ └── AiConfig.tsx # FR22-FR23, FR29: provider configuration
│ └── settings/
│ └── SettingsPanel.tsx # FR36-FR41: configuration UI
├── hooks/
│ ├── useScan.ts # Scan state + triggers
│ ├── useRepos.ts # Repository list + filters
│ ├── useBatch.ts # Batch operation state
│ └── useAi.ts # AI provider state + privacy mode
├── stores/
│ ├── repoStore.ts # Zustand: repo list, filters, sort
│ ├── scanStore.ts # Zustand: scan state, progress
│ └── aiStore.ts # Zustand: AI config, active provider, privacy
├── lib/
│ ├── invoke.ts # Typed Tauri invoke wrappers
│ └── events.ts # Typed Tauri event listeners
├── types.ts # Shared TypeScript types (mirrors Rust structs)
├── App.tsx
└── main.tsx
```
**State management principle:**
- **Rust = source of truth.** All data originates from Rust (scan results, git status, AI responses).
- **React = presentation cache.** Zustand stores are populated via Tauri IPC responses and events.
- **Stores never contain business logic.** They reflect Rust state, not compute independently.
### Infrastructure & Deployment
**Cross-platform CI/CD (GitHub Actions):**
- Matrix build: Windows x64, macOS x64 + ARM, Linux x64
- Tauri CLI handles per-platform packaging
- Artifacts: `.exe` (Windows), `.dmg` (macOS), `.deb` + `.AppImage` (Linux)
- Triggered on version tags (`v*`) for releases
- Lint + test (Rust + TypeScript) on every PR
**Code signing (Phase 1.5):**
- Windows: Authenticode certificate (~$200-500/year)
- macOS: Apple Developer account ($99/year) + notarization
- Linux: GPG signing for APT repository
**Distribution:** GitHub Releases as primary channel. No auto-update in MVP (FR44: manual check only).
### Decision Impact Analysis
**Implementation Sequence:**
1. Scaffold project (`create-tauri-app`) + configure Zustand/Tailwind/Vitest
2. Rust: `git.rs` (process engine) + `scanner.rs` (disk scanner) + `ignore.rs`
3. Rust: `state.rs` (app state) + `commands/scanner.rs` (IPC)
4. React: `CardGrid` + `RepoCard` + `useScan` hook
5. Rust: `commands/batch.rs` + `git.rs` batch execution
6. React: `ListView` + `BatchPanel` + `BatchResults`
7. Rust: `providers/` trait + `ollama.rs` + `commands/ai.rs`
8. React: `SmartStatus` + `PrivacyBadge` + `AiConfig`
9. Rust: `commands/tray.rs` + `commands/settings.rs`
10. CI/CD pipeline setup + cross-platform builds
## Implementation Patterns & Consistency Rules
### Naming Patterns
**Rust Code:**
- Modules/files: `snake_case` (`scanner.rs`, `batch.rs`, `git.rs`)
- Structs/enums: `PascalCase` (`RepoStatus`, `BatchResult`, `AiProvider`)
- Functions/methods: `snake_case` (`scan_disk`, `execute_batch`, `get_health_summary`)
- Constants: `SCREAMING_SNAKE_CASE` (`DEFAULT_SCAN_TIMEOUT_SECS`)
- Tauri commands: `snake_case` (`start_scan`, `batch_pull`, `smart_status`)
**TypeScript/React Code:**
- Components: `PascalCase` (`RepoCard.tsx`, `BatchPanel.tsx`, `PrivacyBadge.tsx`)
- Hooks: `camelCase` with `use` prefix (`useScan`, `useRepos`, `useBatch`)
- Stores: `camelCase` with `Store` suffix (`repoStore.ts`, `aiStore.ts`)
- Functions/variables: `camelCase` (`invokeStartScan`, `activeProviderType`)
- Types/interfaces: `PascalCase` (`Repo`, `BatchResult`, `ScanProgress`)
- Files: `PascalCase` for components, `camelCase` for hooks/stores/lib
**IPC Boundary:**
- Command names: `snake_case` on both sides (Tauri matches directly)
- Event names: `namespace:event` format (`scan:progress`, `batch:repo_result`, `ai:result`)
- Payload types: `PascalCase` in TypeScript, mirroring Rust structs
### Structure Patterns
**Tests:** Co-located — `*.test.ts` beside tested file, `*_test.rs` beside Rust module.
**Components:** Organized by feature (dashboard, batch, ai, settings), not by type.
**Shared types:** `src/types.ts` mirrors Rust structs. Single source of truth.
**No barrel files:** Direct imports, no `index.ts` re-exports.
### Format Patterns
**IPC Command Response (all Tauri commands):**
```rust
// Rust side — all commands return Result<T, AppError>
#[tauri::command]
async fn start_scan(roots: Vec<String>) -> Result<ScanResult, AppError> { ... }
```
```typescript
// TypeScript side — typed wrappers
type CommandResult<T> = { status: "ok"; data: T } | { status: "error"; error: AppError };
```
**Event Payload Format:**
```typescript
{ type: "scan:progress", payload: { current: 5, total: 23 }, timestamp: 1714056600000 }
```
**Dates:** ISO 8601 strings everywhere — never numeric timestamps.
**JSON field naming:** `camelCase` in IPC payloads. Rust structs use `#[serde(rename_all = "camelCase")]`.
### Communication Patterns
**Event namespaces:**
| Namespace | Events |
|-----------|--------|
| `scan` | `scan:started`, `scan:progress`, `scan:complete`, `scan:error` |
| `batch` | `batch:started`, `batch:repo_result`, `batch:complete` |
| `ai` | `ai:query_started`, `ai:result`, `ai:error`, `ai:provider_changed` |
**Zustand store pattern:**
```typescript
interface StoreState<T> {
data: T;
status: 'idle' | 'loading' | 'loaded' | 'error';
error: string | null;
}
```
- Each store = single `create()` call
- Actions = thin wrappers calling Tauri invoke/event listeners
- No business logic in stores — logic lives in Rust
### Process Patterns
**Error handling (Rust):**
- All errors typed via `thiserror` — no `.unwrap()` in production code
- Central `AppError` enum: `ScanError`, `GitError`, `AiError`, `ConfigError`
- Batch errors per-repo: `Vec<RepoOperationResult>` where each item is `Result<RepoResult, RepoError>`
**Error handling (React):**
- Error boundary at App level for fatal errors
- Per-component error states via store `error: string | null`
- No silent `try/catch` — all errors surfaced in UI
**Loading states:**
- Uniform pattern: `{ status: 'idle' | 'loading' | 'loaded' | 'error' }` in each store
- Per-component loading, no global spinner
- Skeleton loading for RepoCard/RepoRow (no layout shift)
### Enforcement Guidelines
**All AI Agents MUST:**
1. Follow naming conventions: `snake_case` Rust, `PascalCase` React components, `camelCase` TypeScript functions
2. Use `#[serde(rename_all = "camelCase")]` on all Rust structs crossing IPC
3. Return `Result<T, AppError>` from all Tauri commands — never panic
4. Use `namespace:event` format for all Tauri events
5. Co-locate tests with tested files (`*.test.ts`, `*_test.rs`)
6. Use Zustand store pattern `{ data, status, error }` — no ad-hoc state
7. Use `tokio::process::Command` for all git operations — never `std::process::Command`
8. Implement `AiProvider` trait for all new AI providers — no provider-specific code outside `providers/`
**Anti-Patterns:**
- No `any` in TypeScript
- No `unwrap()` in Rust production code
- No business logic in React stores
- No barrel files (index.ts re-exports)
- No hardcoded event name strings — use constants
- No synchronous IPC calls for heavy operations — use Commands + Events
## Project Structure & Boundaries
### Complete Project Directory Structure
```
gitpulse/
├── .github/
│ └── workflows/
│ ├── ci.yml # Lint + test on PR
│ └── release.yml # Cross-platform build + release on tag
├── src/ # React Frontend
│ ├── components/
│ │ ├── ui/ # Primitives
│ │ │ ├── Button.tsx
│ │ │ ├── Badge.tsx
│ │ │ ├── Card.tsx
│ │ │ ├── Dialog.tsx
│ │ │ ├── Input.tsx
│ │ │ ├── Select.tsx
│ │ │ ├── Skeleton.tsx
│ │ │ └── Tooltip.tsx
│ │ ├── dashboard/
│ │ │ ├── CardGrid.tsx # FR8
│ │ │ ├── RepoCard.tsx # FR8, FR13
│ │ │ ├── ListView.tsx # FR9, FR11, FR12
│ │ │ ├── RepoRow.tsx # FR9
│ │ │ ├── ViewToggle.tsx # FR10
│ │ │ └── EmptyState.tsx # <10 repos UX
│ │ ├── batch/
│ │ │ ├── BatchToolbar.tsx # FR15-FR18
│ │ │ └── BatchResults.tsx # FR19-FR21
│ │ ├── ai/
│ │ │ ├── SmartStatus.tsx # FR24-FR26
│ │ │ ├── PrivacyBadge.tsx # FR27
│ │ │ └── AiSettings.tsx # FR22-FR23, FR29
│ │ ├── tray/
│ │ │ └── TrayMenu.tsx # FR35
│ │ └── settings/
│ │ ├── SettingsPanel.tsx # FR36-FR41
│ │ ├── ScanRoots.tsx # FR2, FR36
│ │ ├── NotificationSettings.tsx # FR38
│ │ └── TraySettings.tsx # FR39
│ ├── hooks/
│ │ ├── useScan.ts # FR1, FR5, FR7
│ │ ├── useRepos.ts # FR8-FR14
│ │ ├── useBatch.ts # FR15-FR21
│ │ ├── useAi.ts # FR22-FR30
│ │ └── useSettings.ts # FR36-FR41
│ ├── stores/
│ │ ├── repoStore.ts
│ │ ├── scanStore.ts
│ │ ├── batchStore.ts
│ │ ├── aiStore.ts
│ │ └── settingsStore.ts
│ ├── lib/
│ │ ├── invoke.ts # Typed Tauri invoke wrappers
│ │ ├── events.ts # Typed event listeners + constants
│ │ └── utils.ts
│ ├── types.ts # Shared types (mirrors Rust)
│ ├── App.tsx
│ ├── main.tsx
│ └── styles/
│ └── globals.css
├── src-tauri/ # Rust Backend
│ ├── src/
│ │ ├── commands/
│ │ │ ├── mod.rs
│ │ │ ├── scanner.rs # FR1-FR7
│ │ │ ├── dashboard.rs # FR8-FR14
│ │ │ ├── batch.rs # FR15-FR21
│ │ │ ├── ai.rs # FR22-FR30
│ │ │ ├── tray.rs # FR31-FR35
│ │ │ └── settings.rs # FR36-FR41
│ │ ├── providers/
│ │ │ ├── mod.rs # AiProvider trait
│ │ │ ├── ollama.rs
│ │ │ ├── gemini.rs
│ │ │ ├── deepseek.rs
│ │ │ ├── openai.rs
│ │ │ └── anthropic.rs
│ │ ├── git.rs # Git process engine
│ │ ├── ignore.rs # .gitpulseignore parser
│ │ ├── scanner.rs # Disk scanner
│ │ ├── state.rs # App state
│ │ ├── error.rs # AppError enum
│ │ ├── lib.rs # Tauri builder + registration
│ │ └── main.rs # Entry point
│ ├── capabilities/
│ │ └── default.json # Tauri v2 permissions
│ ├── icons/
│ ├── Cargo.toml
│ ├── tauri.conf.json
│ └── build.rs
├── tests/
│ ├── e2e/
│ │ ├── scan.spec.ts
│ │ ├── dashboard.spec.ts
│ │ ├── batch.spec.ts
│ │ ├── ai.spec.ts
│ │ └── settings.spec.ts
│ └── fixtures/
│ └── test-repos/
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
├── vitest.config.ts
├── playwright.config.ts
├── .gitignore
├── .eslintrc.json
├── .prettierrc
└── README.md
```
### Requirements to Structure Mapping
| FR Category | Rust Module | React Components | Store |
|-------------|------------|------------------|-------|
| FR1-FR7: Discovery | `scanner.rs`, `ignore.rs`, `commands/scanner.rs` | `CardGrid`, `RepoCard`, `EmptyState` | `scanStore` |
| FR8-FR14: Dashboard | `commands/dashboard.rs` | `CardGrid`, `ListView`, `RepoCard/Row`, `ViewToggle` | `repoStore` |
| FR15-FR21: Batch Ops | `git.rs`, `commands/batch.rs` | `BatchToolbar`, `BatchResults` | `batchStore` |
| FR22-FR30: Smart Status | `providers/*`, `commands/ai.rs` | `SmartStatus`, `PrivacyBadge`, `AiSettings` | `aiStore` |
| FR31-FR35: Tray | `commands/tray.rs` | `TrayMenu` | — |
| FR36-FR41: Settings | `commands/settings.rs` | `SettingsPanel`, `ScanRoots`, `NotificationSettings`, `TraySettings` | `settingsStore` |
| FR42-FR46: Onboarding | `lib.rs` (build config) | `main.tsx`, `App.tsx` | — |
### Architectural Boundaries
**IPC Boundary (Rust ↔ React):**
- Rust exposes `#[tauri::command]` — React calls via typed `invoke()` wrappers
- Rust emits events — React listens via typed `listen()` wrappers
- Types defined in Rust structs (source of truth), mirrored in `src/types.ts`
**AI Provider Boundary:**
- All providers implement `AiProvider` trait
- Only `commands/ai.rs` accesses providers — no other module knows about providers
- Privacy status (`is_local()`) surfaced via dedicated IPC command
**Git Execution Boundary:**
- Only `git.rs` spawns git processes
- `commands/batch.rs` delegates to `git.rs` for all operations
- Per-repo error isolation — git failures never crash the app
**Platform Abstraction Boundary:**
- System tray, notifications, auto-launch, keychain — all via Tauri plugins (Rust-side)
- No platform-specific code in React
- Feature flags in `tauri.conf.json` for platform-specific capabilities
### Integration Points
**Internal Communication:**
```
React ──invoke()──→ Tauri IPC ──→ Rust Commands ──→ Rust Modules
React ←──listen()── Tauri Events ←── Rust State ←── Module Results
```
**External Integrations:**
- Git CLI: `tokio::process::Command` (isolated processes)
- Ollama: HTTP to `localhost:11434` (local)
- Cloud APIs: HTTPS to provider endpoints
- OS Keychain: `keyring` crate (native)
- OS Notifications: Tauri notification plugin (native)
- Filesystem: `tokio::fs` + `.gitpulseignore` parser
## Architecture Validation Results
### Coherence Validation ✅
**Decision Compatibility:** All technology choices are mutually compatible. Tauri v2 (stable) provides the native tokio runtime for async Rust, the IPC bridge, and webview packaging. React 18+ with TypeScript, Zustand, Tailwind, and Vitest is a standard, battle-tested frontend stack. `keyring` crate wraps all three OS keychains. `tauri-plugin-store` handles both TOML and JSON formats. No version conflicts or contradictory decisions found.
**Pattern Consistency:** Naming conventions are uniform (snake_case Rust, PascalCase components, camelCase TS functions). IPC dual pattern (Commands for CRUD, Events for streaming) is applied consistently across all feature areas. Error pattern (`Result<T, AppError>`) and store pattern (`{ data, status, error }`) are standardized. Event namespaces (`scan:*`, `batch:*`, `ai:*`) follow a single scheme.
**Structure Alignment:** Rust `commands/` modules map directly to React component groups by feature. `providers/` is cleanly isolated behind the `AiProvider` trait. The requirements-to-structure mapping table traces every FR category to specific Rust, React, and store files. Integration points are explicit.
### Requirements Coverage Validation
**Functional Requirements — 44/46 fully covered:**
| FR | Status | Note |
|----|--------|------|
| FR1-FR7 (Discovery) | ✅ Full | scanner.rs, ignore.rs, commands/scanner.rs, scanStore |
| FR8-FR13 (Dashboard) | ✅ Full | CardGrid, ListView, ViewToggle, RepoCard/Row, repoStore |
| FR14 (100+ repos) | ⚠️ Partial | Virtualization mentioned but no library specified |
| FR15-FR21 (Batch) | ✅ Full | commands/batch.rs, git.rs, BatchToolbar, BatchResults |
| FR22-FR25, FR27-FR30 (AI) | ✅ Full | AiProvider trait, all 5 providers, PrivacyBadge |
| FR26 (Dormancy) | ⚠️ Partial | Referenced in SmartStatus.tsx but no explicit detection module |
| FR31-FR33, FR35 (Tray) | ✅ Full | commands/tray.rs, TrayMenu, notification plugin |
| FR34 (Auto-launch) | ⚠️ Partial | Platform abstraction mentioned but `tauri-plugin-autostart` not listed |
| FR36-FR41 (Settings) | ✅ Full | SettingsPanel, all sub-panels, tauri-plugin-store |
| FR42-FR46 (Onboarding) | ✅ Full | No auth module, offline-first, CI matrix, single binary |
**Non-Functional Requirements — 25/27 fully covered:**
| NFR | Status | Note |
|-----|--------|------|
| NFR1-5, NFR7-8 (Perf) | ✅ Full | Tauri/Rust architecture, async patterns, caching |
| NFR6 (60fps) | ⚠️ Partial | Depends on virtualization choice (FR14 gap) |
| NFR9-15 (Security) | ✅ Full | keyring, process isolation, privacy architecture |
| NFR16-20 (Integration) | ✅ Full | Provider abstraction, graceful fallback |
| NFR21-24 (Reliability) | ✅ Full | Fault tolerance, persisted state |
| NFR25-27 (Accessibility) | ✅ Addressed | Keyboard nav, ARIA, high contrast mentioned |
### Implementation Readiness Validation ✅
**Decision Completeness:** All critical decisions documented with rationale. Starter template command specified. Stack additions listed with justifications. Implementation sequence provided (10 steps). Enforcement guidelines and anti-patterns are clear and actionable.
**Structure Completeness:** Full directory tree specified down to individual files. Each file annotated with the FRs it supports. Rust and React structures are symmetric. Integration points mapped explicitly (data flow diagram included).
**Pattern Completeness:** Naming conventions cover all code types (Rust, TypeScript, IPC). Error handling patterns specified for both Rust and React. Store pattern standardized. Event payload format defined. Date format standardized (ISO 8601). Anti-patterns enumerated.
### Gap Analysis Results
**Important Gaps (should address before implementation):**
1. **Virtualization library not specified (FR14/NFR6):** The architecture states "virtualized rendering for 100+ repos" but does not name the library. Options: `@tanstack/react-virtual`, `react-virtuoso`, or `react-window`. This choice affects RepoCard/ListView implementation directly.
2. **Missing Tauri plugins in stack additions:** `tauri-plugin-autostart` (FR34) and `tauri-plugin-notification` (FR32) are not listed alongside the other plugins. These are required for system tray agent features.
3. **Dormancy detection not explicitly placed (FR26):** No Rust module or function is named for configurable dormancy threshold logic. Should be explicit — likely in `scanner.rs` or `commands/dashboard.rs`.
**Minor Gaps (can address during implementation):**
4. **i18n framework not specified:** PRD requires "i18n framework ready from day 1" but no library is listed (e.g., `react-i18next`, `typesafe-i18n`).
5. **`.gitpulseignore` parsing crate not named:** `ignore.rs` is listed but the specific crate (`ignore` from ripgrep, `globset`, or custom) is not specified.
6. **Accessibility testing approach not detailed:** NFR25-27 are architecturally addressed but no testing tooling is specified (e.g., `axe-core` integration with Playwright).
### Validation Issues Addressed
All three important gaps are non-blocking for implementation start but should be resolved early. I recommend resolving gaps 1-3 at the start of the relevant implementation stories rather than blocking architecture completion on them.
### Architecture Completeness Checklist
**✅ Requirements Analysis**
- [x] Project context thoroughly analyzed
- [x] Scale and complexity assessed
- [x] Technical constraints identified
- [x] Cross-cutting concerns mapped
**✅ Architectural Decisions**
- [x] Critical decisions documented with versions
- [x] Technology stack fully specified
- [x] Integration patterns defined
- [x] Performance considerations addressed
**✅ Implementation Patterns**
- [x] Naming conventions established
- [x] Structure patterns defined
- [x] Communication patterns specified
- [x] Process patterns documented
**✅ Project Structure**
- [x] Complete directory structure defined
- [x] Component boundaries established
- [x] Integration points mapped
- [x] Requirements to structure mapping complete
### Architecture Readiness Assessment
**Overall Status:** READY FOR IMPLEMENTATION
**Confidence Level:** High — all critical decisions made, all 46 FRs traceable to structure, patterns are enforceable, and the solo developer constraint is respected (no over-engineering).
**Key Strengths:**
- Clear IPC boundary design (Commands + Events) with typed wrappers on both sides
- `AiProvider` trait cleanly isolates all 5 AI backends behind a single interface
- Privacy indicator permeates the architecture via `is_local()` on the provider trait
- Rust = source of truth, React = presentation cache eliminates state sync issues
- Implementation sequence provides a concrete story-by-story build order
**Areas for Future Enhancement:**
- Virtualization library choice for large repo lists
- i18n framework selection
- Accessibility testing tooling
- File watcher architecture (deferred to Phase 2 per plan)
### Implementation Handoff
**AI Agent Guidelines:**
- Follow all architectural decisions exactly as documented
- Use implementation patterns consistently across all components
- Respect project structure and boundaries
- Refer to this document for all architectural questions
**First Implementation Priority:**
```bash
npm create tauri-app@latest -- --template react-ts --manager npm gitpulse
```
Then configure Zustand, Tailwind CSS, Vitest per the stack additions table.

947
_bmad-output/planning-artifacts/epics.md Normal file
View File

@@ -0,0 +1,947 @@
---
stepsCompleted: [step-01-validate-prerequisites, step-02-design-epics, step-03-create-stories, step-04-final-validation]
status: 'complete'
completedAt: '2025-04-25'
inputDocuments:
- "prd.md"
- "product-brief-gitpulse.md"
- "architecture.md"
- "ux-design-specification.md"
workflowType: 'epics-and-stories'
project_name: 'GitPulse'
user_name: 'Ramez'
date: '2025-04-25'
---
# GitPulse - Epic Breakdown
## Overview
This document provides the complete epic and story breakdown for GitPulse, decomposing the requirements from the PRD, UX Design, and Architecture requirements into implementable stories.
## Requirements Inventory
### Functional Requirements
FR1: The user can initiate a recursive disk scan to discover Git repositories on their machine
FR2: The user can configure which root directories to scan
FR3: The user can exclude directories from scanning via a `.gitpulseignore` file (glob syntax)
FR4: The system can detect Git repositories by identifying `.git` folders
FR5: The user can manually trigger a rescan to refresh the repository list
FR6: The system can gracefully handle inaccessible directories (skip and log, no crash)
FR7: The system can cache scan results for instant reload on subsequent launches
FR8: The user can view repositories in a card grid showing branch, status (clean/dirty/ahead/behind), last commit, and stash count
FR9: The user can view repositories in a sortable, filterable list view with multi-select
FR10: The user can toggle between card grid and list view
FR11: The user can sort repositories by status, last activity date, branch name, or ahead/behind count
FR12: The user can filter repositories by status (clean, dirty, ahead, behind, dormant)
FR13: The system can display visual status indicators (color/badges) for instant pattern recognition across all repos
FR14: The system can render large repository lists (100+) without UI degradation
FR15: The user can select multiple repositories and execute batch `git pull`
FR16: The user can select multiple repositories and execute batch `git push`
FR17: The user can select multiple repositories and execute batch `git fetch`
FR18: The user can batch `git status` across multiple repositories
FR19: The system can report per-repo results for batch operations (success/failure with details)
FR20: The system can handle partial success — repos that succeed continue, repos that fail are reported with error details
FR21: The user can see specific error details (e.g., merge conflicts, auth errors) for failed repos
FR22: The user can enable Ollama integration for local, private repository health summaries
FR23: The user can configure cloud API keys (Gemini, DeepSeek, OpenAI, Anthropic) for AI-powered analysis
FR24: The system can generate one-line repository health summaries via the configured AI backend
FR25: The system can suggest commit messages based on staged changes via the configured AI backend
FR26: The system can detect and flag dormant repositories beyond a configurable threshold
FR27: The user can see a visual privacy indicator showing whether data processing is local or cloud-based
FR28: The system can operate entirely without any AI backend configured (deterministic status parsing as default)
FR29: The user can route different AI tasks to different providers (e.g., Ollama for commits, cloud for analysis)
FR30: The system can provide cross-repo analysis when using a cloud AI model (e.g., shared library dependencies across repos)
FR31: The user can run GitPulse as a background system tray agent with the dashboard closed
FR32: The system can monitor for remote changes and alert the user via native OS notifications
FR33: The system can send push reminders for repos with unpushed commits older than a configurable threshold
FR34: The user can configure GitPulse to auto-launch at system startup (opt-in)
FR35: The user can access common operations (status, pull, push) via the system tray context menu
FR36: The user can configure scan root directories via a settings interface
FR37: The user can configure AI backend settings (Ollama endpoint, cloud API keys, per-task routing)
FR38: The user can configure notification behavior (frequency, types, thresholds)
FR39: The user can configure system tray agent behavior (launch at startup, monitoring interval)
FR40: User settings are persisted locally and survive application restarts
FR41: The user can reset all settings to defaults
FR42: The user can launch GitPulse without any account, login, or network configuration
FR43: The system can operate fully offline (all core features work without network access)
FR44: The user can manually check for application updates via system tray or settings
FR45: The user can download GitPulse as a single binary (no installer wizard required)
FR46: The system can run on Windows, macOS, and Linux from initial release
### NonFunctional Requirements
NFR1: Cold startup < 3 seconds
NFR2: Disk scan speed < 5 seconds (SSD, <100 repos)
NFR3: Memory usage < 200 MB with 50+ repos
NFR4: Binary size ~15 MB
NFR5: Batch operation throughput < 30 seconds (pull/push 20 repos)
NFR6: UI rendering responsiveness < 16ms per frame (60fps)
NFR7: Async AI loading — Smart Status does not block dashboard
NFR8: Incremental scan reload < 1 second from cache
NFR9: API key storage via OS keychain/secure storage, not plaintext
NFR10: Privacy by default — no data leaves machine unless cloud backend explicitly enabled
NFR11: Data flow transparency — visual indicator for cloud data transit
NFR12: Scan scope control — `.gitpulseignore` exclusions enforced
NFR13: Zero telemetry by default — opt-in only
NFR14: Git execution isolation — malicious repo cannot compromise application
NFR15: Dependency auditing — Rust/npm vulnerabilities checked before release
NFR16: Ollama version compatibility (API v1) with graceful fallback
NFR17: Cloud API compliance — stable API versions; rate limit handling
NFR18: Git version compatibility >= 2.20 on all platforms
NFR19: Native OS integration — platform-native tray, notifications, startup
NFR20: AI offline resilience — deterministic fallback when Ollama/cloud unavailable
NFR21: Scan fault tolerance — completes even if individual directories fail
NFR22: Batch fault tolerance — successful repos complete even when others fail
NFR23: Crash recovery — state preserved across crashes
NFR24: User data persistence — settings, scan configs, API keys survive updates
NFR25: Keyboard navigation for all core operations
NFR26: High contrast support — status indicators distinguishable in dark/high contrast mode
NFR27: Screen reader compatibility — ARIA markup on key dashboard components
### Additional Requirements (Architecture)
- Starter template: `npm create tauri-app@latest -- --template react-ts --manager npm gitpulse`
- Post-scaffold stack: Zustand, Tailwind CSS, Vitest, Playwright
- Tauri plugins: tauri-plugin-store, tauri-plugin-shell, tauri-plugin-fs, tauri-plugin-autostart, tauri-plugin-notification
- Rust crates: keyring (OS keychain), thiserror (errors), async-trait (AI trait)
- Virtualization: @tanstack/react-virtual for 100+ repo rendering (FR14/NFR6)
- AiProvider trait: health_summary, suggest_commit_message, cross_repo_analysis, provider_type, is_local
- 5 provider implementations: Ollama, Gemini, DeepSeek, OpenAI, Anthropic
- CI/CD: GitHub Actions matrix (Windows x64, macOS x64+ARM, Linux x64)
- Distribution: GitHub Releases, single binary per platform, manual updates only
- Code signing deferred to Phase 1.5
- Error handling: AppError enum (ScanError, GitError, AiError, ConfigError), no unwrap in production
- IPC: Commands (CRUD) + Events (async streaming), namespace:event format
- Frontend state: Zustand stores as presentation cache, Rust = source of truth
- Dormancy detection logic in scanner.rs or commands/dashboard.rs
- .gitpulseignore parser using ignore or globset crate
- i18n framework (react-i18next or typesafe-i18n) ready from day 1
### UX Design Requirements
UX-DR1: Implement Tailwind design token system — status colors (clean/dirty/ahead/behind/dormant), privacy colors (local/cloud), neutral palette, spacing scale (4px base)
UX-DR2: Implement StatusBadge component — 5 variants (color+icon+label), 3 sizes (sm/md/lg), WCAG AA accessible
UX-DR3: Implement RepoCard component — anatomy (header/branch/stats/footer/AI line), 6 states, keyboard nav, click-expand, right-click context menu
UX-DR4: Implement RepoRow component — checkbox, status icon, name, branch, ahead/behind, last commit, action menu, sortable columns
UX-DR5: Implement StatsBar component — 5 metric cards, collapsible, clickable-to-filter, collapse at <900px width
UX-DR6: Implement PrivacyBadge component — local (shield/green) and cloud (cloud/amber) modes, transition animation, aria-live
UX-DR7: Implement BatchToolbar component — slide-down on selection, progress counter, disable during ops
UX-DR8: Implement SmartStatusLine component — AI summary with blue left border, skeleton loading, graceful absence on error
UX-DR9: Implement EmptyState component — 0 repos CTA ("Open Settings"), 0 filter results ("Clear filter"), scan progress transition
UX-DR10: Implement dark mode (default) and light mode with system fonts and 4px spacing grid
UX-DR11: Implement Card Grid layout — auto-fill minmax(280px, 1fr), 16px gap, 2-5 cards per row based on window width
UX-DR12: Implement List View layout — 56px rows, fixed/flexible columns, virtualized rendering
UX-DR13: Implement TopBar (48px) — title, Grid/List toggle, filter pills with counts, rescan button, PrivacyBadge
UX-DR14: Implement command palette (Cmd/Ctrl+K) — fuzzy search, keyboard navigable, 8+ commands
UX-DR15: Implement keyboard shortcuts — Cmd/Ctrl+K/G/L/R/,, Cmd/Ctrl+A, Escape, Space, Enter
UX-DR16: Implement right-click context menu — Pull/Push/Fetch, Open Terminal/File Manager, Copy Path, Refresh
UX-DR17: Implement skeleton loading (initial scan), streaming progress (batch ops), inline loading (AI queries)
UX-DR18: Implement inline error feedback — red border + text on cards/rows, never modal for batch errors
UX-DR19: Implement WCAG 2.1 AA — 4.5:1 contrast, ARIA labels, focus indicators, screen reader support, reduced motion, high contrast mode
UX-DR20: Implement responsive window breakpoints — sm(<900px)/md(900-1199px)/lg(1200-1599px)/xl(>=1600px)
UX-DR21: Implement window persistence — position/size remembered via tauri-plugin-store
UX-DR22: Implement toastless design — all feedback inline, native OS notifications via tray only
UX-DR23: Implement window close behavior — close minimizes to tray, Cmd/Ctrl+Q quits
UX-DR24: Implement Radix UI primitives layer — Dialog, Select, Tooltip, DropdownMenu, Checkbox, ToggleGroup, Popover
UX-DR25: Implement 3-layer component architecture — Layer 1 (Radix+Tailwind primitives), Layer 2 (domain components), Layer 3 (feature compositions)
### FR Coverage Map
| FR | Epic | Description |
|---|---|---|
| FR1 | Epic 1 | Recursive disk scan for Git repos |
| FR2 | Epic 1 | Configure root directories to scan |
| FR3 | Epic 1 | `.gitpulseignore` exclusion |
| FR4 | Epic 1 | Detect repos via `.git` folders |
| FR5 | Epic 1 | Manual rescan trigger |
| FR6 | Epic 1 | Handle inaccessible directories |
| FR7 | Epic 1 | Cache scan results |
| FR8 | Epic 1 | Card grid view with repo details |
| FR9 | Epic 1 | Sortable/filterable list view |
| FR10 | Epic 1 | Toggle card/list view |
| FR11 | Epic 1 | Sort by status/activity/branch/ahead-behind |
| FR12 | Epic 1 | Filter by status |
| FR13 | Epic 1 | Visual status indicators |
| FR14 | Epic 1 | Render 100+ repos without degradation |
| FR15 | Epic 2 | Batch git pull |
| FR16 | Epic 2 | Batch git push |
| FR17 | Epic 2 | Batch git fetch |
| FR18 | Epic 2 | Batch git status |
| FR19 | Epic 2 | Per-repo batch results |
| FR20 | Epic 2 | Partial success handling |
| FR21 | Epic 2 | Error details for failed repos |
| FR22 | Epic 3 | Ollama integration for local AI |
| FR23 | Epic 3 | Cloud API key configuration |
| FR24 | Epic 3 | AI health summaries |
| FR25 | Epic 3 | AI commit message suggestions |
| FR26 | Epic 3 | Dormant repo detection |
| FR27 | Epic 3 | Visual privacy indicator |
| FR28 | Epic 3 | Operate without AI backend |
| FR29 | Epic 3 | Per-task AI provider routing |
| FR30 | Epic 3 | Cross-repo AI analysis |
| FR31 | Epic 4 | Background system tray agent |
| FR32 | Epic 4 | Remote change monitoring & alerts |
| FR33 | Epic 4 | Push reminders for unpushed commits |
| FR34 | Epic 4 | Auto-launch at startup (opt-in) |
| FR35 | Epic 4 | Tray context menu operations |
| FR36 | Epic 5 | Configure scan root directories |
| FR37 | Epic 5 | Configure AI backend settings |
| FR38 | Epic 5 | Configure notification behavior |
| FR39 | Epic 5 | Configure system tray behavior |
| FR40 | Epic 5 | Persist settings locally |
| FR41 | Epic 5 | Reset settings to defaults |
| FR42 | Cross-cutting | No account/login required |
| FR43 | Cross-cutting | Fully offline operation |
| FR44 | Cross-cutting | Manual update check |
| FR45 | Cross-cutting | Single binary distribution |
| FR46 | Cross-cutting | Windows/macOS/Linux support |
## Epic List
### Epic 1: Repository Discovery & Dashboard
Users can discover all Git repositories on their machine and see them at a glance with status, branch, and activity information in both card grid and list views.
**FRs covered:** FR1, FR2, FR3, FR4, FR5, FR6, FR7, FR8, FR9, FR10, FR11, FR12, FR13, FR14
**Key NFRs:** NFR1 (cold startup <3s), NFR2 (scan <5s), NFR3 (memory <200MB), NFR6 (60fps), NFR8 (cache reload <1s), NFR21 (scan fault tolerance), NFR23 (crash recovery)
**Standalone value:** "Launch and Know" moment — users open GitPulse and instantly see all their repos with visual status. Fully functional without any other epic.
### Epic 2: Batch Git Operations
Users can select multiple repositories and execute pull, push, fetch, and status operations in batch, with per-repo success/failure reporting and partial success handling.
**FRs covered:** FR15, FR16, FR17, FR18, FR19, FR20, FR21
**Key NFRs:** NFR5 (batch 20 repos <30s), NFR14 (git isolation), NFR22 (batch fault tolerance)
**Standalone value:** Once repos are displayed (Epic 1), users can immediately act on them in bulk. Complete batch operation domain.
### Epic 3: AI-Powered Repository Insights
Users can leverage local (Ollama) or cloud AI providers for repository health summaries, commit message suggestions, dormancy detection, and cross-repo analysis — with clear privacy indicators.
**FRs covered:** FR22, FR23, FR24, FR25, FR26, FR27, FR28, FR29, FR30
**Key NFRs:** NFR7 (async AI loading), NFR9 (API key via keychain), NFR10 (privacy by default), NFR11 (data flow transparency), NFR16 (Ollama compat), NFR17 (cloud API compliance), NFR20 (AI offline resilience)
**Standalone value:** Adds intelligent analysis layer. Works without AI (deterministic fallback) and with any combination of providers. Privacy-first with visual indicators.
### Epic 4: Background Agent & Notifications
Users can run GitPulse as a background system tray agent that monitors for remote changes, sends push reminders, and provides quick access to common operations via tray context menu.
**FRs covered:** FR31, FR32, FR33, FR34, FR35
**Key NFRs:** NFR19 (native OS integration), NFR18 (Git >= 2.20 compat)
**Standalone value:** Transforms GitPulse from a "check when needed" tool to an "always watching" agent. Tray menu provides quick operations even with dashboard closed.
### Epic 5: Settings & Preferences
Users can configure all aspects of GitPulse — scan roots, AI backends, per-task AI routing, notification behavior, system tray behavior — with settings persisted locally and resettable to defaults.
**FRs covered:** FR36, FR37, FR38, FR39, FR40, FR41
**Key NFRs:** NFR24 (data persistence)
**Standalone value:** Complete configuration management. Users can customize every aspect of their GitPulse experience.
### Cross-Cutting Requirements (span all epics)
**FRs:** FR42 (no account), FR43 (fully offline), FR44 (update check), FR45 (single binary), FR46 (cross-platform)
**NFRs:** NFR4 (binary ~15MB), NFR12 (scan scope control), NFR13 (zero telemetry), NFR15 (dependency auditing), NFR25 (keyboard nav), NFR26 (high contrast), NFR27 (screen reader)
**UX-DRs:** Applied across all epics as design system standards
### Natural Dependencies
- **Epic 1** is the foundation — all other epics build on having repos discovered and displayed
- **Epic 2** requires Epic 1 (needs repo list for batch operations)
- **Epic 3** requires Epic 1 (needs repo data for AI analysis), integrates with Epic 5 for AI config
- **Epic 4** requires Epic 1 (needs repo list for monitoring), integrates with Epic 5 for tray/notification config
- **Epic 5** can be developed in parallel with Epics 2-4, but settings UI for each epic should be available when that epic ships
## Epic 1: Repository Discovery & Dashboard
### Story 1.1: App Shell & First Launch Experience
As a user,
I want to launch GitPulse and see a polished dark-mode dashboard with an empty state prompting me to configure scan roots,
So that I have a clear starting point.
**Acceptance Criteria:**
**Given** GitPulse is launched for the first time
**When** no scan roots are configured
**Then** the dashboard shows an empty state with a "Open Settings" CTA
**And** the TopBar (48px) shows title, Grid/List toggle, filter area, rescan button, and PrivacyBadge placeholder
**And** dark mode is the default with system fonts and 4px spacing grid
**And** window position and size are persisted via tauri-plugin-store
**FRs:** FR2 (partial) | **UX-DRs:** UX-DR9, UX-DR10, UX-DR13, UX-DR22, UX-DR24, UX-DR25
---
### Story 1.2: Scan Root Configuration
As a user,
I want to configure which root directories GitPulse should scan for repositories,
So that I control the scope of discovery.
**Acceptance Criteria:**
**Given** the settings interface is open
**When** the user adds a scan root directory path
**Then** the path is validated (exists, is directory, readable)
**And** invalid paths show inline error feedback
**And** configured roots are persisted via tauri-plugin-store and survive restarts
**And** user can remove previously configured roots
**FRs:** FR2
---
### Story 1.3: Recursive Repository Discovery
As a user,
I want GitPulse to recursively scan my configured directories and discover Git repositories by detecting `.git` folders,
So that I don't have to manually add each one.
**Acceptance Criteria:**
**Given** scan root directories are configured
**When** a scan is initiated
**Then** the scanner recursively walks the directory tree
**And** detects Git repositories by identifying `.git` folders
**And** collects repo metadata (path, current branch, ahead/behind, dirty/clean status, last commit date, stash count)
**And** directories matching `.gitpulseignore` patterns (glob syntax) are excluded
**And** scan completes within 5 seconds on SSD with <100 repos
**FRs:** FR1, FR3, FR4 | **NFRs:** NFR2, NFR12
---
### Story 1.4: Scan Fault Tolerance
As a user,
I want GitPulse to skip inaccessible or permission-denied directories gracefully,
So that one problem directory doesn't stop the entire scan.
**Acceptance Criteria:**
**Given** a scan is running
**When** the scanner encounters an inaccessible or permission-denied directory
**Then** the directory is skipped and logged
**And** the scan continues without crashing
**And** error count is available for display
**FRs:** FR6 | **NFRs:** NFR21
---
### Story 1.5: Scan Result Caching & Manual Rescan
As a user,
I want GitPulse to cache scan results so subsequent launches load instantly, and I want a manual rescan button to refresh on demand,
So that I get instant access to my repos without waiting.
**Acceptance Criteria:**
**Given** a scan has completed successfully
**When** GitPulse is relaunched
**Then** cached results load within 1 second
**And** the user sees the repository dashboard immediately
**Given** the user clicks the rescan button in the TopBar
**When** a rescan is triggered
**Then** the scan runs fresh and updates the cache
**And** streaming progress is visible during the scan
**FRs:** FR5, FR7 | **NFRs:** NFR8, NFR23
---
### Story 1.6: Repository Card Grid View
As a user,
I want to see my discovered repositories as cards in a responsive grid, each showing branch, status indicator, last commit, and stash count,
So that I can assess all repos at a glance.
**Acceptance Criteria:**
**Given** repositories have been discovered
**When** the card grid view is active
**Then** each repo displays as a card with: repo name, branch name, StatusBadge (clean/dirty/ahead/behind/dormant), last commit relative time, stash count
**And** the grid uses auto-fill minmax(280px, 1fr) with 16px gap
**And** cards are keyboard navigable (Tab, Enter to expand)
**And** status colors use the design token system (clean=green, dirty=red, ahead=blue, behind=orange, dormant=gray)
**And** cards have 6 visual states (default, hover, selected, active, loading, error)
**FRs:** FR8, FR13 | **UX-DRs:** UX-DR1, UX-DR2, UX-DR3, UX-DR11
---
### Story 1.7: Repository List View with Multi-Select
As a user,
I want to see repositories in a compact list with sortable columns and multi-select checkboxes,
So that I can efficiently manage many repositories.
**Acceptance Criteria:**
**Given** repositories have been discovered
**When** the list view is active
**Then** repos display in 56px rows with columns: checkbox, status icon, name, branch, ahead/behind, last commit, action menu
**And** multi-select is supported via checkboxes and Cmd/Ctrl+A
**And** columns are sortable by clicking headers
**And** rendering is virtualized for 100+ repos
**FRs:** FR9, FR14 | **UX-DRs:** UX-DR4, UX-DR12 | **NFRs:** NFR6
---
### Story 1.8: View Toggle, Sorting, and Filtering
As a user,
I want to toggle between card and list view, sort by various fields, and filter by status,
So that I can customize the dashboard to my workflow.
**Acceptance Criteria:**
**Given** repositories are displayed in either view
**When** the user clicks the Grid/List toggle in the TopBar
**Then** the view switches between card grid and list view
**Given** the user clicks a column header or sort option
**Then** repos sort by status, last activity date, branch name, or ahead/behind count
**Given** the user clicks a filter pill in the TopBar
**Then** repos filter by status (clean, dirty, ahead, behind, dormant)
**And** filter pills show counts for each status
**And** keyboard shortcuts work: Cmd/Ctrl+G (grid), Cmd/Ctrl+L (list), Cmd/Ctrl+, (toggle)
**FRs:** FR10, FR11, FR12 | **UX-DRs:** UX-DR13, UX-DR15
---
### Story 1.9: Stats Bar & Command Palette
As a user,
I want to see aggregate stats across all repos and access a command palette for quick actions,
So that I have an overview and can navigate efficiently.
**Acceptance Criteria:**
**Given** repositories are loaded
**When** the StatsBar is visible
**Then** it shows 5 metric cards: total repos, clean, dirty, ahead, behind
**And** clicking a metric filters the repo list by that status
**And** StatsBar collapses at <900px width
**Given** the user presses Cmd/Ctrl+K
**When** the command palette opens
**Then** fuzzy search is available across 8+ commands (toggle view, rescan, filter by status, open settings, pull/push selected)
**And** the palette is keyboard navigable (arrows, Enter, Escape)
**UX-DRs:** UX-DR5, UX-DR14, UX-DR15
---
### Story 1.10: Loading States & Responsive Design
As a user,
I want skeleton loading during scans and a dashboard that adapts to window resizing,
So that the experience feels polished at any size and stage.
**Acceptance Criteria:**
**Given** a scan is in progress
**When** the dashboard is loading
**Then** skeleton loading placeholders are shown (not spinners)
**Given** the window is resized
**When** crossing breakpoints (sm<900, md 900-1199, lg 1200-1599, xl>=1600)
**Then** layout adapts with 2-5 cards per row accordingly
**And** window position and size are remembered across sessions
**UX-DRs:** UX-DR17, UX-DR20, UX-DR21
---
### Story 1.11: Accessibility Foundation
As a user,
I want the dashboard to be keyboard navigable with screen reader support and high contrast compatibility,
So that GitPulse is usable regardless of ability.
**Acceptance Criteria:**
**Given** the user navigates via keyboard
**Then** all core operations are accessible (Tab, Enter, Escape, arrow keys)
**And** focus indicators are visible and distinct
**Given** a screen reader is active
**Then** ARIA labels are present on key dashboard components
**And** StatusBadge includes aria-live for status changes
**Given** high contrast mode is enabled
**Then** status indicators are distinguishable beyond color alone (icons + labels)
**UX-DRs:** UX-DR19 | **NFRs:** NFR25, NFR26, NFR27
---
## Epic 2: Batch Git Operations
### Story 2.1: Repository Multi-Select & Batch Toolbar
As a user,
I want to select multiple repositories and see a batch action toolbar appear,
So that I know which operations I can run on my selection.
**Acceptance Criteria:**
**Given** repositories are displayed in list view
**When** the user selects one or more repos via checkboxes or Cmd/Ctrl+A
**Then** a BatchToolbar slides down showing Pull, Push, Fetch, Status buttons
**And** a selection counter shows "N repos selected"
**And** all batch buttons are disabled while an operation is in progress
**UX-DRs:** UX-DR7
---
### Story 2.2: Batch Git Pull
As a user,
I want to select multiple repos and execute `git pull` on all of them,
So that I can update all repos at once.
**Acceptance Criteria:**
**Given** multiple repos are selected and the batch toolbar is visible
**When** the user clicks "Pull"
**Then** `git pull` executes across selected repos in parallel via tokio::process::Command
**And** per-repo progress is shown in the streaming toolbar
**And** the operation completes within 30 seconds for 20 repos
**FRs:** FR15 | **NFRs:** NFR5, NFR14
---
### Story 2.3: Batch Git Push
As a user,
I want to batch push selected repositories,
So that I can sync local commits to remotes efficiently.
**Acceptance Criteria:**
**Given** multiple repos are selected
**When** the user clicks "Push"
**Then** `git push` executes across selected repos in parallel
**And** per-repo progress is shown
**And** auth errors are caught and reported per repo
**FRs:** FR16
---
### Story 2.4: Batch Git Fetch
As a user,
I want to batch fetch selected repositories,
So that I can check for remote changes without merging.
**Acceptance Criteria:**
**Given** multiple repos are selected
**When** the user clicks "Fetch"
**Then** `git fetch` executes across selected repos in parallel
**And** ahead/behind counts are updated after fetch
**And** per-repo results are shown
**FRs:** FR17
---
### Story 2.5: Batch Git Status
As a user,
I want to run `git status` across multiple repos,
So that I can see which repos have uncommitted changes.
**Acceptance Criteria:**
**Given** multiple repos are selected
**When** the user clicks "Status"
**Then** `git status` runs across selected repos
**And** dirty/clean status is updated for each repo
**And** cards/rows update their StatusBadge accordingly
**FRs:** FR18
---
### Story 2.6: Batch Results Reporting & Partial Success
As a user,
I want to see per-repo results with specific error details for batch operations,
So that I know exactly what succeeded and failed.
**Acceptance Criteria:**
**Given** a batch operation is running
**When** some repos succeed and others fail
**Then** successful repos complete normally (partial success)
**And** failed repos show inline error feedback (red border + error text on card/row, never modal)
**And** specific error details are shown (merge conflicts, auth errors, network errors)
**And** the toolbar shows final summary: "N succeeded, M failed"
**FRs:** FR19, FR20, FR21 | **UX-DRs:** UX-DR18 | **NFRs:** NFR22
---
### Story 2.7: Right-Click Context Menu
As a user,
I want to right-click a repository for quick actions like pull, push, fetch, open terminal, or open file manager,
So that I can act on individual repos without multi-selecting.
**Acceptance Criteria:**
**Given** the user right-clicks on a repo card or row
**When** the context menu appears
**Then** options include: Pull, Push, Fetch, Open in Terminal, Open in File Manager, Copy Path, Refresh
**And** each option triggers the corresponding action
**And** the menu is keyboard navigable
**UX-DRs:** UX-DR16
---
## Epic 3: AI-Powered Repository Insights
### Story 3.1: AI Provider Trait & Ollama Integration
As a user,
I want to connect GitPulse to my local Ollama instance for private AI-powered insights,
So that I can get intelligent summaries without sending data to the cloud.
**Acceptance Criteria:**
**Given** Ollama is configured with an endpoint URL
**When** GitPulse connects to Ollama
**Then** the AiProvider trait is implemented with health_summary, suggest_commit_message, cross_repo_analysis, provider_type, is_local methods
**And** Ollama provider uses API v1 with graceful fallback on version mismatch
**And** health check verifies the endpoint is reachable
**And** when Ollama is unavailable, deterministic status parsing is used as fallback
**FRs:** FR22, FR28 | **NFRs:** NFR16, NFR20
---
### Story 3.2: Cloud AI Provider Configuration & Secure Key Storage
As a user,
I want to configure API keys for cloud providers (Gemini, DeepSeek, OpenAI, Anthropic) stored in my OS keychain,
So that I can use cloud AI securely.
**Acceptance Criteria:**
**Given** the AI settings section is open
**When** the user enters an API key for a provider
**Then** the key is stored via the OS keychain (keyring crate), not plaintext
**And** a connection test verifies the key works
**And** the key is never displayed in full after saving
**FRs:** FR23 | **NFRs:** NFR9
---
### Story 3.3: AI Health Summary (Smart Status Line)
As a user,
I want to see a one-line AI-generated health summary for each repository,
So that I can quickly understand repo state without reading git output.
**Acceptance Criteria:**
**Given** an AI provider is configured and a repo has status data
**When** the SmartStatusLine component renders
**Then** a one-line summary appears with a blue left border
**And** loading shows skeleton animation (non-blocking)
**And** on error, the line is absent (graceful degradation, no error shown)
**And** PrivacyBadge indicates local vs cloud processing
**FRs:** FR24, FR27 | **UX-DRs:** UX-DR6, UX-DR8 | **NFRs:** NFR7, NFR10, NFR11
---
### Story 3.4: AI Commit Message Suggestions
As a user,
I want AI to suggest commit messages based on my staged changes,
So that I can write better commit messages faster.
**Acceptance Criteria:**
**Given** a repository has staged changes
**When** the user requests a commit message suggestion
**Then** the AI generates a suggestion based on the staged diff
**And** the suggestion is shown inline (non-blocking)
**And** the feature works with any configured AI provider
**FRs:** FR25
---
### Story 3.5: Dormant Repository Detection
As a user,
I want GitPulse to flag repositories with no activity beyond a configurable threshold,
So that I can identify stale projects.
**Acceptance Criteria:**
**Given** a configurable dormancy threshold (default: 30 days)
**When** a repo's last commit is older than the threshold
**Then** the repo is flagged with "dormant" status
**And** the StatusBadge shows the dormant variant (gray)
**And** dormant repos appear in the dormant filter
**FRs:** FR26
---
### Story 3.6: Per-Task AI Provider Routing
As a user,
I want to route different AI tasks to different providers,
So that I can optimize for speed, cost, or privacy per task type.
**Acceptance Criteria:**
**Given** multiple AI providers are configured
**When** the user sets routing rules (e.g., Ollama for commits, cloud for analysis)
**Then** each AI task routes to the configured provider
**And** fallback to a default provider if the routed provider is unavailable
**FRs:** FR29
---
### Story 3.7: Cross-Repository AI Analysis
As a user,
I want AI to analyze patterns across my repositories,
So that I can understand relationships like shared library dependencies.
**Acceptance Criteria:**
**Given** a cloud AI provider is configured (cross-repo analysis not available with Ollama)
**When** the user requests cross-repo analysis
**Then** the AI provides insights about shared dependencies, patterns, and relationships across repos
**And** PrivacyBadge shows "cloud" indicator during analysis
**FRs:** FR30 | **NFRs:** NFR17
---
## Epic 4: Background Agent & Notifications
### Story 4.1: System Tray Agent & Window Management
As a user,
I want GitPulse to minimize to the system tray when I close the window,
So that it stays available in the background.
**Acceptance Criteria:**
**Given** GitPulse is running
**When** the user closes the window
**Then** the app minimizes to system tray (platform-native tray icon)
**And** double-clicking the tray icon reopens the dashboard
**Given** the user presses Cmd/Ctrl+Q
**Then** the app quits entirely
**FRs:** FR31 | **UX-DRs:** UX-DR23 | **NFRs:** NFR19
---
### Story 4.2: Tray Context Menu Operations
As a user,
I want to right-click the tray icon for quick access to common operations,
So that I can act without opening the dashboard.
**Acceptance Criteria:**
**Given** GitPulse is running in the tray
**When** the user right-clicks the tray icon
**Then** a context menu shows: status overview, Pull All, Push All, Open Dashboard, Quit
**And** selecting an action executes it immediately
**And** status overview shows clean/dirty/ahead/behind counts
**FRs:** FR35
---
### Story 4.3: Remote Change Monitoring & Alerts
As a user,
I want GitPulse to periodically check for remote changes and alert me via native OS notifications,
So that I stay informed about upstream activity.
**Acceptance Criteria:**
**Given** background monitoring is enabled
**When** remote changes are detected on a monitored repo
**Then** a native OS notification is sent identifying the repo and change count
**And** the monitoring interval is configurable
**FRs:** FR32
---
### Story 4.4: Push Reminders for Unpushed Commits
As a user,
I want GitPulse to remind me about unpushed commits older than a configurable threshold,
So that I don't forget to push important work.
**Acceptance Criteria:**
**Given** a repo has unpushed commits older than the configured threshold
**When** the background check runs
**Then** a native OS notification reminds the user to push
**And** the notification identifies the repo and commit age
**And** the threshold is configurable in settings
**FRs:** FR33
---
### Story 4.5: Auto-Launch at System Startup
As a user,
I want to configure GitPulse to start automatically with my system,
So that monitoring begins without manual intervention.
**Acceptance Criteria:**
**Given** auto-launch is enabled in settings (opt-in, default off)
**When** the system starts up
**Then** GitPulse launches and minimizes to tray
**And** tauri-plugin-autostart handles platform-specific startup registration
**FRs:** FR34
---
## Epic 5: Settings & Preferences
### Story 5.1: Settings Interface Foundation
As a user,
I want a clean settings interface organized into sections,
So that I can find and configure any aspect of GitPulse easily.
**Acceptance Criteria:**
**Given** the user opens settings (via menu, keyboard shortcut, or empty state CTA)
**When** the settings dialog appears
**Then** sections are organized as: Scan, AI, Notifications, System Tray
**And** all settings are persisted via tauri-plugin-store
**And** settings survive application restarts
**FRs:** FR40
---
### Story 5.2: Scan Configuration Settings
As a user,
I want to manage scan root directories and exclusions in settings,
So that I can control repository discovery behavior.
**Acceptance Criteria:**
**Given** the Scan settings section
**When** the user adds/removes scan root directories
**Then** changes take effect on next scan
**And** the dormancy threshold is configurable
**And** .gitpulseignore patterns can be previewed
**FRs:** FR36
---
### Story 5.3: AI Backend Settings & Per-Task Routing
As a user,
I want to configure AI providers, API keys, and per-task routing,
So that I can control how AI features work.
**Acceptance Criteria:**
**Given** the AI settings section
**When** the user configures providers
**Then** Ollama endpoint URL is configurable
**And** cloud API keys can be entered (stored in OS keychain)
**And** per-task routing can be set (health summary → provider, commit message → provider)
**And** connection test buttons verify each provider
**FRs:** FR37
---
### Story 5.4: Notification Behavior Settings
As a user,
I want to configure notification frequency, types, and thresholds,
So that I'm alerted about what matters without being overwhelmed.
**Acceptance Criteria:**
**Given** the Notifications settings section
**When** the user configures notifications
**Then** individual notification types can be enabled/disabled (remote changes, push reminders)
**And** the monitoring interval is configurable
**And** push reminder threshold is configurable
**FRs:** FR38
---
### Story 5.5: System Tray & Startup Settings
As a user,
I want to configure tray behavior and auto-launch,
So that GitPulse runs the way I prefer.
**Acceptance Criteria:**
**Given** the System Tray settings section
**When** the user configures tray behavior
**Then** auto-launch at startup can be toggled (opt-in)
**And** minimize-to-tray on close can be toggled
**And** monitoring behavior is configurable
**FRs:** FR39
---
### Story 5.6: Reset Settings to Defaults
As a user,
I want to reset all settings to defaults,
So that I can start fresh if my configuration becomes problematic.
**Acceptance Criteria:**
**Given** any settings section
**When** the user clicks "Reset to Defaults"
**Then** a confirmation dialog appears
**And** on confirmation, all settings revert to defaults
**And** API keys are preserved (with option to clear)
**FRs:** FR41

353
_bmad-output/planning-artifacts/implementation-readiness-report-2025-04-25.md Normal file
View File

@@ -0,0 +1,353 @@
---
stepsCompleted: [step-01-document-discovery, step-02-prd-analysis, step-03-epic-coverage, step-04-ux-alignment, step-05-epic-quality, step-06-final-assessment]
documents:
prd: "prd.md"
architecture: null
epics: null
ux: null
supporting:
- "product-brief-gitpulse.md"
- "product-brief-gitpulse-distillate.md"
- "research/market-git-dashboard-ia-research-2026-04-24.md"
---
# Implementation Readiness Assessment Report
**Date:** 2025-04-25
**Project:** GitPulse
## PRD Analysis
### Functional Requirements
**Repository Discovery (7 requirements):**
- FR1: The user can initiate a recursive disk scan to discover Git repositories on their machine
- FR2: The user can configure which root directories to scan
- FR3: The user can exclude directories from scanning via a `.gitpulseignore` file (glob syntax)
- FR4: The system can detect Git repositories by identifying `.git` folders
- FR5: The user can manually trigger a rescan to refresh the repository list
- FR6: The system can gracefully handle inaccessible directories (skip and log, no crash)
- FR7: The system can cache scan results for instant reload on subsequent launches
**Dashboard & Visualization (7 requirements):**
- FR8: The user can view repositories in a card grid showing branch, status (clean/dirty/ahead/behind), last commit, and stash count
- FR9: The user can view repositories in a sortable, filterable list view with multi-select
- FR10: The user can toggle between card grid and list view
- FR11: The user can sort repositories by status, last activity date, branch name, or ahead/behind count
- FR12: The user can filter repositories by status (clean, dirty, ahead, behind, dormant)
- FR13: The system can display visual status indicators (color/badges) for instant pattern recognition across all repos
- FR14: The system can render large repository lists (100+) without UI degradation
**Batch Operations (7 requirements):**
- FR15: The user can select multiple repositories and execute batch `git pull`
- FR16: The user can select multiple repositories and execute batch `git push`
- FR17: The user can select multiple repositories and execute batch `git fetch`
- FR18: The user can batch `git status` across multiple repositories
- FR19: The system can report per-repo results for batch operations (success/failure with details)
- FR20: The system can handle partial success — repos that succeed continue, repos that fail are reported with error details
- FR21: The user can see specific error details (e.g., merge conflicts, auth errors) for failed repos
**Smart Status / AI Integration (9 requirements):**
- FR22: The user can enable Ollama integration for local, private repository health summaries
- FR23: The user can configure cloud API keys (Gemini, DeepSeek, OpenAI, Anthropic) for AI-powered analysis
- FR24: The system can generate one-line repository health summaries via the configured AI backend
- FR25: The system can suggest commit messages based on staged changes via the configured AI backend
- FR26: The system can detect and flag dormant repositories beyond a configurable threshold
- FR27: The user can see a visual privacy indicator showing whether data processing is local or cloud-based
- FR28: The system can operate entirely without any AI backend configured (deterministic status parsing as default)
- FR29: The user can route different AI tasks to different providers (e.g., Ollama for commits, cloud for analysis)
- FR30: The system can provide cross-repo analysis when using a cloud AI model (e.g., shared library dependencies across repos)
**System Tray Agent & Notifications (5 requirements):**
- FR31: The user can run GitPulse as a background system tray agent with the dashboard closed
- FR32: The system can monitor for remote changes and alert the user via native OS notifications
- FR33: The system can send push reminders for repos with unpushed commits older than a configurable threshold
- FR34: The user can configure GitPulse to auto-launch at system startup (opt-in)
- FR35: The user can access common operations (status, pull, push) via the system tray context menu
**Settings & Configuration (6 requirements):**
- FR36: The user can configure scan root directories via a settings interface
- FR37: The user can configure AI backend settings (Ollama endpoint, cloud API keys, per-task routing)
- FR38: The user can configure notification behavior (frequency, types, thresholds)
- FR39: The user can configure system tray agent behavior (launch at startup, monitoring interval)
- FR40: User settings are persisted locally and survive application restarts
- FR41: The user can reset all settings to defaults
**Onboarding & Distribution (5 requirements):**
- FR42: The user can launch GitPulse without any account, login, or network configuration
- FR43: The system can operate fully offline (all core features work without network access)
- FR44: The user can manually check for application updates via system tray or settings
- FR45: The user can download GitPulse as a single binary (no installer wizard required)
- FR46: The system can run on Windows, macOS, and Linux from initial release
**Total FRs: 46**
### Non-Functional Requirements
**Performance (8 requirements):**
- NFR1: Cold startup < 3 seconds
- NFR2: Disk scan speed < 5 seconds (SSD, <100 repos)
- NFR3: Memory usage < 200 MB with 50+ repos
- NFR4: Binary size ~15 MB
- NFR5: Batch operation throughput < 30 seconds (pull/push 20 repos)
- NFR6: UI rendering responsiveness < 16ms per frame (60fps)
- NFR7: Async AI loading — Smart Status does not block dashboard
- NFR8: Incremental scan reload < 1 second from cache
**Security (7 requirements):**
- NFR9: API key storage via OS keychain/secure storage, not plaintext
- NFR10: Privacy by default — no data leaves machine unless cloud backend explicitly enabled
- NFR11: Data flow transparency — visual indicator for cloud data transit
- NFR12: Scan scope control — `.gitpulseignore` exclusions enforced
- NFR13: Zero telemetry by default — opt-in only
- NFR14: Git execution isolation — malicious repo cannot compromise application
- NFR15: Dependency auditing — Rust/npm vulnerabilities checked before release
**Integration (5 requirements):**
- NFR16: Ollama version compatibility (API v1) with graceful fallback
- NFR17: Cloud API compliance — stable API versions for Gemini, DeepSeek, OpenAI, Anthropic; rate limit handling
- NFR18: Git version compatibility >= 2.20 on all platforms; clear error if missing/outdated
- NFR19: Native OS integration — platform-native tray, notifications, startup (no workarounds)
- NFR20: AI offline resilience — deterministic fallback when Ollama/cloud unavailable
**Reliability (4 requirements):**
- NFR21: Scan fault tolerance — completes even if individual directories fail
- NFR22: Batch fault tolerance — successful repos complete even when others fail
- NFR23: Crash recovery — state preserved across crashes, no reconfiguration needed
- NFR24: User data persistence — settings, scan configs, API keys survive updates
**Accessibility (3 requirements):**
- NFR25: Keyboard navigation for all core operations
- NFR26: High contrast support — status indicators distinguishable in dark/high contrast mode
- NFR27: Screen reader compatibility — ARIA markup on key dashboard components
**Total NFRs: 27**
### Additional Requirements & Constraints
**Platform-specific (Desktop App):**
- Windows x64: `.exe` portable + optional MSI, SmartScreen/code signing handling
- macOS x64 + ARM: `.dmg`, universal binary, Apple notarization
- Linux x64: `.deb` + `.AppImage` + `.rpm`
- Tauri v2: native webview per platform, Rust backend identical cross-platform
- System tray: platform-specific implementations (Windows/macOS menu bar/Linux D-Bus)
- Auto-launch: Windows Registry, macOS LaunchAgent, Linux XDG autostart
**Update strategy:**
- Manual check via system tray/settings; GitHub Releases distribution
- No forced auto-update; update check = only outbound request in local-only mode
- Code signing required: Authenticode (Win), Apple Developer + notarization (Mac), GPG (Linux)
- Post-MVP: Tauri built-in updater, delta updates
**Phased delivery constraints:**
- Phase 1 (weeks 1-6): Core MVP — scan + dashboard + batch + tray + Ollama
- Phase 1.5 (weeks 7-10): Cloud AI, dormancy, code signing, i18n framework
- Phase 2 (months 4-6): Grouping, advanced AI, file watcher, CLI companion, cloud tier
- Phase 3 (months 7-12): Dependency graph, MCP, autonomous agents, GitHub/GitLab, enterprise
**Resource constraint:** Solo developer execution (2-3 months for MVP core)
### PRD Completeness Assessment
**Strengths:**
- All 46 FRs are testable, implementation-agnostic, and clearly state WHO and WHAT
- All 27 NFRs are measurable with specific targets
- 4 user journeys provide narrative context for all capability areas
- Clear phased roadmap with must-have vs nice-to-have prioritization
- Risk mitigation tables cover technical, market, and resource risks
- Innovation areas identified with validation methods
**Minor observations:**
- FR14 ("render large repository lists 100+ without degradation") partially overlaps with NFR6 (60fps rendering) — both valid but architect should be aware of the dual coverage
- FR28 (no AI = still works) and NFR20 (AI offline resilience) express the same graceful degradation principle at different levels — intentional and correct
- Desktop App platform-specific requirements (distribution formats, code signing) are not numbered as FRs — they are implementation constraints that the architect should account for
## Epic Coverage Validation
**Status: NO EPICS DOCUMENT EXISTS**
No epics or stories document was found during document discovery. Epic coverage validation cannot be performed.
### Coverage Matrix
| FR Range | Capability Area | FRs | Epic Coverage | Status |
|----------|----------------|-----|---------------|--------|
| FR1-FR7 | Repository Discovery | 7 | None | BLOCKED |
| FR8-FR14 | Dashboard & Visualization | 7 | None | BLOCKED |
| FR15-FR21 | Batch Operations | 7 | None | BLOCKED |
| FR22-FR30 | Smart Status (AI) | 9 | None | BLOCKED |
| FR31-FR35 | System Tray & Notifications | 5 | None | BLOCKED |
| FR36-FR41 | Settings & Configuration | 6 | None | BLOCKED |
| FR42-FR46 | Onboarding & Distribution | 5 | None | BLOCKED |
### Coverage Statistics
- Total PRD FRs: 46
- FRs covered in epics: **0**
- Coverage percentage: **0%**
- Total PRD NFRs: 27
- NFRs addressed in architecture: **0** (no architecture document)
### Critical Gap: Missing Epics & Stories
All 46 functional requirements lack a traceable implementation path. No epics, user stories, or sprint-ready backlog exists. **This is the single largest blocker for implementation readiness.**
**Recommendation:** Create epics document that maps each FR to one or more user stories, organized by MVP Phase 1/1.5 priority.
## UX Alignment Assessment
### UX Document Status
**Not Found.** No UX design document exists in the project.
### UX Implied Analysis
GitPulse is a **UI-heavy desktop application** with significant visual interface requirements:
- **Card Grid View** (FR8) — compact tiles with color-coded status, branch names, ahead/behind counts
- **List View** (FR9) — sortable/filterable rows with multi-select
- **View Toggle** (FR10) — seamless switching between grid and list
- **Visual Status Indicators** (FR13) — color/badge system for pattern recognition
- **Privacy Indicator** (FR27) — visual badge for local vs cloud mode
- **System Tray** (FR31-FR35) — platform-specific tray UI with context menus
- **Settings Interface** (FR36-FR41) — configuration panels for scan roots, AI backends, notifications
- **Error Reporting** (FR19-FR21) — per-repo error display in batch operations
- **Smart Status Display** (FR24-FR26) — AI-generated summaries in dashboard
The PRD defines WHAT the UI must show (capabilities) but not HOW it should look (layout, interaction patterns, visual design, component hierarchy).
### Critical Warning: UX Design Missing
**Severity: HIGH** — A user-facing desktop application with 7 distinct UI capability areas cannot proceed to implementation without UX design. Without UX documentation:
- Developers will make ad-hoc UI decisions during implementation
- Visual consistency across Card Grid, List View, Settings, and Tray cannot be guaranteed
- The privacy indicator (FR27) — a key innovation differentiator — has no visual specification
- The "5-Second Wow" conversion moment depends entirely on visual design quality
- Platform-specific adaptations (Windows/macOS/Linux tray behavior) need UX guidance
**Recommendation:** Create UX design document covering:
1. Layout wireframes for Card Grid and List View
2. Status indicator visual language (colors, badges, icons)
3. Privacy indicator component design
4. Settings panel structure
5. System tray menu hierarchy
6. Error state and empty state designs
7. Small repo count UX (Jay's Journey — dashboard with <10 repos)
## Epic Quality Review
**Status: NO EPICS DOCUMENT EXISTS**
Epic quality review cannot be performed. No epics or stories document was found.
### Best Practices Checklist (Pre-Validation)
When epics are eventually created, the following checks should be enforced:
**Epic Structure:**
- [ ] Each epic delivers user value (not technical milestones like "Setup Tauri" or "Create Rust Backend")
- [ ] Epics are independently deployable
- [ ] No forward dependencies between epics
- [ ] Epic 1 stands completely alone
**Greenfield Considerations for GitPulse:**
- [ ] Epic 1 Story 1: Project scaffolding from Tauri starter template
- [ ] Development environment configuration (Rust toolchain, Node.js, platform-specific webview)
- [ ] CI/CD pipeline for cross-platform builds early in backlog
- [ ] No "create all database tables upfront" pattern (this project uses file-based storage, so equivalent: no "setup all configuration structures upfront")
**Specific GitPulse Quality Risks:**
- Risk of technical epics like "Tauri Integration" or "Ollama API Layer" that don't deliver user value alone
- Risk of forward dependency: Smart Status stories depending on Dashboard stories that depend on Scanner stories
- Risk of oversized stories: "Implement entire Card Grid view" is too large; should be split into tile component, status badge, grid layout, interaction handlers
### Quality Violations
**No violations to report** — no epics exist to violate standards. This section will be populated when epics are created and re-assessed.
### Remediation Guidance (For Future Epic Creation)
1. **Epic 1 should deliver:** "Users can see all their Git repositories in a visual dashboard" (FR1, FR2, FR4, FR7, FR8, FR13)
2. **Epic 2 should deliver:** "Users can perform batch operations across repositories" (FR9-FR11, FR15-FR21)
3. **Epic 3 should deliver:** "Users receive passive monitoring via system tray" (FR31-FR35)
4. **Epic 4 should deliver:** "Users get AI-powered repository insights" (FR22-FR30)
5. **Epic 5 should deliver:** "Users can configure GitPulse to their preferences" (FR3, FR5, FR36-FR41, FR42-FR44)
## Summary and Recommendations
### Overall Readiness Status
**NOT READY** — The PRD is strong and comprehensive, but three critical artifacts are missing before implementation can begin.
### Assessment Summary
| Category | Status | Detail |
|----------|--------|--------|
| PRD Quality | **STRONG** | 46 FRs + 27 NFRs, all testable and measurable. Clear vision, journeys, scope. |
| Architecture | **MISSING** | No technical architecture document exists. |
| UX Design | **MISSING** | No UX design document exists. Critical for a UI-heavy desktop app. |
| Epics & Stories | **MISSING** | 0% FR coverage. No sprint-ready backlog exists. |
### Critical Issues Requiring Immediate Action
**1. No Architecture Document (Severity: CRITICAL)**
The PRD specifies Tauri v2 + Rust + React, but no technical architecture exists to guide implementation. Without it:
- No component/module boundaries defined
- No data flow between Rust backend and React frontend specified
- No AI provider abstraction layer designed
- No cross-platform build and packaging strategy documented
- No state management approach defined
**2. No Epics & Stories (Severity: CRITICAL)**
All 46 functional requirements lack a traceable implementation path. No sprint-ready backlog exists. Zero epic coverage. Implementation cannot begin without knowing what to build first, in what order, and how stories map to FRs.
**3. No UX Design Document (Severity: HIGH)**
GitPulse has 7 distinct UI capability areas. The "5-Second Wow" conversion moment depends entirely on visual design quality. The privacy indicator (a key differentiator) has no visual specification. Developers will make ad-hoc UI decisions without guidance.
### Recommended Next Steps
1. **Create Architecture Document** — Define Rust backend modules, React frontend components, data flow, AI abstraction layer, cross-platform build strategy, state management, and file-based storage approach. Map architecture components to FRs/NFRs.
2. **Create UX Design Document** — Wireframes for Card Grid and List View, visual status language, privacy indicator component, settings panels, system tray menus, error/empty states. Validate against user journeys.
3. **Create Epics & Stories** — Break the 46 FRs into user-value epics with independently completable stories. Ensure epic independence, no forward dependencies, and full FR coverage. Use the remediation guidance in this report as starting point.
4. **Re-run Implementation Readiness** — After creating the three missing artifacts, re-run this assessment to validate complete coverage.
### What's Working Well
The PRD is the strongest artifact in the project:
- **46 FRs** are all testable, implementation-agnostic, and clearly scoped
- **27 NFRs** have specific measurable targets
- **4 user journeys** provide narrative context that bridges vision and requirements
- **Phased roadmap** with clear must-have vs nice-to-have prioritization
- **Risk mitigation** covers technical, market, and resource dimensions
- **Innovation validation** methods are defined for each differentiator
This PRD provides an excellent foundation. The missing artifacts are downstream work that should flow naturally from this quality baseline.
### Final Note
This assessment identified **3 missing artifacts** (Architecture, UX Design, Epics & Stories) that are prerequisites for implementation. The PRD itself is production-quality — the gaps are in downstream planning, not in requirements definition. Address the three missing artifacts in sequence (Architecture → UX → Epics), then re-assess.
---
**Assessment completed:** 2025-04-25
**Assessor:** Implementation Readiness Workflow
**Report:** `implementation-readiness-report-2025-04-25.md`

392
_bmad-output/planning-artifacts/implementation-readiness-report-2026-04-25-v2.md Normal file
View File

@@ -0,0 +1,392 @@
---
stepsCompleted: [step-01-document-discovery, step-02-prd-analysis, step-03-epic-coverage-validation, step-04-ux-alignment, step-05-epic-quality-review, step-06-final-assessment]
documents:
prd: "prd.md"
architecture: "architecture.md"
epics: "epics.md"
ux: "ux-design-specification.md"
---
# Implementation Readiness Assessment Report
**Date:** 2026-04-25
**Project:** GitPulse
## Document Inventory
### PRD Documents
**Whole Documents:**
- prd.md
**Sharded Documents:**
- None
### Architecture Documents
**Whole Documents:**
- architecture.md
**Sharded Documents:**
- None
### Epics & Stories Documents
**Whole Documents:**
- epics.md
**Sharded Documents:**
- None
### UX Design Documents
**Whole Documents:**
- ux-design-specification.md
**Sharded Documents:**
- None
### Supporting Documents
- product-brief-gitpulse.md
- product-brief-gitpulse-distillate.md
- research/market-git-dashboard-ia-research-2026-04-24.md
### Issues Found
- No duplicates detected
- No missing documents — all 4 required documents found
### Documents Selected for Assessment
| Document | File | Status |
|---|---|---|
| PRD | prd.md | Found |
| Architecture | architecture.md | Found |
| Epics & Stories | epics.md | Found |
| UX Design | ux-design-specification.md | Found |
## PRD Analysis
### Functional Requirements
FR1: The user can initiate a recursive disk scan to discover Git repositories on their machine
FR2: The user can configure which root directories to scan
FR3: The user can exclude directories from scanning via a `.gitpulseignore` file (glob syntax)
FR4: The system can detect Git repositories by identifying `.git` folders
FR5: The user can manually trigger a rescan to refresh the repository list
FR6: The system can gracefully handle inaccessible directories (skip and log, no crash)
FR7: The system can cache scan results for instant reload on subsequent launches
FR8: The user can view repositories in a card grid showing branch, status (clean/dirty/ahead/behind), last commit, and stash count
FR9: The user can view repositories in a sortable, filterable list view with multi-select
FR10: The user can toggle between card grid and list view
FR11: The user can sort repositories by status, last activity date, branch name, or ahead/behind count
FR12: The user can filter repositories by status (clean, dirty, ahead, behind, dormant)
FR13: The system can display visual status indicators (color/badges) for instant pattern recognition across all repos
FR14: The system can render large repository lists (100+) without UI degradation
FR15: The user can select multiple repositories and execute batch `git pull`
FR16: The user can select multiple repositories and execute batch `git push`
FR17: The user can select multiple repositories and execute batch `git fetch`
FR18: The user can batch `git status` across multiple repositories
FR19: The system can report per-repo results for batch operations (success/failure with details)
FR20: The system can handle partial success — repos that succeed continue, repos that fail are reported with error details
FR21: The user can see specific error details (e.g., merge conflicts, auth errors) for failed repos
FR22: The user can enable Ollama integration for local, private repository health summaries
FR23: The user can configure cloud API keys (Gemini, DeepSeek, OpenAI, Anthropic) for AI-powered analysis
FR24: The system can generate one-line repository health summaries via the configured AI backend
FR25: The system can suggest commit messages based on staged changes via the configured AI backend
FR26: The system can detect and flag dormant repositories beyond a configurable threshold
FR27: The user can see a visual privacy indicator showing whether data processing is local or cloud-based
FR28: The system can operate entirely without any AI backend configured (deterministic status parsing as default)
FR29: The user can route different AI tasks to different providers (e.g., Ollama for commits, cloud for analysis)
FR30: The system can provide cross-repo analysis when using a cloud AI model (e.g., shared library dependencies across repos)
FR31: The user can run GitPulse as a background system tray agent with the dashboard closed
FR32: The system can monitor for remote changes and alert the user via native OS notifications
FR33: The system can send push reminders for repos with unpushed commits older than a configurable threshold
FR34: The user can configure GitPulse to auto-launch at system startup (opt-in)
FR35: The user can access common operations (status, pull, push) via the system tray context menu
FR36: The user can configure scan root directories via a settings interface
FR37: The user can configure AI backend settings (Ollama endpoint, cloud API keys, per-task routing)
FR38: The user can configure notification behavior (frequency, types, thresholds)
FR39: The user can configure system tray agent behavior (launch at startup, monitoring interval)
FR40: User settings are persisted locally and survive application restarts
FR41: The user can reset all settings to defaults
FR42: The user can launch GitPulse without any account, login, or network configuration
FR43: The system can operate fully offline (all core features work without network access)
FR44: The user can manually check for application updates via system tray or settings
FR45: The user can download GitPulse as a single binary (no installer wizard required)
FR46: The system can run on Windows, macOS, and Linux from initial release
Total FRs: 46
### Non-Functional Requirements
NFR1: Cold startup < 3 seconds
NFR2: Disk scan speed < 5 seconds (SSD, <100 repos)
NFR3: Memory usage < 200 MB with 50+ repos
NFR4: Binary size ~15 MB
NFR5: Batch operation throughput < 30 seconds (pull/push 20 repos)
NFR6: UI rendering responsiveness < 16ms per frame (60fps)
NFR7: Async AI loading — Smart Status does not block dashboard
NFR8: Incremental scan reload < 1 second from cache
NFR9: API key storage via OS keychain/secure storage, not plaintext
NFR10: Privacy by default — no data leaves machine unless cloud backend explicitly enabled
NFR11: Data flow transparency — visual indicator for cloud data transit
NFR12: Scan scope control — `.gitpulseignore` exclusions enforced
NFR13: Zero telemetry by default — opt-in only
NFR14: Git execution isolation — malicious repo cannot compromise application
NFR15: Dependency auditing — Rust/npm vulnerabilities checked before release
NFR16: Ollama version compatibility (API v1) with graceful fallback
NFR17: Cloud API compliance — stable API versions; rate limit handling
NFR18: Git version compatibility >= 2.20 on all platforms
NFR19: Native OS integration — platform-native tray, notifications, startup
NFR20: AI offline resilience — deterministic fallback when Ollama/cloud unavailable
NFR21: Scan fault tolerance — completes even if individual directories fail
NFR22: Batch fault tolerance — successful repos complete even when others fail
NFR23: Crash recovery — state preserved across crashes
NFR24: User data persistence — settings, scan configs, API keys survive updates
NFR25: Keyboard navigation for all core operations
NFR26: High contrast support — status indicators distinguishable in dark/high contrast mode
NFR27: Screen reader compatibility — ARIA markup on key dashboard components
Total NFRs: 27
### Additional Requirements
- Starter template: `npm create tauri-app@latest -- --template react-ts --manager npm gitpulse`
- Post-scaffold stack: Zustand, Tailwind CSS, Vitest, Playwright
- Tauri plugins: store, shell, fs, autostart, notification
- Rust crates: keyring, thiserror, async-trait
- Virtualization: @tanstack/react-virtual
- CI/CD: GitHub Actions matrix (Win x64, macOS x64+ARM, Linux x64)
- Distribution: GitHub Releases, single binary per platform, manual updates only
- Code signing deferred to Phase 1.5
- i18n framework ready from day 1
### PRD Completeness Assessment
PRD is comprehensive and well-structured. All requirements are numbered and traceable. Phase scoping (MVP/Phase 1.5/Phase 2) is clear. Risk mitigation documented. User journeys provide concrete validation scenarios.
## Epic Coverage Validation
### Coverage Matrix
| FR | PRD Requirement | Story Coverage | Status |
|---|---|---|---|
| FR1 | Recursive disk scan | Story 1.3 | Covered |
| FR2 | Configure root directories | Story 1.1 + 1.2 | Covered |
| FR3 | `.gitpulseignore` exclusion | Story 1.3 | Covered |
| FR4 | Detect repos via `.git` | Story 1.3 | Covered |
| FR5 | Manual rescan trigger | Story 1.5 | Covered |
| FR6 | Handle inaccessible directories | Story 1.4 | Covered |
| FR7 | Cache scan results | Story 1.5 | Covered |
| FR8 | Card grid view | Story 1.6 | Covered |
| FR9 | Sortable/filterable list view | Story 1.7 | Covered |
| FR10 | Toggle card/list view | Story 1.8 | Covered |
| FR11 | Sort repositories | Story 1.8 | Covered |
| FR12 | Filter by status | Story 1.8 | Covered |
| FR13 | Visual status indicators | Story 1.6 | Covered |
| FR14 | Render 100+ repos | Story 1.7 | Covered |
| FR15 | Batch git pull | Story 2.2 | Covered |
| FR16 | Batch git push | Story 2.3 | Covered |
| FR17 | Batch git fetch | Story 2.4 | Covered |
| FR18 | Batch git status | Story 2.5 | Covered |
| FR19 | Per-repo batch results | Story 2.6 | Covered |
| FR20 | Partial success handling | Story 2.6 | Covered |
| FR21 | Error details for failed repos | Story 2.6 | Covered |
| FR22 | Ollama integration | Story 3.1 | Covered |
| FR23 | Cloud API key configuration | Story 3.2 | Covered |
| FR24 | AI health summaries | Story 3.3 | Covered |
| FR25 | AI commit message suggestions | Story 3.4 | Covered |
| FR26 | Dormant repo detection | Story 3.5 | Covered |
| FR27 | Visual privacy indicator | Story 3.3 | Covered |
| FR28 | Operate without AI backend | Story 3.1 | Covered |
| FR29 | Per-task AI provider routing | Story 3.6 | Covered |
| FR30 | Cross-repo AI analysis | Story 3.7 | Covered |
| FR31 | Background system tray agent | Story 4.1 | Covered |
| FR32 | Remote change monitoring | Story 4.3 | Covered |
| FR33 | Push reminders | Story 4.4 | Covered |
| FR34 | Auto-launch at startup | Story 4.5 | Covered |
| FR35 | Tray context menu | Story 4.2 | Covered |
| FR36 | Scan root settings | Story 5.2 | Covered |
| FR37 | AI backend settings | Story 5.3 | Covered |
| FR38 | Notification settings | Story 5.4 | Covered |
| FR39 | System tray settings | Story 5.5 | Covered |
| FR40 | Settings persistence | Story 5.1 | Covered |
| FR41 | Reset to defaults | Story 5.6 | Covered |
| FR42 | No account/login required | Cross-cutting | Covered |
| FR43 | Fully offline operation | Cross-cutting | Covered |
| FR44 | Manual update check | Cross-cutting | Covered |
| FR45 | Single binary distribution | Cross-cutting | Covered |
| FR46 | Cross-platform support | Cross-cutting | Covered |
### Missing Requirements
None. All 46 FRs have traceable story coverage.
### Coverage Statistics
- Total PRD FRs: 46
- FRs covered in epics: 46
- Coverage percentage: 100%
## UX Alignment Assessment
### UX Document Status
Found: ux-design-specification.md (complete, 14-step workflow, status: complete)
### UX ↔ PRD Alignment
- Personas match: Sarah, Leo, Max, Jay appear in both UX spec and PRD journeys
- "Launch and Know" experience aligns with PRD "5-Second Wow" success criterion
- 8 custom components cover all dashboard FRs (card grid, list view, batch ops, privacy)
- PrivacyBadge directly implements FR27
- Toastless design philosophy aligns with PRD zero-friction approach
- Design direction (Compact Grid + Collapsible Stats Bar) supports PRD FR8-FR14
### UX ↔ Architecture Alignment
- UX specifies Tailwind CSS → Architecture confirms Tailwind CSS setup
- UX specifies Radix UI primitives → Architecture confirms Radix layer
- UX specifies @tanstack/react-virtual → Architecture confirms virtualization
- UX specifies Zustand stores → Architecture confirms Zustand for state management
- UX specifies tauri-plugin-store for persistence → Architecture confirms
- UX dark mode default → Architecture frontend supports theme system
- UX WCAG 2.1 AA target → Architecture mentions accessibility, no specific WCAG testing tools
### Alignment Issues
- **Minor**: Architecture does not specify CI-level WCAG testing tooling (e.g., axe-core integration). UX-DR19 targets WCAG 2.1 AA but no automated accessibility testing is specified in CI/CD pipeline.
- **No critical misalignments detected.**
### Warnings
None critical. UX documentation is comprehensive and well-aligned with both PRD and Architecture.
## Epic Quality Review
### Epic Structure Validation
#### User Value Focus Check
| Epic | Title | User Value | Verdict |
|---|---|---|---|
| Epic 1 | Repository Discovery & Dashboard | Users see all repos at a glance | PASS |
| Epic 2 | Batch Git Operations | Users batch pull/push/fetch across repos | PASS |
| Epic 3 | AI-Powered Repository Insights | Users get AI summaries and suggestions | PASS |
| Epic 4 | Background Agent & Notifications | Users get passive monitoring and alerts | PASS |
| Epic 5 | Settings & Preferences | Users configure all aspects of GitPulse | PASS |
All 5 epics deliver clear user value. No technical-only epics detected.
#### Epic Independence Validation
| Epic | Depends On | Independent? | Verdict |
|---|---|---|---|
| Epic 1 | Nothing | Fully standalone | PASS |
| Epic 2 | Epic 1 only | Yes — batch ops on visible repos | PASS |
| Epic 3 | Epic 1 only | Yes — AI analysis on repo data | PASS |
| Epic 4 | Epic 1 only | Yes — monitors discovered repos | PASS |
| Epic 5 | Epic 1 only | Yes — configures running app | PASS |
No circular dependencies. No epic requires a later epic to function.
### Story Quality Assessment
#### Story Sizing & Independence
- 36 stories across 5 epics
- All stories follow As a/I want/So that format
- All stories have Given/When/Then acceptance criteria
- No story is a pure technical setup without user value
- Story 1.1 (App Shell) frames scaffolding as user value (empty dashboard), which is appropriate
#### Dependency Analysis (Within-Epic)
**Epic 1:** Stories 1.1→1.2→1.3→1.4→1.5→1.6→1.7→1.8→1.9→1.10→1.11 — sequential, no forward deps. Story 1.8 (toggle/sort/filter) correctly depends on both views (1.6, 1.7) which precede it. ✓
**Epic 2:** Story 2.1 (toolbar) enables 2.2-2.5 (individual ops). Story 2.6 (results reporting) builds on batch ops. Story 2.7 (context menu) is independent of toolbar flow. All backward-only. ✓
**Epic 3:** Stories 3.1→3.2→3.3→3.4→3.5→3.6→3.7 — sequential. Story 3.5 (dormancy) is deterministic logic but correctly sequenced after AI foundation. Story 3.6 (routing) depends on 3.1 (trait) + 3.2 (providers), both precede it. ✓
**Epic 4:** Stories 4.1→4.2→4.3→4.4→4.5 — sequential. 4.2-4.5 all depend on tray agent (4.1). 4.4 (push reminders) depends on monitoring (4.3). ✓
**Epic 5:** Stories 5.1→5.2→5.3→5.4→5.5→5.6 — sequential. 5.2-5.6 all depend on settings foundation (5.1). ✓
#### Starter Template Compliance
Architecture specifies `npm create tauri-app@latest`. Story 1.1 integrates project scaffolding into the "App Shell & First Launch Experience" story, framed as user value (user sees empty dashboard). This is the correct approach — scaffolding is a means to user value, not an end.
#### Cross-Cutting FRs (FR42-FR46)
These are documented as "Cross-Cutting Requirements" spanning all epics. No single story owns them, which is appropriate since they are architectural constraints (no account, offline, cross-platform, single binary, update check).
### Quality Issues Found
#### Critical Violations
None.
#### Major Issues
None.
#### Minor Concerns
1. **Story 3.5 placement**: Dormancy detection (FR26) is deterministic (last commit date > threshold) but placed in Epic 3 (AI). FR26 is listed under "Smart Status (AI Integration)" in PRD, so the grouping follows PRD structure. Not incorrect, but worth noting for implementation — the core dormancy logic doesn't require AI.
2. **Cross-cutting FRs lack story ownership**: FR42-FR46 (zero-config, offline, cross-platform, single binary, update check) have no specific story assignments. They're architectural constraints that must be validated across all stories, not single-story deliverables. Acceptable for cross-cutting concerns.
3. **Story 1.1 scope**: Includes Tauri scaffolding + React setup + Tailwind + Zustand + TopBar + EmptyState + dark mode + window persistence. This is a large story but bounded by "first launch experience" and is standard for project initialization. Single dev agent completable.
## Summary and Recommendations
### Overall Readiness Status
## READY
All planning artifacts are complete, aligned, and validated. Implementation can begin.
### Critical Issues Requiring Immediate Action
None.
### Minor Items to Consider During Implementation
1. **WCAG testing in CI**: UX-DR19 targets WCAG 2.1 AA compliance but the architecture does not specify automated accessibility testing (e.g., axe-core) in the CI pipeline. Consider adding accessibility linting and testing to the GitHub Actions workflow during Epic 1 implementation.
2. **Cross-cutting FR validation**: FR42-FR46 (zero-config, offline, cross-platform, single binary, update check) have no single story owner. Validate these as acceptance criteria during each epic's review rather than deferring to end-of-project testing.
3. **Dormancy detection placement**: Story 3.5 (Dormant Detection) is in Epic 3 (AI) but the core logic is deterministic. If dormancy detection is needed earlier, it could be moved to Epic 1 without requiring AI infrastructure.
### Recommended Next Steps
1. Begin implementation with **Epic 1, Story 1.1** (App Shell & First Launch Experience) — scaffold the Tauri project and build the empty state dashboard
2. Follow the story sequence within each epic — all dependencies are backward-only
3. Develop epics in order (1→2→3→4→5) for natural dependency flow, though Epics 2-5 can be parallelized by different developers if available
### Assessment Summary
| Category | Findings | Status |
|---|---|---|
| Document Inventory | 4/4 documents found, no duplicates | PASS |
| FR Coverage | 46/46 FRs mapped to stories (100%) | PASS |
| NFR Coverage | 27/27 NFRs addressed across epics | PASS |
| UX-DR Coverage | 25/25 UX-DRs mapped to stories | PASS |
| UX ↔ PRD Alignment | Strong, no critical misalignments | PASS |
| UX ↔ Architecture Alignment | Strong, 1 minor gap (WCAG CI testing) | PASS |
| Epic User Value | All 5 epics deliver user value | PASS |
| Epic Independence | All epics standalone, no circular deps | PASS |
| Story Quality | 36 stories, all properly structured | PASS |
| Forward Dependencies | None detected | PASS |
| Critical Issues | 0 | — |
| Major Issues | 0 | — |
| Minor Concerns | 3 (non-blocking) | ACCEPTABLE |
### Final Note
This assessment identified **0 critical issues** and **0 major issues** across 6 validation categories. 3 minor concerns were noted but none block implementation start. The planning artifacts (PRD, Architecture, UX Design, Epics & Stories) are complete, internally consistent, and ready for development.
**Assessor:** Implementation Readiness Workflow
**Date:** 2026-04-25

525
_bmad-output/planning-artifacts/prd.md Normal file
View File

@@ -0,0 +1,525 @@
---
stepsCompleted: [step-01-init, step-02-discovery, step-02b-vision, step-02c-executive-summary, step-03-success, step-04-journeys, step-05-domain-skipped, step-06-innovation, step-07-project-type, step-08-scoping, step-09-functional, step-10-nonfunctional, step-11-polish, step-12-complete]
inputDocuments:
- "product-brief-gitpulse.md"
- "product-brief-gitpulse-distillate.md"
- "market-git-dashboard-ia-research-2026-04-24.md"
workflowType: 'prd'
documentCounts:
briefs: 2
research: 1
projectDocs: 0
classification:
projectType: desktop_app
domain: general
complexity: low
projectContext: greenfield
---
# Product Requirements Document - GitPulse
**Author:** Ramez
**Date:** 2025-04-25
## Executive Summary
GitPulse is a local-first, open source desktop application that serves as the multi-repository command center for developers managing five or more Git repositories on a single machine. It automatically discovers all Git repos on disk, presents their status in a unified visual dashboard, enables batch git operations, and provides model-agnostic AI insights — all without requiring a login, configuration file, or cloud connection.
**Target users:** Indie developers, freelances, and power users managing 10-50+ repositories across client work, open source contributions, and personal projects. These developers lose significant time daily to manual `git status` checks, forgotten pushes, stale branches, and the cognitive overhead of tracking repository state across directories.
**The problem:** No open source tool combines automatic disk discovery, a visual multi-repo dashboard, batch git operations, and AI-powered insights in a performant, cross-platform, zero-configuration package. GitKraken (Electron, paid, 3.1/5 rating) paywalls private repos. GitButler ($17M raised, Tauri/Rust) is single-repo by design and Fair Source licensed. lazygit and gita offer no visual dashboard. The niche is empty.
**The product:** Built on Tauri v2 with a Rust backend and React frontend, GitPulse delivers a ~15 MB binary with <200 MB RAM. The AI layer is model-agnostic — users bring their own intelligence via Ollama (local, private) or cloud APIs (Gemini, DeepSeek, OpenAI, Anthropic). Privacy is the default; cloud is the opt-in, with a clear visual indicator showing data flow mode. The system tray agent provides passive monitoring without requiring the dashboard to be open.
### What Makes This Special
1. **Model-agnostic AI infrastructure.** Unlike GitKraken (Gemini-only) or GitButler (Claude-only), GitPulse lets developers choose their AI engine per task — Ollama for private commit messages, DeepSeek for cost-effective analysis, Gemini for complex reasoning. The product provides the plumbing; the user provides the intelligence.
2. **Zero-friction onboarding.** From download to full dashboard in under 30 seconds. No sign-up, no token, no network, no configuration. The first scan — seeing all repositories appear instantly — is the primary conversion moment. Every competitor gates value behind auth flows or manual setup.
3. **Structural performance moat.** Tauri + Rust produces binaries 10-15x smaller and 3-5x less memory-hungry than Electron competitors. This is architectural — competitors would need to rebuild from scratch to match it.
4. **Truly open source (MIT/Apache).** GitButler's Fair Source license prohibits building competitors and is not OSI-approved. GitPulse's MIT/Apache licensing allows forking, commercial use, and community trust — a genuine adoption accelerator in the open source ecosystem.
5. **Complementary to AI IDEs.** Cursor, Copilot, and Windsurf solve intra-repo productivity. GitPulse solves inter-repo visibility. Developers use both without conflict — eliminating the "us vs. the giants" positioning trap.
## Project Classification
| Attribute | Value |
|-----------|-------|
| **Project Type** | Desktop Application (Tauri v2 + React + Rust) |
| **Domain** | Developer Productivity / Developer Infrastructure |
| **Complexity** | Low (no regulatory requirements; complexity is technical, not compliance-driven) |
| **Project Context** | Greenfield — new product, no existing system |
| **License** | MIT/Apache (truly open source) |
| **Target Platforms** | Windows, macOS, Linux |
## Success Criteria
### User Success
**The 5-Second Wow:** From launch to a fully populated dashboard in under 30 seconds. No login, no config, no wizard — just instant visibility. This is the primary conversion moment. If the first scan doesn't delight, nothing else matters.
**Measurable Success Signals:**
- Average repos scanned per user > 10 (validates the multi-repo problem exists for this user)
- Batch operation used within first session (validates the "command center" value proposition)
- Smart Status consulted > 3 times per session (validates AI layer adds real value)
- System tray notification acted upon within 24 hours (validates passive monitoring utility)
- At least 2 AI backends configured per active user (validates model-agnostic approach)
**Emotional Success:**
- *Monday morning relief:* "I can see exactly which repos need attention" replaces the dread of 23 `git status` commands
- *Control feeling:* "I know the state of all my code" replaces anxiety about forgotten pushes and stale branches
- *Trust moment:* "My code never leaves my machine" (local mode badge) establishes the privacy foundation
### Business Success
| Timeframe | Metric | Target |
|-----------|--------|--------|
| **Month 3** | GitHub stars | 500+ |
| **Month 3** | Monthly active users | 500+ |
| **Month 3** | Cumulative downloads | 2,000+ |
| **Month 3** | Hacker News Show HN score | 200+ upvotes |
| **Month 6** | GitHub stars | 2,000+ |
| **Month 6** | Monthly active users | 2,000+ |
| **Month 6** | Paying subscribers (cloud tier) | 50 |
| **Month 6** | D30 retention | 40%+ |
| **Month 12** | GitHub stars | 5,000+ |
| **Month 12** | Monthly active users | 10,000+ |
| **Month 12** | Paying subscribers | 200 |
| **Month 12** | MRR | $1,500+ |
| **Month 12** | D30 retention | 50%+ |
**Fundraising trigger:** Seed round ($1–2M) if 5,000 MAU + 3% free-to-cloud conversion by month 9.
### North Star & KPIs
**North Star KPI:** Monthly active users who scan 10+ repositories (validates both adoption and problem-solution fit).
**Secondary KPIs:**
- D7 retention > 30%, D30 retention > 40% (product stickiness)
- Batch operations per session > 1 (power feature adoption)
- Smart Status engagement rate > 50% of sessions (AI value validation)
- System tray notification action rate > 60% (passive monitoring value)
- GitHub star-to-download ratio > 0.25 (organic enthusiasm signal)
**Technical performance targets** are defined in the Non-Functional Requirements section (NFR1–NFR8).
## Product Scope & Phased Development
### MVP Strategy
**Approach: Problem-Solving MVP** — deliver the core "repo visibility" problem solved in 30 seconds, then layer intelligence and automation on top.
- The first scan IS the product. If it doesn't delight, nothing else matters.
- AI is a progressive enhancement, never a dependency. The product works perfectly without it.
- Zero-friction is non-negotiable. Every config step or login screen is a conversion killer.
- Cross-platform from day 1 — the target audience (indie devs, freelancers) is platform-diverse.
- **Resource assumption:** Solo developer with potential community contributors post-launch. MVP designed for one-person execution over 2-3 months.
### Phase 1 — MVP Core (Weeks 1-6)
- Weeks 1-2: Rust backend — disk scanner, git status parser, Tauri scaffolding
- Weeks 3-4: React frontend — Card Grid, List View, batch operations UI
- Weeks 5-6: System tray + Ollama integration + privacy indicator + packaging
- **Delivers:** Auto-scan + Dashboard + Batch Ops + System Tray + Smart Status (Ollama) + Zero-config launch
### Phase 1.5 — MVP Complete (Weeks 7-10)
- Cloud AI integration (Gemini, DeepSeek, OpenAI, Anthropic)
- Dormancy detection, `.gitpulseignore` refinements
- Code signing for Windows/macOS, i18n framework scaffolding
- **Delivers:** Full MVP as originally scoped — all Day 1 features
**Must-have capabilities for Day 1 launch:**
| Capability | Why Must-Have |
|------------|---------------|
| Auto disk scan | Core value proposition — no scan, no product |
| Card Grid view | Primary visual interface for pattern recognition |
| List View with batch ops | Differentiator vs single-repo tools |
| Per-repo error reporting | Batch ops fail partially — silent failures destroy trust |
| System tray agent | Passive monitoring = sustained engagement |
| Smart Status (Ollama) | "Wow" moment — AI-generated health summaries |
| Privacy indicator | Trust foundation — shows data flow mode |
| Zero-config launch | Conversion moment — 30 seconds to value |
| Cross-platform (Win/Mac/Linux) | Target audience is platform-diverse |
| `.gitpulseignore` | Privacy control — exclude sensitive repos |
**Nice-to-have for Day 1 (cut if timeline pressure):**
| Capability | Rationale | Target |
|------------|-----------|--------|
| Cloud AI (4 providers) | Ollama covers core AI use case | Phase 1.5 |
| Dormancy detection | Useful but not conversion-critical | Phase 1.5 |
| i18n framework | English sufficient for launch | Phase 2 |
### Phase 2 — Growth (Months 4-6)
- Repository grouping, tagging, workspace contexts
- Advanced Smart Status: cross-repo dependency detection
- File watcher for real-time status updates
- Git worktree integration, CLI companion (`gitpulse-cli`)
- Premium cloud tier: multi-machine sync, team analytics
### Phase 3 — Expansion (Months 7-12)
- Inter-repository dependency graph visualization, MCP support
- Autonomous AI agents for code review and anomaly detection
- GitHub/GitLab integration (PRs, issues, CI status)
- Enterprise tier: SSO, compliance dashboards, audit trails
### Explicitly Out of MVP
Cloud sync/team collaboration, built-in code editor/diff viewer, merge conflict resolution UI, CI/CD integration, GitHub/GitLab API integration (issues, PRs, CI), mobile companion, enterprise features (SSO, compliance, audit logs). Telemetry: opt-in only with clear disclosure.
### Risk Mitigation
**Technical:**
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| Scan performance on slow/network drives | Medium | High | Benchmark early (week 2); async scan with progress; scan timeout |
| Tauri v2 tray inconsistencies across platforms | Medium | Medium | Use stable tray API; test all 3 platforms weekly |
| Ollama model loading times | Low | Medium | Smart Status runs async — don't block dashboard |
| Large repo count (100+) UI perf | Medium | Medium | Virtualized list/grid rendering from day 1 |
| SmartScreen/code signing friction | High | High | Budget for signing cert ($200-500/yr); prioritize in Phase 1.5 |
**Market:**
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| GitButler ships multi-repo first | Low | High | First-mover speed; model-agnostic as durable differentiator |
| No adoption (tooling fatigue) | Medium | High | Zero-friction is the moat; Show HN as primary launch |
| AI features perceived as gimmick | Medium | Medium | Deterministic fallback always available |
| Provider API changes break integration | Medium | Low | Abstract AI behind provider interface |
**Resource:**
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| Solo dev bandwidth — all platforms | Medium | High | Tauri handles cross-platform; test all OS weekly |
| Burnout from scope creep | Medium | High | Strict Phase 1/1.5 boundary; cut cloud AI to 1.5 if needed |
| Post-launch support drain | High | Medium | GitHub Issues triage; community contribution guidelines from day 1 |
## Innovation & Novel Patterns
### Detected Innovation Areas
**1. Model-Agnostic AI Plumbing for Git (Primary Innovation)**
No git tool offers per-task AI engine selection. GitKraken locks to Gemini. GitButler locks to Claude. GitPulse provides the plumbing — the user provides the intelligence. Per-task routing (Ollama for routine commits, cloud for complex analysis) is unprecedented in this category.
*Assumption challenged:* A git tool must choose its AI provider for the user. GitPulse: the user chooses per task.
*Validation:* Users configuring 2+ AI backends (Success Criteria metric).
**2. Vacant Quadrant — Auto-Discovery + Dashboard + Batch + AI**
No open source tool occupies the intersection of automatic disk discovery, multi-repo visual dashboard, batch git operations, and AI-powered insights. This is a first-mover position, not incremental improvement.
*Assumption challenged:* Developers don't need a dedicated multi-repo tool — shell scripts and CLI suffice. GitPulse: instant visual visibility fundamentally changes the experience.
*Validation:* D7 retention > 30% validates visibility as a game-changer.
**3. Multi-Level Privacy Indicator**
The visual badge switching between "Your code never leaves your machine" (Ollama) and "Cloud — data transits to [provider]" is novel UX. No competitor offers this transparency. Aligns with post-Copilot data policy momentum (April 2025).
*Assumption challenged:* Developers trust tools by default. GitPulse: in a post-Copilot world, trust is earned through explicit transparency.
*Validation:* If local mode remains most-used even when cloud keys are configured, privacy-first hypothesis is validated.
**4. Zero-Friction as Architectural Competitive Advantage**
No login, no config, no wizard. The first scan is the conversion moment. Made possible by Tauri + Rust architecture (<30 seconds total). Electron competitors physically cannot deliver this experience.
*Assumption challenged:* Guided onboarding improves retention. GitPulse: retention comes from instant value, not hand-holding.
*Validation:* Time from download to first batch operation < 2 minutes.
### Validation Approach
| Innovation | Validation Method | Success Signal |
|------------|-------------------|----------------|
| Model-agnostic AI | Track backend configuration count per user | 2+ backends per active user |
| Vacant quadrant | D7/D30 retention + repos scanned per user | D7 > 30%, avg repos > 10 |
| Privacy indicator | Local vs cloud usage ratio | Local mode dominant even with cloud configured |
| Zero-friction | Time-to-first-action measurement | < 2 minutes download to first batch op |
### Innovation Risk Mitigation
| Risk | Mitigation |
|------|------------|
| Model-agnostic too complex to configure | Smart defaults: Ollama auto-detected, cloud as opt-in guided setup |
| Users stay in "no AI" mode | Smart Status works in deterministic mode — AI is enhancement, not dependency |
| Performance degrades at 100+ repos | Lazy loading, pagination, incremental scan |
| GitButler adds multi-repo | First-mover + MIT/Apache vs Fair Source + model-agnostic as durable differentiator |
## User Journeys
### Journey 1: Sarah's Monday Morning (Indie Dev — Happy Path)
**Persona:** Sarah, 32, freelance full-stack developer. She juggles 23 repositories: 8 client projects, 6 open source contributions, 5 personal experiments, and 4 configuration/utility repos. She context-switches daily and routinely loses track of uncommitted changes.
**Opening Scene:** Monday 9 AM. Sarah sits down with coffee, dreading the ritual of checking each repo. She's been burned before — last month she lost 3 hours of work in a client repo because she forgot to push before switching machines.
**Rising Action:** She launches GitPulse for the first time. No login screen. No setup wizard. The binary opens instantly and begins scanning her home directory. In under 30 seconds, 23 tiles populate the dashboard — each showing branch name, status color (green/yellow/red), ahead/behind count, and last commit timestamp.
**Climax:** Three tiles immediately catch her eye:
- `client-acme-app` — yellow, "3 uncommitted changes, last activity Friday 6 PM"
- `oss-contrib-lib` — red, "12 commits behind origin/main"
- `personal-scripts` — yellow, "uncommitted changes, 2 weeks ago"
She selects all three with Shift+Click, clicks "Batch Pull" — the two behind repos update in seconds. For the uncommitted changes, she clicks into `client-acme-app`, sees the diff summary, and Ollama suggests a commit message: "Update authentication middleware for session timeout handling." She accepts, commits, pushes. Total time: 2 minutes.
**Resolution:** Her entire repo fleet is green. She minimizes GitPulse to the system tray and starts coding with confidence. The tray icon will pulse if anything changes during the day — she doesn't need to check again.
**Emotional arc:** Dread → surprise (it just works) → relief (visible clarity) → confidence (everything handled) → trust (passive monitoring has her back).
**Capabilities revealed:** Auto-discovery, Card Grid view, batch operations, Smart Status (Ollama), commit message suggestions, system tray agent, per-repo status visualization.
---
### Journey 2: Leo's Post-Sprint Audit (Power User / Tech Lead — Advanced Workflow)
**Persona:** Leo, 38, senior backend engineer at a mid-size SaaS company. He manages 18 microservice repositories in a monorepo-like architecture. His team just finished a 2-week sprint, and he needs to verify all services are synchronized and identify any cross-repo dependencies that need attention.
**Opening Scene:** Sprint retrospective just ended. Leo needs to confirm all 18 services are on the latest version and identify any cascade effects from a shared library update.
**Rising Action:** He opens GitPulse and switches to List View — sortable rows let him see all 18 repos at once. He clicks the "Behind" column header — 7 repos are behind their remotes. He selects all 7, executes "Batch Pull." Two fail with merge conflicts (clearly reported per-repo with error details). Five succeed.
**Climax:** For the two conflicts, Leo doesn't panic — the per-repo error report shows exactly which files conflict. He switches to his terminal for manual resolution (GitPulse doesn't do merge conflict UI in MVP). Back in GitPulse, he refreshes — both now show green.
Now he enables Smart Status in cloud mode (his Gemini API key is already configured). The privacy badge shifts from "Local" to "Cloud — data transits to Google." He runs a cross-repo health analysis. Gemini reports: "`shared-auth-lib` was updated in 5 repos but not in `payment-service` and `notification-service` — these may need version bumps." He selects the two flagged repos, pulls, and verifies.
**Resolution:** All 18 repos green. He screenshots the dashboard for his team standup. The Smart Status saved him from a potential auth token mismatch in production.
**Emotional arc:** Responsibility → systematic control → alert (conflicts detected, handled) → insight (AI catches what manual checks missed) → professional confidence.
**Capabilities revealed:** List View with sorting/filtering, batch pull with per-repo error reporting, Smart Status cloud mode (Gemini), cross-repo dependency analysis, privacy indicator, graceful error handling with partial success UX.
---
### Journey 3: Max's Great Cleanup (Maker / Side-Project Builder — Dormancy Discovery)
**Persona:** Max, 28, creative developer with a habit of starting projects. He has 47 repositories — some active, many dormant, a few he's forgotten entirely. He hasn't done a cleanup in over a year.
**Opening Scene:** It's a Saturday afternoon. Max decides it's time to organize his digital life. He's vaguely aware that some old projects might have uncommitted changes or API keys he should secure.
**Rising Action:** He launches GitPulse. The scan finds 47 repos across 4 directories. The Card Grid is overwhelming at first — too many tiles. He switches to List View and sorts by "Last Activity." The Smart Status (Ollama, local mode — privacy matters here) generates summaries:
- 12 repos dormant for 3+ months
- 3 repos with uncommitted changes older than 2 weeks
- 8 repos with unmerged feature branches
- 2 repos with remote URLs pointing to deleted GitHub repositories
**Climax:** Max creates a mental triage:
1. The 3 repos with uncommitted changes — he reviews each, commits what's worth keeping, discards the rest
2. The 2 repos with deleted remotes — he archives them locally
3. The 8 repos with stale branches — he bulk-deletes branches that were clearly experiments (branch names like `test-thing`, `wip-new-api`)
For the 12 dormant repos, he doesn't delete anything — but he tags them "dormant" for future reference (a Phase 2 feature — for now he makes a mental note).
**Resolution:** In 20 minutes, Max has cleaned up 15 repos. His dashboard now shows a manageable set of active projects. He feels lighter — like cleaning a cluttered desk.
**Emotional arc:** Overwhelm → discovery (visual clarity from chaos) → triage control → satisfaction (order restored) → lightness.
**Capabilities revealed:** Large repo count handling, List View sorting by activity, Smart Status dormancy detection (Ollama), commit message suggestions for forgotten changes, batch operations for cleanup, clear per-repo status even at scale.
---
### Journey 4: Jay's 30-Second Trial (Newcomer — Conversion Moment)
**Persona:** Jay, 25, junior developer. He saw GitPulse on Hacker News Show HN with 200+ upvotes. He has only 5 repos — mostly personal projects and a fork of a popular library. He's curious but skeptical.
**Opening Scene:** Jay clicks the download link. 15 MB binary. No installer — he double-clicks the executable. On Windows, SmartScreen shows an "unrecognized app" warning (a known friction point for new desktop apps). He clicks "Run anyway."
**Rising Action:** GitPulse opens. No login screen. No "Welcome to GitPulse!" onboarding overlay. Just a clean window asking which directories to scan. He selects his `~/Projects` folder. 5 repos appear in under 3 seconds. Each tile shows meaningful data — branch, status, last commit.
**Climax:** Jay doesn't have 50 repos, so the multi-repo value isn't immediately life-changing. But he notices one tile is yellow — a personal project with uncommitted changes from 3 weeks ago that he forgot about. He clicks it, sees a Smart Status summary: "2 files modified, likely CSS adjustments based on file names." He doesn't even need AI to remember what it was — the visibility alone solved the problem.
He decides to try the AI feature. He configures Ollama (already installed from previous experiments), runs Smart Status on his forked library. The one-line summary is genuinely useful: "Up to date with upstream, 1 local modification in README." He stars the GitHub repo.
**Resolution:** Jay keeps GitPulse running in the system tray. With 5 repos it's not essential — but it's lightweight enough to justify keeping. When his repo count grows (new job, more side projects), GitPulse will already be there.
**Emotional arc:** Curiosity → skepticism → mild surprise (it works immediately) → small delight (found forgotten changes) → investment decision (keeping it for future value).
**Capabilities revealed:** Small footprint binary download, zero-friction launch, SmartScreen handling (implicit requirement), small repo count UX (dashboard shouldn't feel empty with <10 repos), Smart Status value even at small scale, system tray persistence.
---
### Journey Requirements Summary
| Capability Area | Journeys Revealing Need | Priority |
|----------------|------------------------|----------|
| Auto Discovery | Sarah, Max, Jay | MVP |
| Card Grid View | Sarah, Jay | MVP |
| List View (sort/filter/select) | Leo, Max | MVP |
| Batch Operations | Sarah, Leo, Max | MVP |
| Per-repo Error Reporting | Leo | MVP |
| System Tray Agent | Sarah, Jay | MVP |
| Smart Status — Ollama | Sarah, Max, Jay | MVP |
| Smart Status — Cloud APIs | Leo | MVP |
| Privacy Indicator | Leo | MVP |
| Commit Message Suggestions | Sarah, Max | MVP |
| Dormancy Detection | Max, Jay | MVP |
| Cross-repo Analysis | Leo | MVP |
| Small Repo Count UX | Jay | MVP |
| Download/First-launch UX | Jay | MVP |
| Repo Tagging/Grouping | Max | Phase 2 |
| SmartScreen/Code Signing | Jay | MVP (implicit) |
## Functional Requirements
### Repository Discovery
- FR1: The user can initiate a recursive disk scan to discover Git repositories on their machine
- FR2: The user can configure which root directories to scan
- FR3: The user can exclude directories from scanning via a `.gitpulseignore` file (glob syntax)
- FR4: The system can detect Git repositories by identifying `.git` folders
- FR5: The user can manually trigger a rescan to refresh the repository list
- FR6: The system can gracefully handle inaccessible directories (skip and log, no crash)
- FR7: The system can cache scan results for instant reload on subsequent launches
### Dashboard & Visualization
- FR8: The user can view repositories in a card grid showing branch, status (clean/dirty/ahead/behind), last commit, and stash count
- FR9: The user can view repositories in a sortable, filterable list view with multi-select
- FR10: The user can toggle between card grid and list view
- FR11: The user can sort repositories by status, last activity date, branch name, or ahead/behind count
- FR12: The user can filter repositories by status (clean, dirty, ahead, behind, dormant)
- FR13: The system can display visual status indicators (color/badges) for instant pattern recognition across all repos
- FR14: The system can render large repository lists (100+) without UI degradation
### Batch Operations
- FR15: The user can select multiple repositories and execute batch `git pull`
- FR16: The user can select multiple repositories and execute batch `git push`
- FR17: The user can select multiple repositories and execute batch `git fetch`
- FR18: The user can batch `git status` across multiple repositories
- FR19: The system can report per-repo results for batch operations (success/failure with details)
- FR20: The system can handle partial success — repos that succeed continue, repos that fail are reported with error details
- FR21: The user can see specific error details (e.g., merge conflicts, auth errors) for failed repos
### Smart Status (AI Integration)
- FR22: The user can enable Ollama integration for local, private repository health summaries
- FR23: The user can configure cloud API keys (Gemini, DeepSeek, OpenAI, Anthropic) for AI-powered analysis
- FR24: The system can generate one-line repository health summaries via the configured AI backend
- FR25: The system can suggest commit messages based on staged changes via the configured AI backend
- FR26: The system can detect and flag dormant repositories beyond a configurable threshold
- FR27: The user can see a visual privacy indicator showing whether data processing is local or cloud-based
- FR28: The system can operate entirely without any AI backend configured (deterministic status parsing as default)
- FR29: The user can route different AI tasks to different providers (e.g., Ollama for commits, cloud for analysis)
- FR30: The system can provide cross-repo analysis when using a cloud AI model (e.g., shared library dependencies across repos)
### System Tray Agent & Notifications
- FR31: The user can run GitPulse as a background system tray agent with the dashboard closed
- FR32: The system can monitor for remote changes and alert the user via native OS notifications
- FR33: The system can send push reminders for repos with unpushed commits older than a configurable threshold
- FR34: The user can configure GitPulse to auto-launch at system startup (opt-in)
- FR35: The user can access common operations (status, pull, push) via the system tray context menu
### Settings & Configuration
- FR36: The user can configure scan root directories via a settings interface
- FR37: The user can configure AI backend settings (Ollama endpoint, cloud API keys, per-task routing)
- FR38: The user can configure notification behavior (frequency, types, thresholds)
- FR39: The user can configure system tray agent behavior (launch at startup, monitoring interval)
- FR40: User settings are persisted locally and survive application restarts
- FR41: The user can reset all settings to defaults
### Onboarding & Distribution
- FR42: The user can launch GitPulse without any account, login, or network configuration
- FR43: The system can operate fully offline (all core features work without network access)
- FR44: The user can manually check for application updates via system tray or settings
- FR45: The user can download GitPulse as a single binary (no installer wizard required)
- FR46: The system can run on Windows, macOS, and Linux from initial release
## Non-Functional Requirements
### Performance
| ID | Requirement | Measurement | Target |
|----|-------------|-------------|--------|
| NFR1 | Cold startup | Time from launch to interactive dashboard | < 3 seconds |
| NFR2 | Disk scan speed | Time to discover all repositories | < 5 seconds (SSD, <100 repos) |
| NFR3 | Memory usage | RAM during normal operation | < 200 MB with 50+ repos |
| NFR4 | Binary size | Distribution artifact size | ~15 MB |
| NFR5 | Batch operation throughput | Time to pull/push 20 repos | < 30 seconds |
| NFR6 | UI rendering responsiveness | No perceptible jank during scrolling or view switching | < 16ms per frame (60fps) |
| NFR7 | Async AI loading | Smart Status does not block dashboard | AI results appear asynchronously; UI stays responsive |
| NFR8 | Incremental scan | Reload scan on subsequent launch | < 1 second from cache |
### Security
| ID | Requirement | Details |
|----|-------------|---------|
| NFR9 | API key storage | Cloud API keys stored using OS keychain/secure storage, not plaintext in config files |
| NFR10 | Privacy by default | No repository data leaves the machine unless user explicitly enables a cloud backend |
| NFR11 | Data flow transparency | Visual indicator always clearly shows whether data transits to a cloud provider |
| NFR12 | Scan scope control | Directories excluded via `.gitpulseignore` are never scanned or indexed |
| NFR13 | Zero telemetry by default | No usage data collected unless user explicitly opts in |
| NFR14 | Git execution isolation | Git commands run in isolated processes; a malicious repo cannot compromise the application |
| NFR15 | Dependency auditing | Rust and npm dependencies audited for known vulnerabilities before each release |
### Integration
| ID | Requirement | Details |
|----|-------------|---------|
| NFR16 | Ollama version compatibility | Supports Ollama stable releases (API v1) with graceful fallback on version mismatch |
| NFR17 | Cloud API compliance | Supports stable API versions for Gemini, DeepSeek, OpenAI, Anthropic; handles API error responses and rate limits gracefully |
| NFR18 | Git version compatibility | Supports Git >= 2.20 on all platforms; graceful fallback with clear error if Git is missing or too old |
| NFR19 | Native OS integration | Uses platform-native system tray APIs, notification centers, and startup launch methods — no workarounds |
| NFR20 | AI offline resilience | Ollama failure or cloud unavailability does not block any feature — deterministic fallback with AI status indication |
### Reliability
| ID | Requirement | Details |
|----|-------------|---------|
| NFR21 | Scan fault tolerance | Scan completes even if individual directories are inaccessible, corrupted, or permission-denied |
| NFR22 | Batch fault tolerance | Batch operations complete for successful repos even when individual repos fail |
| NFR23 | Crash recovery | Application state preserved across crashes — reopening does not require reconfiguration |
| NFR24 | User data persistence | Settings, scan configurations, and API keys survive application updates |
### Accessibility
| ID | Requirement | Details |
|----|-------------|---------|
| NFR25 | Keyboard navigation | All core operations (selection, batch ops, view switching) accessible via keyboard |
| NFR26 | High contrast support | Visual status indicators remain distinguishable in high contrast/dark mode |
| NFR27 | Screen reader compatibility | Key dashboard components use ARIA markup for basic screen reader support |
## Desktop Application Specific Requirements
### Platform Support
| Platform | Architecture | Distribution | Notes |
|----------|-------------|--------------|-------|
| Windows | x64 | `.exe` (portable) + optional MSI | SmartScreen handling required (code signing needed) |
| macOS | x64 + ARM (Apple Silicon) | `.dmg` | Universal binary preferred; Apple notarization required |
| Linux | x64 | `.deb` + `.AppImage` + `.rpm` | AppImage for zero-install, deb/rpm for package managers |
**Tauri v2 strategy:** Native webview per platform (WebView2/WebKit/WebKitGTK). Rust backend compiles identically across platforms. React frontend platform-agnostic. Platform-specific code (system tray, auto-launch) isolated behind feature flags.
### System Integration
- **System tray:** Windows (native via Tauri), macOS (menu bar), Linux (D-Bus/libappindicator)
- **Notifications:** Native OS notifications (Windows Action Center, macOS Notification Center, libnotify)
- **Auto-launch:** Opt-in via settings. Windows Registry, macOS LaunchAgent, Linux XDG autostart
- **Disk scanner:** Recursive `.git` detection with `.gitpulseignore` support (glob syntax)
### Update Strategy
- Manual update check via system tray / settings; GitHub Releases as distribution channel
- No forced auto-update — respect user control
- Update check is the only outbound network request in local-only mode
- Post-MVP: Tauri built-in updater (opt-in), delta updates
- **Code signing required:** Authenticode (Windows), Apple Developer + notarization (macOS), GPG (Linux)
### Offline Capabilities
- Core functionality (scan, dashboard, batch ops, deterministic status) requires zero network
- Ollama works entirely offline when running locally
- Cloud AI gracefully degrades to deterministic parsing
- Settings stored locally (JSON/TOML in app data directory)
- Scan results cached for instant reload on subsequent launches

159
_bmad-output/planning-artifacts/product-brief-gitpulse-distillate.md Normal file
View File

@@ -0,0 +1,159 @@
---
title: "Product Brief Distillate: GitPulse"
type: llm-distillate
source: "product-brief-gitpulse.md"
created: "2025-04-25"
purpose: "Token-efficient context for downstream PRD creation"
---
# GitPulse — Product Brief Distillate
## Product Identity
- **Name:** GitPulse (project codename; also considered: GitRadar)
- **Tagline concept:** "The command center for your code"
- **Positioning:** Developer infrastructure (not tooling) — the control plane for local code ecosystems
- **License:** MIT/Apache (truly open source, not Fair Source)
- **Stack:** Tauri v2 + React frontend + Rust backend
- **Target:** Indie devs, freelances, power users managing 5+ repos
## Problem Context
- Core pain: developers lose track of repo state across 5-50+ repos, leading to forgotten pushes, stale branches, undetected conflicts
- Time cost: significant monthly time loss to manual `git status` checks (GitKraken marketing claims 20+ hours/month — should be validated with independent research before citing to investors)
- Coping mechanisms: shell scripts (fragile), VS Code workspaces (basic), GitKraken Workspaces (paid/heavy), gita (manual config), lazygit (single-repo)
- Key insight: no tool combines auto-discovery + visual dashboard + batch ops + AI in a free/open package
## User Segments (Detailed)
**Segment 1 — Indie Dev Poly-Project (primary):**
- Freelance/solo, 10-50+ repos across clients, OSS, personal
- Context-switches daily, loses track of uncommitted changes
- Wants instant visibility, zero config
- Budget: $0-10/month for tools
**Segment 2 — Power User / Tech Lead:**
- Senior dev, microservices architecture, 12-30+ repos
- Uses CLI + GUI hybrid workflow
- Wants batch ops, cross-repo dependency visibility, advanced AI analysis
- Willing to configure cloud API keys for powerful reasoning
**Segment 3 — Maker / Side-Project Builder:**
- Creative dev with 20+ side projects, many dormant
- Needs dormancy detection, cleanup prompts
- Budget-constrained, values free/open source
## UX Decisions
- **Card Grid view:** compact tiles for pattern recognition (branch, status, ahead/behind, last commit, stash)
- **List view:** sortable/filterable/selectable rows for batch operations
- **System tray:** always-on monitoring, push reminders, remote change alerts
- **First launch experience:** scan starts immediately, no wizard, no login. Target: full dashboard visible in < 30 seconds from download
- **i18n:** English at launch, framework ready from day 1, French planned as first additional language
- **.gitpulseignore:** exclude sensitive directories from auto-discovery (client work, tutorial clones, etc.)
## AI Architecture — Model-Agnostic
- **Local mode (Ollama):** Default, fully private, free. Used for commit messages, health summaries
- **Cloud mode:** User's own API keys for Gemini, DeepSeek, OpenAI, Anthropic
- **Hybrid mode:** Per-task routing — Ollama for routine tasks (free), cloud for complex analysis (paid by user)
- **Privacy indicator:** Visual badge in UI showing local vs cloud mode. "Your code never leaves your machine" in local mode
- **Graceful degradation:** Works perfectly without any AI (deterministic status parsing)
- **No vendor lock-in:** Unlike GitKraken (Gemini-only) or GitButler (Claude-only)
- **DeepSeek specifically:** Very popular for cost-performance ratio, competitive advantage to support it
## Competitive Intelligence
**GitKraken:**
- Electron (500MB+ RAM), 3.1/5 AlternativeTo rating
- Free tier blocks ALL private repos since v6.0
- Mandatory login even for local repos
- AI limited to Gemini (cloud only)
- Pricing: Free (public only), Pro $8/seat/mo, Advanced $12, Business $16
- Weakness: performance, paywall, login requirement
**GitButler:**
- Tauri/Rust/Svelte (same stack as GitPulse, ~15MB binary)
- Raised $17M Series A (April 2026) — validates git tooling market
- Fair Source license (NOT open source — cannot build competitors, not OSI-approved)
- v0.19.9 beta, 291 open issues, critical bugs (files disappearing #5877, SSH signing broken #5873)
- Single-repo focused, issue #5825 for multi-repo exists but not prioritized
- AI: cloud only (Claude integration)
- Testimonials from Sentry, Notion, ex-Stripe engineers
**Hive (hive-ai.dev):**
- New entrant April 2026
- Multi-repo workspace with agent SDK
- Earliest direct competitor — monitor closely
**RepoZ:**
- Auto disk scan (closest to GitPulse's discovery)
- .NET/WPF, Windows/macOS only, minimal UI
- No batch ops, no AI, appears unmaintained
**lazygit:**
- 50k+ GitHub stars, single-repo TUI
- Performance issues on large repos (topological log traversal)
- No multi-repo view
**gita:**
- Python CLI, batch operations with "superman" mode
- Manual repo registration, no auto-discovery
- ANSI color issues on Windows
## Monetization — Open Core
- **Community tier (free forever):** ALL local features, unlimited repos, full model-agnostic AI, zero restrictions. Not a trial — the complete local product
- **Cloud tier (paid):** Multi-machine sync, team analytics, SaaS integrations (Jira, Linear, Slack). Price TBD — model at $5-10/month
- **Enterprise tier (paid):** SSO, compliance dashboards, audit trails, on-premise. Price TBD — model at $15-25/seat/month
- **Key principle:** Never paywall features that GitKraken paywalls (private repos, local features). Premium is additive cloud value, not restricted local value
- **Conversion funnel assumption:** 2-5% free-to-paid (needs validation)
- **Fundraising trigger:** Seed $1-2M if 5,000 MAU + 3% conversion by month 9
## Technical Constraints & Preferences
- Single binary distribution (.exe, .dmg, .deb) — no installer wizard
- Zero telemetry by default (opt-in only, with clear disclosure)
- Performance targets: ~15MB binary, <200MB RAM, scan results in seconds (qualify: SSD, <100 repos)
- Cross-platform: Windows + macOS + Linux from day 1
- File watcher for real-time updates: Phase 2 (not MVP)
- MCP (Model Context Protocol) support: Phase 3 (extensibility strategy)
- Batch operation error handling: per-repo error reporting, partial success UX (must be in MVP)
## Rejected Ideas & Decisions
- **AI features paywalled:** REJECTED. All AI features free in community tier. Cloud tier monetizes sync/analytics, not intelligence
- **Electron stack:** REJECTED. Tauri/Rust chosen for structural performance advantage
- **Ollama-only AI:** REJECTED. Multi-model from day 1 (Ollama + 4 cloud APIs)
- **Mandatory account/login:** REJECTED. Zero-login, zero-config, works offline
- **CI/CD integration in MVP:** REJECTED. Deferred to Phase 3
- **Merge conflict UI in MVP:** REJECTED. Deferred to post-MVP
- **Mobile companion:** REJECTED. Desktop + system tray only
- **Cloud features in MVP:** REJECTED. Local-first MVP, cloud tier in Phase 2+
## Go-to-Market Signals
- Launch channels: Hacker News Show HN (#1), Product Hunt (#2), Reddit r/programming + r/git + r/selfhosted (#3)
- Optimal Show HN timing: Tuesday/Wednesday 8-10am EST
- Target: 200+ upvotes on Show HN, 500 stars in month 1
- Partnership opportunity: Tauri showcase case study (disproportionate visibility to right demographic)
- Partnership opportunity: Ollama ecosystem (canonical "Git meets local AI" app)
- Content flywheel: auto-generated repo health reports / "year in code" summaries (shareable on social)
- CLI companion tool (gitpulse-cli) as terminal-first adoption path
## Open Questions
- Product name final: GitPulse confirmed, but GitRadar still under consideration
- Pricing: Cloud and Enterprise tier pricing not yet modeled in detail
- MAU measurement: how to track monthly active users for a privacy-first, local-only desktop app (opt-in telemetry vs. proxy metrics like downloads/stars)
- Ollama model selection: which model to recommend as default for Smart Status (quality vs. resource trade-off)
- 20+ hours/month claim: should be validated with independent user research before citing to investors
- Disk scan performance on slow/network drives: needs real-world benchmarking
## Scope Boundaries
**MVP (Day 1):** Scan + Dashboard (cards + list) + Batch ops + System tray + Smart Status (Ollama + 4 cloud APIs) + .gitpulseignore + i18n framework
**Phase 2 (M4-6):** Repo grouping/tagging + Advanced AI + Worktrees + File watcher + CLI companion + Cloud tier
**Phase 3 (M7-12):** Dependency graph + MCP + Autonomous agents + GitHub/GitLab integration + Enterprise tier

254
_bmad-output/planning-artifacts/product-brief-gitpulse.md Normal file
View File

@@ -0,0 +1,254 @@
---
title: "Product Brief: GitPulse"
status: "complete"
created: "2025-04-25"
updated: "2025-04-25"
inputs:
- "market-git-dashboard-ia-research-2026-04-24.md"
- "recherche_comportement_developpeurs.md"
- "recherche-points-de-douleur-developpeurs.md"
---
# Product Brief: GitPulse
## Executive Summary
**GitPulse** is the open source command center for multi-repo governance — a local-first desktop dashboard that automatically discovers every Git repository on a developer's machine and presents them in a single, AI-enhanced view.
Developers managing five or more repositories lose significant time each month to "workflow chaos": forgotten pushes, stale branches, undetected conflicts, and the cognitive overhead of tracking project state across directories. Current solutions fail comprehensively: GitKraken requires Electron (500 MB+ RAM), mandatory login, and paywalls private repos. GitButler ($17M raised) is single-repo by design. lazygit and gita offer no visual dashboard. **No open source tool combines automatic disk scanning, a visual multi-repo dashboard, batch git operations, and AI-powered insights in a performant, zero-configuration package.**
GitPulse occupies this gap. Built on Tauri v2 with a Rust backend and React frontend, it delivers native performance (~15 MB binary, <200 MB RAM) with zero configuration: launch it once and every repository appears. The AI layer is **model-agnostic**: users bring their own intelligence — Ollama for fully local, private analysis, or cloud APIs (Gemini, DeepSeek, OpenAI, Anthropic) for more powerful reasoning. **Your code, your rules.** Privacy is the default; cloud is the opt-in.
Positioned as developer infrastructure (not just a tool), GitPulse targets indie developers, freelances, and power users. It is the "mission control" complementary to AI-powered IDEs — where Cursor writes your code, GitPulse watches your codebase.
## The Problem
A developer sits down Monday morning. She has 23 Git repositories scattered across her disk: client projects, side experiments, open source contributions, internal microservices, and configuration repos. Three have uncommitted changes she forgot about on Friday. Two are behind their remote by a dozen commits. One has a merge conflict she hasn't noticed. Another has branches that haven't been touched in six months.
To discover any of this, she must open a terminal, `cd` into each directory, and run `git status`. Twenty-three times. Every day.
> "I work across many local git repositories and I often lose track of which ones are dirty, ahead/behind, or where I last made changes. Checking each repo with git status became a daily time sink."
> — Git-Scope author, Hacker News (December 2025)
This is not a minor inconvenience. It is a daily, quantifiable time loss that scales linearly with the number of repositories a developer manages.
**How developers cope today — and why it fails:**
- **Shell scripts**: Fragile, unshared, unable to handle edge cases. Most developers write one, use it for a week, then abandon it.
- **GitKraken Workspaces**: The only commercial multi-repo dashboard, but built on Electron (500 MB+ RAM, 3.1/5 user rating), requires mandatory login even for local repos, and locks private repositories behind a paywall since v6.0.
- **GitButler**: Raised $17M, ships on Tauri/Rust (great performance), but single-repo focused, Fair Source licensed (not truly open source), and still in beta with 291 open issues.
- **gita / mu-repo**: CLI batch tools requiring manual repository registration, no visual dashboard, inconsistent Windows support.
- **lazygit / gitui**: Excellent single-repo TUIs, fundamentally one-repo-at-a-time.
- **VS Code Workspaces**: Basic multi-repo awareness, no unified dashboard, no batch operations, no AI insights.
## The Solution
GitPulse is developer infrastructure that works in three layers:
### 1. Instant Discovery
On first launch, GitPulse recursively scans configured directories for `.git` folders. Results appear in seconds. No setup wizard, no login, no configuration file. Just launch and see everything.
**Privacy-respecting by design:** Users control which directories are scanned. An `.gitpulseignore` file (like `.gitignore`) lets developers exclude sensitive client projects, tutorial clones, or any directory from discovery.
### 2. Visual Command Center
Two complementary views:
- **Card Grid** — compact tiles showing each repository's branch, status (clean/dirty/ahead/behind), last commit time, and stash count. Designed for instant pattern recognition across 5 to 100+ repos.
- **List View** — sortable, selectable rows for batch operations: select 15 stale repos and `git pull` them all at once. Filter by status, group by project, tag by context (work, personal, client).
### 3. Smart Status — Model-Agnostic AI
GitPulse provides AI-powered intelligence through a pluggable model backend. The user chooses their engine:
| Mode | Provider | Privacy | Cost | Best For |
|------|----------|---------|------|----------|
| **Local** | Ollama | Full — nothing leaves the machine | Free | Commit messages, health summaries |
| **Cloud** | Gemini, DeepSeek, OpenAI, Anthropic | Data transits to provider API | Pay-per-use (user's own API key) | Cross-repo analysis, impact assessment |
| **Hybrid** | Mix and match | Per-task control | Optimized | Best of both worlds |
**Smart Status capabilities:**
- One-line repository health summaries: *"3 uncommitted changes, 12 commits behind origin/main, last activity 2 weeks ago"*
- Commit message suggestions based on staged changes
- Dormancy alerts for repos inactive beyond a configurable threshold
- Cross-repo impact analysis (cloud models): *"This shared library was updated in 3 repos — 2 may need version bumps"*
**Privacy multi-level indicator:** When a cloud model is active, a clear visual badge in the UI signals that data will transit externally. Local mode (Ollama) always shows "Your code never leaves your machine." The user stays in control at all times.
**Cost-optimized routing:** A smart selector allows per-task model assignment — Ollama for routine commit messages (free), DeepSeek or Gemini for complex cross-repo analysis (user's API key). The user configures the intelligence; GitPulse provides the plumbing.
**No AI? No problem.** If no model is configured, GitPulse works perfectly with deterministic status parsing. Smart Status is a progressive enhancement, never a dependency.
### 4. Always-on Awareness
GitPulse runs a system tray agent that monitors for remote changes and push reminders. A subtle notification appears when a repository falls behind its remote or has uncommitted changes older than a threshold. The developer doesn't need to open the dashboard to stay informed.
## What Makes This Different
| | GitPulse | GitKraken | GitButler | lazygit | gita |
|---|---|---|---|---|---|
| Auto disk scan | Yes | No | No | No | Partial |
| Multi-repo dashboard | Yes | Yes (paid) | No | No | No |
| Batch operations | Yes | Limited | No | No | Yes |
| AI — model agnostic | **Ollama + 4 cloud APIs** | Gemini (cloud only) | Claude (cloud only) | No | No |
| AI — local option | **Yes (Ollama)** | No | No | No | No |
| Open source | **MIT/Apache** | No | Fair Source | GPL-3 | Apache 2.0 |
| Private repos free | **Yes** | **No** (paywall) | Yes | Yes | Yes |
| Login required | **No** | Yes | Yes | No | No |
| Privacy indicator | **Yes** | No | No | N/A | N/A |
| Tech stack | Tauri/Rust | Electron | Tauri/Rust | Go | Python |
| Binary size (target) | ~15 MB | ~200 MB | ~15 MB | ~10 MB | ~1 MB |
| RAM usage (target) | <200 MB | 500 MB–1 GB | 80–150 MB | <50 MB | <20 MB |
**Unfair advantages:**
1. **First mover in the open multi-repo quadrant.** No tool occupies the intersection of auto-discovery + multi-repo dashboard + batch ops + model-agnostic AI + truly open source (MIT/Apache).
2. **Model-agnostic AI plumbing.** GitKraken locks users to Gemini. GitButler to Claude. GitPulse lets developers bring their own intelligence — Ollama for privacy, DeepSeek for cost-performance, Gemini for reasoning, Anthropic for quality. This is infrastructure, not a walled garden.
3. **Structural performance moat.** Tauri + Rust produces binaries 10–15x smaller and 3–5x less memory-hungry than Electron competitors. This is architectural — competitors would need to rebuild from scratch.
4. **Trust through licensing.** MIT/Apache vs GitButler's Fair Source (cannot build competitors, not OSI-approved). Developers can fork, build commercial tools on top, and trust it won't be re-licensed. Genuine adoption accelerator.
5. **Complementary to AI IDEs.** Cursor, Copilot, and Windsurf solve intra-repo productivity. GitPulse solves inter-repo visibility. Developers use both. No "us vs. the giants" positioning trap.
**Why now:**
- Tauri v2 production-stable (90k+ GitHub stars). Framework risk eliminated.
- Ollama on millions of developer machines (100k+ stars, stable API). Local AI infrastructure ready.
- GitHub Copilot data policy change (April 2025): interactions used for training by default. Privacy momentum accelerating.
- DeepSeek's rise creates demand for tools that support diverse model backends — not just the one vendor's cloud.
- GitButler's $17M validates git tooling market but confirms single-repo focus. Window is open.
## Who This Serves
**Primary: The Indie Dev Poly-Project**
A freelance or solo developer juggling 10–50+ projects across clients, open source, and personal experiments. They context-switch daily between repositories and lose track of state. Their pain is constant and immediate.
*Success looks like:* Monday morning, launch GitPulse, instantly see 3 repos need attention, handle them in 30 seconds instead of 20 minutes.
**Secondary: The Power User / Tech Lead**
A senior developer managing a microservices architecture across multiple repositories. They need batch operations, cross-repo visibility, and team-level awareness. They already use CLI tools but crave a visual overview and are willing to configure cloud APIs for advanced analysis.
*Success looks like:* Batch-pulling 12 microservice repos, then seeing the Smart Status summary confirm all are clean — with cross-repo dependency analysis powered by their preferred cloud model.
**Tertiary: The Maker / Side-Project Builder**
A creative developer with dozens of side projects, prototypes, and experiments. Many repos are dormant. They need to discover which projects are still alive, which are stale, and which have changes they forgot to push.
*Success looks like:* GitPulse flagging 8 repos dormant for 3+ months and 2 with uncommitted changes from weeks ago — a cleanup session they'd never have initiated manually.
## Success Criteria
**Month 3 (post-launch):**
| Metric | Target |
|--------|--------|
| GitHub stars | 500+ |
| Monthly active users | 500+ |
| Cumulative downloads | 2,000+ |
| Hacker News Show HN score | 200+ upvotes |
**Month 6:**
| Metric | Target |
|--------|--------|
| GitHub stars | 2,000+ |
| Monthly active users | 2,000+ |
| Paying subscribers (cloud tier) | 50 |
| D30 retention | 40%+ |
**Month 12:**
| Metric | Target |
|--------|--------|
| GitHub stars | 5,000+ |
| Monthly active users | 10,000+ |
| Paying subscribers | 200 |
| MRR | $1,500+ |
| D30 retention | 50%+ |
**User success signals:**
- Average repos scanned per user > 10 (validates multi-repo need)
- Batch operations used within first session (validates batch value)
- Smart Status consulted > 3 times per session (validates AI value)
- System tray notifications acted upon within 24 hours (validates passive monitoring)
- At least 2 AI backends configured per active user (validates model-agnostic value)
## Scope
**In — MVP (Day 1 launch):**
- Automatic recursive disk scan for Git repositories with `.gitpulseignore` support
- Card grid view: branch, status, ahead/behind, last commit, stash count
- List view: sortable, filterable, selectable for batch operations
- Batch operations: pull, push, fetch, status across selected repos (with per-repo error reporting)
- System tray agent: remote change alerts, push reminders
- Smart Status with model-agnostic AI backend:
- Ollama integration (local, default)
- Cloud API support: Gemini, DeepSeek, OpenAI, Anthropic (user's own keys)
- Privacy indicator: visual badge showing local vs cloud mode
- One-line repo summaries, commit message suggestions, dormancy alerts
- Zero-config, zero-login, single binary distribution
- Cross-platform: Windows, macOS, Linux
- English UI with i18n framework ready
- MIT/Apache open source license
**Explicitly Out — MVP:**
- Cloud sync or team collaboration features
- Built-in code editor or diff viewer
- Merge conflict resolution UI
- CI/CD integration or pipeline dashboards
- Integration with GitHub/GitLab APIs (issues, PRs, CI status)
- Mobile companion app
- Enterprise features (SSO, compliance, audit logs)
- Telemetry (opt-in anonymous usage stats only, with clear disclosure)
**Planned — Phase 2 (months 4–6):**
- Repository grouping, tagging, and workspace contexts
- Advanced Smart Status: cross-repo dependency detection, activity patterns
- Git worktree integration in the dashboard
- File watcher for real-time status updates
- CLI companion tool (`gitpulse-cli`) for terminal-first workflows
- Premium cloud tier: multi-machine sync, team analytics
**Planned — Phase 3 (months 7–12):**
- Inter-repository dependency graph visualization
- MCP (Model Context Protocol) support for extensibility
- Autonomous AI agents for code review and anomaly detection
- GitHub/GitLab integration (PRs, issues, CI status)
- Enterprise tier: SSO, compliance, fleet analytics
## Competitive Dynamics
**GitButler** ($17M raised, Tauri/Rust, Fair Source) is the most credible fast-follower. Issue #5825 (multi-repo) is open but not prioritized — their focus is virtual branches and agentic workflows. **Mitigation:** Ship first, build community traction, and differentiate on model-agnostic AI. GitButler's Fair Source license is a permanent friction point for the OSS community.
**GitKraken** (Electron, proprietary) could improve Workspaces performance, but rebuilding on a native framework would be a multi-year effort. **Mitigation:** The structural performance gap is uncloseable without an Electron migration — a decision they're unlikely to make given their codebase investment.
**Hive** (hive-ai.dev, appeared April 2026) is the earliest direct competitor to monitor. Multi-repo workspace with agent SDK. **Mitigation:** GitPulse's open source licensing, model-agnostic approach, and local-first architecture are fundamentally different value propositions.
**AI IDEs** (Cursor, Copilot, Windsurf) are architecturally mono-repo. Adding a multi-repo dashboard view is not imminent. **Mitigation:** GitPulse is complementary, not competitive. Coexistence is the strategy.
## Vision
**In 2–3 years, GitPulse becomes the open source standard for multi-repo governance** — the infrastructure every developer installs alongside their IDE and terminal.
Where GitButler owns individual branch workflows and AI-powered IDEs own code generation, GitPulse owns the macro view: the health, synchronization, and coordination of every repository a developer or team touches.
The business model evolves from indie project to structured **Open Core** company:
- **Community tier** (free, MIT/Apache): All local features, unlimited repos, full model-agnostic AI capabilities, zero restrictions. Growth engine — every user is a potential advocate and contributor.
- **Cloud tier** (paid): Multi-machine sync, team analytics, SaaS integrations (Jira, Linear, Slack), fleet-level repository monitoring. Revenue without compromising the local-first promise.
- **Enterprise tier** (paid): SSO, compliance dashboards, audit trails, on-premise deployment. The segment where GitKraken operates with high dissatisfaction.
**Fundraising trigger:** Seed round ($1–2M) if GitPulse reaches 5,000 MAU and 3% free-to-cloud conversion by month 9. Funds accelerate enterprise integrations and team hiring while preserving the open source core. The community product stays free forever; the company monetizes coordination, visibility, and compliance at scale.
GitPulse is not a feature. It is the category-defining infrastructure for a problem 100 million developers have but no one has solved properly — yet.

1138
_bmad-output/planning-artifacts/research/market-git-dashboard-ia-research-2026-04-24.md Normal file
View File

File diff suppressed because it is too large Load Diff

1047
_bmad-output/planning-artifacts/ux-design-directions.html Normal file
View File

File diff suppressed because it is too large Load Diff

1276
_bmad-output/planning-artifacts/ux-design-specification.md Normal file
View File

File diff suppressed because it is too large Load Diff